ng2-wp-api

Angular WordPress Module

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

Table of Contents

• Live example that uses ng2-wp-api

• Features

• Requirments

• Installation

• Usage

  • WP Directives
    • Collection Directive
    • Model Directive
  • WP Service
    • Getting a Collection
    • Getting a Model
    • Add/Update/Delete Operations
    • Authentication

• Embedded Responses

• 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 Directives
• WordPress Service
• Authentication
  • Basic Authentication
  • Cookies Authentication

## Requirments

Wordpress installation.

## Installation

Install it with npm

npm install ng2-wp-api --save

## Usage

Import ShareButtonsModule in your module

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

@NgModule({
imports: [
    WordPressModule.forRoot('https://example.com')
  ]
})

## Using the directives

[wpCollection] to specify which endpoint you want to request the resources e.g. WpEndpoint.posts, WpEndpoint.pages, WpEndpoint.categories ..etc

[wpArgs] to specify the arguments of the requests e.g. { _embed: true, per_page: 4}. for more info, check WordPress Query parameters

(wpResponse) Get the result of your query, which looks like this $event {data, pagination, error}

(wpLoading) Is helpfull to display loading icon, $event: boolean

To get full control on the directive, use the `@ViewChild()

**For collection:**

<div class="feed" [wpCollection]="postsEndpoint" [wpArgs]="postsArgs" (wpResponse)="posts = $event.data">
    <ul>
      <li *ngFor="let post of posts">{{post.title.rendered}}</li>
    </ul>
</div>

See collection usage in depth Collection Gist

• Get a single post by Slug

<div class="single-post" [wpCollection]="endpoint" [wpArgs]="{slug: 'hello-world'}" (wpResponse)="single = $event.data[0]">
  <h1 [innerHtml]="single?.title?.rendered"></h1>
</div>

**For model:**

• Get a single post by ID

<div class="single-post" [wpModel]="endpoint" [wpId]="29043" (wpResponse)="single = $event.data">
  <h1 [innerHtml]="single?.title?.rendered"></h1>
</div>

## Using the service **For collection:**

A basic example of getting 6 embedded posts:

/** Posts Response */
posts;
/** Posts Endpoint */
endpoint = WpEndpoint.posts;
/** Posts Args */
args = new {
    per_page: 6,
    _embed: true
};

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

See WpService Collection gist

**For model:**

/** Post Response */
post;
/** Post Endpoint */
endpoint = WpEndpoint.posts;

this.wpService.model()
  .endpoint(endpoint)     //or posts() or pages() or users() ..etc
  .get(id)
  .subscribe((res: ModelResponse) => {
    if(res.error){
      console.log(res.error);
    }
    else{
      this.post = res.data;
    }
  });

See WpService Model gist

## 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:

  Install and activate Basic-Auth Plugin

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

• Cookies Authentication:

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

WpService Summary

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

    WpService
    ├── config 
    |    ├── baseUrl                       ** WordPress baseURL
    |    ├── debug                         ** if enabled, Logs request URL to the console 
    |
    ├── collection()
    |    ├── endpoint(ep)
    |        ├── get(args?)                ** Get Collection of endpoint type.
    |        ├── more()                    ** Get Next page collection combined with any previous ones.
    |        ├── next()                    ** Get Next page collection.
    |        ├── prev()                    ** Get Prev page collection.
    |
    ├── model()
    |    ├── endpoint(ep)
    |        ├──  get(id, args?)           ** Get Model by Id.
    |        ├──  add(body)                ** Add Model to WP.
    |        ├──  update(id, body)         ** Update Model by Id.
    |        ├──  delete(id)               ** Delete Model by Id.
    |
    ├── auth()
    |    ├── basic(username, password)     ** Basic authentication, returns loggedInUser.
    |    ├── cookies()                     ** Cookies authentication, returns loggedInUser.
    |    ├── logout()                      ** Removes authentication info from all requests.

## Embedded Responses

Usually when displaying a post, you want to display post's featured image, categories, tags, author and comments. The normal post response contains only the Id references which you will have to request each one of them individually.

Embedded responses are very useful to reduce the amount of http requets. you will get all the information you need in one response.

Embedding is triggered by setting the _embed=true in args, check Linking and Embedding

And now WpPost class will be useful to access the following properties:

post                        **  the original object
get(properyName)            **  get any property by its name
id()                        **  post id                  
title()                     **  post title
content()                   **  post content
excerpt()                   **  post excerpt without the (read more) link
date()                      **  post date
type()                      **  post type 
categories()                **  post categories array  
tags()                      **  post tags array
author()                    **  post author object (WpUser)
featuredMedia()             **  check if post has featured image
featuredImageUrl(size)      **  get featured image by size, ("full", large", "medium") or 
                                any other valid size you have in your WP

## Hints

• Use WpEndpoint to get the default endpoints and their addresses.
• WpService.collection.posts().get(...) is a equal to WpService.Collection.endpoint(WpEndpoint.posts).get(...)
• 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 for user response.
• If you struggle with specifying your query arguments, check WordPress Query parameters to get a better idea.

## 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!

## Author

Murhaf Sousli

• github/murhafsousli
• twitter/murhafsousli

## License

Changelog

3.0.0-beta1

• feat(CollectionDirective) Collection directive
• feat(ModelDirective) Model directive
• docs(Readme): docs for version 3.x
• feat(ConfigService): Use wpService.config.debug = true; to log WP requests' URLs to console.
• feat(build): Support systemjs
• refactor(gulp.js): improve build system

Breaking Changes:

• WpQueryArgs removed, use an object instead
• DirectLink removed
• Components are replaced with directives
• ConfigService:
  • requests' timeout removed
  • loading notifier removed
  • errors notifier removed