JavaScriptのEntityServiceの使用

概要

EntityServiceには、フロントエンドとバックエンド間のデータ取引を支援する多くのユーティリティやヘルパーがあります。例えば:

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.createEntity.should.be.a.type( "function" ); peopleService.fetchEntity.should.be.a.type( "function" ); peopleService.fetchEntities.should.be.a.type( "function" ); peopleService.loadMetadata.should.be.a.type( "function" );

エンティティオブジェクトの構造はメタデータ(スキーマ)に基づいています。 EntityServiceはこのメタデータをサーバーからOPTIONSリクエストとして一度だけ要求します。

この例は、エンティティサービスをどのようにインスタンス化し、エンティティを作成するかを示しています:

1. EntityServiceがインスタンス化されます。

2. EntityServiceがサーバー関連のリクエスト(createEntity、fetchEntityなど)を実行するよう求められると、提供されたURLにOPTIONSリクエストでアクセスされます。その後のすべてのリクエストは、サーバーが有効なメタデータオブジェクトで応答するまでキューに入ります。

3. メタデータオブジェクトが返された後、それはコンテキストEntityServiceに紐付けられ、すべてのエンティティがこのメタデータに基づいて検証・サニティ化されます。

   以下のコード例はこのメタデータに基づいています:

   var metadata = { "entity": { "key": "ItemID", "properties": { "key": "id", "datatype": "number" }, { "key": "ItemID", "datatype": "guid" }, { "key": "isActive", "datatype": "boolean" }, { "key": "balance", "datatype": "string" }, { "key": "picture", "datatype": "string" }, { "key": "age", "datatype": "number" }, { "key": "name", "datatype": "string" }, { "key": "gender", "datatype": "string" }, { "key": "company", "datatype": "string" }, { "key": "email", "datatype": "email" }, { "key": "phone", "datatype": "string" }, { "key": "address", "datatype": "string" }, { "key": "about", "datatype": "string" }, { "key": "registered", "datatype": "date" }, { "key": "latitude", "datatype": "number" }, { "key": "longitude", "datatype": "number" }, { "key": "subscribed", "datatype": "string" }, { "key": "children", "datatype": { "properties": { "key": "name", "datatype": "string" } } }, { "key": "tags", "datatype": "string" } } };

エンティティサービス.エンティティ

エンティティはクライアント側のエンティティを表します

エンティティの作成

エンティティを作成するには、オブジェクトを渡し、Sitecoreコンテンツツリーでそのアイテムを作成したいパスを設定し、executeメソッドを呼び出します。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); var aNewGuy = { name: "David", isActive: "true", gender: "male" }; peopleService.createEntity( aNewGuy ).then( function ( david ) { david.should.be.an.instanceOf( EntityService.Entity )}; david.isNew.should.be.false; david.ItemID.should.not.be.empty; david.name.should.eql( "David" ); david.isActive.should.eql( true ); david.gender.should.eql( "male" ); /** * ... and because not all of the key/values for this `Entity` were given based on the * `peopleService` end point metadata, they will still be added to the `Entity`. Their default * values are also based on the metadata. */ david.should.have.a.property( "id", null ); david.should.have.a.property( "balance", null ); david.should.have.a.property( "picture", null ); david.should.have.a.property( "age", null ); david.should.have.a.property( "company", null ); david.should.have.a.property( "email", null ); david.should.have.a.property( "phone", null ); david.should.have.a.property( "address", null ); david.should.have.a.property( "about", null ); david.should.have.a.property( "registered" ); david.should.have.a.property( "latitude", null ); david.should.have.a.property( "longitude", null ); david.should.have.a.property( "subscribed", null ); david.should.have.a.property( "children", null ); david.should.have.a.property( "tags", null ); done(); } ).fail( done );

createEntityメソッドにオブジェクトを与えなければ、サーバーに呼び出さずにダーティエンティティを作成します。すべてのダーティエンティティは新規と見なされます。isNewプロパティでこれを確認できます。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.createEntity().then( function ( david ) { david.isNew.should.be.true; done(); } ).fail( done );

単一のエンティティの取得

fetchEntityメソッドで単一のエンティティを取得し、エンティティにid/guidを与えます。fetchEntityはクエリを返すので、実行を呼び出す必要があります。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntity( "951c3e2e-02e8-4bbc-bbc8-e69ada95e670" ).execute().then( function ( cooley ) { cooley.name.should.eql( "Queen Cooley" ); done(); } ).fail( done );

複数のエンティティの取得

