您可以建立要在 Oracle Analytics 中使用的自訂資料動作 Plug-in。
資料動作 Plug-in 可擴充 Oracle Analytics,並讓使用者能夠選取視覺化中的資料點及呼叫特定的動作。Oracle Analytics 提供一組核心的資料動作,該動作涵蓋許多常見使用案例,但您可以透過寫入自己的資料動作 Plug-in ,更進一步擴充此功能。
您必須對以下內容具有基本瞭解,才能建立自訂資料動作 Plug-in:
資料動作 Plug-in 利用資料動作架構來提供已緊密整合至 Oracle Analytics 使用者介面的自訂資料導向動作。
當使用者呼叫資料動作時,資料動作管理員會將要求相關資訊環境 (例如,限定資料參照、計量值、篩選和中繼資料) 傳遞給負責處理要求的資料動作 Plug-in。Oracle 提供四種類型的資料動作 Plug-in:CanvasDataAction
、URLNavigationDataAction
、HTTPAPIDataAction
和 EventDataAction
。您可以延伸這些資料動作 Plug-in 類型及其抽象基礎類別,以提供自己的資料動作。
資料動作類別包括「瀏覽至 URL」、「HTTP API」、「瀏覽至工作區」和「事件」動作:
GET/POST/PUT/DELETE/TRACE
命令以 HTTP API 為目標,且不會產生新頁籤。相反地,會檢查 HTTP 狀態代碼,並顯示暫時成功或失敗訊息。瀏覽至 URL 和 HTTP API 資料動作類別類型都會使用記號語法,將視覺化的資料或中繼資料引入 URL
和 POST
參數中。
URL 記號取代
HTTP 資料動作可以使用傳送至資料動作的相關資訊環境值取代 URL 中的記號。例如,限定資料參照值、篩選值、使用者名稱、工作簿路徑以及工作區名稱。
記號 | 附註 | 取代為 | 範例 | 結果 |
---|---|---|---|---|
${valuesForColumn:COLUMN} |
NA | 限定資料參照的資料欄顯示值 | ${valuesForColumn: "Sales"."Products"."Brand"} |
BizTech,FunPod |
${valuesForColumn:COLUMN, separator:"/"} |
任何可能取代為多個值的記號皆支援選擇性區隔符號選項。separator 預設為逗號 (,),但您可以將其設為任何字串。您可以使用反斜線 (\) 在此字串內遁離雙引號。 |
限定資料參照的資料欄顯示值 | ${valuesForColumn: "Sales"."Products"."Brand"} |
BizTech,FunPod |
${valuesForColumn:COLUMN, separationStyle:individual} |
任何 separationStyle 皆預設為 delimited ,但如果使用者需要對每個值產生個別 URL 參數,您可以將它設為 individual 。 |
限定資料參照的資料欄顯示值 | &myParam=${valuesForColumn: "Sales"."Products"."Brand"} |
&myParam=BizTech&myParam=FunPod |
${keyValuesForColumn:COLUMN} |
NA | 限定資料參照的資料欄索引鍵值。 | ${keyValuesForColumn:COLUMN} |
10001,10002 |
${env:ENV_VAR} |
支援的環境變數包括:sProjectPath 、sProjectName 、sCanvasName 、sUserID 和 sUserName 。 |
環境變數。 | ${env:'sUserID'} |
myUserName |
您可以定義當使用者呼叫資料動作時傳送的相關資訊環境。
您可以定義當您建立資料動作時要傳送多少相關資訊環境至資料動作。
限定資料參照
呼叫資料動作時,系統會使用 LogicalFilterTree
物件陣列為每個標示的資料點產生限定資料參照。LogicalFilterTree
包含多個在樹狀結構中排列的 LogicalFilterNode
物件。此物件包括:
環境變數
除了描述每個標示資料點的資料和中繼資料之外,某些資料動作可能還需要描述呼叫資料動作的環境其進一步的相關資訊環境。此類環境變數包括:
您可以使用 API 類別建立資料動作。
AbstractDataAction
的具體類別:
CanvasDataAction
URLNavigationDataAction
HTTPAPIDataAction
EventDataAction
DataActionPluginHandler
所管理。DataActionManager
進行處理。資料動作模型類別有數種不同的類型。
AbstractDataAction
此類別負責下列作業:
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) <<abstract>>
透過傳送的相關資訊環境呼叫資料動作 - 應該僅限由 DataActionManager
呼叫。
+ getGadgetInfos(oReport): AbstractGadgetInfo[] <<abstract>>
建構並傳回負責呈現使用者介面欄位以編輯此類型之資料動作的 GadgetInfos
。
+ validate() : DataActionError
驗證資料動作,如果有效則傳回空值,如果無效則傳回 DataActionError
。
+ getSettings():JSON
將資料動作的「剔除模型」序列化至已準備好包含在報表中的 JSON (使用 komapping.toJS(_koModel))。
+ createNameGadgetInfo(oReport) : AbstractGadgetInfo
建構並傳回可呈現資料動作的名稱欄位的 GadgetInfo
。
+ createAnchorToGadgetInfo(oReport) : AbstractGadgetInfo
建構並傳回可呈現資料動作的定錨至欄位的 GadgetInfo
。
+ createPassValuesGadgetInfo(oReport) : AbstractGadgetInfo
建構並傳回可呈現資料動作的傳送值欄位的 GadgetInfo
。
子類別可能不需要基礎類別提供的所有 GadgetInfo
,因此它們可能不需要呼叫所有這些方法。透過此方式將每個欄位的呈現方式分離出來,子類別可以自由挑選其所需的小工具。某些子類別甚至可以選擇提供這些一般資料動作小工具的其他實行。
CanvasDataAction、URLNavigationDataAction、HTTPAPIDataAction、EventDataAction
這些是基本類型的資料動作其具體類別。這些類別可自行運作以提供給這些類型的資料動作一般使用者介面。它們也可以作為便利的基礎類別,讓自訂資料動作 Plug-in 延伸。
GET/POST/PUT/DELETE/TRACE
要求,並以程式設計的方式處理 HTTP Response
。每個類別負責的作業如下:
invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext)
此方法應藉由將在 KOModel 中定義的特性與指定的 DataActionContext
物件結合來呼叫資料動作。
getGadgetInfos(oReport): AbstractGadgetInfo[]
此方法應:
AbstractGadgetInfos
的陣列。AbstractGadgetInfo
推送至陣列的個別 createXXXGadgetInfo()
方法。這些具體類別的子類別可能不需要使用其自訂使用者介面之超級類別所提供的所有小工具。透過此方式將每個小工具的建構分離出來,子類別可以自由挑選其所需的小工具。
DataActionKOModel、ValuePassingMode
DataActionKOModel
類別提供不同子類別之 AbstractDataAction
所共用的基礎 KOModel。請參閱 DataActionKOModel 類別。
資料動作有數種不同的服務類別。
DataActionManager
所有與 DataActionManager
的通訊都使用實行事件處理程式的 ClientEvents
.DataActionManager
,以進行下列作業:
DataActionContext、EnvironmentContext
呼叫資料動作時,DataActionContext
類別會包含已傳送至目標的相關資訊環境。
getColumnValueMap()
傳回以屬性資料欄名稱作為索引鍵的屬性資料欄值對應。這些項目定義呼叫資料動作的資料點其限定資料參照。
getLogicalFilterTrees()
傳回 LogicalFilterTrees
物件,此物件描述呼叫資料動作的特定資料點其限定資料參照 (請參閱 InteractionService
以瞭解詳細資訊)。
getEnvironmentContext()
EnvironmentContext
類別的執行處理,描述來源環境,例如:
getProjectPath()
getCanvasName()
getUserID()
getUserName()
getReport()
傳回呼叫資料動作的報表。
DataActionHandler
DataActionHandler
類別會註冊各種資料動作 Plug-in。其 API 與其他 Plug-in 處理程式 (例如,VisualizationHandler
) 大致一致。
DataActionHandler
類別提供下列公用方法:
getClassName(sPluginType:String) : String
傳回指定資料動作類型的完整類別名稱。
getDisplayName(sPluginType:String) : String
傳回指定資料動作類型的翻譯顯示名稱。
getOrder(sPluginType:String) : Number
傳回用於將資料動作類型清單依偏好順序排序的數字。
DataActionHandler
類別提供下列靜態方法:
getDependencies(oPluginRegistry:Object) : Object.<String, Array>
傳回涵蓋所有已註冊資料動作類型的相依性對應。
getHandler(oPluginRegistry:Object, sExtensionPointName:String, oConfig:Object) : DataActionPluginHandler
建構並傳回 DataActionHandler
類別的新執行處理。
DataActionUpgradeHandler
當報表開啟時,UpgradeService
會呼叫 DataActionUpgradeHandler
類別。
DataActionHandler
類別提供兩個主要方法:
deferredNeedsUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext) : Promise
傳回解析為布林值的 Promise
,指出指定的資料動作是否必須升級 (true
) 或 (false
)。此方法是藉由比較資料動作執行處理與從資料動作的建構子,來決定是否必須升級資料動作。
performUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext, oUpgradeContext) : Promise
在指定的資料動作上執行升級,並解析 Promise
。升級本身是透過呼叫資料動作的 upgrade()
方法執行 (只有正在升級的資料動作其特定的子類別本身可以升級)。
getOrder(sPluginType:String) : Number
傳回用於將資料動作類型清單依偏好順序排序的數字。
資料動作在建立使用者介面欄位時,以及在使用者呼叫資料動作時,會與 Oracle Analytics 程式碼互動。
建立新資料動作執行處理的欄位
此互動會在 Oracle Analytics 想要呈現資料動作使用者介面欄位時啟動。方法為:
PanelGadgetInfo
,作為資料動作傳回的 GadgetInfos
其父項 GadgetInfo
。getGadgetInfos()
。GadgetInfos
,作為第一個步驟中所建立的 PanelGadgetInfo
其子項。PanelGadgetInfo
的PanelGadgetView
。PanelGadgetView
,此為 HTMLElement
的容器。PanelGadgetView
註冊為已經連附至 HostedComponent
樹狀結構的 HostedComponent
其子項 HostedComponent
。
這會在「面板」小工具內,依照 getGadgetInfos()
所傳回陣列中的顯示順序,呈現資料動作的小工具。
呼叫資料動作
此互動會在使用者透過 Oracle Analytics 使用者介面 (例如,從視覺化中資料點上的彈出式功能表) 呼叫資料動作時啟動。
程式碼會執行下列作業以回應使用者互動:
INVOKE_DATA_ACTION
事件,其中包含資料動作的 ID、呼叫資料動作的 DataVisualization
,以及 TransientVizContext
物件。DataActionManager
透過下列方法處理此事件:
DataVisualization
中取得已標記資料點的 LogicalFilterTrees
。DataActionContext
,其中包含所有要傳送至資料動作其目標的資訊。invoke(oDataActionContext)
。本主題顯示 CanvasDataAction
資料動作的 plugin.xml 檔案範例。
plugin.xml 範例
<?xml version="1.0" encoding="UTF-8"?> <tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle" xmlns:viz="http://plugin.frameworks.tech.bi.oracle/extension-points/visualization" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="obitech-currencyconversion" name="Oracle BI Currency Conversion" version="0.1.0.@qualifier@" optimizable="true" optimized="false"> <tns:resources> <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/> <tns:resource-folder id="nls" path="resources/nls" optimizable="true"> <tns:extensions> <tns:extension name="js" resource-type="script"/> </tns:extensions> </tns:resource-folder> </tns:resources> <tns:extensions> <tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0"> <tns:configuration> { "resourceBundle": "obitech-currencyconversion/nls/messages", "properties": { "className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction", "displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" }, "order": 100 } } </tns:configuration> </tns:extension> </tns:extensions> </tns:obiplugin>
開始寫入自訂資料動作 Plug-in 之前,請決定要延伸的現有資料動作類別。選擇可提供與您想要的資料動作執行功能最相符的資料動作類別。
每個資料動作都繼承自類別圖表所示的 AbstractDataAction
類別。類別圖表顯示兩個抽象資料動作類別 (AbstractDataAction
和 AbstractHTTPDataAction
) 以及您可以延伸的四個具體動作類別 (CanvasDataAction
、URLNavigationDataAction
、HTTPAPIDataAction
和 EventDataAction
)。您提供的每個資料動作必須延伸其中一個類別。您要延伸的類別取決於當您呼叫資料動作時想要實行的行為。大多數的第三方資料動作可能會延伸 URLNavigationDataAction
、HTTPAPIDataAction
或 EventDataAction
。
無論您延伸哪一個類別,呼叫您的資料動作時,將會提供您描述呼叫資料動作的完整資料點相關資訊環境的中繼資料。請參閱資料動作相關資訊環境。
AbstractDataAction
是抽象基礎類別,所有類型的資料動作皆繼承自此類別。它負責提供子類別可以使用的通用功能和預設行為。
AbstractDataAction
所有類型的資料動作皆為 AbstractDataAction
基礎類別的子類別。它提供一組所有資料動作皆通用的核心功能。除非是要建立在呼叫時會執行多個類型動作的複雜資料動作,或者您必須執行具體類別不支援的一些動作,否則您不應直接延伸此類別。如果您需要建立複雜資料動作,請考慮延伸最能提供您所需功能的具體類別。
AbstractDataAction 語法
+ AbstractDataAction(oKOModel)
+ getKOViewModel():DataActionKOModel
+ createFromJS(fDataActionConstructor, sClassName, oDataActionKOModelUS) : AbstractDataAction
+ invoke(oActionContext, oDataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[] + validate() : DataActionError
+ getSettings() : Object + requiresActionContextToInvoke() : Boolean + isAllowedHere() : Boolean
# createNameGadgetInfo(oReport) : AbstractGadgetInfo # createAnchorToGadgetInfo(oReport) : AbstractGadgetInfo # createPassValuesGadgetInfo(oReport) : AbstractGadgetInfo
AbstractDataAction
的每個子類別都有可能建立 DataActionKOModel
自己的子類別。DataActionKOModel
基礎類別提供下列特性:
DataActionKOModel、ValuePassingMode
sID:String
指定給資料動作執行處理的唯一 ID。
sClass:String
此特定類型的資料動作其類別名稱。
sName:String
指定給資料動作執行處理的顯示名稱。
sVersion
sScopeID
eValuePassingMode:ValuePassingMode
傳送相關資訊環境值時所使用的模式。模式可以是其中一個 ValuePassingMode
值 (ALL、ANCHOR_DATA、NONE、CUSTOM
)。
aAnchorToColumns: ColumnKOViewModel[]
將此資料動作定錨至的資料欄。此為選擇性特性。若未提供,則資料動作可在所有資料欄上使用。
aContextColumns : ColumnKOViewModel[]
相關資訊環境中包含此資料動作的資料欄,已於呼叫資料動作時傳送至資料動作目標。若未提供,所有標示的資料欄都會包含在相關資訊環境中。
CanvasDataAction
是 AbstractDataAction
基礎類別的子類別。您可以延伸此實體類別來提供您需要的功能。
CanvasDataAction
使用 CanvasDataAction
類別從視覺化中的資料點瀏覽至不同的工作區。您要瀏覽的工作區可以位於相同或不同的工作簿中。所有來源視覺化的作用中篩選條件會與描述資料點本身的「限定資料參照」一起傳送至目標工作區。如果您的資料動作需要瀏覽至其他工作區,則此類別為您的資料動作應該延伸的類別。
+ CanvasDataAction(oKOModel)
+ create(s)ID_sName) : CanvasDataAction + upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[] + validate() : DataActionError
# createProjectGadgetInfo(oReport) : AbstractGadgetInfo # createCanvasGadgetInfo(oReport) : AbstractGadgetInfo
EventDataAction
是 AbstractDataAction
基礎類別的子類別。您可以延伸此實體類別來提供您需要的功能。
EventDataAction
使用 EventDataAction
類別來發布從屬端事件。您可以接著註冊一或多個監聽事件並執行自己動作的訂戶。在較複雜的使用案例中使用此類型的資料動作,其中您已具有大量的程式碼,且能讓資料動作程式碼與呼叫資料動作時執行必要動作的程式碼保持鬆散結合。
+ EventDataAction(oKOModel)
+ create(sID_sName) : EventDataAction + upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[] + validate() : DataActionError
# createEventGadgetInfo(oReport) : AbstractGadgetInfo
AbstractHTTPDataAction
是抽象基礎類別,URLNavigationDataAction
和 HTTPAPIDataAction
子類別會繼承此類別的通用功能與預設行為。
AbstractHTTPDataAction
AbstractHTTPDataAction
抽象基礎類別由 URLNavigationDataAction
和 HTTPAPIDataAction
類別所共用。如果資料動作必須以新的瀏覽器頁籤開啟網頁,您必須延伸 URLNavigationDataAction
。如果資料動作必須呼叫 HTTP API,則您應延伸 HTTPAPIDataAction
。您可以決定最好是直接延伸 AbstractHTTPDataAction
。
+ HTTPDataAction(oKOModel)
+ validate() : DataActionError
# createURLGadgetInfo(oReport) : AbstractGadgetInfo
URLNavigationDataAction
是 AbstractHTTPDataAction
基礎類別的子類別。
URLNavigationDataAction
使用 URLNavigationDataAction
類別以在新的瀏覽器頁籤中開啟特定的 URL。您可以使用當使用者呼叫資料動作時,選取的資料點衍生的值所取代的記號來撰寫 URL。資料點值會作為資料動作相關資訊環境的一部分傳送至外部網頁。例如,使用 CustomerID
資料欄建立呼叫的資料動作,此動作會在客戶關係管理應用程式 (例如 Oracle Sales Cloud) 中開啟客戶的網頁。
+ URLNavigationDataAction(oKOModel)
+ create(sID_sName) : URLNavigationDataAction + upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[]
HTTPAPIDataAction
是 AbstractHTTPDataAction
基礎類別的子類別。您可以延伸此實體類別來提供您需要的功能。
HTTPAPIDataAction
使用 HTTPAPIDataAction
類別來呼叫 HTTP API,方法是建立非同步 XMLHTTPRequest
(XHR) 並將其送出至指定的 URL。HTTP 回應代碼可讓訊息短暫顯示在工作區上。例如,您可以自訂要求將 JSON 或 XML 有效負載傳送至 REST 或 SOAP 伺服器,也可以自訂回應處理程式以顯示自訂使用者介面。
為了讓 HTTPAPIDataAction
資料動作運作,您必須將要存取的 HTTP API 其 URL 新增至「安全網域」清單,並對其授予連線存取權。請參閱註冊安全網域。
+ HTTPAPIDataAction(oKOModel)
+ create(sID_sName) : HTTPAPIDataAction + upgrade(oOldDataActionJS) : Object
+ invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) + getGadgetInfos(oReport) : AbstractGadgetInfo[]
# createHTTPMethodGadgetInfo(oReport) : AbstractGadgetInfo # createPostParamGadgetInfo(oReport) : AbstractGadgetInfo
您使用一系列的命令產生開發環境,並在其中填入 HTTP API 資料動作,以及建立自訂資料動作 Plug-in 時所需的資料夾和檔案。
所有 Plug-in 檔案都遵循相同的基本結構。您可以手動建立檔案和資料夾,也可以從範本產生。可使用的工具是 Oracle Analytics Desktop 隨附的 Oracle Analytics Desktop 軟體開發套件 (SDK) 的一部分。請參閱 Oracle Analytics Desktop SDK 參考資料。
使用下列命令產生開發環境,並在其中填入 HTTP API 資料動作。
新產生的資料動作開發環境包含下列資料夾和檔案:
1 %PLUGIN_DEV_DIR%\src\customdataaction 2 company-mydataaction\ 3 extensions\ 4 oracle.bi.tech.plugin.dataaction\ 5 company.mydataaction.json 6 nls\ 7 root\ 8 messages.js 9 messages.js 10 mydataaction.js 11 mydataactionstyles.css 12 plugin.xml
company-mydataaction
資料夾為您所指定的 ID。nls
資料夾包含用於具體化字串的檔案,以便讓 Plug-in 提供原生語言支援。nls\root
資料夾底下之檔案中的字串為預設字串,在沒有要求語言的翻譯時使用。messages.js
檔案包含您可新增的 Plug-in 具體化字串。messages.js
檔案必須包含對每個要為其提供本地化字串之額外語言所新增的項目。您必須在每個您要為其新增翻譯的地區設定 nls
資料夾底下新增相對應的資料夾。每個資料夾必須包含同一組檔案,且檔案名稱與 nls\root
資料夾底下新增的檔案名稱相同。mydataaction.js
檔案是新產生的 JavaScript 模組範本,提供開發自訂資料動作的起始點。mydataactionstyles.css
檔案可包含任何您要新增的 CSS 樣式,以及資料動作的使用者介面可以使用的 CSS 樣式。plugin.xml
檔案會在 Oracle Analytics 註冊您的 Plug-in 與其檔案。選擇您要延伸的資料動作子類別,並已產生必要的資料夾與檔案之後,就可以開始寫入新資料動作特定的程式碼。
您可以從 %PLUGIN_DEV_DIR%\src\dataaction
底下找到新產生的資料動作程式碼。請參閱產生的資料夾和檔案以取得檔案與資料夾結構的說明。您必須編輯的主要檔案是 JavaScript 檔案。例如,如果您的自訂資料動作 ID 為 company.MyDataaction
,則您要尋找的檔案是 %PLUGIN_DEV_DIR%\src\dataaction\company-mydataaction\mydataaction.js
。
如果資料動作具有需要儲存的其他特性,您必須將它們作為可監測特性新增至「剔除模型」。如果提供給資料動作的 ID 為company.MyDataaction
,則「剔除模型」的名稱為 mydataaction.MyDataActionKOModel
(靠近 mydataaction.js
頂端的位置)。依照預設,會設定此「剔除模型」以延伸資料動作其超級類別所使用的「剔除模型」,因此您只需要新增其他特性至該模型中。
對於延伸 HTTPAPIDataAction
基礎類別的資料動作,請使用類似如下的程式碼:
1 - mydataaction.MydataactionKOModel = function (sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams) 2 - { 3 - mydataaction.MydataactionKOModel.baseConstructor.call(this, sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams); 4 - }; 5 - jsx.extend(mydataaction.MydataactionKOModel, dataaction.HTTPAPIDataActionKOModel);
baseConstructor
),您會將其中一個「剔除模型」其超級類別處理的所有特性值傳送至此建構子。使用類似如下的程式碼新增字串和陣列,以設定由資料動作進行保存的特性。
1 mydataaction.MydataactionKOModel = function (sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams) 2 { 3 mydataaction.MydataactionKOModel.baseConstructor.call(this, sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams); 4 5 6 // Set Defaults 7 sMyString = sMyString || "My default string value"; 8 aMyArray = aMyArray || []; 9 10 11 // Asserts 12 jsx.assertString(sMyString, "sMyString"); 13 jsx.assertArray(aMyArray, "aMyArray"); 14 15 16 // Add observable properties 17 this.sMyString = ko.observable(sMyString); 18 this.aMyArray = ko.observableArray(aMyArray); 19 }; 20 jsx.extend(mydataaction.MydataactionKOModel, dataaction.HTTPAPIDataActionKOModel);
每個資料動作都必須實行各種不同的方法才能正常運作,因此您只需要覆寫這些實行您要變更之行為的方法。
一般方法
假設延伸其中一個具體資料動作類別,例如 HTTPAPIDataAction
,其中大多數的必要方法都已經實行,因此您只需要覆寫實行想要變更之行為的方法。
本節描述各種方法及其預期的功能。
所有類型的資料動作必須實行此處描述的方法。
create(sID, sName)
當您建立的是新資料動作,並從下拉式功能表中選取資料動作類型時,會呼叫 create()
靜態方法。此方法負責下列作業:
「剔除模型」類別必須具有與所有其他特性的合理預設值一同傳送給 create()
方法的 ID 和名稱。例如,針對幣別轉換資料動作,您可能想要設定要轉換為「美元」的預設幣別。「剔除模型」是可提供您預設值的正確位置。
invoke(oActionContext, oDataActionContext)
當使用者從視覺化中的資料點其彈出式功能表呼叫您的資料動作時,系統會呼叫 invoke()
方法。此方法會傳送 DataActionContext
引數,此引數包含描述所選資料點、視覺化、篩選、工作簿及階段作業的中繼資料。請參閱資料動作服務類別。
validate()
當使用者按一下資料動作對話方塊中的確定時,系統會對每個資料動作呼叫 validate()
方法。validate()
方法會傳回 null
來指出所有項目皆有效,如果部分內容無效則傳回 DataActionError
。如果對話方塊中的其中一個資料動作有錯誤,則錯誤會讓對話方塊無法關閉,並會向使用者顯示錯誤訊息。此方法使用 this.validateName()
方法驗證資料動作的名稱。
getGadgetInfos(oReport)
系統會呼叫 getGadgetInfos()
方法,讓使用者介面顯示資料動作特性欄位。此方法會按照您要在使用者介面顯示的順序傳回 GadgetInfos
陣列。系統提供所有最常見類型之欄位 (例如文字、下拉式清單、密碼、複選、選項按鈕、核取方塊) 的小工具,但如果您想要更複雜的欄位 (例如,其中多個小工具群組在一起,或視您選取的選項顯示不同的小工具欄位),您可以建立自訂小工具。最佳做法是建立您要在陣列中建構每個 GadgetInfo
的方法,因為這會讓潛在子類別更容易從您提供的 GadgetInfo
中挑選。如果您遵循此最佳做法,則已經有不同的資料動作基礎類別實行的各種方法,可為它們在其使用者介面中所使用的每個欄位傳回 GadgetInfo
。如果您還需要其中一個 GadgetInfo
,則您可以呼叫對應的 create****GadgetInfo()
方法,並將其傳回值推送至小工具陣列。
isAllowedHere(oReport)
當使用者在視覺化中的資料點上按一下滑鼠右鍵,且使用者介面開始產生彈出式功能表時,系統會呼叫 isAllowedHere()
方法。如果有與所選資料點相關的資料動作,則方法會傳回 true
,且資料動作會顯示在彈出式功能表中。如果方法傳回 false
,則資料動作不會顯示在彈出式功能表中。請考量接受繼承自超級類別的預設行為。
upgrade(oOldDataActionJS)
若是要建立您的第一個資料動作,請勿使用 upgrade(oOldDataActionJS)
方法。只有在您已建立第一個「剔除模型」之後,且正在對第二版「剔除模型」的特性進行大幅變更時,才使用此模型。例如,如果第一版的資料動作將 URL 儲存在其「剔除模型」中,但您決定下一版會將 URL 元件部分儲存在個別的特性中 (例如 protocol
、hostname
、port
、path
、queryString
和 bookmark
)。
第二版「剔除模型」程式碼會要求開啟已與第一版「剔除模型」程式碼一起儲存的資料動作,這會造成問題。為了解決此問題,系統會識別目前的資料動作程式碼版本比正在開啟的資料動作版本還要新,並對新資料動作類別呼叫 upgrade()
方法,然後在舊的資料動作「剔除模型」中傳送 (序列化至 JSON 物件)。接著您可以使用舊 JSON 物件來填入新的「剔除模型」,並傳回升級版本的 JSON 物件。這可確保當您改善資料動作程式碼時,舊資料動作中繼資料會繼續運作。
HTTPAPIDataAction 方法
延伸 HTTPAPIDataAction
類別時,它會提供下列的其他方法供您選擇覆寫:
getAJAXOptions(oDataActionContext)
getAJAXOptions()
方法由資料動作的 invoke()
方法呼叫。getAJAXOptions()
方法會建立 AJAX Options
物件,此物件描述您要資料動作提出的 HTTP 要求。oDataActionContext
物件會傳送給 getAJAXOptions()
方法,該物件包含描述所選資料點、視覺化、篩選、工作簿及階段作業的中繼資料。依據您嘗試整合的 HTTP API 要求設定 AJAX Options
,並指定當 HTTPRequest
成功或產生錯誤時所要呼叫的函數。請參閱 JQuery 網站以取得 jQuery.ajax
物件及其特性的說明。
下列實行繼承自 HTTPAPIDataAction
類別。您必須重新寫入用以指定需求的繼承方法。例如,形成 HTTP 要求與處理 HTTP 回應的程式碼。此實行非常實用,因為它會顯示傳送給 getAJAXOptions()
函數的參數、預期傳回的物件及提供如何在該方法內建構程式碼的明確範例。
1 /** 2 * This method returns an object containing the AJAX settings used when the data action is invoked. 3 * Subclasses may wish to override this method to provide their own behavior. 4 * @param {module:obitech-reportservices/dataactionmanager.DataActionContext} oDataActionContext The context metadata describing where the data action was invoked from. 5 * @returns {?object} A JQuery AJAX settings object (see http://api.jquery.com/jQuery.ajax/ for details) - returns null if there is a problem. 6 */ 7 dataaction.HTTPAPIDataAction.prototype.getAJAXOptions = function (oDataActionContext) 8 { 9 jsx.assertInstanceOfModule(oDataActionContext, "oDataActionContext", "obitech-reportservices/dataactionmanager", "DataActionContext"); 10 11 var oAJAXOptions = null; 12 var oKOViewModel = this.getKOViewModel(); 13 var sURL = oKOViewModel.sURL(); 14 if (sURL) 15 { 16 // Parse the URL 17 var sResultURL = this._parseURL(sURL, oDataActionContext); 18 if (sResultURL) 19 { 20 // Parse the POST parameters (if required) 21 var eHTTPMethod = oKOViewModel.eHTTPMethod()[0]; 22 var sData = null; 23 if (eHTTPMethod === dataaction.HTTPDataActionKOModel.HTTPMethod.POST) 24 { 25 var sPOSTParams = oKOViewModel.sPOSTParams(); 26 sData = sPOSTParams.replace(dataaction.AbstractHTTPDataAction.RegularExpressions.LINE_END, "&"); 27 sData = this._parseURL(sData, oDataActionContext, false); 28 } 29 oAJAXOptions = { 30 type: eHTTPMethod, 31 url: sResultURL, 32 async: true, 33 cache: false, 34 success: function (/*oData, sTextStatus, oJQXHR*/) 35 { 36 oDataActionContext.getReport().displaySuccessMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_SUCCESSFUL.format(oKOViewModel.sName())); 37 }, 38 error: function (oJQXHR/*, sTextStatus, sError*/) 39 { 40 oDataActionContext.getReport().displayErrorMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_FAILED.format(oKOViewModel.sName(), oJQXHR.statusText, oJQXHR.status)); 41 } 42 }; 43 if (sData) 44 { 45 oAJAXOptions.data = sData; 46 } 47 } 48 } 49 return oAJAXOptions; 50 };
對於部分「剔除模型」變更,您需要使用升級處理程式來升級資料動作 Plug-in。
改善資料動作 Plug-in 但不變更剔除模型時,通常要編輯 JavaScript 或 CSS 檔案、建立新壓縮檔,以及使用新壓縮檔取代現有資料動作 Plug-in。不過,如果您已變更資料動作的「剔除模型」,則可能需要變更資料動作 VERSION
特性以及提供升級處理程式。
決定是否需要使用升級處理程式:
每個資料動作 Plug-in 都需要 plugin.xml 檔案,且每個 plugin.xml 檔案可以包含任意數目的資料動作。
plugin.xml 檔案包含 tns:obiplugin
、tns:resources
以及 tns:extension
這三個主要區段。
plugin.xml 範例
此範例顯示一個資料動作的典型 plugin.xml 檔案。
1 <?xml version="1.0" encoding="UTF-8"?> 2 <tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle" 3 id="obitech-currencyconversion" 4 name="Oracle BI Currency Conversion" 5 version="0.1.0.@qualifier@" 6 optimizable="true" 7 optimized="false"> 8 9 10 <tns:resources> 11 <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/> 12 <tns:resource-folder id="nls" path="resources/nls" optimizable="true"> 13 <tns:extensions> 14 <tns:extension name="js" resource-type="script"/> 15 </tns:extensions> 16 </tns:resource-folder> 17 </tns:resources> 18 19 20 <tns:extensions> 21 <tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0"> 22 <tns:configuration> 23 { 24 "host": { "module": "obitech-currencyconversion/currencyconversion" }, 25 "resourceBundle": "obitech-currencyconversion/nls/messages", 26 "properties": 27 { 28 "className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction", 29 "displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" }, 30 "order": 100 31 } 32 } 33 </tns:configuration> 34 </tns:extension> 35 </tns:extensions> 36 37 </tns:obiplugin>
tns:obiplugin
區段主要定義所有類型之 Plug-in 的通用特性。
Plug-in 特性
tns:obiplugin
區段會定義所有 Plug-in 類型通用的特性。
1 <?xml version="1.0" encoding="UTF-8"?> 2 <tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle" 3 id="obitech-currencyconversion" 4 name="Oracle BI Currency Conversion" 5 version="0.1.0.@qualifier@" 6 optimizable="true" 7 optimized="false">
tns
命名空間宣告。tns:resources
區段主要註冊計入 Plug-in 的所有檔案。
資源
1 <tns:resources> 2 <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/> 3 <tns:resource-folder id="nls" path="resources/nls" optimizable="true"> 4 <tns:extensions> 5 <tns:extension name="js" resource-type="script"/> 6 </tns:extensions> 7 </tns:resource-folder> 8 </tns:resources>
您需要在此處註冊每個 JavaScript、CSS、影像以及翻譯資源檔案。此區段包含在 <tns:resources>
元素內,其中包含下列任何數目的元素:
<tns:resource>
這些元素用來註冊單一檔案 (例如,JavaScript 或 CSS 檔案)。
<tns:resource-folder>
這些元素用來同時註冊指定資料夾底下的所有檔案。例如,影像資料夾或包含原生語言支援的資源檔案的資料夾。
以下各節提供如何註冊每個檔案類型的其他資訊。
JavaScript 檔案
Plug-in 中的每個 JavaScript 檔案必須使用類似下列所示的行註冊。
<tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
其中:
將 ID 設為與沒有 .js 副檔名的 JavaScript 檔案名稱相同。
scripts
目錄底下。
請對 JavaScript 檔案全部使用小寫字元,不可包含特殊字元 (例如,底線、連字號)。
script
。base
。CSS 檔案
Plug-in 中的每個 CSS 檔案必須使用類似下列所示的行註冊。
<tns:resource id="currencyconversionstyles" path="resources/currencyconversion.css" type="css"/>
其中:
將 ID 設為與沒有 .css 副檔名的 CSS 檔案名稱相同。
resources
目錄底下。
請對 CSS 檔案全部使用小寫字元,不可包含特殊字元 (例如,底線、連字號)。
css
。影像資料夾
如果 Plug-in 具有您需要從 Javascript 程式碼內進行參照的影像,請將它們放置在 Plug-in 目錄結構內的 resources/images
目錄中,並將 <tns:resource-folder>
元素新增至 plugin.xml
檔案,如下所示:
<tns:resource-folder id="images" path="resources/images" optimizable="false"/>
如果只有 CSS 檔案參照您的影像,則您不需要將 <tns:resource-folder>
元素新增至 plugin.xml
檔案。在此情況下,您仍然必須將它們新增至 resources/images
目錄,以便可以從 CSS 檔案使用相對路徑參照它們。
原生語言支援資源資料夾
Oracle Analytics 實行原生語言支援。這需要開發人員將顯示在其使用者介面中的字串具體化成個別的 JSON 資源檔案。您可以接著在指定的目錄結構中提供這些檔案的各種本地化版本,Oracle Analytics 會針對使用者選擇的語言自動使用正確的檔案。您可以視需要提供資源檔案所需的翻譯版本。原生語言支援資源資料夾會將 Oracle Analytics 指向 Plug-in 所使用之指定的原生語言支援目錄結構的根。使用原生語言支援資源檔案的所有 Plug-in 必須具有與以下範例所示完全相同的 <tns:resource-folder>
項目。
1 <tns:resource-folder id="nls" path="resources/nls" optimizable="true"> 2 <tns:extensions> 3 <tns:extension name="js" resource-type="script"/> 4 </tns:extensions> 5 </tns:resource-folder>
請參閱產生的資料夾和檔案以瞭解檔案內容與應遵循的指定目錄結構詳細資訊。
對於您要 Plug-in 提供的每個資料動作,您必須使用 <tns:extension>
元素註冊資料動作擴充,類似以下所示:
<tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0"> <tns:configuration> { "host": { "module": "obitech-currencyconversion/currencyconversion" }, "resourceBundle": "obitech-currencyconversion/nls/messages", "properties": { "className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction", "displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" }, "order": 100 } } </tns:configuration> </tns:extension>
其中:
oracle.bi.tech.plugin.dataaction
。<tns:configuration>
元素包含進行下列定義的 JSON 字串:
%PluginID%/%ModuleName%
的格式,其中:
%PluginID%
必須取代為您在 <tns:obiplugin>
元素之 ID 屬性中指定的 Plug-in ID。%ModuleName%
必須取代為包含資料動作之 JavaScript 檔案的 <tns:resource>
元素 ID 屬性中指定的資源 ID。nls
目錄結構中,則請將此特性設為 %PluginID%/nls/messages
(其中 %PluginID%
必須取代為您在 plugin.xml
檔案頂端之 <tns:obiplugin>
元素的 ID 屬性中指定的 Plug-in ID)。%PluginID%/%ModuleName%.%ClassName%
的格式,其中:
%PluginID%
必須取代為您在 <tns:obiplugin>
元素之 ID 屬性中指定的 Plug-in ID。%ModuleName%
必須取代為包含資料動作之 JavaScript 檔案的 <tns:resource>
元素 ID 屬性中指定的資源 ID。%ClassName%
必須取代為您在 JavaScript 檔案中提供給資料動作類別的名稱。resourceBundle
內查尋資料動作的本地化顯示名稱。