ContextHub JavaScript API參考 contexthub-javascript-api-reference

將ContextHub元件新增至頁面後，您的指令碼即可使用ContextHub JavaScript API。

ContextHub常數 contexthub-constants

ContextHub JavaScript API定義的常數值。

事件常數 event-constants

下表列出ContextHub存放區發生的名稱事件。 另請參閱ContextHub.Utils.Eventing。

UI事件常數 ui-event-constants

下表列出ContextHub UI中發生的事件名稱。

ContextHub JavaScript API參考 contexthub-javascript-api-reference-2

ContextHub物件提供所有存放區的存取權。

函式(ContextHub) functions-contexthub

getAllStores() getallstores

傳回所有已註冊的ContextHub存放區。

此函式沒有引數。

傳回 returns-

包含所有ContextHub存放區的物件。 每個存放區都是一個物件，使用與該存放區相同的名稱。

範例 example-

下列範例會擷取所有存放區，然後擷取地理位置存放區：

var allStores = ContextHub.getAllStores();
var geoloc = allStores.geolocation

getStore(name) getstore-name

擷取存放區做為JavaScript物件。

參數 parameters-

傳回 returns-getstore-name

代表存放區的物件。

範例 example-getstore-name

下列範例會擷取地理位置存放區：

var geoloc = ContextHub.getStore("geolocation");

ContextHub.SegmentEngine.Segment contexthub-segmentengine-segment

代表ContextHub區段。 使用ContextHub.SegmentEngine.SegmentManager取得區段。

函式(ContextHub.ContextEngine.Segment) functions-contexthub-contextengine-segment

getName() getname

以字串值的形式傳回區段名稱。

getPath() getpath

以字串值的形式傳回區段定義的存放庫路徑。

ContextHub.SegmentEngine.SegmentManager contexthub-segmentengine-segmentmanager

提供ContextHub區段的存取權。

函式(ContextHub.SegmentEngine.SegmentManager) functions-contexthub-segmentengine-segmentmanager

getResolvedSegments() getresolvedsegments

傳回在目前內容中解析的區段。 此函式沒有引數。

傳回 returns-getresolvedsegments

ContextHub.SegmentEngine.Segment物件的陣列。

ContextHub.Store.Core contexthub-store-core

ContextHub存放區的基底類別。

屬性(ContextHub.Store.Core) properties-contexthub-store-core

事件 eventing

ContextHub.Utils.Eventing物件。 將此物件用於繫結函式，以儲存事件。 如需預設值和初始化的相關資訊，請參閱init(name,config)。

名稱 name

存放區的名稱。

persistence persistence

ContextHub.Utils.Persistence物件。 如需預設值和初始化的相關資訊，請參閱init(name,config)。

函式(ContextHub.Store.Core) functions-contexthub-store-core

addAllItems(tree， options) addallitems-tree-options

將資料物件或陣列與存放區資料合併。 物件或陣列中的每個索引鍵/值組都會新增至存放區（透過setItem函式）：

值可以是物件。

參數 parameters-addallitems

傳回 returns-addallitems

boolean值：

addReference(key， anotherKey) addreference-key-anotherkey

建立從一個索引鍵到另一個索引鍵的參照。 索引鍵不能參考自身。

參數 parameters-addreference

傳回 returns-addreference

boolean值：

announceReadiness() announcereadiness

觸發此存放區的ready事件。 此函式沒有引數且未傳回任何值。

clean() clean

從存放區移除所有資料。 函式沒有引數也沒有傳回值。

getItem(key) getitem-key

傳回與索引鍵相關聯的值。

參數 parameters-getitem

傳回 returns-getitem

代表索引鍵值的物件。

getKeys(includeInternals) getkeys-includeinternals

從存放區擷取金鑰。 您可以選擇擷取ContextHub架構內部使用的金鑰。

參數 parameters-getkeys

傳回 returns-getkeys

索引鍵名稱陣列（string值）。

