{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"Basic Usage","type":"basic","slug":"usage","excerpt":"","body":"**The basic features makes apiNG to a high-flyer for receiving and displaying data, you regularly consume via [$http](https://docs.angularjs.org/api/ng/service/$http).**\n\napiNG 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.\n\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Table of Content\"\n}\n[/block]\n* **[Features](#features)**\n* **[Simple Setup](#simple-setup)**\n* **[Parameters](#parameters)** \n* **[Events](#events)** \n* **[Built-in plugin \"JSON-Loader\"](#built-in-plugin-json-loader)**\n* **[Built-in plugin \"XML\"](#built-in-plugin-xml)**\n* **[Built-in plugin \"Local-Storage\"](#built-in-plugin-local-storage)**\n* **[Built-in plugin \"NG-Array\"](#built-in-plugin-ng-array)**\n\n<br>\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Features\"\n}\n[/block]\n## Setup :fa-wrench:\n* **Easy to setup** via HTML data-attributes\n* Additional, you can **pre-define your default settings** in a **[config file](configuration)**, which could be overwritten by every apiNG instance\n* Store your **access tokens & api keys** in the **[credential-manager](advanced#credential-manager)**\n* **Isolated scope** - Use **more than one apiNG instance** per page.\n* You can **nestle apiNG instances**\n\n## Get & Aggregate your data :fa-download:\n* **Receive data** from any source (JSON/XML File, URL or REST API)\n* Receive data **from more than one source** and **aggregate** all the data\n* Enhance with **additional data from local storage**\n* Enhance with **additional data from your controller**\n\n## Optimize your data :fa-tasks:\n* **Limit** the received data **per request**\n* **Limit** the aggregated data **per apiNG instance**\n* **Sort** your data **by property** (asc or desc)\n* **Remove duplicates** from your aggregated data\n* **Merge duplicates** from your aggregated data\n* **Create identifiers** by combining some properties in your own way\n\n## Display your data :fa-eye:\n* apiNG delivers the **data to your angular template**\n* Use **template files** or **inline html** as template\n* **Change the template file on the fly**\n* The data is available in **`$scope.results`**, which you could access in your template with `{{results}}`\n* Inject additional **payload data** into your template, which you could access with `{{payload}}`\n\n## Work with your data :fa-exchange:\n* As needed, the data can be **available** in an **injectable and persistent angular value** [(Plnkr)](http://plnkr.co/edit/cziMAy?p=preview)\n\n<br>\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Simple Setup\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Plnkr demo (view & edit)\",\n  \"body\": \"[plnkr.co/xmflhJ](http://plnkr.co/edit/xmflhJ?p=preview)\"\n}\n[/block]\n1. [Install apiNG](installation)\n2. Add the apiNG directive to your html:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<aping aping-jsonloader=\\\"[{ 'path': 'https://randomuser.me/api/' }]\\\">\\n    <pre>{{results | json}}</pre>\\n</aping>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"`$scope.results` contains the data and is available in the template.\",\n  \"title\": \"\"\n}\n[/block]\n&nbsp;\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Parameters\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Sample\",\n    \"h-3\": \"Description\",\n    \"h-4\": \"\",\n    \"0-0\": \"**`template-url`**\",\n    \"0-1\": \"`string`\",\n    \"0-2\": \"`template.html`\",\n    \"0-3\": \"Path to template file\\nUse result data in template with `{{results}}`\",\n    \"0-4\": \"\",\n    \"1-0\": \"**`items`**\",\n    \"1-1\": \"`int`\",\n    \"1-2\": \"`20`\",\n    \"1-3\": \"Number of displayed items **per request**\",\n    \"1-4\": \"\",\n    \"2-0\": \"**`max-items`**\",\n    \"2-1\": \"`int`\",\n    \"2-2\": \"`100`\",\n    \"2-3\": \"Number of items of this **apiNG instance**<br>Use `-1` for no limitation\",\n    \"2-4\": \"\",\n    \"3-0\": \"**`order-by`**\",\n    \"3-1\": \"`string`\",\n    \"3-2\": \"`timestamp`\",\n    \"3-3\": \"Order result by this attribute<br>Use `$NONE` for no order<br>Use `$RANDOM` for random order\",\n    \"3-4\": \"yes\",\n    \"4-0\": \"**`order-reverse`**\",\n    \"4-1\": \"`boolean`\",\n    \"4-2\": \"`false`\",\n    \"4-3\": \"Use `true` for reverse order<br>Default value: `false`\",\n    \"4-4\": \"yes\",\n    \"7-0\": \"**`remove-doubles`**\",\n    \"7-1\": \"`boolean`\",\n    \"7-2\": \"`false`\",\n    \"7-3\": \"Use `true` to remove identical objects\\nor with the same ID (`id-by`).\\nGets ignored if `merge-doubles` is set.\\nDefault value: `false`\",\n    \"7-4\": \"yes\",\n    \"8-0\": \"**`payload-json`**\",\n    \"8-1\": \"`json object`\",\n    \"8-2\": \"`{'key1':'value1'}`\",\n    \"8-3\": \"Inject additional data into your template.\\nUse payload data in template with `{{payload}}`\",\n    \"8-4\": \"yes\",\n    \"9-0\": \"**`value-name`**\",\n    \"9-1\": \"`string`\",\n    \"9-2\": \"`videos`\",\n    \"9-3\": \"Inject `apingResults` into your app. [(Plnkr)](http://plnkr.co/edit/cziMAy?p=preview)\\nAccess the results with `apingResults.valueName`\",\n    \"5-0\": \"**`id-by`**\",\n    \"5-1\": \"`string` or `json array`\",\n    \"5-2\": \"`intern_id`\\n`['name','date']`\\n`['user.0','user.1']`\",\n    \"5-3\": \"Create id for each item by this properties.\\nProperty name: `aping_id`\",\n    \"6-0\": \"**`merge-doubles`**\",\n    \"6-1\": \"`boolean`\",\n    \"6-2\": \"`false`\",\n    \"6-3\": \"Use `true` to merge objects with the same ID.\\nWorks only with `id-by`\\nDefault value: `false`\",\n    \"10-0\": \"**`result-name`**\",\n    \"10-1\": \"`string`\",\n    \"10-2\": \"`events`\",\n    \"10-3\": \"Change the `result-name` to set the `$scope`\\nproperty that will contain the results.\\nDefault value: `results`\",\n    \"11-0\": \"**`protocol`**\",\n    \"11-1\": \"`string`\",\n    \"11-2\": \"`https`\",\n    \"11-3\": \"Change the `protocol` of some plugins to `https`\\nor `http`. If no value is set, the some requests will get\\nmade without any given protocol.\\nUse this parameter, if you work with Ionic, Cordova or PhoneGaph\"\n  },\n  \"cols\": 4,\n  \"rows\": 12\n}\n[/block]\n**Sample:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<aping\\n    template-url=\\\"templates/events.html\\\"\\n    items=\\\"10\\\"\\n    order-by=\\\"timestamp\\\"\\n    order-reverse=\\\"true\\\"\\n    remove-doubles=\\\"true\\\"\\n    payload-json=\\\"{'title':'All Events (Munich and Berlin)'}\\\"\\n    aping-jsonloader=\\\"[{'path':'events_munich.json'}, {'path':'events_berlin.json'}]\\\">\\n</aping>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Plnkr demo (view & edit)\",\n  \"body\": \"[plnkr.co/k3DPNc](http://plnkr.co/edit/k3DPNc?p=preview)\"\n}\n[/block]\n<br>\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Events\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Event\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"**`apiNG.resultMerged`**\",\n    \"1-0\": \"**`apiNG.templateRendered`**\",\n    \"0-1\": \"This event fires every time a plugin submits some data and apiNG merged this data with `$scope.results`\",\n    \"1-1\": \"This event fires every time the template is rendered.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n<br>\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Built-in plugin \\\"JSON-Loader\\\"\"\n}\n[/block]\n## 1. Sample\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<aping\\n    template-url=\\\"templates/events.html\\\"\\n    aping-jsonloader=\\\"[{'path':'json/events.json'}]\\\">\\n</aping>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n## 2. USAGE\n\n**Supported Sources**\n* JSON files (local)\n* JSON files (external)\n* restful JSON urls\n* restful JSONP urls (does not work with angular 1.6 or higher)\n\n\n### Requests\n|  parameter  | sample | default | description | optional |\n|----------|---------|---------|---------|---------|\n| **`path`** | `data.json` |  | **Valid values:** <br>* JSON files (local)<br>* JSON files (external)<br>* restful JSON urls | no |\n| **`format`**  | `jsonp` | `json` | Request format (`json` or `jsonp`). `jsonp` |  yes  |\n| **`xAuthToken`**  | `e42cb6a6ecc949c88` |  | Headers X-Auth-Token |  yes  |\n| **`Authorization`**  | `Bearer e42cb6a6ecc949c88` |  | Headers Authorization |  yes  |\n| **`resultProperty`** | `result_items` |  | Property name, containing the result. For deep results, use this this syntax: `data.0.results`  | yes |\n| **`items`**  | `20` | | Items per request (`0`-`n`) |  yes  |\n| **`orderBy`** | `position` |  | Order result by this attribute<br>Use `$RANDOM` for random order |  yes | \n| **`orderReverse`** | `true` | `false` | Use `true` for reverse order | yes | \n\nSample requests:\n* `[{'path':'data.json', 'items':5}]`\n* `[{'path':'//rawgit.com/JohnnyTheTank/apiNG/master/bower.json'}]`\n* `[{'path':'https://api.dailymotion.com/user/Bishop-live/videos'}]`\n* `[{'path':'http://jsonplaceholder.typicode.com/posts/1', 'format':'jsonp'}]`\n<br><br>\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Built-in plugin \\\"XML\\\"\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"[plnkr.co/MXxMni](http://plnkr.co/edit/MXxMni?p=preview)\",\n  \"title\": \"Plnkr demo (view & edit)\"\n}\n[/block]\n## 1. Sample\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<aping\\n    template-url=\\\"templates/events.html\\\"\\n    aping-xml=\\\"[{'path':'xml/events.xml'}]\\\">\\n</aping>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n## 2. USAGE\n\n**Supported Sources**\n* XML files (local)\n* XML files (external)\n\n\n### Requests\n|  parameter  | sample | default | description | optional |\n|----------|---------|---------|---------|---------|\n| **`path`** | `data.json` |  | **Valid values:** <br>* XML files (local)<br>* XML files (external)  | no |\n| **`resultProperty`** | `result_items` |  | Property name, containing the result. For deep results, use this this syntax: `data.0.results`  | yes |\n| **`items`**  | `20` | | Items per request (`0`-`n`) |  yes  |\n| **`orderBy`** | `position` |  | Order result by this attribute<br>Use `$RANDOM` for random order |  yes | \n| **`orderReverse`** | `true` | `false` | Use `true` for reverse order | yes | \n\nSample requests:\n* `[{'path':'data.xml', 'items':5}]`\n* `[{'path':'https://raw.githubusercontent.com/JohnnyTheTank/apiNG/master/demos/xml/event.xml'}]`\n<br><br>\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Built-in plugin \\\"Local Storage\\\"\"\n}\n[/block]\n## 1. Sample\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<aping\\n    template-url=\\\"templates/favorites.html\\\"\\n    aping-local-storage=\\\"[{'key':'favorites'}]\\\">\\n</aping>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n## 2. USAGE\n\n### Requests\n|  parameter  | sample | default | description | optional |\n|----------|---------|---------|---------|---------|\n| **`key`** | `favorites` |  | Local Storage key  | no |\n| **`resultProperty`** | `result_items` |  | Property name, containing the result. For deep results, use this this syntax: `data.0.favorites`  | yes |\n| **`items`**  | `20` | | Items per request (`0`-`n`) |  yes  |\n| **`orderBy`** | `position` |  | Order result by this attribute<br>Use `$RANDOM` for random order |  yes | \n| **`orderReverse`** | `true` | `false` | Use `true` for reverse order | yes | \n\nSample request:\n* `[{'key':'favorites', 'items':5}]`\n<br><br>\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Built-in plugin \\\"NG-Array\\\"\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Plnkr demo (view & edit)\",\n  \"body\": \"[plnkr.co/2GavLG](http://plnkr.co/edit/2GavLG?p=preview)\"\n}\n[/block]\n## 1. Sample\n\nYou have an Angular Controller like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"angular.module('app')\\n    .controller('appController', ['$rootScope', '$scope', function ($rootScope, $scope) {\\n        $rootScope.array1 = [\\n            {name: \\\"lisa\\\", position: 6, parentVar:\\\"array1\\\"},\\n            {name: \\\"mona\\\", position: 4, parentVar:\\\"array1\\\"},\\n            {name: \\\"sarah\\\", position: 1, parentVar:\\\"array1\\\"},\\n        ];\\n\\n        $rootScope.array2 = [\\n            {name: \\\"johnny\\\", position: 7, parentVar:\\\"array2\\\"},\\n            {name: \\\"moritz\\\", position: 3, parentVar:\\\"array2\\\"},\\n            {name: \\\"johannes\\\", position: 5, parentVar:\\\"array2\\\"},\\n        ];\\n\\n        $rootScope.object1 = {name: \\\"fabian\\\", position: 2, parentVar:\\\"object1\\\"};\\n    }]);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNow you can load this `$rootScope` Arrays and Object like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div ng-controller=\\\"appController\\\">\\n    <aping\\n        template-url=\\\"unstyled_template.html\\\"\\n        order-by=\\\"position\\\"\\n        aping-ng-array=\\\"[{'name':'array1'}, {'name':'array2'}, {'name':'object1'}]\\\">\\n    </aping>\\n</div>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n## 2. Usage\n\n**Supported Sources**\n* Arrays\n* Objects\n\n### Requests\n|  parameter  | sample | default | description | optional |\n|----------|---------|---------|---------|---------|\n| **`name`** | `dataArray` |  | Array or Object in `$rootScope` | no |\n| **`items`**  | `20` |  | Items per request (`0`-`n`) |  yes  |\n| **`orderBy`** | `position` |  | Order result by this attribute<br>Use `$RANDOM` for random order |  yes | \n| **`orderReverse`** | `true` | `false` | Use `true` for reverse order | yes | \n\nSample requests:\n* `[{'name':'dataArray', 'items':5}]`\n* `[{'name':'array1'}, {'name':'array2'}, {'name':'object1'}]`","updates":[],"order":5,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5770617ad7c6cd1900a57e79","user":"56830b4870331a0d00484a77","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Documentation","slug":"documentation","order":1,"from_sync":false,"reference":false,"_id":"57706179d7c6cd1900a57e70","version":"57706179d7c6cd1900a57e6e","__v":0,"project":"56830b883b87430d00483b3d","createdAt":"2015-12-29T22:39:05.596Z"},"createdAt":"2016-01-08T15:51:10.391Z","__v":7,"githubsync":"","project":"56830b883b87430d00483b3d","version":{"version":"1","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["57706179d7c6cd1900a57e6f","57706179d7c6cd1900a57e70","57706179d7c6cd1900a57e71","57706179d7c6cd1900a57e72","57706179d7c6cd1900a57e73","57706179d7c6cd1900a57e74"],"_id":"57706179d7c6cd1900a57e6e","project":"56830b883b87430d00483b3d","__v":1,"createdAt":"2016-06-26T23:12:57.873Z","releaseDate":"2016-06-26T23:12:57.873Z"}}