❤
npm
Sign UpSign In

backbone-relational-hal

0.1.3 • Public • Published

backbone-relational-hal

Consume HAL+JSON APIs with Backbone.js and Backbone-relational.js.

NPM version Build Status

Requirements

backbone-relational-hal is currently tested with the following libraries:

Installation

With bower:

bower install --save backbone-relational-hal

Builds:

Usage

This library adds a new Backbone.RelationalHalResource class that you can extend like Backbone.RelationalModel or Backbone.Model.

var Person = Backbone.RelationalHalResource.extend({
  url: '/people/2'
});

HAL Links

HAL Embedded Resources

Hyperlinks

HAL resources can parse HAL+JSON links out of the box.

Let's instantiate the above sample class and fetch data from the server.

var person = new Person();
person.fetch();

Assume the server would return this data containing several links.

{
  "_links": {
    "self": { "href": '/people/2' },
    "search": { "href": '/people/2/search{?email}', "templated": true },
    "alternate": [
      { "href": '/people/2.html', "type": 'text/html' },
      { "href": '/people/2.xml', "type": 'application/xml' }
    ]
  },
  "name": "Nobody"
}

Use the link method of a HAL resource to retrieve useful link objects.

// get a link object
person.link('self'); // => a Backbone.RelationalModel
 
// get the href of a link
person.link('self').href(); // => '/people/2'
 
// get a list of links
var alternates = person.link('alternate', { all: true }); // => Backbone.Collection of link objects
 
// get one of the links in the list
alternates.at(0).href(); // => '/people/2.html'
 
// find a link matching criteria
// (using Backbone's Underscore proxy methods)
alternates.findWhere({ type: 'application/xml' }).href(); // => '/people/2.xml'

URI Templates

Templated links can be expanded using the uri-templates library.

// get a templated link without parameters
person.link('search').href(); // => '/people/2/search'
 
// expand a link template with parameters
person.link('search').href({ template: { email: 'foo@example.com' } }); // => '/people/2/search?email=foo@example.com'

Generating <a> Tags from Links

The tag method of link objects can generate HTML link tags for you.

// simple tag with text content
person.link('self').tag('John'); // => $('<a href="/people/2">John</a>')
 
// HTML content
var content = $('<strong />').text('Jane');
person.link('self').tag(content, { html: true }); // => $('<a href="/people/2"><strong>Jane</strong></a>')

Embedding Resources

Define embedded resources with the halEmbedded property when extending a HAL resource. Embedded resources are Backbone-relational.js relations and use the same options.

var Company = Backbone.RelationalHalResource.extend({
 
  halEmbedded: [
    {
      type: Backbone.HasOne,
      key: 'http://example.com/rel/manager',
      relatedModel: Person
    },
    {
      type: Backbone.HasMany,
      key: 'http://example.com/rel/employees',
      relatedModel: Person
    }
  ]
});

You can also use an equivalent HAL-like syntax where the key in the halEmbedded object is automatically used as the relation key.

var Company = Backbone.RelationalHalResource.extend({
 
  halEmbedded: {
    'http://example.com/rel/manager': {
      type: Backbone.HasOne,
      relatedModel: Person
    },
    'http://example.com/rel/employees': {
      type: Backbone.HasMany,
      relatedModel: Person
    }
  }
});

Assume the server would return this data for a company.

{
  "name": "Initech",
  "_embedded": {
    "http://example.com/rel/manager": {
      "name": "Bill Lumbergh"
    },
    "http://example.com/rel/employees": [
      {
        "name": "Peter Gibbons"
      },
      {
        "name": "Michael Bolton"
      },
      {
        "name": "Samir Nagheenanajar"
      }
    ]
  }
}

You can retrieve embedded resources with the embedded method.

// get an embedded resource
company.embedded('http://example.com/rel/manager'); // => Person
company.embedded('http://example.com/rel/manager').get('name'); // => 'Bill Lumbergh'
 
// get a Backbone.Collection of embedded resources
var employees = company.embedded('http://example.com/rel/employees'); // => Backbone.Collection
 
// get one of the resources in the collection
employees.at(0); // => Person
employees.at(0).get('name'); // => 'Peter Gibbons'

Meta

  • Author: Simon Oulevay (Alpha Hydrae)
  • License: MIT (see LICENSE.txt)

Readme

Keywords

Package Sidebar

Install

npm i backbone-relational-hal

Repository

github.com/AlphaHydrae/backbone-relational-hal

Homepage

github.com/AlphaHydrae/backbone-relational-hal

Weekly Downloads

0

Version

0.1.3

License

MIT

Last publish

Collaborators

  • alphahydrae
Try on RunKit
Report malware