ng2now-rest-call v1.0.2

RestCall annotations for angular2-now

This package exports restConfig (function) and RestCall (annotation), which you can use together with angular2-now to easily create methods that make calls to REST/Ajax data sources.

Installation

npm i -S ng2now-rest-call

Usage

In the JavaScript (ES6) file where you first import from 'angular2-now' do this:

// Import from angular2-now
import {SetModule, Component, bootstrap, init} from 'angular2-now';

// Initialise the library
init();

// Now, you can import from ng2now
import {restConfig} from 'ng2now-rest-call';

// And then you can configure some options
restConfig({
    baseUrl: 'http://jsonplaceholder.typicode.com/',
    spinner: {
        show: function () { document.body.style.background = 'yellow'; },
        hide: function () { document.body.style.background = ''; }
    },
    events:  {
        beforeCall: () => console.log('< BEFORE call'),
        afterCall:  () => console.log('> AFTER call'),
    }
});

Note that spinner and events are optional and only shown above to demonstrate how to use them, should you want to.

Now, define some REST methods by annotating stub methods in a class, and then call them:

import {RestCall} from 'ng2now-rest-call';

class myComponent {

    constructor() {

        this.getUser(this.userid).then(data => {
            console.log('original user record:\n', data);

            // Update the user's name
            this.updateUser(1, {name: 'John Citizen'}).then(data => {
                console.log('udpated record:\n', data);
            });
        });
    }

    @RestCall('users/${user}')
    getUser() {
    }

    @RestCall('users/${user}', {method: 'PUT'})
    updateUser() {
    }

}

When the above class is instantiated, its constructor will make the calls to the getUser() and updateUser() methods.

API

restConfig( options ) - function

The options argument is an object that may contain the following attributes. These options can be overridden by using the options argument in the RestCall itself.

@RestCall( apiUrl, ?options) - decorator

Use it to annotate stub methods in your class. The stub method must follow this pattern:

class myClass {
    getUser() {}
}

Name the stub method after the function that your REST call is expected to perform. The annotation will replace the stub with an actual function that will perform the call to the rest/ajax end-point and return a promise to the data (or error) returned.

apiUrl

It is the url or the REST api that you actually want to call, such as "users/1". apiUrl may contain replaceable parameters like ${arg1}, which will be replaced with actual values that you will pass in as an argument when you call the method iek this:

 getUser(1);

Multiple replaceable parameters can exist, such as /member/${dept}/holiday/${holiday}.

@RestCall('/member/${dept}/holiday/${holiday}')
getMembersHoliday() {}

When calling the method, make sure to provide one argument per replaceable parameter.

getMembersHoliday( 'john', 2 )

If using a 'PUT' or 'POST' method, the payload is passed in last, after all the arguments.

The method definition

@RestCall('/member/${dept}/holiday/${holiday}', { method: 'PUT' })
updateMemberHoliday() {}

And here is how to call it, passing a payload as an object

updateMemberHoliday( 'john', 2, { startDate: '2016-01-01' })

options

options is optional. This argument allows you to override the global options defined with restConfig. It takes the same options argument as restConfig.

Using a custom error handler

There is a default error handler provided by this package, so, it is not necessary to provide a custom one. However, in most cases you'll want to provide your own global handler that manages errors the way you need to and displays messages in the way you find aesthetically pleasing.

To that end, the errorHandler property of the options argument to @RestCall allows us to specify a custom global error handler, which will replace the default one provided with this package. errorHandler can be either a function or the name of a service.

When an $http error occurs, your error handler will be called with one argument injected, which contains the following properties: