Cape.ResourceAgent - API Reference

1.2

Constructor - #_ - #adapter - #afterRefresh() - #ajax() - #basePath - #client - #collectionPath() - #create() - #data - #dataType - #defaultErrorHandler() - #destroy() - #errors - #formName - #headers - #id - #init() - #memberPath() - #object - #newPath() - #nestedIn - #paramName - #refresh() - #resourceName - #shallow - #show() - #singular - #singularPath() - #update()

Constructor

The Cape.ResourceAgent constructor takes a Cape.Component object and an optional object (options) as arguments.

Options

  • resourceName: the name of resource.
  • basePath: the string that is added to the request path. Default value is ‘/’.
  • nestedIn: the string that is inserted between path prefix and the resource name. Default value is “.
  • adapter: the name of adapter (e.g., 'rails'). Default is undefined. Default value can be changed by setting Cape.defaultAgentAdapter property.
  • autoRefresh: a boolean value that controls if a POST/PATCH/PUT/DELETE request triggers this.refresh() after its completion. Default is false.
  • dataType: the type of data that you’re expecting from the server. The value must be 'json' (default) or 'text'.
  • pathPrefix: the string that is added to the request path. Default value is '/'.
  • singular: a boolean value that specifies if the resource is singular or not. Resources are called singular when they have a URL without ID. Default is false.
  • formName: the name of form with which the users edit the properties of the resource. Default is undefiend. When the formName option is not defined, the name is derived from the resourceName property, e.g. user if the resource name is user.
  • paramName: the name of parameter to be used when the object property is initialized and the request parameter is constructed. Default is undefiend. When the paramName option is not defined, the name is derived from the resourceName property, e.g. user if the resource name is user.
  • shallow: a boolean value that controls whether the agent should omit the nestedIn string from the member path. Default is false.

Adapters

Currently, Cape.JS provides only RailsAdapter, which sets the X-CSRF-Token header for Ajax requests.

Example

Cape.defaultAgentAdapter = 'rails';

var Form = Cape.createComponentClass({
  init: function() {
    this.agent = new Cape.ResourceAgent(this, { resourceName: 'user' });
    this.agent.id = 123;
    this.agent.init();
  },

  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('login_name');
      m.onclick(e => this.agent.update()).btn('Update');
    });
  }
});

Usually, You will want to define a class inheriting Cape.ResourceAgent:

Cape.defaultAgentAdapter = 'rails';

var UserAgent = Cape.createResourceAgentClass({
  constructor: function(client, options) {
    super(client, options);
    this.resourceName = 'user';
  }
})

var Form = Cape.createComponentClass({
  init: function() {
    this.agent = new UserAgent(this);
    this.agent.id = 123;
    this.agent.init();
  },

  render: function(m) {
    m.formFor('user', function(m) {
      m.textField('login_name');
      m.onclick(e => this.agent.update()).btn('Update');
    });
  }
});

#_

This property holds the agent’s inner object, which keeps private properties and methods. Developers should not tamper with it.

#adapter

See “Options” section of the Constructor.

#afterRefresh 1.5

This method gets called by the refresh() method after it updates the data property.

The afterRefresh() does this.client.refresh() by default. Developers may override this method to let the agent do some post-processing jobs.

#ajax()

Usage

  • ajax(httpMethod, path, params)
  • ajax(httpMethod, path, params, callback)
  • ajax(httpMethod, path, params, callback, errorHandler)

Sends an Ajax request to the server.

Example

Cape.defaultAgentAdapter = 'rails';

var Page = Cape.createComponentClass({
  init: function() {
    this.agent = new Cape.ResourceAgent(this);
    this.refresh();
  },

  render: function(m) {
    m.onclick(e => {
      this.agent.ajax('POST', '/counter', {}, function(data) {
        alert(data);
      })
    });
    m.btn('Click');
  }
});

#basePath

See “Options” section of the Constructor.

#client