fetchEntitiesメソッドで与えられたURLに基づいてすべてのエンティティを取得します。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntities().execute().then( function ( people ) { people.should.be.an.Array.with.a.lengthOf( 3 ); people 0 .should.be.an.instanceOf( EntityService.Entity ); people 1 .should.be.an.instanceOf( EntityService.Entity ); people 2 .should.be.an.instanceOf( EntityService.Entity ); people 0 .isValid().should.be.ok; people 1 .isValid().should.be.ok; /* * The data of people 2 has been intentionally made invalid */ people 2 .isValid().should.not.be.ok; done(); } ).fail( done );

セーブエンティティ

エンティティを取得または作成してから保存する必要があります。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntity( "951c3e2e-02e8-4bbc-bbc8-e69ada95e670" ).execute().then( function ( cooley ) { cooley.should.be.an.instanceOf( EntityService.Entity ); cooley.name = "Mrs Queen Cooley"; cooley.save().then( function ( savedCooley ) { savedCooley.name.should.eql( "Mrs Queen Cooley" ); done(); } ).fail( done ); } ).fail( done ); Each time you save an Entity, it will trigger a ‘save’ event that you can listen for: ( entity.on(’save’, callback) ).

破壊する存在

破壊する前にエンティティを取ってくるか創出しなければなりません。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntity( "951c3e2e-02e8-4bbc-bbc8-e69ada95e670" ).execute().then( function ( cooley ) { cooley.should.be.an.instanceOf( EntityService.Entity ); cooley.destroy().then( function () { done(); } ).fail( done ); } ).fail( done );

汚い存在

ダーティエンティティとは、ブラウザメモリ上で保存せずに作成するエンティティのことです。例えば、ユーザーの入力を待っている場合など、これは有用です。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.createEntity().then( function ( aNewDirtyEntity ) { /* At this point `aNewDirtyEntity` has not been saved */ aNewDirtyEntity.should.be.an.instanceOf( EntityService.Entity ); aNewDirtyEntity.name = "Queen"; /* After modifying the dirty item, now we save it */ aNewDirtyEntity.save().then( function () { done(); } ).fail( done ); } );

生のJSON取得

追加のメソッドやプロパティを使わずに、エンティティに保存されたデータを生のJSONとして取得する必要がある状況もあります。サーバーに送られるデータを内部で取得するために、以下のメソッドが使われています:

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntity( "951c3e2e-02e8-4bbc-bbc8-e69ada95e670" ).execute().then( function ( queen ) { var queenAsJson = queen.json(); queen.should.be.an.instanceOf( EntityService.Entity ); queenAsJson.should.be.an.instanceOf( Object ); queenAsJson.should.not.be.an.instanceOf( EntityService.Entity ); done(); } ).fail( done );

追跡エンティティ

追跡機能付きのエンティティを拡張して、例えば以下の機能を追加できます:

• プロパティが変更された際に自動的に保存します。
• hasChanged()を呼び出して、エンティティが変更されているか確認してください。
• プロパティ値を元に戻すにはrevertChanges()を呼び出します。

追跡可能なオプションで事業体に追跡を追加する:

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntity( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) { melton.option( "trackable" ).should.be.true; done(); } ).fail( done );

自動保存

トラッキングをオンにすると、変更は自動的に保存されます。 emitter onやonceを使ってセーブイベントを聞くことができます。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntity( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) { /* Listening to the `save` event `once`. You can also use `on` here to continuously listen to the `save` event. */ melton.once( "save", function ( error ) { done(); } ); melton.name = "Melton the Magnificent"; } ).fail( done );

エンティティが変更されたかどうかを確認する

トラッキング可能を有効にすると、SitecoreはhasChangedメソッドを追加し、エンティティが変更されたかどうかを確認できます:

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntity( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) { melton.hasChanged().should.be.false; melton.name = "Melton the Magnificent"; melton.hasChanged().should.be.true; done(); } ).fail( done );

hasChangedメソッドは、null、unde、そして空文字列の間で値が変化してもtrueを返しません。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntity( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) { melton.hasChanged().should.be.false; melton.subscribed = ""; melton.hasChanged().should.be.false; melton.subscribed = null; melton.hasChanged().should.be.false; melton.subscribed = undefined; melton.hasChanged().should.be.false; done(); } ).fail( done );

変更の戻し

トラッキング可能にすると、Sitecore revertChangesメソッドが追加され、変更を元に戻すことができます。

var peopleService = new EntityService( { url: "/sitecore/api/ssc/people" } ); peopleService.fetchEntity( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) { melton.name.should.eql( "Banks Melton" ); melton.name = "Melton the Magnificent"; melton.name.should.eql( "Melton the Magnificent" ); melton.hasChanged().should.be.true; melton.revertChanges(); melton.hasChanged().should.be.false; melton.name.should.eql( "Banks Melton" ); done(); } ).fail( done );