Edge Version を元に作成しました。安定版の0.9.2とは異なる部分があります。
オブジェクトに対して、イベントが発火した時に呼び出したいコールバック関数を設定します。
イベント名です。半角スペースで区切って複数のイベント名を指定することもできます。all を指定すると、どのイベントが発火した場合にもコールバック関数が呼ばれます。
イベント名とコールバック関数のペアをオブジェクトリテラルで設定することもできます。この場合、第２引数はcontextになります。
var func1 = function () {
console.log(this.msg1);
};
var func2 = function (model) {
console.log(this.msg2);
};
var msg = {
msg1: "Changed!",
msg2: "Destroyed!"
};
var model = new Backbone.Model();
model.on({change: func1, destroy: func2}, msg);
model.set({name: "Tanaka"}); //-> Changed!
model.destroy(); //-> Destroyed!
イベントが発火すると呼ばれるコールバック関数です。コールバック関数に渡される引数は、イベントを発火させるtriggerメソッドが決定します。
Backbone.jsが発火するイベントとコールバック関数の引数の対応は以下の通りです。
| イベント | 引数 |
|---|---|
| add | model, collection, options |
| remove | model, collection, options |
| reset | collection, options |
| sort | collection, options |
| change | model, options |
| change:[attribute] | model, value, options |
| destroy | model, collection, options |
| request | model, xhr, options |
| sync | model, resp, options |
| error | model, xhr, options または model, error, options |
| route:[name] | *args（URLと関連付けたコールバック関数に渡される引数） |
| all | eventName, *args（イベントと関連付けたコールバック関数に渡される引数） |
コールバック関数の中のthisキーワードを束縛します。
設定されているイベントを削除します。全ての引数を省略すると、オブジェクトに設定されているイベントを全て削除します。
削除するイベント名です。半角スペースで区切って複数のイベント名を指定することもできます。省略する場合はnullを渡します。
削除するイベントを、コールバック関数で指定します。省略する場合はnullを渡します。
削除するイベントを、this に束縛しているオブジェクトで指定します。省略する場合はnullを渡します。
イベントを発火します。また、onメソッドで設定したコールバック関数へ渡す引数を指定します。
発火させるイベント名です。複数のイベントを空白で区切って指定できます。
イベントと関連付けされているコールバック関数の引数に渡されます。
var user = {name: "Tanaka"};
_.extend(user, Backbone.Events);
user.on("Say", function (obj, msg) {
console.log(obj.name + " said " + msg);
});
user.trigger("Say", user, "Hello."); //-> Tanaka said Hello.
なお、Backbone.jsのコレクションは、所有するモデルの全てのイベントを監視しており、モデルがイベントを発火すると同じイベントを発火します。
var User = Backbone.Model.extend({
validate: function (attr) {
if (_.isEmpty(attr.name)) {
return "invalid!";
}
}
});
var user = new User();
var users = new Backbone.Collection();
users.add(user);
users.on("all", function (eventName) {
console.log(eventName);
});
user.set({name:"tanaka"});
//-> change:name
//-> change
user.set({name:""});
//-> error
Backbone.jsのメソッドと発火されるイベントの対応は以下の通りです。
| メソッド ／ イベント | add | remove | reset | sort | change | destroy | request | sync | error | route |
|---|---|---|---|---|---|---|---|---|---|---|
| model.set |
|
|
||||||||
| model.unset |
|
|
||||||||
| model.clear |
|
|
||||||||
| model.fetch |
|
|
|
|
||||||
| model.save |
|
|
|
|
||||||
| model.destroy |
|
|
|
|
||||||
| model.validate |
|
|||||||||
| model.change |
|
|||||||||
| collection.add |
|
|||||||||
| collection.push |
|
|||||||||
| collection.unshift |
|
|||||||||
| collection.remove |
|
|||||||||
| collection.pop |
|
|||||||||
| collection.shift |
|
|||||||||
| collection.sort |
|
|||||||||
| collection.reset |
|
|||||||||
| collection.fetch |
|
|
|
|
|
|||||
| collection.create |
|
|
|
|
||||||
| router.navigate |
|
Backbone.Model を継承した新しいモデルを作ります。
インスタンスメンバを定義します。
var User = Backbone.Model.extend({
say: function () {
console.log("Hello.");
}
});
var user = new User();
user.say(); //-> Hello.
静的メンバを定義します。以下はFactoryパターンの例です。
var User = Backbone.Model.extend({
openFile: function () {
console.log(this.canOpen);
}
}, {
create: function (type) {
if (type === "admin") {
return new AdminUser;
} else {
return new NormalUser;
}
}
});
var AdminUser = User.extend({
canOpen: true
});
var NormalUser = User.extend({
canOpen: false
});
var user1 = User.create("admin");
var user2 = User.create("normal");
user1.openFile(); //-> true
user2.openFile(); //-> false
コンストラクタです。
モデルの属性へ設定したい値をオブジェクトリテラルで指定します。
var Model = Backbone.Model.extend();
var model = new Model({name: "Tanaka", country: "Japan"});
options.parse = true を設定すると、parseメソッドを実行します。
var User = Backbone.Model.extend({
parse: function (response) {
return response.user;
}
});
var user = new User({user: {name: "Tanaka"}}, {parse: true});
console.log(user.toJSON()); //-> {name: "Tanaka"}
options.collection にコレクションを設定すると、urlメソッドでモデルのURLをすぐに取得できるようになります。ただし、この時点ではモデルからコレクションへの一方的な参照がなされているだけで、コレクションにモデルが格納されたのではありません。
var users = new Backbone.Collection();
users.url = "/hoge";
var User = Backbone.Model.extend();
var user = new User({id: 1, name: "Tanaka"}, {collection: users});
console.log(user.url()); //-> /hoge/1
console.log(users.length); //-> 0
その他に、initializeメソッドへ一時的な値を渡す用途に利用できます。
インスタンス生成時に呼ばれます。
コンストラクタのattributesへ渡した値です。
コンストラクタのoptionsへ渡した値です。
モデルの属性値を取得します。
モデルの属性値を設定します。属性値が現在の属性値と異なる場合、changeイベントを発火します。また、validateメソッドを実行します。
keyとvalueのペアで指定します。
model.set("name", "Tanaka");
model.set("country", "Japan");
オブジェクトリテラルで指定することもできます。
model.set({name: "Tanaka", country: "Japan"});
options.silent = true を設定すると、changeイベントを発火しません。
var Model = Backbone.Model.extend({
validate: function (attrs) {
if (_.isEmpty(attrs.name)) {
return "invalid!";
}
}
});
var model = new Model();
model.on("change", function () {
console.log("changed!");
});
model.on("error", function (model, error) {
console.log(error);
});
model.set({name: "Tanaka"}); //-> "changed!"
model.set({name: "Suzuki"}, {silent: true});
model.set({name: ""}); //-> "invalid!"
model.set({name: ""}, {silent: true});
getメソッドと同じくモデルの属性値を取得しますが、HTMLをエスケープします。
モデルが属性そのものを持っているかどうかを返します。
var model = new Backbone.Model({name: ""});
console.log(model.has("name")); //-> true
console.log(model.has("country")); //-> false
モデルから属性そのものを削除します。存在する属性であれば changeイベントを発火します。また、validateメソッドを実行します。
options.silent = true を設定すると、changeイベントを発火しません。
モデルから属性そのものを全て削除します。属性が１つでも存在すれば changeイベントを発火します。また、validateメソッドを実行します。
options.silent = true を設定すると、changeイベントを発火しません。
モデルを一意に識別するための識別子です。コレクションの中からモデルを取り出す際のキーとして使用したり、モデルごとに決まるURLの一部に使用されたりします。
idは通常、fetchメソッドやsaveメソッドによってバックエンド側で決定されますが、クライアントサイドで手動でidを設定する場合には、setメソッドでモデルの属性値として設定します。モデルのidプロパティは自動的にその値を参照してくれます。
var model = new Backbone.Model({
id: 1,
name: "Tanaka"
});
console.log(model.toJSON()); //-> {id: 1, name: "Tanaka"}
console.log(model.id); //-> 1
setメソッドで設定せずに、idプロパティに直接設定することも可能ですが、モデルの属性値は変化しませんので注意が必要です。
var model = new Backbone.Model({
name: "Tanaka"
});
model.id = 1;
console.log(model.id); //-> 1
console.log(model.toJSON()); //-> {name: "Tanaka"}
model = new Backbone.Model({
id: 1,
name: "Tanaka"
});
model.id = 2;
console.log(model.id); //-> 2
console.log(model.toJSON()); //-> {id: 1, name: "Tanaka"}
モデルの属性の"id"というネーミングは変更できます。例えばバックエンドのデータベースのカラム名と合わせると便利です。ただし、モデルのidプロパティは"id"のままです。
var Model = Backbone.Model.extend({
idAttribute: "user_id"
});
var model = new Model({
user_id: 1,
name: "Tanaka"
});
console.log(model.id); //-> 1
console.log(model.toJSON()); //-> {user_id: 1, name: "Tanaka"}
console.log(model.user_id); //-> undefined
インスタンス生成時に自動的に振られるユニークな識別子です。
モデルの属性が格納されているプロパティです。属性に値を設定する場合、このプロパティを直接更新することでも可能ですが、イベントの発火などを機能させるためにsetメソッドを使用します。
モデルの属性の初期値を設定します。関数として定義することも可能です。
var Model = Backbone.Model.extend({
defaults: function () {
return {
name: "Tanaka",
country: "Japan"
}
}
});
var model = new Model();
console.log(model.toJSON()); //-> {name: "Tanaka", country: "Japan"}
attributesプロパティを複製したオブジェクトを返します。JSON文字列に変換するのではありません。
var model = new Backbone.Model({
name: "Tanaka"
});
console.log(model.toJSON()); //-> { name: "Tanaka"}
console.log(JSON.stringify(model.attributes)); //-> "{"name": "Tanaka"}"
バックエンドとHTTPリクエストのGETメソッドで通信して、リソースの取得を要求します。取得結果をparseメソッドで変換してからモデルの属性に設定します。validateメソッドも実行します。リクエスト先のURLはurlメソッドで決まります。
通信開始時にrequestイベントを発火します。正常を表すHTTPステータスが返って来た場合、syncイベントを発火します。また、取得結果をモデルの属性に設定する際に、fetch前の値と異なる場合には changeイベントを発火します。
異常を表すHTTPステータスが返って来た場合、errorイベントを発火します。
options.silent = true を設定すると、changeイベントを発火しません。
バックエンドとHTTPリクエストのPOSTまたはPUTメソッドで通信して、リソースの新規作成または更新を要求します。モデルのidプロパティが設定されていない場合はPOSTメソッド、設定されている場合はPUTメソッドで通信します。リクエスト先のURLはurlメソッドで決まります。
まず、モデルに設定されている属性値、およびこのメソッドの引数に渡した属性値は、validateメソッドで検証されます。検証結果に問題があった場合、このメソッドはfalseを返却します。次に、このメソッドの引数に属性値を渡したのであればモデルの属性値に反映され、反映前と反映後とで値が変化するのであれば changeイベントを発火します。ただし、後述する options.wait = true を設定している場合には、属性値の反映は保留され、changeイベントも発火しません。
バックエンドとの通信開始時にrequestイベントを発火します。通信した結果、正常を表すHTTPステータスが返って来た場合、バックエンドから取得した属性値はparseメソッドで変換してからモデルの属性に設定します。この時validateメソッドを実行し、検証結果に問題があった場合、このメソッドはfalseを返してバックエンドから取得した属性値はモデルの属性に反映されません。また、モデルの属性値とバックエンドから取得した属性値とが異なる場合には、changeイベントを発火します。最後に、syncイベントを発火します。
異常を表すHTTPステータスが返って来た場合、errorイベントを発火します。このメソッドは、通信結果に関わらずjqXHRオブジェクトを返します。
options.silent = true を設定すると、changeイベントを発火しません。
このメソッドの引数に渡した属性値はモデルの属性値へ即座に反映されますが、options.wait = true を設定すると、サーバの応答を待ってから反映するようにタイミングを変えることができます。
バックエンドとHTTPリクエストのDELETEメソッドで通信して、リソースの破棄を要求します。リクエスト先のURLはurlメソッドで決まります。
通信開始時にrequestイベントを発火します。正常を表すHTTPステータスが返って来た場合、syncイベントを発火します。この時、destroyイベントを発火します。モデルがコレクションに所有されている場合は、自動的にコレクションからも削除されます。
異常を表すHTTPステータスが返って来た場合、errorイベントを発火します。destroyイベントは発火しません。
このメソッドは、通信結果に関わらずjqXHRオブジェクトを返します。ただし、モデルにidプロパティが設定されていない場合は通信せず、このメソッドはfalseを返します。この時、destroyイベントを発火します。モデルがコレクションに所有されている場合は、自動的にコレクションからも削除されます。
モデルはコレクションから即座に削除されますが、options.wait = true を設定すると、サーバの応答を待ってから削除するようにタイミングを変えることができます。
モデルの属性を操作する直前に呼ばれるメソッドで、値を検証する処理を記述します。
このメソッドは、検証に合格した場合には何も返却しないようにします。検証結果に問題がある場合、エラーメッセージの文字列や、エラー情報を格納したオブジェクトなど好みの値を返却します。この返却値は、発火するerrorイベントの引数に設定されます。
var Model = Backbone.Model.extend({
validate: function (attrs) {
if (_.isEmpty(attrs.name)) {
return "Invalid!";
}
}
});
var model = new Model();
model.on("error", function (model, error) {
console.log(error);
});
model.set({name: ""}); //-> "Invalid!"
上の例では、setメソッドから呼ばれたvalidateメソッドがエラー時に発火する errorイベントを捕捉していますが、setメソッドの options.error にコールバックを定義してエラー処理する方法もあります。なお、その場合も errorイベントは発火します。
var Model = Backbone.Model.extend({
validate: function (attrs) {
if (_.isEmpty(attrs.name)) {
return "Invalid!";
}
}
});
var model = new Model();
model.set({name: ""} , {
error: function (model, error) {
console.log(error);
}});
//-> "Invalid!"
モデルのURLを取得します。
idプロパティが設定されているモデルのURLは "[urlRoot]/id" になります。idプロパティが設定されていない、つまり新規のリソースの場合は "[urlRoot]" になります。urlRootプロパティが未定義の場合は例外がスローされます。ただし、モデルがコレクションに所有されており、そのコレクションのurlプロパティが定義されていれば、"[collection.url]/id" または "[collection.url]" となります。モデルのurlRootプロパティとコレクションのurlプロパティがどちらも定義されている場合は、モデルのurlRootプロパティが優先されます。
var Model = Backbone.Model.extend();
var Collection = Backbone.Collection.extend({
url: "/users"
})
var model = new Model({id: 1});
var collection = new Collection(model);
console.log(model.url()); //-> "/users/1"
model.urlRoot = "/user";
console.log(model.url()); //-> "/user/1"
モデルのurlメソッドの内部で使用されます。関数として定義することも可能です。
var Model = Backbone.Model.extend({
urlRoot: function () {
return "/users";
}
});
var model = new Model({id: 1});
console.log(model.url()); //-> "/users/1"
fetchメソッドやsaveメソッドによりサーバから取得した値がモデルの属性へ設定される直前に呼ばれます。サーバから取得したデータをそのまま属性に取り込むのではなく、加工してから取り込みたい場合に利用します。
サーバが返したデータです。
var Model = Backbone.Model.extend({
parse: function (response) {
return response.user;
}
});
var model = new Model();
model.fetch(); // サーバのレスポンスが {user: {name: "Tanaka"}} と仮定
また、モデルのインスタンス生成時に、コンストラクタで options.parse = true を指定した場合にも実行されます。
属性が全て同じであるモデルを複製します。
モデルのidプロパティが未設定（nullまたはundefined）かどうかを返します。
モデルの属性を options.silent = true で設定すると changeイベントが発火しないまま属性が設定された状態となります。このメソッドは、その状態にある属性に changeイベントを発火します。
var user = new Backbone.Model();
user.on("change:name", function (model, value) {
console.log(value); //-> "Tanaka"
})
user.on("change:country", function (model, value) {
console.log(value); //-> "Japan"
})
user.on("change", function (model) {
console.log(model.toJSON()); //-> {name: "Tanaka", country: "Japan"}
})
user.set({name: "Tanaka", country: "Japan"}, {silent: true});
user.change();
モデルの属性を options.silent = true で設定すると changeイベントが発火しないまま属性が設定された状態となります。このメソッドは、指定した属性がその状態にあるかどうかを返します。
var model = new Backbone.Model();
model.set({name: "Suzuki"}, {silent: true});
console.log(model.hasChanged("name")); //-> true
model.set({name: "Tanaka"});
console.log(model.hasChanged("name")); //-> false
なお、発火しないまま残っている changeイベントは、changeメソッドでまとめて発火できます。
対象の属性を指定します。省略すると、該当する属性が１つでもあればtrueを返します。
モデルの属性を options.silent = true で設定すると changeイベントが発火しないまま属性が設定された状態となります。このメソッドは、その状態にある全ての属性を複製したオブジェクトを返します。該当する属性が無い場合はfalseを返します。
指定したattributesと、最後に changeイベントが発火した時点での属性とを比較して、異なる属性を返します。該当する属性が無い場合はfalseを返します。
var user = new Backbone.Model();
user.set({
name: "Tanaka",
address: "Japan"
});
user.set({name: "Suzuki"}, {silent:true});
console.log(user.changedAttributes({name: "Tanaka", address: "Japan"})); //-> false
console.log(user.changedAttributes({name: "Tanaka", address: "China"})); //-> {address: "china"}
console.log(user.changedAttributes({name: "Suzuki"})); //-> {name: "Suzuki"}
console.log(user.changedAttributes({name: "Yamada"})); //-> {name: "Yamada"}
変更前の属性を取得します。changeイベントにバインドしたコールバック関数の中でのみ使用できます。
var user = new Backbone.Model({name: "Tanaka"});
user.on("change", function (model) {
console.log(model.previous("name")); //-> "Tanaka"
console.log(model.get("name")); //-> "Suzuki"
})
user.set({name: "Suzuki"});
変更前の全ての属性を取得します。changeイベントにバインドしたコールバック関数の中でのみ使用できます。
var user = new Backbone.Model({name: "Tanaka", country: "Japan"});
user.on("change", function (model) {
console.log(model.previousAttributes()); //-> {name: "Tanaka", country: "Japan"}
console.log(model.toJSON()); //-> {name: "Suzuki", country: "China"}
})
user.set({name: "Suzuki", country: "China"});
Backbone.Collection を継承した新しいコレクションを作ります。
インスタンスメンバを定義します。
静的メンバを定義します。
コンストラクタです。
コレクションに格納するモデルを指定します。複数のモデルは配列で指定します。
var User = Backbone.Model.extend();
var user1 = new User({name: "Tanaka"});
var user2 = new User({name: "Suzuki"});
var users = new Backbone.Collection([user1, user2]);
console.log(users.length); //-> 2
options.modelでmodelプロパティを設定できます。
options.comparatorでcomparatorメソッドを設定できます。すでにクラスで定義済みのcomparatorメソッドを無効にする場合はoptions.comparator=falseとします。
options.parse=trueを設定すると、parseメソッドを実行します。
その他、initializeメソッドへ一時的な値を渡す用途に利用できます。
インスタンス生成時に呼ばれます。
コンストラクタのmodelsへ渡した値です。
コンストラクタのoptionsへ渡した値です。
コレクションに格納するモデルのクラス（関数オブジェクト）を指定します。コンストラクタやaddメソッドなどの引数でオブジェクトリテラルを渡すと、このプロパティで指定したクラスに変換されます。
モデルが格納されているプロパティです。ただし、通常はこのプロパティを直接参照するのではなく、getメソッドやatメソッド、Underscore.jsのメソッドを利用します。
各モデルのattributesプロパティを複製したオブジェクトの配列を返します。JSON文字列に変換するのではありません。
Backbone.syncメソッドを実行します。fetchメソッドの内部で呼ばれます。
このメソッドを直接呼ぶ用途としては、コレクションに格納しているモデルを一括してバックエンドへ送る場合が考えられます。
var Users = Backbone.Collection.extend({
createAll: function () {
var self = this;
options = {
success: function(models) {
self.reset(models);
}
};
return this.sync('create', this, options);
}
});
modelsプロパティに対して、Underscore.jsの以下のメソッドを使用できます。
コレクションにモデルを追加します。引数にオブジェクトリテラルを渡すとmodelプロパティで指定されているモデルのクラス（関数オブジェクト）に変換しますが、モデルのvalidateメソッドの検証結果に問題がある場合には例外をスローします。
var User = Backbone.Model.extend({
validate: function (attr) {
if (_.isEmpty(attr.name)) {
return "invalid!";
}
}
});
var Users = Backbone.Collection.extend({
model: User
});
var users = new Users();
users.add({name: ""}); //-> Error: Can't add an invalid model to a collection
このメソッドで追加したモデルはmodelsプロパティの末尾に追加されますが、comparatorメソッドを定義している場合にはソートします。sortメソッドによるソートではsortイベントを発火しますが、このaddメソッドによるソートでは発火しません。
var Users = Backbone.Collection.extend({
comparator: function (model) {
return model.id;
}
});
var users = new Users;
users.add({id: 1});
users.add({id: 3});
users.add({id: 2});
console.log(users.at(0).id); //-> 1
console.log(users.at(1).id); //-> 2
console.log(users.at(2).id); //-> 3
最後に、追加されたモデルはaddイベントを発火します。
このメソッドはコレクション自身を返却します。
複数のモデルを追加する場合は配列で指定します。
同じidプロパティのモデルがすでにコレクションに格納されている場合には追加されませんが、options.merge = true を設定すると、すでに格納されているモデルの属性値を上書きすることができます。
var users = new Backbone.Collection({id: 1, name: "Tanaka"});
users.add({id: 1, name: "Suzuki"});
console.log(JSON.stringify(users)); //-> [{"id":1,"name":"Tanaka"}]
users.add({id: 1, name: "Suzuki"}, {merge: true});
console.log(JSON.stringify(users)); //-> [{"id":1,"name":"Suzuki"}]
options.atでモデルを追加する位置をmodelsプロパティのインデックスで指定することができます。
var users = new Backbone.Collection([
{id: 1},
{id: 2},
{id: 3},
{id: 4},
{id: 5}
]);
console.log(users.pluck("id")); //-> [1, 2, 3, 4, 5]
users.add([{id: "A"}, {id: "B"}], {at: 3});
console.log(users.pluck("id")); //-> [1, 2, 3, "A", "B", 4, 5]
options.silent = true を設定すると、addイベントを発火しません。
options.sort = false を設定するとソートしません。
コレクションからモデルを削除します。モデルそのものは破棄しません。削除されたモデルはremoveイベントを発火して、コールバック関数の引数options.indexには削除したモデルのmodelsプロパティ上のインデックスが設定されます。
var users = new Backbone.Collection([
{id: 1, name: "Tanaka"},
{id: 2, name: "Suzuki"},
{id: 3, name: "Nakata"}
]);
users.on("remove", function(model, collection, options) {
console.log(options.index);
});
users.remove({id: 2});
//-> 1
上記のoptions.indexの注意点として、複数のモデルを削除した場合に得られるインデックスはイベントが発火した時点でのものであり、このremoveメソッドを呼んだ時点でのインデックスではありません。
var users = new Backbone.Collection([
{id: 1, name: "Tanaka"},
{id: 2, name: "Suzuki"},
{id: 3, name: "Nakata"}
]);
users.on("remove", function(model, collection, options) {
console.log(options.index);
});
users.remove([{id: 2}, {id: 3}]);
//-> 1
//-> 1
このメソッドはコレクション自身を返却します。
削除するモデルを指定する方法は３通りあります。モデルのインスタンスそのものを渡す方法、idプロパティの値を渡す方法、"id"という名前のプロパティを持つオブジェクトを渡す方法です。
複数のモデルを削除する場合は配列で指定します。
options.silent = true を設定すると、removeイベントを発火しません。
格納しているモデルを全て入れ替えます。resetイベントを発火します。resetイベントに関連付けしたコールバック関数の中では、入れ替え前のモデルの配列をoptions.previousModelsから参照できます。
var users = new Backbone.Collection([
{name: "Tanaka"},
{name: "Suzuki"}
]);
users.on("reset", function (collection, options) {
console.log(options.previousModels[0].get("name"));
console.log(options.previousModels[1].get("name"));
});
users.reset({name: "Sasaki"});
//-> Tanaka
//-> Suzuki
新しく格納するモデルを配列で指定します。省略すると、コレクションは空になります。
options.silent = true を設定すると、resetイベントを発火しません。
コレクションに格納しているモデルをidプロパティの値、または"id"という名前のプロパティを持つオブジェクト、またはcidプロパティの値をキーに参照します。
var users = new Backbone.Collection([
{id: 1, name: "Tanaka"},
{id: 2, name: "Suzuki"},
{id: 3, name: "Nakata"},
]);
console.log(users.get(2).get("name")); //-> Suzuki
console.log(users.get({id: 2}).get("name")); //-> Suzuki
コレクションに格納しているモデルをmodelsプロパティのインデックスで参照します。なお、modelsプロパティの格納順は、ソートされることにより、addメソッドで追加した順とは限りません。
var Users = Backbone.Collection.extend({
comparator: function (model) {
return model.id;
}
});
var users = new Users();
users.add({id:1});
users.add({id:3});
users.add({id:2});
console.log(users.at(0).id); //-> 1
console.log(users.at(1).id); //-> 2
console.log(users.at(2).id); //-> 3
コレクションの末尾にモデルを追加します。引数にオブジェクトリテラルを渡すとmodelプロパティで指定されているモデルのクラス（関数オブジェクト）に変換しますが、モデルのvalidateメソッドの検証結果に問題がある場合には例外をスローします。
comparatorメソッドを定義している場合にはソートします。sortメソッドによるソートではsortイベントを発火しますが、このpushメソッドによるソートでは発火しません。
最後に、追加されたモデルはaddイベントを発火します。
このメソッドは追加したモデルを返却します。このメソッドはaddメソッドに別名を付けただけに思えますが、返却する値に違いがあります。
options.silent = true を設定すると、addイベントを発火しません。
options.sort = false を設定するとソートしません。
コレクションの末尾のモデルを削除します。モデルそのものは破棄しません。削除されたモデルとこのコレクションはremoveイベントを発火します。
このメソッドは削除したモデルを返却します。
options.silent = true を設定すると、removeイベントを発火しません。
コレクションの先頭にモデルを追加します。引数にオブジェクトリテラルを渡すとmodelプロパティで指定されているモデルのクラス（関数オブジェクト）に変換しますが、モデルのvalidateメソッドの検証結果に問題がある場合には例外をスローします。
このメソッドでモデルを追加した場合には、comparatorメソッドを定義していてもソートしません。
最後に、追加されたモデルはaddイベントを発火します。
このメソッドは追加したモデルを返却します。
options.silent = true を設定すると、addイベントを発火しません。
コレクションの先頭のモデルを削除します。モデルそのものは破棄しません。削除されたモデルはremoveイベントを発火します。
このメソッドは削除したモデルを返却します。
options.silent = true を設定すると、removeイベントを発火しません。
コレクションの指定された範囲のモデルを参照します。
modelsプロパティの開始インデックスを指定します。
modelsプロパティの終了インデックスを指定します。
コレクションに格納されているモデルの数を返します。
sortメソッドで使用する比較関数を設定します。
var users = new Backbone.Collection([
{name: "Tanaka", age: 10},
{name: "Suzuki", age: 40},
{name: "Katou", age: 50},
{name: "Gotou", age: 20},
{name: "Mogi", age: 30}
]);
users.comparator = function (model) {
return model.get("age");
};
users.sort();
console.log(users.pluck("name")); //-> ["Tanaka", "Gotou", "Mogi", "Suzuki", "Katou"]
Javascript標準のArrayオブジェクトが持つsortメソッドと同じく、引数を２つ持つ比較関数でも設定できます。複数のソートキーを指定したい場合に使用します。
var users = new Backbone.Collection([
{name: "Tanaka", age: 10, gender: "male"},
{name: "Suzuki", age: 40, gender: "male"},
{name: "Katou", age: 50, gender: "female"},
{name: "Gotou", age: 20, gender: "female"},
{name: "Mogi", age: 30, gender: "male"}
]);
users.comparator = function (a, b) {
if (a.get("gender") > b.get("gender")) return 1;
if (a.get("gender") < b.get("gender")) return -1;
return a.get("age") - b.get("age");
};
users.sort();
console.log(users.pluck("name")); //-> ["Gotou", "Katou", "Tanaka", "Mogi", "Suzuki"]
格納しているモデルをソートします。comparatorメソッドを定義していない場合、例外をスローします。ソートにより並びが変わったかどうかに関わらず、sortイベントを発火します。
options.silent = true を設定すると、sortイベントを発火しません。
格納しているモデルから指定した属性を取り出した配列を作ります。
var users = new Backbone.Collection();
users.add({id:1, name: "Tanaka"});
users.add({id:2, name: "Suzuki"});
users.add({id:3, name: "Katou"});
console.log(users.pluck("name")); //-> ["Tanaka", "Suzuki", "Katou"]
格納しているモデルのうち、指定した属性値に一致するモデルを取り出した配列を作ります。
var users = new Backbone.Collection();
users.add({name: "Tanaka", age: 10});
users.add({name: "Suzuki", age: 10});
users.add({name: "Katou", age: 30});
console.log(users.where({age: 10}).length); //-> 2
コレクションのfetchメソッドでの通信先となるURLを設定します。また、コレクションが所有するモデルにurlRootプロパティが設定されていない場合には、そのモデルのurlメソッドの内部で使用され、モデルのURLの一部となります。
fetchメソッドによりサーバから取得した値がモデルの属性へ設定される直前に呼ばれます。サーバから取得したデータをそのまま属性に取り込むのではなく、加工してから取り込みたい場合に利用します。
同じmodelsプロパティを持つ新しいコレクションを複製します。
バックエンドとHTTPリクエストのGETメソッドで通信して、リソースの取得を要求します。取得結果をparseメソッドで変換して、さらにモデルのparseメソッドで変換してからモデルを格納します。また、モデルのvalidateメソッドを実行して、検証結果に問題がある場合は例外をスローします。リクエスト先のURLはurlプロパティです。設定していない場合は例外をスローします。
通信開始時にrequestイベントを発火します。正常を表すHTTPステータスが返って来た場合、syncイベントを発火します。また、options.add = trueを設定していない場合にはresetイベントを発火しますが、設定している場合にはaddイベントを発火します。
異常を表すHTTPステータスが返って来た場合、errorイベントを発火します。
options.silent = trueを設定すると、addイベントやresetイベントを発火しません。
コレクションに格納済みのモデルは全て削除して取得したモデルに入れ替えますが、options.add = trueを設定すると削除せずに追加します。この時、options.merge = trueを設定すると、同じidプロパティのモデルがすでにコレクションに格納されている場合は格納済みのモデルの属性値を上書きします。
バックエンドとHTTPリクエストのPOSTメソッドで通信して、リソースの新規作成を要求します。リクエスト先のURLはモデルのurlメソッドで決まります。
このメソッドの引数にモデルのインスタンスではなく単なるオブジェクトリテラルを渡した場合は、validateメソッドで検証されます。検証結果に問題があった場合、このメソッドはfalseを返却します。検証結果に問題がなければ、modelプロパティに設定しているクラス（関数オブジェクト）に変換して、コレクションへ追加します。この時、addイベントを発火します。
バックエンドとの通信開始時にrequestイベントを発火します。通信した結果、正常を表すHTTPステータスが返って来た場合、syncイベントを発火します。
異常を表すHTTPステータスが返って来た場合、errorイベントを発火します。このメソッドは、通信結果に関わらず新しいモデルを返します。
options.silent = true を設定すると、addイベントを発火しません。
モデルは即座にコレクションに追加されますが、options.wait = true を設定すると、サーバの応答を待ってから追加するようにタイミングを変えることができます。
Backbone.Router を継承した新しいルーターを作ります。
インスタンスメンバを定義します。
静的メンバを定義します。
コンストラクタです。
initializeメソッドへ一時的な値を渡す用途に利用します。
インスタンス生成時に呼ばれます。
コンストラクタのoptionsへ渡した値です。
URLとコールバック関数の関連付けをハッシュマップで指定します。下の例では、#usersへアクセスするとcreateView関数を実行します。
var Route = Backbone.Router.extend({
routes: {
"users": "createView"
},
createView: function () {
//
}
});
URLの中にコロンで始まる変数を指定すると、パラメータとしてコールバック関数に渡すことができます。下の例では、#users/1/2へアクセスするとcreateView関数の第１引数に1、第２引数に2が渡ります。
var Route = Backbone.Router.extend({
routes: {
"users/:group/:id": "createView"
},
createView: function (group, id) {
//
}
});
上記の例でidを省略して#users/1へアクセスすると、コールバック関数は呼ばれません。カッコで囲うとそのパラメータは省略可能になります。
routes: {
"users/:group(/:id)": "callback"
}
アスタリスクで始める変数を指定すると、それ以降の全ての文字列がコールバック関数の引数に渡されます。下の例では、#users/1/2/3へアクセスするとコールバック関数の第１引数に1/2/3が渡ります。
routes: {
"users/*query": "callback"
}
これらのURLパターンにマッチすると、コールバック関数が実在するかどうかに関わらずroute:nameイベントを発火します。nameはコールバック関数名です。
routesプロパティを使用せずに個別にルーティングを設定します。
var Route = Backbone.Router.extend({
initialize: function () {
this.route("users/:id", "users", this.createView);
},
createView: function (id) {
console.log(id);
}
});
URLのパターンを指定します。正規表現で指定することもできます。
initialize: function () {
this.route(/users\/([0-9]+)/, "users", this.createView);
},
発火するrouteイベントの名前route:nameを指定します。
コールバック関数を指定します。省略すると、上記のnameで指定した名前を持つ関数がコールバック関数となります。
var Route = Backbone.Router.extend({
initialize: function () {
this.route("users", "userFnc");
},
userFnc: function () {
//
}
});
URLを遷移します。
遷移先のURLを指定します。
このメソッドでURLを遷移すると、routesプロパティやrouteメソッドでURLと関連付けしたコールバック関数は呼ばれませんが、options.trigger = trueを設定するとコールバック関数を呼ぶようになり、またrouteイベントを発火します。
また、options.replace = trueを設定すると、ブラウザの履歴を新しく追加せずに上書きします。
モデルやコレクションの属性をバックエンド側とRESTスタイルで非同期に送受信します。このメソッドはモデルのsaveメソッドなどの内部で呼ばれて通信処理を委譲されます。このメソッドをオーバーライドすることで、例えばブラウザのLocal Storage保存するように動作を変えることができます。
バックエンドとの通信開始時にrequestイベントを発火します。通信した結果、正常を表すHTTPステータスが返って来た場合、syncイベントを発火します。
異常を表すHTTPステータスが返って来た場合、errorイベントを発火します。
create、update、delete、readのいずれかを指定します。それぞれ、以下のHTTPメソッドで通信します。
対象のモデルやコレクションを指定します。
jQuery.ajaxの引数として渡す値です。options.successやoptions.errorのコールバック関数などを指定します。なお、正常を表すHTTPステータスが返って来たにも関わらずoptions.errorが呼ばれる場合、バックエンド側が送ってきたJSON文字列が正しくないことが考えられます。
jQuery.ajaxへのショートカットです。Backbone.js内部でのajaxはこのオブジェクトを参照するので、オーバーライドして独自の処理に変更できます。
trueを設定すると、HTTPリクエストのPUTメソッドとDELETEメソッドの代わりにPOSTメソッドを使います。本来PUTとDELETEのどちらを使いたかったのかは、X-HTTP-Method-Overrideヘッダに設定されます。バックエンド側の都合でPUTやDELETEが利用できない場合に指定します。
POST /user/1 HTTP/1.1
X-Requested-With: XMLHttpRequest
X-HTTP-Method-Override: PUT
Content-Type: application/json
Accept: application/json, text/javascript, */*; q=0.01
{"id":1,"name":"Tanaka"}
trueを設定すると、HTTPヘッダのMIMEタイプはapplication/jsonではなくapplication/x-www-form-urlencodedが設定され、また、データは"model"という名前のパラメータに格納されます。バックエンドとJSON形式でやり取りできない場合に指定します。
また、同時にBackbone.emulateHTTPをtrueに設定している場合、PUTメソッドとDELETEメソッドは_methodパラメータに格納し、HTTPリクエストはPOSTメソッドを使います。
POST /user/1 HTTP/1.1
X-Requested-With: XMLHttpRequest
X-HTTP-Method-Override: PUT
Content-Type: application/x-www-form-urlencoded
Accept: application/json, text/javascript, */*; q=0.01
model:{"id":1,"name":"Tanaka"}
_method:PUT
Backbone.View を継承した新しいビューを作ります。
インスタンスメンバを定義します。
静的メンバを定義します。
コンストラクタです。
モデルのコンストラクタのoptionsはその場限りの値ですが、ビューの場合にはインスタンスメンバであるoptionsプロパティへ格納されるため、いつでも参照することができます。
なお、options.model options.collection options.el options.id options.className options.tagName options.attributes に指定した値は、それぞれmodelプロパティ、collectionプロパティ、elプロパティ、idプロパティ、classNameプロパティ、tagNameプロパティ、attributesプロパティへ設定されます。
インスタンス生成時に呼ばれます。
コンストラクタのoptionsへ渡した値です。
コンストラクタのoptionsへ渡した値です。
ビューに関連付けするDOM要素を設定します。ビューは、このDOM要素をルートとするDOMツリーに対してさまざまな処理を行います。例えば$メソッドはDOMツリー内から要素を探し、eventsプロパティはイベントの関連付けをDOMツリー内の要素に対して行います。
DOM要素はページ上に実在していなくても構いません。DOMへのアクセスはコストが高いため、むしろメモリ上でDOM要素の編集を終えた後にページ上に追加したほうが効率的です。
elプロパティに設定しているDOM要素をjQueryオブジェクトに変換した値へのショートカットです。
elプロパティを設定し直します。eventsプロパティで設定したイベントは古いelプロパティから削除され、新しいelプロパティへ設定されます。
falseを設定すると、新しいelプロパティに対してeventsプロパティで設定したイベントを関連付けしません。
var Profile = Backbone.View.extend({
el: "<h1>",
events: {
"click": function (e) {console.log(e.target, "fire!");}
}
});
var profile = new Profile();
profile.$el.trigger("click"); //-> <h1> fire!
profile.setElement("<h2>");
profile.$el.trigger("click"); //-> <h2> fire!
profile.setElement("<h3>", false);
profile.$el.trigger("click"); //-> 発火しない
ビューで使用するモデルを設定します。
ビューで使用するコレクションを設定します。
ビューに関連付けされるDOM要素のid属性を設定します。インスタンス生成時に参照されます。コンストラクタでelプロパティを設定した場合はそちらが優先されるため意味がありません。
ビューに関連付けするDOM要素の属性をオブジェクトリテラルで設定します。インスタンス生成時に参照されます。コンストラクタでelプロパティを設定した場合はそちらが優先されるため意味がありません。
var Profile = Backbone.View.extend({
tagName: "input",
attributes: {
type: "text",
name: "userName",
value: "Tanaka"
}
});
var profile = new Profile();
console.log(profile.el); //-> <input type="text" name="userName" value="Tanaka">
ビューに関連付けするDOM要素のclass属性を設定します。インスタンス生成時に参照されます。コンストラクタでelプロパティを設定した場合はそちらが優先されるため意味がありません。
var Profile = Backbone.View.extend({
className: "alert alert-info"
});
var profile = new Profile();
console.log(profile.el); //-> <div class="alert alert-info">
ビューに関連付けするDOM要素のタグ名を設定します。インスタンス生成時に参照されます。設定しない場合はdivが設定されます。コンストラクタでelプロパティを設定した場合はそちらが優先されるため意味がありません。
jQyeryおよびZeptoのfindメソッドへのショートカットです。elプロパティに設定されているDOM要素をルートとするDOMツリーから、selectorに合致する子孫要素を返します。
elプロパティに設定されているDOM要素をルートとするDOMツリーに対する操作を記述するメソッドです。別のメソッド名でも特に問題はありません。
thisを返却して、呼び元でメソッドチェーンを使えるようにすると便利です。
var Hoge = Backbone.View.extend({
render: function () {
this.$el.html("Hello.");
return this;
}
});
console.log((new Hoge()).render().$el.html()); //-> Hello.
elプロパティに設定されているDOM要素の破棄、および、このビューに関連付けしているイベントを全て破棄します。
DOM要素を作成するためのユーティリティ・メソッドです。
var profile = new Backbone.View();
var el = profile.make("p", {class: "name"}, "Tanaka");
console.log(el.outerHTML); //-> <p class="name">Tanaka</p>
elプロパティに設定されているDOM要素をルートとするDOMツリー上で発火したイベントとコールバック関数との関連付けを設定します。
{ "イベント名 [セレクタ]", "コールバック関数名" }
var Profile = Backbone.View.extend({
el: "#hoge",
events: {
"click button": "say"
},
say: function (e) {
console.log("Hello.");
}
});
elプロパティに設定されているDOM要素をルートとするDOMツリーに新しいDOM要素を追加した場合にも、このeventsプロパティで設定している関連付けは動的に行われます。
コールバック関数内のthisは、ビューのインスタンスに束縛されます。また、実在しないコールバック関数名を指定すると、例外をスローします。
elプロパティに設定されているDOM要素をルートとするDOMツリーで発火するイベントにコールバック関数を関連付けます。eventsプロパティで設定する手段がありますので、このメソッドを直接呼ぶ場面は限られます。
eventsプロパティと同じ要領で、イベントとコールバック関数の関連付けを指定します。
ただし、このメソッドでイベントを設定すると、eventsに指定した新しいイベント以外は削除されるため、イベントを追加する用途には使えません。代わりにjQuery等のメソッドで設定する方法が考えられますが、このdelegateEventsメソッドで登録していないイベントはundelegateEventsメソッドで削除されないためメモリリークを起こす可能性があります。
そのため、イベントは動的に必要となるイベントも含めてeventsプロパティであらかじめ設定しておきます。
elプロパティに設定されているDOM要素をルートとするDOMツリーに関連付けしているイベントを削除します。ただし、delegateEventsメソッドで関連付けしたイベントのみが対象となります。
インスタンス生成時に自動的に振られるユニークな識別子です。