angular-datafree v1.0.16

Angular Datafree

Freely visualize backend data within an Angular Frontend.

Files

• dist/angular-datafree.build.min.js - No longer used
• dist/angular-datafree.min.js - the version for production use
• dist/angular-datafree-templates.js - include this file and module in your app to use the default template files
• dist/angular-datafree.min.css - the default CSS for the templates

Wireup

After including the files, inject into your app and create a query:

angular.module('app', ['ae.datafree', 'ae.datafree.tpls'])
    .controller('DefaultCtrl', ['DFQuery', function(DFQuery) {
        $scope.query = new DFQuery('/query');
    }])
    ;

The <datafree> element is a simple container that connects child directives to send requests via a client and react on data updates from the same client.

<!-- Table Example but doesn't NEED to be a table -->
<div ng-controller="DefaultCtrl">
    <datafree query="query">
        <table>
            <thead>
                <th datafree-order="id">ID</th>
                <th datafree-order="first_name">First Name</th>
                <th datafree-order="last_name">Last Name</th>
                <th datafree-order="email">Email</th>
                <th datafree-order="gender">Gender</th>
                <th datafree-order="ip_address">IP Address</th>
            </thead>
            <tbody>
                <tr datafree-row>
                    <td>{{ data.id }}</td>
                    <td>{{ data.first_name }}</td>
                    <td>{{ data.last_name }}</td>
                    <td>{{ data.email }}</td>
                    <td>{{ data.gender }}</td>
                    <td>{{ data.ip_address }}</td>
                </tr>
            </tbody>
            <tbody datafree-empty>
                <tr>
                    <td colspan="6">No items found</td>
                </tr>
            </tbody>
        </table>
        <datafree-pager></datafree-pager>
    </datafree>
</div>

Datafree Directive

The <datafree> element requires one of two attributes, query="[ a DFQuery object ]" or client="[ a DFClient object ]".

When only providing a DFQuery object, the Datafree directive will create an isolated DFClient. Only directives within the <datafree> element who require the datafree directive will be able to interact with the DFClient using the DatafreeDirectiveController.

The DatafreeDirectiveController is also accessible via the template by using $df.

If you wish to have access to the DFClient used by the <datafree> element, simply inject the DFClientFactory into your controller and pass a DFQuery object to the createClient() method.

Optionally, use the autoload="truthy statement like true/false or $ctrl.isTruthyValue" to tell the <datafree> element's controller to call the server automatically once all child directives are linked. If this value is false, you will have to make the initial DFClient.send() call via you controller (so in other words, you should use the DFClientFactory).

// Example of creating your own client
angular.module('app', ['ae.datafree', 'ae.datafree.tpls'])
   .controller('DefaultCtrl', ['DFQuery', 'DFClientFactory', function(DFQuery, DFClientFactory) {
       var query = new DFQuery('/query');
       
       $scope.myClient = DFClientFactory.createClient(query);
   }])
   ;

<!-- Assigning a generated client to the Datafree element -->
<div ng-controller="DefaultCtrl">
   <datafree client="myClient">
       <!-- Abridged -->
   </datafree>
</div> 

DFQuery

A DFQuery manages the state of the Query. The Query is mapped to query parameters and passed to the backend URL via the DFClient where the data is processed and data is returned.

IDFQuerySettings

These are the default values which are mapped to the request's query parameters if values are not provided.

When a value is a function, it is executed at the moment the client builds the parameters to send to the server. When a value is null it is not output to the query parameters.

IDFParamsMap

An IDFParamsMap object simply associates the properties on the IFQuerySettings object to a string value that is used as the parameter name.

Example: Using IDFQuerySettings values, this IDFParamsMap would be converted to &page=[$page]&limit=[$limit]&order_by=[$orderBy]&order_direction=[$orderDirection]&q=[$filter]

DFClient

The DFClient makes the calls to the server and processes the data and total count and signals subscribers of changes.

DatafreeDirectiveController

Accessible in the template within the <datafree> element by using $df or within another directive by using require: '^^datafree'.

Additional Directives

datafree-order

Type: Attribute

This is a helper that will set the order column and toggle the order direction for that column on the query. *The value of the attribute becomes the $orderBy value on the DFQuery.

datafree-row

Type: Element, Attribute, Class

This is similar to ng-repeat. datafree-row transcludes elements and repeats them for each row in the response data. The data variable in the scope is an object that represents the current row. I.e., {{ data.id }} or {{ data.first_name }}.

Note: When using datafree-row in a table, do not use it as an element. It's best used as an attribute or class on the <tr>.

datafree-empty

Type: Element, Attribute, Class

A transcluded directive which only appears when the response data is empty. This is useful when DFQuery.$filter is used.

Note: Do not place the datafree-empty directive inside a datafree-row element, it will be removed once data is populated.

Note: When using datafree-empty within a table, it's best to place it on a second <tbody> element. Anything else will result in the element not rendering or being removed from the table.

datafree-pager

Type: Element

This is a very customizable pager element. Using attributes on the element, you can control how it will render.

Include angular-datafree-template.js and ae.datafree.tpls in your application to use the default template.

Overriding the default pager template

If you want to use your own template for the page, rather than the default one provided, simply do the following:

Please refer to the views/datafree-pager.html file for reference. The DatafreePagerDirectiveController is available via the $pager variable in the template.

// If you want to load from a string value
angular.module('myApp', ['ae.datafree'])
    .run(['$templateCache', function($templateCache) {
        $templateCache.put('datafree-pager.html', 'YOUR TEMPLATE HTML HERE');
    }]);

// If you want to load from a URL
angular.module('myApp', ['ae.datafree'])
    .run(['$templateCache', '$http', function($templateCache, $http) {
        $http.get('/path/to/your/template.html', function(response) {
           $templateCache.put('datafree-pager.html', response.data); 
        });
    }]);

Note: It is also possible to use the $provide.decorator() within the .config() method to change the templateUrl value of the pager directive. However, this method is untested and could have complications if you don't know what you're doing. So tread lightly.