|
| 1 | +# Parse for AngularJS |
| 2 | + |
| 3 | +_This is pre-alpha/actively developed. There are no guarantees of |
| 4 | + stability, but you are welcome to play around and submit issues_ |
| 5 | + |
| 6 | +angular-parse is an [AngularJS](http://angularjs.org) module for |
| 7 | +interacting with the [Parse](http://parse.com) [REST |
| 8 | +API](https://parse.com/docs/rest). It *does not* utlize the [Parse |
| 9 | +JavaScript API](https://parse.com/docs/js_guide) but instead is built |
| 10 | +from (mostly) scratch. The reason is the existing Parse JavaScript API |
| 11 | +is not ideal for AngularJS applications. |
| 12 | + |
| 13 | +# Why Angular-Parse |
| 14 | + |
| 15 | +There are a few things that are not ideal about the existing Parse |
| 16 | +JavaScript API in AngularJS. The existing API is modeled after [Backbone |
| 17 | +Models](http://backbonejs.org/#Model) and the main problem is setters |
| 18 | +are used instead of object properties. `instance.set('property', 'value')` |
| 19 | +doesn't really fit well with things like `ng-model` |
| 20 | + |
| 21 | +Instead, angular-parse is based loosely on [Spine |
| 22 | +Models](http://spinejs.com/docs/models) where properties directly |
| 23 | +defined on the object are used. To facilitate this, when defining a |
| 24 | +model, it is "configured" by supplying the class name (as defined in |
| 25 | +Parse) as well as which properties are part of that class. |
| 26 | + |
| 27 | +Angular-parse also uses promises for any methods making network calls. |
| 28 | + |
| 29 | +## Getting started |
| 30 | + |
| 31 | +Include the JavaScript file |
| 32 | + |
| 33 | +```html |
| 34 | +<!-- Include AngularJS --> |
| 35 | +<script src="path/to/angular-parse.js"></script> |
| 36 | +``` |
| 37 | + |
| 38 | +Make sure to add `"Parse"` as a dependency of your main module |
| 39 | + |
| 40 | +```javascript |
| 41 | +var app = angular.module("YourApp", ["Parse"]) |
| 42 | +``` |
| 43 | + |
| 44 | +Angular-parse also requires you provide the value "ParseConfig" as an |
| 45 | +object with the following format |
| 46 | + |
| 47 | +```javascript |
| 48 | +app.value("ParseConfig", { |
| 49 | + applicationId: "YOUR PARSE APPLICATION ID", |
| 50 | + apiKey: "YOUR PARSE REST API KEY" |
| 51 | +}) |
| 52 | +``` |
| 53 | + |
| 54 | +## Defining Models |
| 55 | + |
| 56 | +You can define models by extending Parse.Model. You must call configure |
| 57 | +on the class and pass it the Parse class name, and the name of any |
| 58 | +attributes of that class |
| 59 | + |
| 60 | +Using CoffeeScript: |
| 61 | +```coffeescript |
| 62 | +app.factory 'Car', (Parse) -> |
| 63 | + class Car extends Parse.model |
| 64 | + @configure "Car", "make", "model", "year" |
| 65 | + |
| 66 | + @customClassMethod: (arg) -> |
| 67 | + # add custom class methods like this |
| 68 | + |
| 69 | + customInstanceMethod: (arg) -> |
| 70 | + # add custom instance methods like this |
| 71 | +``` |
| 72 | + |
| 73 | +Using JavaScript: |
| 74 | +```javascript |
| 75 | +// Not implemented yet, sorry |
| 76 | +``` |
| 77 | + |
| 78 | + |
| 79 | +## Using Models |
| 80 | + |
| 81 | +A model acts much the same as a normal JavaScript object with a |
| 82 | +constructor |
| 83 | + |
| 84 | +### Creating a new instance |
| 85 | + |
| 86 | +You can create a new instance by using `new`. Any attributes passed in |
| 87 | +will be set on the instance. This does not save it to parse, that must |
| 88 | +be done with `.save()`. The save method returns a promise, which is |
| 89 | +fulfilled with the instance itself. |
| 90 | + |
| 91 | +```javascript |
| 92 | +var car = new Car({ |
| 93 | + make: "Scion", |
| 94 | + model: "xB", |
| 95 | + year: 2008 |
| 96 | +}); |
| 97 | + |
| 98 | +car.isNew() === true; |
| 99 | +car.objectId == null; |
| 100 | + |
| 101 | +car.save().then(function (_car) { |
| 102 | + _car === car; |
| 103 | + car.isNew() === false; |
| 104 | + car.objectId === "...aParseId"; |
| 105 | + car.createdAt === "...aDateString"; |
| 106 | + car.updatedAt === "...aDateString"; |
| 107 | +} |
| 108 | +``` |
| 109 | +
|
| 110 | +If the object has an objectId, it will be updated properly, and will not |
| 111 | +create a new instance. `save()` can be used either for new or existing |
| 112 | +records. |
| 113 | +
|
| 114 | +### Getting an instance By Id |
| 115 | +
|
| 116 | +The `find` method on your model class takes an objectId, and returns a |
| 117 | +promise that will be fulfilled with your instance if it exists. |
| 118 | +
|
| 119 | +
|
| 120 | +```javascript |
| 121 | +Car.find("someObjectId").then(function (car) { |
| 122 | + car.objectId === "someObjectId"; |
| 123 | +}) |
| 124 | +``` |
| 125 | +
|
| 126 | +### Destroying an instance |
| 127 | +
|
| 128 | +The destroy method on an instance will destroy it set destroyed to true |
| 129 | + and set the item's objectId to null |
| 130 | +
|
| 131 | +```javascript |
| 132 | +Car.find("someObjectId").then(function (car) { |
| 133 | + car.objectId === "someObjectId"; |
| 134 | + |
| 135 | + car.destroy().then(function (_car) { |
| 136 | + car === _car; |
| 137 | + car.destroyed === true; |
| 138 | + car.isNew() === true; |
| 139 | + car.objectId === null; |
| 140 | + }) |
| 141 | +}) |
| 142 | +``` |
| 143 | +
|
| 144 | +### Contributing |
| 145 | +
|
| 146 | +Pull requests and issues are welcome. |
0 commit comments