getReferences() getreferences

從存放區擷取參考。

傳回 returns-getreferences

使用參照索引鍵作為參照索引鍵的索引的陣列：

getTree(includeInternals) gettree-includeinternals

從存放區擷取資料樹狀結構。 您可以選擇加入ContextHub架構在內部使用的索引鍵/值組。

參數 parameters-gettree

傳回 returns-gettree

代表資料樹的物件。 鍵是物件的屬性名稱。

init(name， config) init-name-config

初始化存放區。

參數 parameters-init

isEventingPaused() iseventingpaused

決定是否暫停此存放區的事件。

傳回 returns-iseventingpaused

布林值：

pauseEventing() pauseeventing

暫停存放區的事件，以免觸發任何事件。 此函式不需要引數也未傳回任何值。

removeItem(key， options) removeitem-key-options

從存放區移除索引鍵/值組。

移除索引鍵時，函式會觸發data事件。 事件資料包含存放區名稱、已移除的機碼名稱、已移除的值、機碼的新值(null)以及「移除」的動作型別。

您可以選擇性防止觸發data事件。

參數 parameters-removeitem

傳回 returns-removeitem

boolean值：

removeReference(key) removereference-key

從存放區移除參照。

參數 parameters-removereference

傳回 returns-removereference

boolean值：

reset(keepRemainingData) reset-keepremainingdata

重設存放區儲存資料的初始值。 或者，您也可以從存放區移除所有其他資料。 當存放區重設時，此存放區的事件已暫停。 此函式未傳回任何值。

初始值是在用來具現化存放區物件的設定物件的initialValues屬性中提供。

參數 parameters-reset

resolveReference(key， retry) resolvereference-key-retry

擷取參照的索引鍵。 或者，您可以指定用於解析最佳比對的反複專案數。

參數 parameters-resolvereference

傳回 returns-resolvereference

代表參考索引鍵的string值。 如果未解析任何參考，則會傳回key引數的值。

resumeEventing() resumeeventing

繼續此存放區的事件，以便觸發事件。 此函式不定義任何引數也不傳回任何值。

setItem(key， value， options) setitem-key-value-options

將索引鍵/值配對新增至存放區。

只有在索引鍵的值不同於目前為索引鍵儲存的值時，才會觸發data事件。 您可以選擇防止觸發data事件。

事件資料包含set的存放區名稱、索引鍵、先前的值、新值和動作型別。

參數 parameters-setitem

傳回 returns-setitem

boolean值：

ContextHub.Store.JSONPStore contexthub-store-jsonpstore

包含JSON資料的存放區。 資料會從外部JSONP服務擷取，或選擇性地從傳回JSON資料的服務擷取。 當您建立此類別的執行個體時，請使用init函式指定服務詳細資料。

存放區使用記憶體中持續性(JavaScript變數)。 存放區資料僅在頁面存留期內可用。

ContextHub.Store.JSONPStore擴充ContextHub.Store.Core並繼承該類別的函式。

函式(ContextHub.Store.JSONPStore) functions-contexthub-store-jsonpstore

configureService(serviceConfig， override) configureservice-serviceconfig-override

設定連線至此物件所使用JSONP服務的詳細資訊。 您可以更新或取代現有設定。 函式不會傳回任何值。

參數 parameters-configureservice

getRawResponse() getrawresponse

傳回自上次呼叫JSONP服務後快取的原始回應。 函式不需要引數。

傳回 returns-getrawresponse

代表原始回應的物件。

getServiceDetails() getservicedetails

擷取此ContextHub.Store.JSONPStore物件的服務物件。 服務物件包含建立服務URL所需的資訊。

傳回 returns-getservicedetails

具有下列屬性的物件：

getServiceURL(resolve) getserviceurl-resolve

擷取JSONP服務的URL。

參數 parameters-getserviceurl

傳回 returns-getserviceurl

代表服務URL的string值。

