From 43819894db786b1d2a38a002a5c31f3d0fef4f14 Mon Sep 17 00:00:00 2001 From: Jonathan Hornung Date: Sat, 2 Jan 2016 02:34:28 +0100 Subject: [PATCH] docs: wrote user docs (close #1 & close #2) --- README.md | 134 ++++++++++++++++++++++++++++++-- bower.json | 2 +- demo/aping-config.js | 3 +- dist/aping-plugin-github.min.js | 2 +- package.json | 2 +- 5 files changed, 131 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 5824fe7..e290e2e 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,129 @@ -# apiNG-plugin-github -GitHub Plugin for [apiNG](https://github.com/JohnnyTheTank/apiNG) +[logo]: http://aping.io/logo/320/aping-plugin.png "apiNG Plugin" +![apiNG][logo] -## Promise Library -used promise library: [angular-github-api-factory](https://github.com/JohnnyTheTank/angular-github-api-factory) +**_apiNG-plugin-github_** is a [GitHub Data API v3](https://developer.github.com/v3/) plugin for [**apiNG**](https://github.com/JohnnyTheTank/apiNG). -## supported apiNG models -- **`repo`** +# Information +* **Supported apiNG models: `repo`** +* Used promise library: [angular-github-api-factory](https://github.com/JohnnyTheTank/angular-github-api-factory) _(included in minified distribution file)_ + +# Documentation + I. INSTALLATION + II. API KEY + III. USAGE + +## I. INSTALLATION + a) Get files + b) Include files + c) Add dependencies + d) Add the plugin + +### a) Get files +You can choose your preferred method of installation: + +* Via bower: `bower install apiNG-plugin-github --save` +* Download from github: [apiNG-plugin-github.zip](https://github.com/JohnnyTheTank/apiNG-plugin-github/zipball/master) + +### b) Include files +Include `apiNG-plugin-github.min.js` in your apiNG application +```html + +``` + +### c) Add dependencies +Add the module `jtt_aping_github` as a dependency to your app module: +```js +var app = angular.module('app', ['jtt_aping', 'jtt_aping_github']); +``` + +### d) Add the plugin +Add the plugin's directive `aping-github="[]"` to your apiNG directive and configure your requests (_**III. USAGE**_) +```html + + +``` + +## II. API KEY + a) Generate your `access_token` + b) Insert your `access_token` into `aping-config.js` + +### a) Generate your `access_token` +1. Login on [github.com](https://github.com) +2. Open [github.com/settings/tokens/new](https://github.com/settings/tokens/new) + * Remove all scopes except **public_repo** + * Generate your access_token + +### b) Insert your `access_token` into `aping-config.js` +Open `js/apiNG/aping-config.js` in your application folder. It should be look like this snippet: +```js +apingApp.config(['$provide', function ($provide) { + $provide.constant("apingApiKeys", { + //... + github: [ + {'access_token':''} + ], + //... + }); + + $provide.constant("apingDefaultSettings", { + //... + }); +}]); +``` + +:warning: Replace `` with your github `access_token` + +## III. USAGE + a) Models + b) Requests + c) Rate limit + +### a) Models +Supported apiNG models + +| model | content | support | max items
per request | (native) default items
per request | +|----------|---------|---------|--------|---------| +| `rep` | **repositories** | full | `100` | `30` | + +**support:** +* full: _the source platform provides a full list with usable results_
+* partly: _the source platfrom provides just partly usable results_ + + +### b) Requests +Every **apiNG plugin** expects an array of **requests** as html attribute. + + +#### Requests by User +| parameter | sample | default | description | optional | +|----------|---------|---------|---------|---------| +| **`user`** | `JohnnyTheTank` | | GitHub username | no | +| **`repo`** | `apiNG` | | Limits the request to specific GitHub repository name | yes | +| **`items`** | `75` | `30` | Items per request (`0`-`100`) | yes | + +Sample requests: +* `[{'user':'JohnnyTheTank'}, {'user':'xremix'}]` +* `[{'user':'JohnnyTheTank', 'repo':'apiNG', 'items':10}]` + +#### Requests by Search +| parameter | sample | default | description | optional | +|----------|---------|---------|---------|---------| +| **`search`** | `bootstrap` | | The search keywords, as well as any qualifierse | no | +| **`sort`** | `stars` | | The sort field. One of `stars`, `forks`, or `updated`. Default: results are sorted by best match | yes | +| **`order`** | `asc` | `desc` | The sort order if `sort` parameter is provided. One of `asc` or `desc` | yes | +| **`items`** | `75` | `30` | Items per request (`0`-`100`) | yes | + +Sample requests: +* `[{'search':'apiNG', 'sort':'stars', 'order':'desc', 'items':50}]` + +### c) Rate limit +Visit the official [GitHub Data API documentation](https://developer.github.com/v3/#rate-limiting) +> For requests using Basic Authentication or OAuth, you can make up to 5,000 requests per hour. + +# Licence +MIT -## usage -full documentation coming soon ... \ No newline at end of file diff --git a/bower.json b/bower.json index 4c16bf1..0ae35a1 100644 --- a/bower.json +++ b/bower.json @@ -4,7 +4,7 @@ "authors": [ "Jonathan Hornung " ], - "version": "0.1.3", + "version": "0.6.0", "description": "github plugin for apiNG", "main": "dist/apiNG-plugin-github.min.js", "moduleType": [], diff --git a/demo/aping-config.js b/demo/aping-config.js index fefa09d..d9b2279 100644 --- a/demo/aping-config.js +++ b/demo/aping-config.js @@ -2,7 +2,8 @@ apingApp.config(['$provide', function ($provide) { $provide.constant("apingApiKeys", { - 'github': [{'access_token':''}] + //'github': [{'access_token':''}] + 'github': [{'access_token':'3c15edcd2d60a2cfb2c31922ecd88091d46995f0'}] }); $provide.constant("apingDefaultSettings", { diff --git a/dist/aping-plugin-github.min.js b/dist/aping-plugin-github.min.js index 85c9ea3..dd33c33 100644 --- a/dist/aping-plugin-github.min.js +++ b/dist/aping-plugin-github.min.js @@ -1,3 +1,3 @@ -/*! aping-plugin-github v0.1.3 (21-12-2015) by Jonathan Hornung */ +/*! aping-plugin-github v0.6.0 (02-01-2016) by Jonathan Hornung */ "use strict";var jjtApingGithub=angular.module("jtt_aping_github",["jtt_github"]).directive("apingGithub",["apingGithubHelper","apingUtilityHelper","githubFactory",function(a,b,c){return{require:"?aping",restrict:"A",replace:"false",link:function(d,e,f,g){var h=g.getAppSettings(),i=b.parseJsonFromAttributes(f.apingGithub,a.getThisPlattformString(),h);i.forEach(function(d){var e={model:h.model};"undefined"!=typeof h.getNativeData?e.getNativeData=h.getNativeData:e.getNativeData=!1;var f={access_token:b.getApiCredentials(a.getThisPlattformString(),"access_token")};if("undefined"!=typeof d.items?f.per_page=d.items:f.per_page=h.items,0==f.per_page)return!1;if((f.per_page<0||isNaN(f.per_page))&&(f.per_page=void 0),f.per_page>100&&(f.per_page=100),d.user)switch(f.user=d.user,h.model){case"repo":d.repo?(f.repo=d.repo,c.getRepoByUserAndName(f).success(function(b){g.concatToResults(a.getObjectByJsonData(b,e))}).error(function(a){})):c.getReposByUser(f).success(function(b){g.concatToResults(a.getObjectByJsonData(b,e))}).error(function(a){});break;case"activity":c.getEventsByUser(f).success(function(b){g.concatToResults(a.getObjectByJsonData(b,e))}).error(function(a){})}else if(d.search)switch(f.q=d.search,"undefined"!=typeof d.sort&&(f.sort=d.sort),"undefined"!=typeof d.order&&(f.order=d.order),h.model){case"repo":c.getReposByName(f).success(function(b){g.concatToResults(a.getObjectByJsonData(b,e))}).error(function(a){})}})}}}]);jjtApingGithub.service("apingGithubHelper",["apingModels","apingTimeHelper","apingUtilityHelper",function(a,b,c){this.getThisPlattformString=function(){return"github"},this.getThisPlattformLink=function(){return"https://github.com/"},this.getObjectByJsonData=function(a,b){var c=[];if(a){var d=this;if(a.constructor===Array)angular.forEach(a,function(a,e){var f;f=b.getNativeData===!0||"true"===b.getNativeData?a:d.getItemByJsonData(a,b.model),f&&c.push(f)});else{if(a.items)angular.forEach(a.items,function(a,e){var f;f=b.getNativeData===!0||"true"===b.getNativeData?a:d.getItemByJsonData(a,b.model),f&&c.push(f)});else{var e;e=b.getNativeData===!0||"true"===b.getNativeData?a:d.getItemByJsonData(a,b.model),e&&c.push(e)}}}return c},this.getItemByJsonData=function(a,b){var c={};if(a&&b)switch(b){case"repo":c=this.getRepoItemByJsonData(a);break;default:return!1}return c},this.getRepoItemByJsonData=function(c){var d=a.getNew("repo",this.getThisPlattformString());return $.extend(!0,d,{owner_name:c.owner?c.owner.login:void 0,owner_id:c.owner?c.owner.id:void 0,owner_link:c.owner?c.owner.html_url:void 0,owner_img_url:c.owner?c.owner.avatar_url:void 0,name:c.name,id:c.id,fullname:c.full_name,description:c.description||void 0,url:c.html_url,homepage:c.homepage||void 0,language:c.language||void 0,clone_url:c.clone_url,git_url:c.git_url,ssh_url:c.ssh_url,svn_url:c.svn_url,isFork:c.fork,openIssues:c.open_issues_count,watchers:c.watchers_count,stargazers:c.stargazers_count,forks:c.forks_count,created_timestamp:b.getTimestampFromDateString(c.created_at,1e3,36e5),created_date_time:new Date(c.created_at),updated_timestamp:c.updated_at?b.getTimestampFromDateString(c.updated_at,1e3,36e5):void 0,updated_date_time:c.updated_at?new Date(c.updated_at):void 0,pushed_timestamp:c.pushed_at?b.getTimestampFromDateString(c.pushed_at,1e3,36e5):void 0,pushed_date_time:c.pushed_at?new Date(c.pushed_at):void 0}),d}}]),angular.module("jtt_github",[]).factory("githubFactory",["$http","githubSearchDataService",function(a,b){var c={};return c.getUser=function(c){var d=b.getNew("user",c);return a({method:"GET",url:d.url,params:d.object})},c.getReposByUser=function(c){var d=b.getNew("reposByUser",c);return a({method:"GET",url:d.url,params:d.object})},c.getReposByName=function(c){var d=b.getNew("reposByName",c);return a({method:"GET",url:d.url,params:d.object})},c.getRepoByUserAndName=function(c){var d=b.getNew("repoByUserAndName",c);return a({method:"GET",url:d.url,params:d.object})},c.getEventsByUser=function(c){var d=b.getNew("eventsByUser",c);return a({method:"GET",url:d.url,params:d.object})},c.getEventsFromRepoByUserAndName=function(c){var d=b.getNew("eventsFromRepoByUserAndName",c);return a({method:"GET",url:d.url,params:d.object})},c}]).service("githubSearchDataService",function(){this.getApiBaseUrl=function(a){return"https://api.github.com/"},this.fillDataInObjectByList=function(a,b,c){return angular.forEach(c,function(c,d){"undefined"!=typeof b[c]&&(a.object[c]=b[c])}),a},this.getNew=function(a,b){var c={object:{access_token:b.access_token},url:""};switch("undefined"!=typeof b.per_page&&(c.object.per_page=b.per_page),a){case"user":c.object.per_page=void 0,c=this.fillDataInObjectByList(c,b,[]),c.url=this.getApiBaseUrl()+"users/"+b.user;break;case"reposByUser":c=this.fillDataInObjectByList(c,b,["q","sort","order","page"]),c.url=this.getApiBaseUrl()+"users/"+b.user+"/repos";break;case"reposByName":c=this.fillDataInObjectByList(c,b,["sort","order","page"]),c.url=this.getApiBaseUrl()+"search/repositories?q="+b.q;break;case"repoByUserAndName":c.object={access_token:b.access_token},c=this.fillDataInObjectByList(c,b,[]),c.url=this.getApiBaseUrl()+"repos/"+b.user+"/"+b.repo;break;case"eventsByUser":c=this.fillDataInObjectByList(c,b,["q","sort","order","page"]),c.url=this.getApiBaseUrl()+"users/"+b.user+"/events";break;case"eventsFromRepoByUserAndName":c=this.fillDataInObjectByList(c,b,["q","sort","order","page"]),c.url=this.getApiBaseUrl()+"repos/"+b.user+"/"+b.repo+"/events"}return c}}); \ No newline at end of file diff --git a/package.json b/package.json index aeecf5e..f435067 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "aping-plugin-github", - "version": "0.1.3", + "version": "0.6.0", "description": "github plugin for apiNG", "main": "Gruntfile.js", "scripts": {