README.md 6.53 KB
Newer Older
1
# vue-github-api
2

3
A deadly simple Vue.js plugin to consume GitHub API.
4

5
Head to [the extensive JSDoc API documentation for vue-github-api](https://clorichel.gitlab.io/vue-github-api/Vue_GitHubAPI.html), or keep on reading for an easy process to integrate it in your application.
6
7
8
9
10
11

## Using it

### Install and import

```bash
12
npm install vue-github-api
13
14
15
16
17
18
19
20
21
```

In your main application JS file (typically `main.js` if you are using [vue-cli](https://github.com/vuejs/vue-cli) webpack template), simply use the plugin:

```javascript
// vue-resource is needed too
import VueResource from 'vue-resource'
Vue.use(VueResource)

22
23
24
// import vue-github-api
import GitHubAPI from 'vue-github-api'
Vue.use(GitHubAPI, { token: 'user Personal Access Token' })
25
26
27
28
```

You can configure _application wide_ options while `Vue.use`'ing this plugin:

29
30
31
| Name    | Description                                                           |
|---------|-----------------------------------------------------------------------|
| `token` | one of your GitHub user _Personal Access Token_ to connect to the API |
32

33
### Consume GitHub API
34

35
From anywhere now, you can simply consume GitHub API:
36
37

```javascript
38
Vue.GitHubAPI.get('/projects', {}, [this.myGitHubData, 'projects'])
39
40
```

41
You can also use it in your `.vue` components with `this.GitHubAPI`:
42
43

```javascript
44
this.GitHubAPI.get('/projects', {}, [this.myGitHubData, 'projects'])
45
46
```

47
That was it! Now that you are bootstrapped in, have a look at all the methods available to you in the extensive JSDoc API documentation available on [these auto-generated GitLab Pages](https://clorichel.gitlab.io/vue-github-api/Vue_GitHubAPI.html).
48

49
**Important:** if you want your filled-in property `this.myGitHubData.projects` to be reactive "the Vue.js way", you MUST define this variable as a data in your components or vues, with a default value of an empty object (read `myGitHubData: {}`). See how to do it on a vue component on this example:
50
51
52
53

```javascript
<template>
  <div>
54
    <p>Repositories grabbed: {{ repositoriesCount }}</p>
55
56
57
58
59
60
61
  </div>
</template>

<script>
export default {
  data () {
    return {
62
      myGitHubData: {}
63
64
65
    }
  },
  mounted: function () {
66
    this.GitHubAPI.get('/user/repos', {}, [this.myGitHubData, 'repositories'])
67
68
  },
  computed: {
69
70
71
    repositoriesCount: function () {
      if (this.myGitHubData.repositories) {
        return this.myGitHubData.repositories.length
72
73
74
75
76
77
78
79
80
81
      }
      return 'none yet...'
    }
  }
}
</script>
```

This is due to the fact Vue does not allow to add new reactive properties dynamically. Read more about it on the awesome [Vue.js guide](http://vuejs.org/guide/reactivity.html#Change-Detection-Caveats).

82
During your application workflow, you could want to change GitHub user authentication token. This method will let you do it easily:
83
84

```javascript
85
86
// set application wide GitHubAPI token value
this.GitHubAPI.setToken('other user Personal Access Token')
87
88
89
90
```

## Vuex store module

91
Using Vuex? You can attach _vue-github-api_ Vuex module to your application store. Within one of your `.vue` components, simply register it before you using it from your application:
92
93

```javascript
94
95
// registers GitHubAPI Vuex module to your application Vuex store
this.GitHubAPI.registerStore(this.$store)
96
97

// you are now able to read this state
98
this.$store.state.GitHubAPI.downloading
99
100
```

101
Here are Vuex `states` provided by _vue-github-api_ to your application:
102
103
104

| Vuex state    | Type    | Description                                        |
|---------------|---------|----------------------------------------------------|
105
106
| `downloading` | Boolean | Defines if vue-github-api is currently downloading |
| `running`     | Number  | Count vue-github-api requests running now          |
107
108
109
110
111
112
113
114
115
116

Have a look at [Vuex](https://github.com/vuejs/vuex) for more details, or read on this complete example:

```javascript
import Vue from 'vue'

// your application is using Vuex
import Vuex from 'vuex'
Vue.use(Vuex)

117
// remember vue-resource is needed for vue-github-api
118
119
120
import VueResource from 'vue-resource'
Vue.use(VueResource)

121
122
123
// using vue-github-api
import GitHubAPI from 'vue-github-api'
Vue.use(GitHubAPI, { token: 'user Private Token' })
124
125
126
127
128
129
130
131

// declare your Vuex store
const store = new Vuex.Store({})

// this is your application
const app = new Vue({
  el: '#app',
  mounted: {
132
133
    // register GitHubAPI Vuex store!
    this.GitHubAPI.registerStore(store)
134
135
136
  },
  computed: {
    // with this computed property, do something insanely simple such as:
137
    // <p v-if="downloading">Downloading from GitHub...</p>
138
    downloading: function () {
139
140
      if (typeof store.state.GitHubAPI !== 'undefined') {
        return store.state.GitHubAPI.downloading
141
142
143
144
145
146
147
148
149
150
151
152
      } else {
        return false
      }
    }
  }
})
```

## Contributing

Initial scaffolding was done with [vue-cli](https://github.com/vuejs/vue-cli) webpack template. For detailed explanation on how things work, checkout the [guide](http://vuejs-templates.github.io/webpack/) and [docs for vue-loader](http://vuejs.github.io/vue-loader).

153
Simply said, one can start working on its own customized version of _vue-github-api_ in no time:
154
155
156
157
158
159
160
161
162

``` bash
# install dependencies
npm install

# run unit tests
npm run unit

# build JSDoc API documentation (defaults to the ./out folder)
163
./node_modules/.bin/jsdoc src/GitHubAPI.js
164
165
166
167
168
169
170

# serve with hot reload at localhost:8080
npm run dev
```

## What's next?

171
Without any obligation nor due date, one could expect to be done this non-exhaustive [list of improvements grouped on issues labeled `Feature`](https://gitlab.com/clorichel/vue-github-api/issues?scope=all&state=opened&utf8=%E2%9C%93&label_name%5B%5D=Feature).
172
173
174
175
176

You can read on the [Changelog](CHANGELOG.md) too, for historical and upcoming new features, changes, deprecations, removed features, bug and security fixes.

## Support

177
Your are free to [open an issue](https://gitlab.com/clorichel/vue-github-api/issues/new) right in this GitLab repository whether you should be facing a problem or a bug. Please advise this is not a commercial product, so one could experience random response time. Positive, friendly and productive conversations are expected on the issues. Screenshots and steps to reproduce are highly appreciated. Chances are you may get your issue solved if you follow these simple guidelines.
178
179
180
181
182
183
184
185


## Credits

- Logo derived from a [SlideGenius](https://thenounproject.com/slidegenius/) creation [CC licensed](https://creativecommons.org/licenses/by/3.0/us/)

## License

186
The _vue-github-api_ plugin is distributed under the [MIT License (MIT)](LICENSE). Please have a look at the dependencies licenses if you plan on using, building, or distributing this plugin.