init(name， config) init-name-config-1

初始化ContextHub.Store.JSONPStore物件。

參數 parameters-init-1

queryService（重新載入） queryservice-reload

查詢遠端JSONP服務並快取回應。 如果自上次呼叫此函式以來的時間小於config.service.ttl的值，則不會呼叫服務，也不會變更快取的回應。 您可以選擇強制呼叫服務。 呼叫init函式以初始化存放區時，已設定config.service.ttl屬性。

查詢完成時觸發就緒事件。 如果未設定JSONP服務URL，則函式不會執行任何動作。

參數 parameters-queryservice

重設 reset

重設存放區儲存資料的初始值，然後呼叫JSONP服務。 或者，您也可以從存放區移除所有其他資料。 初始值重設時，此存放區的事件已暫停。 此函式未傳回任何值。

初始值是在用來具現化存放區物件的設定物件的initialValues屬性中提供。

參數 parameters-reset-1

resolveParameter(f) resolveparameter-f

解析指定的引數。

ContextHub.Store.PersistedJSONPStore contexthub-store-persistedjsonpstore

ContextHub.Store.PersistedJSONPStore擴充ContextHub.Store.JSONPStore，因此繼承該類別的所有函式。 不過，從JSONP服務擷取的資料會根據ContextHub持續性的設定持續存在。 （請參閱持續模式：）

ContextHub.Store.PersistedStore contexthub-store-persistedstore

ContextHub.Store.PersistedStore擴充ContextHub.Store.Core，因此繼承該類別的所有函式。 此存放區中的資料會根據ContextHub持續性的設定持續儲存。

ContextHub.Store.SessionStore contexthub-store-sessionstore

ContextHub.Store.SessionStore擴充ContextHub.Store.Core，因此繼承該類別的所有函式。 此存放區中的資料是使用記憶體內持續性(JavaScript物件)來持續儲存。

ContextHub.UI contexthub-ui

管理UI模組和UI模組轉譯器。

函式(ContextHub.UI) functions-contexthub-ui

registerRenderer(moduleType， renderer， dontRender) registerrenderer-moduletype-renderer-dontrender

向ContextHub註冊UI模組轉譯器。 在註冊轉譯器後，它可用於建立UI模組。 當您延伸ContextHub.UI.BaseModuleRenderer以建立自訂UI模組轉譯器時，請使用此函式。

參數 parameters-registerrenderer

範例 example-registerrenderer

下列範例會將轉譯器註冊為contexthub.browserinfo模組型別。

ContextHub.UI.registerRenderer('contexthub.browserinfo', new SurferinfoRenderer());

ContextHub.Utils.Cookie contexthub-utils-cookie

與Cookie互動的公用程式類別。

函式(ContextHub.Utils.Cookie) functions-contexthub-utils-cookie

exists（鍵） exists-key

判斷Cookie是否存在。

參數 parameters-exists

傳回 returns-exists

值為true的boolean表示Cookie存在。

範例 example-exists

if (ContextHub.Utils.Cookie.exists("name")) {
   // conditionally-executed code
}

getAllItems(filter) getallitems-filter

傳回索引鍵符合篩選器的所有Cookie。

參數 parameters-getallitems

傳回 returns-getallitems

Cookie的物件。 物件屬性是Cookie金鑰，金鑰值是Cookie值。

範例 example-getallitems

ContextHub.Utils.Cookie.getAllItems([/^cq-authoring/, /^cq-editor/])

getItem(key) getitem-key-1

傳回Cookie值。

參數 parameters-getitem-1

傳回 returns-getitem-1

Cookie值，或若找不到索引鍵的Cookie則為null。

範例 example-getitem-1

ContextHub.Utils.Cookie.getItem("name");

getKeys(filter) getkeys-filter

傳回符合篩選條件的現有Cookie索引鍵陣列。

參數 parameters-getkeys-1

傳回 returns-getkeys-1

