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

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)

plnkr.co/xmflhJ

  1. Install apiNG
  2. 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

AttributeTypeSampleDescription
template-urlstringtemplate.htmlPath to template file
Use result data in template with {{results}}
itemsint20Number of displayed items per request
max-itemsint100Number of items of this apiNG instance
Use -1 for no limitation
order-bystringtimestampOrder result by this attribute
Use $NONE for no order
Use $RANDOM for random order
order-reversebooleanfalseUse true for reverse order
Default value: false
id-bystring or json arrayintern_id
['name','date']
['user.0','user.1']
Create id for each item by this properties.
Property name: aping_id
merge-doublesbooleanfalseUse true to merge objects with the same ID.
Works only with id-by
Default value: false
remove-doublesbooleanfalseUse true to remove identical objects
or with the same ID (id-by).
Gets ignored if merge-doubles is set.
Default value: false
payload-jsonjson object{'key1':'value1'}Inject additional data into your template.
Use payload data in template with {{payload}}
value-namestringvideosInject apingResults into your app. (Plnkr)
Access the results with apingResults.valueName
result-namestringeventsChange the result-name to set the $scope
property that will contain the results.
Default value: results
protocolstringhttpsChange the protocol of some plugins to https
or http. If no value is set, the some requests will get
made 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)

plnkr.co/k3DPNc


Events

EventDescription
apiNG.resultMergedThis event fires every time a plugin submits some data and apiNG merged this data with $scope.results
apiNG.templateRenderedThis 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

parametersampledefaultdescriptionoptional
pathdata.jsonValid values:
JSON files (local)
JSON files (external)
* restful JSON urls
no
formatjsonpjsonRequest format (json or jsonp). jsonpyes
xAuthTokene42cb6a6ecc949c88Headers X-Auth-Tokenyes
AuthorizationBearer e42cb6a6ecc949c88Headers Authorizationyes
resultPropertyresult_itemsProperty name, containing the result. For deep results, use this this syntax: data.0.resultsyes
items20Items per request (0-n)yes
orderByposition Order result by this attribute
Use $RANDOM for random order
yes
orderReversetrue falseUse true for reverse orderyes

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)

plnkr.co/MXxMni

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

parametersampledefaultdescriptionoptional
pathdata.jsonValid values:
XML files (local)
XML files (external)
no
resultPropertyresult_itemsProperty name, containing the result. For deep results, use this this syntax: data.0.resultsyes
items20Items per request (0-n)yes
orderByposition Order result by this attribute
Use $RANDOM for random order
yes
orderReversetrue falseUse true for reverse orderyes

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

parametersampledefaultdescriptionoptional
keyfavoritesLocal Storage keyno
resultPropertyresult_itemsProperty name, containing the result. For deep results, use this this syntax: data.0.favoritesyes
items20Items per request (0-n)yes
orderByposition Order result by this attribute
Use $RANDOM for random order
yes
orderReversetrue falseUse true for reverse orderyes

Sample request:

  • [{'key':'favorites', 'items':5}]


Built-in plugin "NG-Array"

👍

Plnkr demo (view & edit)

plnkr.co/2GavLG

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

parametersampledefaultdescriptionoptional
namedataArrayArray or Object in $rootScopeno
items20Items per request (0-n)yes
orderByposition Order result by this attribute
Use $RANDOM for random order
yes
orderReversetrue falseUse true for reverse orderyes

Sample requests:

  • [{'name':'dataArray', 'items':5}]
  • [{'name':'array1'}, {'name':'array2'}, {'name':'object1'}]