UNPKG

3.35 kBMarkdownView Raw
1wpcom.js
2========
3
4Official JavaScript library for the [WordPress.com][] [REST API][].
5Compatible with Node.js and web browsers.
6
7## How to use
8
9### Node.js
10
11Introduce the `wpcom` dependency into your `package.json` ...
12
13```cli
14npm install --save wpcom
15```
16
17... and then initialize it with your API token ( [optional ] ( #authentication ) ).
18
19
20```js
21// Edit a post on a site
22var wpcom = require( 'wpcom' )( '<your-token>' );
23
24wpcom
25 .site( 'your-blog.wordpress.com' )
26 .postsList( { number: 8 } )
27 then( list => { ... } )
28 catch( error => { ... } );
29```
30
31### Browser
32
33Include `dist/wpcom.js`.
34
35```html
36<script src="wpcom.js"></script>
37<script>
38 var wpcom = WPCOM( '<your-token>' );
39 var blog = wpcom.site( 'your-blog.wordpress.com' );
40 blog.postsList( { number: 8 } )
41 .then( list => { ... } )
42 .catch( error => { ... } );
43</script>
44```
45
46**If bundling your project with webpack**, you may need to add this to your main `webpack.config.js` file to avoid `Cannot resolve module fs` errors when bundling.
47
48```
49node: {
50 fs: 'empty'
51},
52```
53
54This instructs webpack to mock the `fs` module.
55
56### Authentication
57
58Not all requests require a REST API token. For example, listing posts on a
59public site is something anyone can do.
60
61If you do need a token, here are some links that will help you generate one:
62- [OAuth2 Authentication]( https://developer.wordpress.com/docs/oauth2/)
63 at WordPress.com Developer Resources
64- [`wpcom-oauth-cors`]( https://github.com/Automattic/wpcom-oauth-cors ):
65 a client-side WordPress.com OAuth2 library using CORS
66- [`wpcom-oauth`]( https://github.com/Automattic/node-wpcom-oauth ):
67 a server-side ( Node.js ) WordPress.com OAuth2 library
68- If you just want to quickly create a token, the
69 [example app bundled with `wpcom-oauth`]( https://github.com/Automattic/node-wpcom-oauth/tree/master/example )
70 is probably the easiest way.
71
72## API
73
74* [WPCOM](./docs/wpcom.md )
75* [WPCOM#Req](./docs/wpcom.req.md ) - Direct requests to WordPress REST-API
76* [Me](./docs/me.md )
77* [Site](./docs/site.md )
78* [Post](./docs/post.md )
79* [Media](./docs/media.md )
80* [Users](./docs/users.md )
81
82## Examples
83
84```js
85// Edit a post on a site
86var wpcom = require( 'wpcom' )( '<your-token>' );
87var blog = wpcom.site( 'your-blog.wordpress.com' );
88blog.post( { slug: 'a-post-slug' } ).update( data )
89 then( res => { ... } )
90 catch( err => { ... } );
91```
92
93You can omit the API token for operations that don't require permissions:
94
95```js
96// List the last 8 posts on a site
97var wpcom = require( 'wpcom' )();
98var blog = wpcom.site( 'your-blog.wordpress.com' );
99blog.postsList( { number: 8 } )
100 .then( list => { ... } )
101 .catch( error => { ... } );
102```
103
104More pre-made examples are in the [`examples/`](./examples/) directory.
105
106## Test
107
108The `token` and `site` vars must be given to testing scripts either using
109`TOKEN` and `SITE` environment vars respectively or through of a
110config.json file into `test/` folder like bellow:
111
112```json
113{
114 "site": "<site-id>",
115 "token": "<token>"
116}
117```
118
119Run tests:
120
121```cli
122$ make test-all
123```
124
125Also tests can be filtered using `make test <filter>`:
126
127```cli
128$ make test wpcom.site.post
129```
130
131## License
132
133MIT – Copyright 2014 Automattic
134
135[Node.js]: http://nodejs.org
136[REST API]: http://developer.wordpress.com/docs/api
137[WordPress.com]: http://www.wordpress.com
138[node-wpcom-oauth]: https://github.com/Automattic/node-wpcom-oauth