angular-datafree

1.0.16 • Public • Published

Angular Datafree

Build Status

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.

Property/Method Definition
constructor(url, [method], [defaultSettings], [defaultParameterMap]) The DFQuery Constructor. Accepts up to 4 parameters. url: the backend URL where the data will be processed, method: the HTTP method for the request, defaultSettings a IDFQuerySettings object, defaultParametersMap: a IDFParamsMap object.
$url Sets and Gets the url used to call the backend.
$method Sets ang Gets the method used in the HTTP Request
$settings Gets the current state of the IDFQuerySettings of the Query
$page Sets and Gets the page of the query
$limit Sets and Gets the limit, or the max number of records per page
$orderBy Sets and Gets the column/field by which records are ordered/sorted.
$orderDirection Sets and Gets the order/sort direction, accepts "ASC" or "DESC"
$filter Sets and Gets the keywords that results should be filtered by.
$paramsMap Gets the IDFParamsMap the query is using to map settings to the query parameters.
$dataResponseType Sets and Gets the expected response type. Must be either "PROPERTY" or "BODY" (default). If set to "PROPERTY", the DFClient will look for a property on the data object returned from the server. "BODY" is the default and accepts the entire body of the response as the data to be set.
$dataProperty Sets and Gets the property name used to extact data from the server response. Required when $dataResponseType is "PROPERTY"
$countProperty Set and Gets the property name used to get the total record count. This is required if records are paged. When $dataResponseType is "BODY", the value of $countProperty will be used to get its respective header from the response, otherwise it will look for a property on the response object within the body. Defaults to "X-Count"

IDFQuerySettings

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

Property Type Default
page number 0
limit number 10
orderBy string null
orderDirection "ASC" or "DESC" null
filter string null
orderCallback function(orderBy, orderDirection) a function that returns an array of [ orderBy, orderDirection ]
filterCallback function(filter) a default getter function for the filter value
pageCallback function(page, limit) returns the page value, by default. Use this to do something like page * limit.

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.

Settings Property Default Parameter Name
page page
limit limit
orderBy order_by
orderDirection order_direction
filter q

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.

Property/Method Description
$query Sets and Gets an DFQuery object.
$headers Sets and Gets a headers object that is passed along with the request. This is useful when requiring authentication headers.
$withCredentials Sets and Gets a boolean which is passed along with the server request. This is used to set the XHR.withCredentials flag.
send([params: Object]) Sends a request to the server using the Query provided. The params argument will override any of the IDFQuerySettings for this request only and will append any extra query parameters. Triggers subcribers and returns a Promise.
page(p: number) Sets the $page property on the DFQuery object, sends a request to the server, triggers subscribers and returns a Promise.
next() Adds 1 the $page property on the DFQuery and calls page().
prev() Subtracts 1 from $page and calls page().
first() Calls page(0).
last() Calls page($total). If $total hasn't been set, a dummy request is sent to populate it. Requires the $countProperty to be set and used in the server response.
order(column: string, direction: string) Sets $orderBy with the column argument and $orderDirection with the direction argument and then calls send().
filter(q) Sets $filter on DFQuery and calls send().
limit(n) Sets the $limit on DFQuery and calls page(0).
subscribe(f: Function) Subscribes the function f to the client. When data is successfully processed from the server, f is triggered with the the data as the argument and this will point the client.
unsubscribe(f: Function) Unsubscribe a function from the client.

DatafreeDirectiveController

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

Property/Method Description
$data Gets the data that was processed from the server response. If you want, you can use this with ng-repeat="data in $df.$data"
send([params: Object]) Shortcut to client.send()
page(p: number) Shortcut to client.page()
next() Shortcut to client.next()
prev() Shortcut to client.prev()
first() Shortcut to client.first()
last() Shortcut to client.last()
order(column: string, direction: string) Shortcut to client.order()
filter(q) Shortcut to client.filter()
limit(n) Shortcut to client.limit()
subscribe(f: Function) Shortcut to client.subscribe()
unsubscribe(f: Function) Shortcut to client.unsubscribe()

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.

Attribute Description
number-limit This controls the maximum number of pages that are shown. Default: 5
show-first A truthy expression that will determine if the "First" button is rendered.
show-last A truthy expression that will determine if the "Last" button is rendered.
show-next A truthy expression that will determine if the "Next" button is rendered.
show-prev A truthy expression that will deterine if the "Back" button is rendered.
first-label The text used to label the "First" button. Default: First
last-label The text used to label the "Last" button. Default: Last
next-label The text used to label the "Next" button. Default: Next
prev-label The text used to label the "Back" button. Default: Back

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.

Package Sidebar

Install

npm i angular-datafree

Weekly Downloads

1

Version

1.0.16

License

MIT

Last publish

Collaborators

  • curiosity26