字串陣列，其中每個字串是符合篩選器的Cookie索引鍵。

範例 example-getkeys-1

ContextHub.Utils.Cookie.getKeys([/^cq-authoring/, /^cq-editor/])

removeItem(key， options) removeitem-key-options-1

移除Cookie。 若要移除Cookie，此值會設為空字串，而到期日期會設為目前日期之前的日期。

參數 parameters-removeitem-1

傳回 returns-removeitem-1

此函式未傳回值。

範例 example-removeitem-1

ContextHub.Utils.Cookie.vanish([/^cq-authoring/, 'cq-scrollpos']);

setItem(key， value， options) setitem-key-value-options-1

建立指定索引鍵和值的Cookie，並將Cookie新增至目前檔案。 您可以選擇指定用來設定Cookie屬性的選項。

參數 parameters-setitem-1

傳回 returns-setitem-1

具有設定值的Cookie。

範例 example-setitem-1

ContextHub.Utils.Cookie.setItem("name", "mycookie", {
    expires: 3,
    domain: 'localhost',
    path: '/some/directory',
    secure: true
});

消失（篩選，選項） vanish-filter-options

移除符合指定篩選器的所有Cookie。 Cookie是使用getKeys函式來比對，並使用removeItem函式來移除。

參數 parameters-vanish

傳回 returns-vanish

此函式未傳回值。

ContextHub.Utils.Eventing contexthub-utils-eventing

可讓您將函式繫結和解除繫結至ContextHub存放區事件。 使用存放區的eventing屬性存取存放區的ContextHub.Utils.Eventing物件。

函式(ContextHub.Utils.Eventing) functions-contexthub-utils-eventing

off(name， selector) off-name-selector

從事件中取消繫結函式。

參數 parameters-off

傳回 returns-off

此函式未傳回任何值。

on(name， handler， selector， triggerForPastEvents) on-name-handler-selector-triggerforpastevents

將函式繫結至事件。 每次事件發生時都會呼叫函式。 或者，可以為過去發生的事件（在建立繫結之前）呼叫函式。

參數 parameters-on

傳回 returns-on

當triggerForPastEvents引數為true時，此函式傳回boolean值，指出事件是否過去發生：

如果triggerForPastEvents是false，此函式不會傳回任何值。

範例 example-on

下列範例會將函式繫結至地理位置存放區的資料事件。 函式會使用存放區中Latitude資料專案的值填入頁面上的元素。

<div class="location">
    <p>latitude: <span id="lat"></span></p>
</div>

<script>
    var geostore = ContextHub.getStore("geolocation");
    geostore.eventing.on(ContextHub.Constants.EVENT_DATA_UPDATE,getlat,"getlat");

    function getlat(){
       latitude = geostore.getItem("latitude");
       $("#lat").html(latitude);
    }
</script>

once(name， handler， selector， triggerForPastEvents) once-name-handler-selector-triggerforpastevents

將函式繫結至事件。 函式只會在第一次發生事件時呼叫一次。 您可以選擇在建立繫結之前，為過去發生的事件呼叫函式。

參數 parameters-once

傳回 returns-once

當triggerForPastEvents引數為true時，此函式傳回boolean值，指出事件是否過去發生：

如果triggerForPastEvents是false，此函式不會傳回任何值。

ContextHub.Utils.inheritance contexthub-utils-inheritance

一種公用程式類別，可讓物件繼承另一個物件的屬性和方法。

函式(ContextHub.Utils.inheritance) functions-contexthub-utils-inheritance

inherit(child， parent) inherit-child-parent

讓物件繼承另一個物件的屬性和方法。

參數 parameters-inherit

ContextHub.Utils.JSON contexthub-utils-json

提供將物件序列化為JSON格式並將JSON字串還原序列化為物件的函式。

函式(ContextHub.Utils.JSON) functions-contexthub-utils-json

parse(data) parse-data

將字串值剖析為JSON並將其轉換為Javascript物件。

