angular-mesa

If labelTemplate or labelTemplateUrl is specified, it will replace the default text with the provided template.
The scope of this template will include the column definition object as column and the options object as options.


Row Sorting
-----------
The rows of the table can be sortable based on a column by setting the sort attribute of a Column Definition Object to a function with the following signature:

/**
* Defines sort function for ascending order.
* @param {Object} rowA First row being compared
* @param {Object} rowB Second row being compared
* @return {Number} Result of comparison.
*/
function MySortFunction(rowA, rowB) {
// Assuming propertyKey is numeric,
// this would work as a number sorter:
return rowA.propertyKey - rowB.propertyKey;
}

The returned value should mirror how Array.prototype.sort works: If the returned value is negative, rowA will be placed above rowB in the ascending sort order. If it is negative, rowB will be placed above rowA in the ascending sort order. If it is zero, the two rows will be considered the same in terms of sorting precedence.

There are four built-in sort functions available which handle the most common use-cases: "string", "number", "stringFormatted", and "numberFormatted". To use these, simply set the sort attribute to one of these strings.

Sorting can be set by the user by clicking the headers of sortable columns, and can be stacked by holding shift and clicking. The initial sort order can be set using the initialSorts option in the Options Object, shown in the table above.

Row Filtering
-------------

If a filter function is set on a Column Definition Object, that column will contain an input field below the main column header where the user can type in a value and the rows will be filtered based on what they type and the behavior of the function. This function should have the following signature:

/**
* Defines a filtering function
* @param {String} term The term entered by the user into the filter field.
* @param {Mixed} value The value of row[column.key]
* @param {Mixed} computedValue The value of column.format(row[column.key], row). Will be the same as value if there is no format function for the column.
* @param {Object} row The actual row of data
* @return {Boolean}
*/
function MyFilterFunction(term, value, computedValue, row) {
// Assuming row[column.key] is a string,
// this would work as a simple matching filter:
return value.indexOf(term) >= 0;
}

When there is a value provided by the user in the filter field, every row in the dataset is passed through this function. If the function returns true, the row will be included in the resulting rows that get displayed. Otherwise it is left out. To set placeholder text for the filter field, simply add a placeholder attribute directly to the filter function. To add a title/tooltip, add a title attribute, e.g.:

`js
MyFilterFunction.placeholder = "enter text";
MyFilterFunction.title = "Perform a simple text search";
`

There are several common filter functions that are built-in. Use them by passing one of the following strings instead of a function:

| string | description |
|--------|-------------|
| like | Search by simple substring, eg. "foo" matches "foobar" but not "fobar". Use "!" to exclude and "=" to match exact text, e.g. "!bar" or "=baz". |
| likeFormatted | Same as "like", but looks at formatted cell value instead of raw. |
| number | Search by number, e.g. "123". Optionally use comparator expressions like ">=10" or "<1000". Use "~" for approx. int values, eg. "~3" will match "3.2". |
| numberFormatted | Same as number, but looks at formatted cell value instead of raw |
| date | Search by date. Enter a date string (RFC2822 or ISO 8601 date). You can also type "today", "yesterday", "> 2 days ago", "< 1 day 2 hours ago", etc. |

Cell Formatting
---------------
You can format the result of row[key] by specifying a format function on the column definition object. For example, perhaps you want to add a dollar sign to a column which represents an amount of money:

`javascript
var columns = [
{
key: 'price',
format: function(price) {
return '$' + price.toFixed(2);
}
}
];
var rows = [
{ price: 12 },
{ price: 14 }
];
`

Row Selection
-------------
There is a special type of column called a selector, which will render as a checkbox that, when clicked, will populate a selected array that is provided through an attribute of the ap-mesa element. The following is an example column definition for a selector (Usually this column appears first):

$scope.myColumns = [
{
id: 'selector',
key: 'idKeyOfObjects', // used to populate the selected array
label: '', // no label for checkbox column
selector: true,
width: '40px', // Fixed width of 40px
lockWidth: true, // to keep it narrow
selectObject: true // Optional: by default, selecting a row puts the value of
// row[idKeyOfObjects] into the selected array. If this option
// is set to true, the entire object will be placed into the
// selected array.
}
]


Expandable Rows
---------------

To use the expandable rows feature, you will need to specify an expandableTemplate or expandableTemplateUrl and call toggleRowExpand() from a custom column template. For example, a column definition may look like:

`javascript
$scope.tableOptions = {
expandableTemplate: '

Row Details:

{{ row | json }}

As shown above, there will also be a property on the row scope called rowIsExpanded which is a boolean indicating if the row's panel is expanded.
It's also recommended to make the rowPadding option at least as large as the expected pixel height of the expanded panels.

For a complete example, please check out /app/scripts/controllers/expandable.js.

If the content of the panel is dynamic and changes height, there is a method in the row scope called refreshExpandedHeight which should
be called when the height has changed.

Paging Strategies
-----------------

You can specify the paging strategy as 'PAGINATE', 'SCROLL', or 'NONE'.

$3

The default paging strategy is a scrollable table body with height defined by the tableHeight, fillHeight, and fixedHeight options.

$3

This strategy will render the table as pages instead of an endlessly scrolling tbody. The tableHeight, fillHeight, and fixedHeight options will NOT be honored

Server-side Interaction
-----------------------

You have the option to specify a getData function on your table options object which will enable server-side interaction. It must implement the following function signature (see inline explanation):

`javascript
function getData (offset, limit, activeFilters, activeSorts) {

// offset and limit are numbers, indicating the subset of the total
// result set, given the filter and sort states

// activeFilters is an array of objects, each containing the string that the user has entered into the
// filter text input, as well as the corresponding column definition object, e.g.:

// [
// { value: 'im typing', column: [COLUMN DEF OBJECT] },
// { value: 'me too thanks', column: [COLUMN DEF OBJECT] },
// ]

// Note that columns whose filter inputs are empty will not show up here.

// activeSorts is an array of objects similar to activeFilters, except that instead of value field
// there is a direction field that will either be 'ASC' or 'DESC'. Note that the order of this
// array reflects the order that the user chose to sort columns on (stacked sorting).

// This function should return a promise that resolves with an object that looks like this:
// {
// total: [NUMBER OF TOTAL ROWS BEFORE LIMIT],
// rows: [ARRAY OF ROWS FOR GIVEN OFFSET, LIMIT, SORT, FILTERS]
// }
}
`

Note that when getData is specified, angular-mesa only checks the filter and sort fields in the column definition objects for "truthiness".It does not perform any sort of sorting and filtering itself; that is left up to the server to do.

Also note that the angular-mesa.d.ts` typescript definition file has a more formal signature for this function that may help if you are familiar with TS.

Browser Support
---------------
IE 9+
Firefox 4+
Safari 5+
Chrome 5+