{"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 \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"}}