參數 parameters-parse

傳回 returns-parse

JavaScript物件。

範例 example-parse

程式碼：

ContextHub.Utils.JSON.parse("{'city':'Basel','country':'Switzerland','population':'173330'}");

傳回下列物件：

Object {
   city: "Basel",
   country: "Switzerland",
   population: 173330
}

stringify(data) stringify-data

將JavaScript值和物件序列化為JSON格式的字串值。

參數 parameters-stringify

傳回 returns-stringify

序列化字串值。 當data是R egExp值時，此函式傳回空白物件。 當data為函式時，傳回undefined。

範例 example-stringify

下列程式碼：

ContextHub.Utils.JSON.stringify({
   city: "Basel",
   country: "Switzerland",
   population: 173330
});

傳回：

"{'city':'Basel','country':'Switzerland','population':'173330'}":

ContextHub.Utils.JSON.tree contexthub-utils-json-tree

此類別有助於處理要儲存或從ContextHub存放區擷取的資料物件。

函式(ContextHub.Utils.JSON.tree) functions-contexthub-utils-json-tree

addAllItems() addallitems

建立資料物件的復本，並從第二個物件將資料樹新增至該復本。 函式會傳回覆本，而不會修改任何原始物件。 當兩個物件的資料樹包含相同的索引鍵時，第二個物件的值會覆寫第一個物件的值。

參數 parameters-addallitems-1

傳回 returns-addallitems-1

包含合併資料的物件。

cleanup() cleanup

建立物件的復本，尋找並移除資料樹狀結構中不含任何值、空值或未定義值的專案，然後傳回覆本。

參數 parameters-cleanup

傳回 returns-cleanup

已清除的樹狀結構復本。

getItem() getitem

從物件擷取索引鍵的值。

參數 parameters-getitem-2

傳回 returns-getitem-2

與索引鍵對應的值。 當索引鍵具有子索引鍵時，此函式會傳回複雜的物件。 當索引鍵的值型別為undefined時，會傳回null。

範例 example-getitem-2

考量下列JavaScript物件：

myObject {
  user: {
    location: {
      city: "Basel",
        details: {
          population: 173330,
          elevation: 260
        }
      }
    }
  }

下列範常式式碼傳回值260：

ContextHub.Utils.JSON.tree.getItem(myObject, "/user/location/details/elevation");

下列範常式式碼會擷取具有子索引鍵之索引鍵的值：

ContextHub.Utils.JSON.tree.getItem(myObject, "/user");

此函式傳回以下物件：

Object {
  location: {
    city: "Basel",
    details: {
      population: 173330,
      elevation: 260
    }
  }
}

getKeys() getkeys

從物件的資料樹狀結構中擷取所有索引鍵。 您可以選擇只擷取特定鍵的子系鍵。 您也可以選擇指定擷取之索引鍵的排序順序。

參數 parameters-getkeys-2

傳回 returns-getkeys-2

索引鍵陣列。

範例 example-getkeys-2

請考量下列物件：

myObject {
  location: {
    weather: {
      temperature: "28C",
      humidity: "77%",
      precipitation: "10%",
      wind: "8km/h"
    },
    city: "Basel",
    country: "Switzerland",
    longitude: 7.5925727,
    latitude: 47.557421
  }
}

ContextHub.Utils.JSON.tree.getKeys(myObject);指令碼傳回下列陣列：

["/location", "/location/city", "/location/country", "/location/latitude", "/location/longitude", "/location/weather", "/location/weather/humidity", "/location/weather/precipitation", "/location/weather/temperature", "/location/weather/wind"]

removeItem() removeitem

建立指定物件的復本，從資料樹狀結構中移除指定的分支，並傳回修改後的復本。

參數 parameters-removeitem-2

傳回 returns-removeitem-2

移除金鑰的原始資料物件復本。

範例 example-removeitem-2

請考量下列物件：

