backbone.associate /README.md

Language MARKDOWN Lines 119
MD5 Hash 444bd36ba89a3f37c0c30dce09c460cf
Repository https://github.com/watsoncj/backbone.associate.git View Raw File View Project SPDX
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
Backbone.associate 
==================

Presumptionless model relations for Backbone in < 1kb.

[![Build Status](https://travis-ci.org/rjz/backbone-associate.png)](https://travis-ci.org/rjz/backbone-associate)


## Usage

Use `Backbone.associate` to define relationships between application models 
and collections.

    var Flag = Backbone.Model.Extend({ /* ... */ }),
        City = Backbone.Model.Extend({ /* ... */ }),
        Cities = Backbone.Collection.extend({ model: City }),
        Country = Backbone.Model.Extend({ /* ... */ });

    Backbone.associate(Country, {
      flag: { type: Flag },
      cities: { type: Cities, url: '/cities' }
    });

Here, we're associating a model (`Country`) with two relations: a `Flag`
model and a collection of `Cities`. The association keys can be anything,
but they should match the keys used in the data that will be passed into
the application's `parse` method.

    var canada = new Country({
      url: '/countries/canada',
      flag: { 
        colors: ['red','white'] 
      },
      cities: [
        { name: 'Calgary' },
        { name: 'Regina' }
      ]
    });

When it's time to sync the parent resource back up with the server, 
child resources can be serialized and included in the request.

    canada.toJSON(); // { flag: { colors: ['red','white'] }, ...

Since associates are *just attributes*, they may be accessed at any 
time using the usual `get`. 

    // GET /countries/canada/cities
    canada.get('cities').fetch();

For the truly lazy, `associate` provides a convenient accessor for 
each association:

    canada.flag().set({ colors: ['red','white'] });
    canada.cities().add([
      { name: 'Edmonton' },
      { name: 'Montreal' },
      { name: 'Ottawa' },
      { name: 'Vancouver' }
    ]);

That's handy for manipulating the relations, setting up eventing, or 
any of the many other things this plugin won't do for you. Speaking of
which,

## Things this plugin won't do...

...include making any but the most basic presumptions about how it will 
be used. Fortunately, all of these can be implemented as needed 
([fiddle here](http://jsfiddle.net/rjzaworski/79T94/)):

#### Identity mapping

    var getCountry = function (id) {
      _countries = {};
      return (getCountry = function (id) {
        if (!_countries[id]) {
          _countries[id] = new Country({ id : id });
        }
        return _countries[id];
      })(id);
    };

#### Child events

    canada.onCityAdded = function (model) {
      console.log('city added!', model.get('name'));
    }

    canada.listenTo(canada.cities(), 'add', canada.onCityAdded);

## Testing

Specs are implemented with `jasmine-node`. After cloning this repo, 
install dependencies and test with npm.

    $ npm install
    $ npm test

## Contributing

Have something to add? Contributions are enormously welcome!

  1. Fork this repo
  2. Update the spec and implement the change
  3. Submit a [pull request](help.github.com/pull-requests/)

## Related projects

Looking for a more fully-featured alternative? Check out:

  * [Backbone.Relational](https://github.com/PaulUithol/Backbone-relational)
  * [Supermodel](https://github.com/pathable/supermodel)

## License

Backbone.associate is released under the terms of the MIT license
Back to Top