API Documentation

General info

Terms

The terms used in this documentation with some explanation.

• User– the developer who is using the data table API (not the end user)
• HTML– the view in which the data table is defined
• Controller– the AngularJS controller behind the view
• Directive– the inside logic of the data table
• DataTables– the original library behind this implementation
• Data table– the angular-datatable

Two way communication

Communication between the source in the controller and the table settings in the directive is bidirectional.

From the directive to the controller

Refresh(data) – the function which is defined by the user in the controller and bound to the data table with the HTML attribute, ‘refresh’. It is the way of communication from the directive to the source. The user gets the settings data through this channel. From the controller to the directive The changes of the source are monitored inside the directive. It is hidden from the user of the data table but the directive will know every change of the data source and redraw the table according to the changes.

Minimal data table setup

HTML

<div my-data-table my-source="projects" refresh="refresh(data)">
</div>

Controller

var refresh = function(data){
            //alter $scope.projects according to data
        };
        $scope.projects = [];

data – the options coming from the data table according to the UI manipulation of the table The data object:

pageIndex: actualPageIndex, 
pageSize: pageSize,
 	orderBy: orderBy, 
filterOptions: filterOptions
};

Hiding the pagination if you have only one page of data is not available through the API. But it is easy to change. The user need to delete only one row of the data table implementation. By default it will show always the NEXT button according to the original requirements of the data table.

Available data table settings (optional)

Header

User can define custom header to the data table.

HTML

<div my-data-table
   my-source="dataSource"
   refresh="refresh(data)"
   header="headerControls">
</div>

headerControls – It needs to be an array. The array can contain control options and array of control options.

Individual controls have self-triggering mechanism. Control groups will be handled coherent on the UI and frequently have a common trigger mechanism.

Controller

$scope.headerControls = [[selector, textBox, button1], button2];

Control descriptions

The following controls are available as header control:

• button
• selector
• textbox (input)

type : {DataTableExtensions.headerControls} is an enum with three options: button, select (will be renamed to selector), textBox (will be renamed to input) properties: {object}

• label (only for selector and textbox) {string} label for the control OPTIONAL – if it is not defined no extra label will be added to the control
• options (only for selector) {array of strings} the options to the selector
• filterName {string} the id to identify this setting in the refresh data
• trigger (only for selector and textbox){object} o mode { DataTableExtensions.triggerModes } explicit/implicit in the case of implicit the change of the value of the control will trigger the calling of the controller’s refresh function o starter (only for explicit) {string} the name of the button which will trigger to send the actual value of the current control
• name (only for button but required) {string} the id of the button it is necessary to identify it later as a trigger
• text (only for button) {string} the text on the button (will be renamed to label to be consequent)
• callback (only for button){function} callback if the button is not a trigger method this function will be called on click do not define it if the button is only for triggering (data table will handle it in this case calling the refresh function of the controller)

Examples

        var selector = {
            type: DataTableExtensions.headerControls.select,
            properties: {
                label: "Version:",
                options: ["0-10", "10-100", "100-1000"],
                filterName: "version",
                trigger: {mode: DataTableExtensions.triggerModes.explicit, starter: "buttonFilter"}
            }
        };

        var textBox = {
            type: DataTableExtensions.headerControls.textBox,
            properties: {
                label: "Search:",
                filterName: "search",
                trigger: {mode: DataTableExtensions.triggerModes.explicit, starter: "buttonFilter"}
            }
        };

        var button1 = {
            type: DataTableExtensions.headerControls.button,
            properties: {
                name: "bauttonFilter",
                text: "Search"
                //callback: function(){console.log("fucking awesome")} //option to bind controller function to button
            }
        };

        var button2 = {
            type: DataTableExtensions.headerControls.button,
            properties: {
                name: "buttonDoNotClick",
                text: "DO NOT CLICK",
                callback: function(){alert("I said do not click it!")} //option to bind controller function to button
            }
        };

PageSizes

{array of numbers} Default value: 10 User can define the available sizes of the element count on one page.

Setting this property will show a selector in the header with the given options.

HTML

<div my-data-table
     my-source="dataSource"
     refresh="refresh(data)"
     page-sizes="pageSizes">
</div>

Controller

 $scope.pageSizes = [10,50,100];

Plan for the future

Option to set one value as a page size without showing a selector on the UI. It will only redefine on start the default 10 and will be not changeable later on UI.

Hiding

Case insensitive

User can define an array of properties that will not show up in the data table.

HTML

<div my-data-table
     my-source="dataSource"
     refresh="refresh(data)"
    hiding-properties="hidingProperties">
</div>

Controller

 	$scope.hidingProperties = ["id"];

Plan for the future

I want to support the opposite way of defining the shown properties. Instead the array of the properties which the user wants to hide is easer to define the properties which the user want to see in the table. If I want to show only name and status (2 from the many properties) why should I know all the other property names and if I would know it will be a bigger array to define.

Sorting

Case insensitive

User can define an array of the property names and with clicking on the certain header titles the table will be sortable by this properties.

HTML

<div my-data-table
     my-source="dataSource"
     refresh="refresh(data)"
    sorting-properties="sortingProperties"></div>

Controller

$scope.sortingProperties = ["name", "status"];

This sorting is using only the built-in sorting mechanism of the DataTables and will sort only the actual page without sending the info from the directive back to the controller.

Plans for the future

Sorting the whole source with own mechanism. With calling the refresh function of the controller with the extended data object.

Select

Optional callback function on row selection.

HTML

<div my-data-table
     my-source="dataSource"
     refresh="refresh(data)"
     select-row="select(item)"></div>

Controller

        $scope.select = function(item){
	//some manipulation of the item
	};

Inline controls

In this version it is only two types of inline controls that is supported.

• The button to delete the actual row.
• The button to edit the actual row.

HTML

<div my-data-table
     my-source="dataSource"
     refresh="refresh(data)"
    delete-row="deleteRow(item)"
     edit-row="editRow(item)"></div>

Controller

        $scope.editRow = function(item){
	//edit the item object or show an edit window with the item …
};

        $scope.deleteRow = function(item){
	//delete the item from the source
};

item - The selected object contained by the data source

Plans for the future

The same API as used by the header controls to define custom buttons to a row.

Inline converters

The user can define converters to a column. If you define the name of the property and the converter function the data table will convert the data of the column through the defined converter function.

Example

If you have a property containing types 0 for live and 1 for draft. In the table this property will be represented with the value of it, with 0 or 1. But the user can define a converter function to write in the table not the 0 or the 1 but the string live or draft according to the certain value.

HTML

<div my-data-table
     my-source="dataSource"
     refresh="refresh(data)”
     converters=”converters”></div>

Controller

          $scope.converters = [{ 
property : 'state', 
converterCallback : 'statusConverter(value)'}];

        $scope.statusConverter = function(value){
          console.log('I got a value!! ' + value);
          if(value === 0){
              return 'draft';
          }else{
              return 'live';
          }
        };

Built-in options

Arrow key navigation

Moving up and down on the rows with arrow keys of the keyboard are available and paging as well.

• With pushing down key after the last row of the page it will navigate to the next page.
• With pushing up key after the first row of the page it will navigate to the previous page.