myObject {
  one: {
    foo: "bar",
    two: {
      three: {
        four: {
          five: 5,
          six: 6
        }
      }
    }
  }
}

以下範例指令碼會從資料樹狀結構中移除/one/two/three/four分支：

myObject = ContextHub.Utils.JSON.tree.removeItem(myObject, "/one/two/three/four");

此函式傳回以下物件：

myObject {
  one: {
    foo: "bar"
  }
}

sanizeKey(key) sanitizekey-key

清理字串值，使其可用作索引鍵。 若要清除字串，此函式會執行下列動作：

使用結果陣列建立可用的索引鍵。

參數 parameters-sanitizekey

傳回 returns-sanitizekey

string值的陣列，其中每個字串都是以斜線分隔的key部分。 代表已清除的金鑰。 如果經過清理的陣列長度為零，此函式會傳回null。

範例 example-sanitizekey

下列程式碼會清理字串以產生陣列["this", "is", "a", "path"]，然後從陣列產生索引鍵"/this/is/a/path"：

var key = " / this////is/a/path ";
ContextHub.Utils.JSON.tree.sanitizeKey(key)
"/" + ContextHub.Utils.JSON.tree.sanitizeKey(key).join("/");

setItem(tree， key， value) setitem-tree-key-value

將索引鍵/值配對新增至物件復本的資料樹狀結構。 如需資料樹狀結構的相關資訊，請參閱持續性。

參數 parameters-setitem-2

傳回 returns-setitem-2

包含key/ value配對的tree物件復本。

範例 example-setitem-2

考量下列JavaScript程式碼：

var myObject = {
     user: {
        location: {
           city: "Basel"
           }
        }
     };

var myKey = "/user/location/details";

var myValue = {
      population: 173330,
      elevation: 260
     };

myObject = ContextHub.Utils.JSON.tree.setItem(myObject, myKey, myValue);

ContextHub.Utils.storeCandidates contexthub-utils-storecandidates

可讓您註冊候選商店並取得已註冊的候選商店。

函式(ContextHub.Utils.storeCategors) functions-contexthub-utils-storecandidates

getRegisteredCandidates(storeType) getregisteredcandidates-storetype

傳回註冊為候選商店的商店型別。 擷取特定存放區型別或所有存放區型別的已登入候選者。

參數 parameters-getregisteredcandidates

傳回 returns-getregisteredcandidates

存放區型別的物件。 物件屬性是存放區型別名稱，而屬性值是已登入的存放區候選陣列。

getStoreFromCandidates(storeType) getstorefromcandidates-storetype

從註冊的候選者中傳回存放區型別。 如果註冊了多個相同名稱的存放區型別，此函式會傳回具有最高優先順序的存放區型別。

參數 parameters-getstorefromcandidates

傳回 returns-getstorefromcandidates

代表已登入的存放區候選者的物件。 如果未登入要求的存放區型別，則會擲回錯誤。

getSupportedStoreTypes() getsupportedstoretypes

傳回註冊為候選商店的商店型別名稱。 此函式不需要引數。

傳回 returns-getsupportedstoretypes

字串值的陣列，其中每個字串是用來登入存放區候選的存放區型別。 檢視ContextHub.Utils.storeCandidates.registerStoreCandidate函式的storeType引數。

registerStoreCandidate(store， storeType， priority， applies) registerstorecandidate-store-storetype-priority-applies

使用名稱和優先順序將存放區物件註冊為存放區候選。

優先順序是指示同名存放區之重要性的數字。 當使用與已登入的候選商店相同的名稱登入候選商店時，會使用具有較高優先順序的候選商店。 註冊存放區候選時，只有當優先順序高於同名已註冊存放區候選時，才會註冊存放區。

參數 parameters-registerstorecandidate

範例 example-registerstorecandidate

ContextHub.Utils.storeCandidates.registerStoreCandidate(myStoreCandidate,
                                'contexthub.mystorecandiate', 0);