This property holds an instance of Cape.Component class, which has been passed as the first argument of constructor.

#collectionPath()

Returns the URL path to a collection of resources in accordance with the values of resourceName, basePath and nestedIn properties:

#resourceName #basePath #nestedIn #collectionPath()
user /users
user /api/ /api/users
user teams/123/ /teams/123/users
user /api/ teams/123/ /api/teams/123/users

Note that the default value of basePath property is /.

#create()

Usage

  • create()
  • create(callback)
  • create(callback, errorHandler)

Send an Ajax request with POST method to the URL that is constructed by the collectionPath() method.

#data

This property holds the object that is build from the JSON string returned from the server during refresh() process if the response data from the server is a valid JSON string.

Otherwise, it holds the response data from the server as is.

#dataType

This property holds the type of data that you’re expecting from the server. The value must be 'json', 'text' or undefined. When the dataType option is not defined, the type is detected automatically.

#defaultErrorHandler()

This method handles the exception thrown during the Fetch API.

The default implementation is just console.log(ex). Developers may override this for a better exception handling.

#destroy()

Usage

  • destroy()
  • destroy(callback)
  • destroy(callback, errorHandler)

Send an Ajax request with DELETE method to the URL that is constructed by the memberPath() method.

#errors

This property holds an object (key-value pairs) whose keys are the attribute names of the resource and whose values are the validation error messages.

#formName

See “Options” section of the Constructor.

#headers

This property holds the HTTP headers for Ajax requests. The default valued is { 'Content-Type': 'application/json' }.

#id

This property holds the id of resource.

#init()

Usage

  • init()
  • init(callback)
  • init(callback, errorHandler)

This method initializes the object property by sending an Ajax request to the server.

#memberPath()

Returns the URL path to a resource in accordance with the values of resourceName, basePath and nestedIn properties:

#resourceName #basePath #nestedIn #memberPath()
user /users/9
user /api/ /api/users/9
user teams/123/ /teams/123/users/9
user /api/ teams/123/ /api/teams/123/users/9

The id part of the URL path (9) derives from the id property of the agent.

Note that the default value of basePath property is '/'.

#object

This property holds an object (hash) that represents the resource which the agent is associated to.

#newPath()

Returns the URL path to a new resource in accordance with the values of resourceName, basePath and nestedIn properties:

#resourceName #basePath #nestedIn #newPath()
user /users/new
user /api/ /api/users/new
user teams/123/ /teams/123/users/new
user /api/ teams/123/ /api/teams/123/users/new

A new resource is a resource for a form for creating an resource.

Note that the default value of basePath property is '/'.

#nestedIn

See “Options” section of the Constructor.

#paramName

See “Options” section of the Constructor.

#refresh() 1.5

This method sends an Ajax request with GET method to the URL that is constructed by the #requestPath().

#requestPath()

This method returns the return value of:

  • #singularPath() if the attribute singular is set true
  • #collectionPath() if the attribute singular is set false and the attribute id is undefined
  • #memberPath() if the attribute singular is set false and the attribute id is defined

#resourceName

See “Options” section of the Constructor.

#shallow

See “Options” section of the Constructor.

#show() 1.5

Usage

  • show()
  • show(callback)
  • show(callback, errorHandler)

Send an Ajax request with POST method to the URL that is constructed by the #requestPath().

#singular

See “Options” section of the Constructor.

#singularPath()

Returns the URL path to a singular resource in accordance with the values of resourceName, basePath and nestedIn properties:

#resourceName #basePath #nestedIn #singularPath()
account /account
account /api/ /api/account
account teams/123/ /teams/123/account
account /api/ teams/123/ /api/teams/123/account

A singular resource is a resource that clients always look up without referencing an ID.

Note that the default value of basePath property is '/'.

#update()

Usage

  • update()
  • update(callback)
  • update(callback, errorHandler)

Sends an Ajax request with PATCH method to the URL that is constructed by the memberPath() method.