ng2-wp-api

Angular2 WordPress API Service

This library is designed to make it easy for your Angular2 application to request specific resources from a WordPress install.

Requirments

Wordpress installation and WP API v2 plugin activated.

Installation

Install it with npm

npm install ng2-wp-api --save

Table of Contents

• Features
• Abstract
• Usage
  • Initialization
  • Services
    • Getting Collections
    • Getting Models
    • Direct Link
    • Add/Update/Delete Operations
  • Components
    • Collection Component
    • Model Component
• Authentication
• Hints
• Issues
• Author
• License

## Features

This library is very flexible and easy to use, you will find everything you need included out of the box:

• WordPress Service
• WordPress Components (an alternative to the service)
• Direct link
• Async http calls, runs in the background (no UI blocking)
• Useful classes to access several models and their properties
• Timeout for Http requests
• Error Notifier
• Loading Notifier
• Discovery
• Authentication
  • Basic Authentication
  • Cookie Authentication

## Abstract

Services:

• WpService One service for all operations (Access/Authenticate/Configure).

---

Components:

• <wp-collection> Inputs: args, endpoint - Output: collection response.
• <wp-model> Inputs: id, args, endpoint - Output: model response.

---

Helper Classes:

• WpPost Useful class for posts and pages (contains functions for accessing embedded posts).
• WpUser Interface for user response.
• WpQueryArgs Class for creating query arguments for collection/model.
• WpEndpoint List of default endpoints and their addresses.

---

Default Endpoints are : posts, pages, users, categories, tags, taxonomies, statuses, comments, media

    WpService
    ├── config 
    |    ├── baseUrl: string
    |    ├── timeOut: number
    |    ├── errors: Observable
    |    ├── loading: Observable
    |
    ├── discover(url): Observable
    ├── link(url): Observable
    ├── collection()
    |    ├── endpoint(ep)
    |        ├── get(args?): Observable
    |        ├── more(): Observable
    ├── model()
    |    ├── endpoint($ep)
    |        ├──  get(id, args?): Observable
    |        ├──  add(body): Observable
    |        ├──  update(id, body): Observable
    |        ├──  delete(id): Observable
    ├── auth()
    |    ├── basic(username, password): Observable
    |    ├── cookies(): Observable
    |    ├── logout()

## Usage

Add WordPressModule to NgModule imports array.

import { WordPressModule } from 'ng2-wp-api';

@NgModule({
imports: [
    WordPressModule
  ]
})

### Initialization

Set your WordPress base url in the root component

constructor(wpService: WpService){
}

ngOnInit(){
   wpService.config.baseUrl = "http://localhost/wordpress";
   
   /** Optional */
   //catch loading state (useful for spinner)
   wpService.config.loading.subscribe(...);
   //catch any errors occurs in all requests
   wpService.config.errors.subscribe(...); 
}

See [Initializing example](/examples/Initilizing WP Service.ts).

After initializing, you can either consume the library as a service, or as a component.

---

## Using the service

Import WpService in component constructor Import WpEndpoint to get the desired endpoint address

import {WpService} from "ng2-wp-api";

@Component({...})
export class testComponent {
    constructor(private wpService: WpService) {

    }
}

**For collection:**

A basic example of fetching 6 embedded posts:

import {WpService,WpEndpoint,WpQueryArgs,CollectionResponse} from "ng2-wp-api";
.
.
var endpoint = WpEndpoint.posts;

var args = new WpQueryArgs({
    perPage: 6,
    embed: true
});

this.wpService.collection()
  .endpoint(endpoint)       //or posts()
  .get(args)
  .subscribe((res: CollectionResponse) => {
      this.data = res.data;
      this.pagination = res.pagination;
  });

See [WpService Collection example](/examples/Collection using the service.ts)

**For model:**

var endpoint = WpEndpoint.posts;

this.wpService.model()
    .endpoint(endpoint)     //or posts() or pages() or users() ..etc
    .get(id)
    .subscribe((res) => {
        this.data = res;
    });

See [WpService Model example](/examples/Model using the service.ts)

---

## Using the components **For collection:**

<wp-collection [args]="args" [endpoint]="endpoint" (response)="wpResponse($event)">
<!-- Your Template Goes Here -->
</wp-collection>

WpCollection component gets a new response automatically when the input [args] value has set/changed.

See [Collection Component example](/examples/Collection using the component.ts)

NOTE: Make sure enableProdMode() is called to avoid onChanges error.

**For model:**

<wp-model [id]="id" [endpoint]="endpoint" (response)="wpResponse($event)">
<!-- Your Template Goes Here -->
<wp-model>

WpModel component gets a new response automatically when the input [id] value has set/changed.

See [Model Component example](/examples/Model using the component.ts)

---

## Add/Update/Delete

//add new post
wpService.model().posts().add(body);

//update page by id
wpService.model().pages().update(pageId, body);

//delete user by id
wpService.model().users().delete(userId);

## Authentication

• Basic Authentication:

 this.wpService.auth().basic('username', 'password').subscribe(
  (loggedInUser: WpUser)=> {
    console.log(loggedInUser);
  });

• Cookies Authentication:

 this.wpService.auth().cookies().subscribe(
  (loggedInUser: WpUser)=> {
    console.log(loggedInUser);
  });

Direct Link

If you want to do a GET request for any URL, Use WpService.link(url).subscribe(...) to get the advantage of error and loading notifiers.

## Issues

If you identify any errors in the library, or have an idea for an improvement, please open an issue. I am excited to see what the community thinks of this project, and I would love your input!

## Hints

• Use WpEndpoint to get the default endpoints and their addresses.
• WpService.collection.posts().get(...) is a shortcut of WpService.Collection.endpoint(WpEndpoint.posts)
• Use WpQueryArgs class to specify your request argument.
• Use WpPost class when the response is embedded, it has useful functions for accessing embedded posts.
• WpPost class works for posts, pages and custom post types.
• Use WpUser interface if the response is user.
• If you struggle with specifying your query arguments, check WordPress Query parameters to get a better idea.

## Author

Murhaf Sousli

• github/murhafsousli
• twitter/murhafsousli

## License

Changelog

2.1.0

Use WpService.config instead of WpConfig to keep all usages in one service.

###Bugs:

• Basic Authentication: Fixes request and return observable instead of void

  WpService.auth().basic(username,password).subscribe(...)

Features:

• WpService.Collection(): Added next() and prev() functions

  • collectionService = wpService.collection().posts().get.subscribe(...) Get collection
  • collectionService.more().subscrube(...) Combine current page with next page collection
  • collectionService.next().subscrube(...) Get next page collection
  • collectionService.prev().subscrube(...) Get prev page collection

• WpCollectionComponent: Added next() and prev() functions

• Discovery endpoint: Discover if a url has WP API install. WpService.discover(url).subscribe(...)

• Cookies Authentication: WpService.auth().cookies().subscribe(...)

Breaking Changes:

All helper classes has been prefixed with Wp

• Post is now WpPost
• User is now WpUser
• QueryArgs is now WpQueryArgs
• WpHelper.endpoint is now WpEndpoint
• WpHelper is deprecated.
• authentication notifier is deprecated from WpConfig.