Basic Usage
The basic features makes apiNG to a high-flyer for receiving and displaying data, you regularly consume via $http.
apiNG enables you to receive, aggregate, limit, order and display data from one or more sources. The complete setup is dead simple, just by adding data-attributes to your html.
Table of Content
- Features
- Simple Setup
- Parameters
- Events
- Built-in plugin "JSON-Loader"
- Built-in plugin "XML"
- Built-in plugin "Local-Storage"
- Built-in plugin "NG-Array"
Features
Setup
- Easy to setup via HTML data-attributes
- Additional, you can pre-define your default settings in a config file, which could be overwritten by every apiNG instance
- Store your access tokens & api keys in the credential-manager
- Isolated scope - Use more than one apiNG instance per page.
- You can nestle apiNG instances
Get & Aggregate your data
- Receive data from any source (JSON/XML File, URL or REST API)
- Receive data from more than one source and aggregate all the data
- Enhance with additional data from local storage
- Enhance with additional data from your controller
Optimize your data
- Limit the received data per request
- Limit the aggregated data per apiNG instance
- Sort your data by property (asc or desc)
- Remove duplicates from your aggregated data
- Merge duplicates from your aggregated data
- Create identifiers by combining some properties in your own way
Display your data
- apiNG delivers the data to your angular template
- Use template files or inline html as template
- Change the template file on the fly
- The data is available in
$scope.results
, which you could access in your template with{{results}}
- Inject additional payload data into your template, which you could access with
{{payload}}
Work with your data
- As needed, the data can be available in an injectable and persistent angular value (Plnkr)
Simple Setup
Plnkr demo (view & edit)
- Install apiNG
- Add the apiNG directive to your html:
<aping aping-jsonloader="[{ 'path': 'https://randomuser.me/api/' }]">
<pre>{{results | json}}</pre>
</aping>
$scope.results
contains the data and is available in the template.
Parameters
Attribute | Type | Sample | Description |
---|---|---|---|
template-url | string | template.html | Path to template file Use result data in template with {{results}} |
items | int | 20 | Number of displayed items per request |
max-items | int | 100 | Number of items of this apiNG instance Use -1 for no limitation |
order-by | string | timestamp | Order result by this attribute Use $NONE for no orderUse $RANDOM for random order |
order-reverse | boolean | false | Use true for reverse orderDefault value: false |
id-by | string or json array | intern_id ['name','date'] ['user.0','user.1'] | Create id for each item by this properties. Property name: aping_id |
merge-doubles | boolean | false | Use true to merge objects with the same ID.Works only with id-by Default value: false |
remove-doubles | boolean | false | Use true to remove identical objectsor with the same ID ( id-by ).Gets ignored if merge-doubles is set.Default value: false |
payload-json | json object | {'key1':'value1'} | Inject additional data into your template. Use payload data in template with {{payload}} |
value-name | string | videos | Inject apingResults into your app. (Plnkr)Access the results with apingResults.valueName |
result-name | string | events | Change the result-name to set the $scope property that will contain the results. Default value: results |
protocol | string | https | Change the protocol of some plugins to https or http . If no value is set, the some requests will getmade without any given protocol. Use this parameter, if you work with Ionic, Cordova or PhoneGaph |
Sample:
<aping
template-url="templates/events.html"
items="10"
order-by="timestamp"
order-reverse="true"
remove-doubles="true"
payload-json="{'title':'All Events (Munich and Berlin)'}"
aping-jsonloader="[{'path':'events_munich.json'}, {'path':'events_berlin.json'}]">
</aping>
Plnkr demo (view & edit)
Events
Event | Description |
---|---|
apiNG.resultMerged | This event fires every time a plugin submits some data and apiNG merged this data with $scope.results |
apiNG.templateRendered | This event fires every time the template is rendered. |
Built-in plugin "JSON-Loader"
1. Sample
<aping
template-url="templates/events.html"
aping-jsonloader="[{'path':'json/events.json'}]">
</aping>
2. USAGE
Supported Sources
- JSON files (local)
- JSON files (external)
- restful JSON urls
- restful JSONP urls (does not work with angular 1.6 or higher)
Requests
parameter | sample | default | description | optional |
---|---|---|---|---|
path | data.json | Valid values: JSON files (local) JSON files (external) * restful JSON urls | no | |
format | jsonp | json | Request format (json or jsonp ). jsonp | yes |
xAuthToken | e42cb6a6ecc949c88 | Headers X-Auth-Token | yes | |
Authorization | Bearer e42cb6a6ecc949c88 | Headers Authorization | yes | |
resultProperty | result_items | Property name, containing the result. For deep results, use this this syntax: data.0.results | yes | |
items | 20 | Items per request (0 -n ) | yes | |
orderBy | position | Order result by this attribute Use $RANDOM for random order | yes | |
orderReverse | true | false | Use true for reverse order | yes |
Sample requests:
[{'path':'data.json', 'items':5}]
[{'path':'//rawgit.com/JohnnyTheTank/apiNG/master/bower.json'}]
[{'path':'https://api.dailymotion.com/user/Bishop-live/videos'}]
[{'path':'http://jsonplaceholder.typicode.com/posts/1', 'format':'jsonp'}]
Built-in plugin "XML"
Plnkr demo (view & edit)
1. Sample
<aping
template-url="templates/events.html"
aping-xml="[{'path':'xml/events.xml'}]">
</aping>
2. USAGE
Supported Sources
- XML files (local)
- XML files (external)
Requests
parameter | sample | default | description | optional |
---|---|---|---|---|
path | data.json | Valid values: XML files (local) XML files (external) | no | |
resultProperty | result_items | Property name, containing the result. For deep results, use this this syntax: data.0.results | yes | |
items | 20 | Items per request (0 -n ) | yes | |
orderBy | position | Order result by this attribute Use $RANDOM for random order | yes | |
orderReverse | true | false | Use true for reverse order | yes |
Sample requests:
[{'path':'data.xml', 'items':5}]
[{'path':'https://raw.githubusercontent.com/JohnnyTheTank/apiNG/master/demos/xml/event.xml'}]
Built-in plugin "Local Storage"
1. Sample
<aping
template-url="templates/favorites.html"
aping-local-storage="[{'key':'favorites'}]">
</aping>
2. USAGE
Requests
parameter | sample | default | description | optional |
---|---|---|---|---|
key | favorites | Local Storage key | no | |
resultProperty | result_items | Property name, containing the result. For deep results, use this this syntax: data.0.favorites | yes | |
items | 20 | Items per request (0 -n ) | yes | |
orderBy | position | Order result by this attribute Use $RANDOM for random order | yes | |
orderReverse | true | false | Use true for reverse order | yes |
Sample request:
[{'key':'favorites', 'items':5}]
Built-in plugin "NG-Array"
Plnkr demo (view & edit)
1. Sample
You have an Angular Controller like this:
angular.module('app')
.controller('appController', ['$rootScope', '$scope', function ($rootScope, $scope) {
$rootScope.array1 = [
{name: "lisa", position: 6, parentVar:"array1"},
{name: "mona", position: 4, parentVar:"array1"},
{name: "sarah", position: 1, parentVar:"array1"},
];
$rootScope.array2 = [
{name: "johnny", position: 7, parentVar:"array2"},
{name: "moritz", position: 3, parentVar:"array2"},
{name: "johannes", position: 5, parentVar:"array2"},
];
$rootScope.object1 = {name: "fabian", position: 2, parentVar:"object1"};
}]);
Now you can load this $rootScope
Arrays and Object like this:
<div ng-controller="appController">
<aping
template-url="unstyled_template.html"
order-by="position"
aping-ng-array="[{'name':'array1'}, {'name':'array2'}, {'name':'object1'}]">
</aping>
</div>
2. Usage
Supported Sources
- Arrays
- Objects
Requests
parameter | sample | default | description | optional |
---|---|---|---|---|
name | dataArray | Array or Object in $rootScope | no | |
items | 20 | Items per request (0 -n ) | yes | |
orderBy | position | Order result by this attribute Use $RANDOM for random order | yes | |
orderReverse | true | false | Use true for reverse order | yes |
Sample requests:
[{'name':'dataArray', 'items':5}]
[{'name':'array1'}, {'name':'array2'}, {'name':'object1'}]
Updated less than a minute ago