Sites SDK for Oracle Content Management
Introduction
The Sites SDK for Oracle Content Management is a JavaScript library that provides a set of functions which enable components to have a more integrated experience with Oracle Content Management.
The Sites SDK is available for download from the Oracle Content Management server:
http://{server}/_sitesclouddelivery/renderer/app/sdk/js/sites.min.js
The main purpose of the Sites SDK is to enable users to build and manage applications. It provides several features:
Communication across inline frame and domain boundaries:
Enables a component to communicate with a page regardless of where the component is hosted
Includes participation in the page model life cycle:
- create the component
- render the component with stored properties
- update the component and saving those changes
- delete the component from the page
Stores and retrieves custom settings used to configure a component for use in a page
Uses intercomponent communication to take part in triggers and actions
Geometry hints to a page (doesn’t apply to custom components):
Enables a page to dynamically resize the inline frame when told to do so by a component
Results in a component appearing to be part of a page, and the page moving in response to component resize events (no scroll bars)
Component awareness of when it’s called by Oracle Content Management:
Communication between a component and a page contains a token signed by a private key.
Sites SDK enables a component to decode the token and facilitate verification of the caller.
You include Sites SDK functions by providing a known path of the script, for example:
<script type="text/javascript"
src="<sdk_install_dir_path_prefix>/sites.min.js">
</script>
The Sites SDK has two global objects:
SitesSDK
The SitesSDK global object can be used in rendering and settings endpoints. It supports these commands:
Command | Task |
---|---|
SitesSDK.getProperty(‘componentAssets’, callback) | Returns a list of assets currently being stored on behalf of the component within the site. |
SitesSDK.getProperty(propertyName, callback) | Gets the value of the named property from the host site. |
SitesSDK.getSiteProperty(propertyName, callback) | Gets a named site property value from the host site. For example, it could fetch the current theme design that’s being used by the host site. |
SitesSDK.setProperty(‘componentAssets’, [assets]) | Updates the list of site assets stored on behalf of the custom component. |
SitesSDK.setProperty(propertyName, propertyValue) | Sets the value of a named property to the specified value. |
SitesSDK.filePicker({options}, callback) | Returns a list of selected files. |
SitesSDK.openDocumentPicker(options) | Returns a list of selectee documents. |
SitesSDK.openAssetPicker(options) | Returns a list of selected assets. |
SitesSDK.publish(messageType, payload) | Sends a message to the server, and accepts a message type and JSON object as a payload. |
SitesSDK.subscribe(messageType, callback) | A message listener for messages dispatched from the host site. The call is asynchronous. These are JavaScript callbacks, so the function should use JavaScript Closure or suitably bind the function to ensure it has access to the appropriate context. |
SitesSDK.getProperty(‘componentAssets’, callback)
This function returns a list of assets currently being stored on behalf of the component within the site.
Name | Type | Description |
---|---|---|
componentAssets |
String | Invokes list creator. |
callback |
Function | Callback function. |
// get/set list of assets
.getProperty('componentAssets', callback);
SitesSDK.setProperty('componentAssets', [assets]);
SitesSDK
// invoking list creator
// after calling this, the developer needs to call setProperty against
// 'componentAssets' to persist all currently used assets
//
// args:
// fileTypes - list of supported file types
// multiSelect - single or multiple file select
//
// returns a list of selected assets. If user cancels out of the picker,
// the callback is never called
.filePicker({options}, callback);
SitesSDK
//
// example 'componentAssets' JSON returned:
//
'componentAssets': [{
'name': <nameOfAssetInContentFolder>, // this is used to uniquely and persistently identify the asset. It is typically prefixed by the 'originalName' followed by a 16 digit string
'originalName': <originalName>, // name of the asset as selected from DOCS
'description': <description>, // description/other attributes that are available from DOCS
'url': <fully qualified url to the asset>
}]
SitesSDK.getProperty(propertyName, callback)
This function gets the value of the named property from the host site.
Name | Type | Description |
---|---|---|
propertyName |
String | Name of the property. |
callback |
Function | Callback function. |
Property Name | Description | Settings | Render |
---|---|---|---|
height |
Height of frame | n/a | Yes |
width |
Width of frame | n/a | Yes |
customSettingsData |
Settings data | Yes | Yes |
styleClass |
Selected style class | Yes | Yes |
Any other style attribute, such as
borderColor , borderRadius ,
alignment , borderStyle ,
margin , and so on. |
.getProperty('customSettingsData', function (propertyData) {
SitesSDK// store settings data
.configuration(
self
{'id': propertyData.id || self.id,
'url': propertyData.url || self.params.url,
'limit': propertyData.limit || self.params.limit
;
}); })
In addition to using getProperty() to fetch property values, other related properties that can be fetched from the rendering URL include the following:
Property Name | Description |
---|---|
id |
Component Id |
instance |
Encrypted token |
width |
Width of iframe |
height |
Height of iframe |
viewMode |
Render mode values |
locale |
Language set in site or browser |
settingsId |
Current settings Id |
In additional to using getProperty() to fetch property values, other properties that can be fetched from the settings URL include the following:
Property Name | Description |
---|---|
currCompId |
Id of the component being edited |
instance |
Encrypted token |
width |
Width of the settings iframe |
locale |
Language set in site or browser |
OrigSettingsId |
Original settings Id of the component |
settingsId |
New settings Id |
SitesSDK.getSiteProperty(propertyName, callback)
This function gets a named site property value from the host site. An example is fetching the current theme design that is being used by the host site.
Name | Type | Description |
---|---|---|
propertyName |
String | Name of the site property |
callback |
Function | Callback function to read the property value |
Property Name | Description | Settings | Render |
---|---|---|---|
theme |
URL of the current theme design | n/a | Yes |
.getSiteProperty('theme',function(data){
SitesSDKconsole.log(Theme data ' + JSON.stringify(data));
// check if we got an url back
if ( data.url && typeof data.url === 'string' ) {
if ( data.url !== '') {
// theme is loaded so dynamically inject theme
.Utils.addSiteThemeDesign(data.url);
SitesSDK
}
}; })
SitesSDK.setProperty(‘componentAssets’, [assets])
This function updates the list of site assets stored on behalf of the custom component.
Name | Type | Description |
---|---|---|
componentAssets |
String | Creates list of component assets. |
assets |
JSON object | Returns list of selected assets. |
Name | Description |
---|---|
filetypes |
List of supported file types. |
multiSelect |
Select single or multiple files. |
// get/set list of assets
.getProperty('componentAssets', callback);
SitesSDK.setProperty('componentAssets', [assets]);
SitesSDK
// invoking list creator
// after calling this, the developer needs to call setProperty against
// 'componentAssets' to persist all currently used assets
//
// args:
// fileTypes - list of supported file types
// multiSelect - single or multiple file select
//
// returns a list of selected assets. If user cancels out of the picker,
// the callback is never called
.filePicker({options}, callback);
SitesSDK
//
// example 'componentAssets' JSON returned:
//
'componentAssets': [{
'name': <nameOfAssetInContentFolder>, // this is used to uniquely and persistently identify the asset. It is typically prefixed by the ¿originalName¿ followed by a 16 digit string
'originalName': <originalName>, // name of the asset as selected from DOCS
'description': <description>, // description/other attributes that are available from DOCS
'url': <fully qualified url to the asset>
}]
SitesSDK.setProperty(propertyName, propertyValue)
This function sets the value of the named property to the specified value.
Name | Type | Description |
---|---|---|
propertyName |
String | Name of the property. |
propertyValue |
JSON object | Value of the property. |
This table lists the set of related properties that can be fetched using setProperty().
Property Name | Description | Settings | Render |
---|---|---|---|
height |
Height of frame | n/a | Yes |
width |
Width of frame | n/a | Yes |
customSettingsData |
Settings data | Yes | Yes |
styleClass |
Selected style class | Yes | Yes |
description |
Used in banner for an instance of local component on the page | ||
layout |
Returns the currently selected layout only for local components. Can be updated from the Settings panel based on values in the appinfo.json file. | ||
renderStatus |
Allows a custom component to report that rendering is done. | true | |
Any other style attribute, such as
borderColor , borderRadius ,
alignment , borderStyle ,
margin , and so on. |
// configuration that can be saved
var saveconfig = {
//current settings id
'id': self.appSettingsProperties['settingsId'],
'url': self.url(),
'limit': self.limit()
;
}// save property 'customSettingsData'
.setProperty('customSettingsData',saveconfig); SitesSDK
SitesSDK.filePicker({options}, callback)
This function returns a list of selected files.
Name | Type | Description |
---|---|---|
options |
String | Options to specify selected files to return. |
callback |
Function | Callback function. If user cancels out of the picker, the callback is never called. |
// get/set list of assets
.getProperty('componentAssets', callback);
SitesSDK.setProperty('componentAssets', [assets]);
SitesSDK
// invoking list creator
// after calling this, the developer needs to call setProperty against
// 'componentAssets' to persist all currently used assets
//
// args:
// fileTypes - list of supported file types
// multiSelect - single or multiple file select
//
// returns a list of selected assets. If user cancels out of the picker,
// the callback is never called
.filePicker({options}, callback);
SitesSDK
//
// example 'componentAssets' JSON returned:
//
'componentAssets': [{
'name': <nameOfAssetInContentFolder>, // this is used to uniquely and persistently identify the asset. It is typically prefixed by the ¿originalName¿ followed by a 16 digit string
'originalName': <originalName>, // name of the asset as selected from DOCS
'description': <description>, // description/other attributes that are available from DOCS
'url': <fully qualified url to the asset>
}]
SitesSDK.openDocumentPicker(options)
This function returns a list of selected files. It takes a single argument and returns a Promise that resolves to the selected document(s). The available options match those for the documentsView component in the Embed UI API V2.
.openDocumentPicker({
SitesSDKselectable: "any",
layout: "grid"
.then(function (selection) {
})console.log(selection);
; })
Once documents have been retrieved, Oracle Content Management must be told to store the IDs of these documents with the site using the SitesSDK.getProperty(‘componentAssets’, callback) and SitesSDK.setProperty(‘componentAssets’, [assets]) properties. Otherwise they won’t be published with the site and could be deleted.
SitesSDK.openAssetPicker(options)
This function returns a list of selected files. It takes a single argument and returns a Promise that resolves to the selected asset(s). The available options match those for the assetsView component in the Embed UI API V2.
.openAssetPicker({
SitesSDKselect: "single"
.then(function (selection) {
})console.log(selection);
; })
Once assets have been retrieved, Oracle Content Management must be told to store the IDs of these assets with the site using the SitesSDK.getProperty(‘componentAssets’, callback) and SitesSDK.setProperty(‘componentAssets’, [assets]) properties. Otherwise they won’t be published with the site and could be deleted.
SitesSDK.publish(messageType, payload)
This function sends a message to the server. It accepts a message type and JSON object as a payload. The message type is recognized and handled in the page. If there’s no handler, then the message type passed across is ignored.
Name | Type | Description |
---|---|---|
messageType |
String | Type of message |
payload |
JSON object | Message payload |
This table lists the types of messages that are known to a local component (using inline frames) or remote component and can be sent using the SitesSDK.publish() function.
Message Type | Description |
---|---|
SETTINGS_UPDATED |
Use in the Settings panel to send a Settings updated message to the rendering endpoint. |
TRIGGER_ACTIONS |
Use in the component rendering endpoint to trigger actions in the host site. |
// raise trigger
.publish(SitesSDK.MESSAGE_TYPES.TRIGGER_ACTIONS,{
SitesSDK'triggerName': 'scsChangeSettings',
'triggerPayload': { 'url': this.configuration()['url'],'feedcount': this.configuration()['limit'] }
; })
SitesSDK.subscribe(messageType, callback)
This function is effectively a message listener for messages dispatched from the host site. The call is asynchronous.
The registered callback is called when a message of a specific type is received by the SDK. If the callback returns a value, then that value is returned back to the page. If no callback is passed to this function, then any registered listener for that specific message type is deleted.
These are JavaScript callbacks, so the function should use JavaScript Closure or suitably bind the function to ensure it has access to the appropriate context.
Name | Type | Description |
---|---|---|
messageType |
String | Type of message: - SETTINGS_UPDATED - TRIGGER_ACTIONS - EXECUTE_ACTION - GET_ACTIONS - GET_TRIGGERS - COPY_CUSTOM_DATA - PASTE_CUSTOM_DATA |
callback |
Function | The function when a message is received from a host site. |
Message Type | Description |
---|---|
SETTINGS_UPDATED |
Subscribe to this message to be notified when any value is changed in the Settings panel. Typically the component will respond by updating its rendition in the user interface. |
TRIGGER_ACTIONS |
Publishing this message raises a trigger and passes payload. |
EXECUTE_ACTION |
Subscribe to this message to handle custom actions. The listener typically handles this message by performing the given action. |
GET_ACTIONS |
Subscribe to this message to declare an array of actions that the component can execute. Returns array of actions. |
GET_TRIGGERS |
Subscribe to this message to declare an array of triggers that the component can raise. Returns array of triggers. |
COPY_CUSTOM_DATA |
Subscribe to this message to handle copying Custom Settings Data to the clipboard. Returns an object representing data to be put on the clipboard. |
PASTE_CUSTOM_DATA |
Subscribe to this message to handle pasting Custom Settings Data from the clipboard. |
Some listeners expect data to be passed, and some are expected to return data.
Example 1:
Register a message listener for message type EXECUTE_ACTION:
SitesSDK.subscribe(SitesSDK.MESSAGE_TYPES.EXECUTE_ACTION, self.executeAction,self);
The registered callback function should accept an argument as shown here:
// typical signature of a callback function registered with a message
// type
function (args) {
var payload = args.detail.message.payload,
action = args.detail.message.action,
actionName = action && action.actionName;
// do something here with the payload data
}
Example 2:
The COPY_CUSTOM_DATA listener is typically implemented with code like this:
// listen for COPY_CUSTOM_DATA request
SitesSDK.subscribe(SitesSDK.MESSAGE_TYPES.COPY_CUSTOM_DATA,
The copyCustomDataListener() method would return an object representing the data to be copied to the clipboard, for example:
// Handle Copy Style (save customSettingsData to the clipboard)
self.copyCustomDataListener = function() {
return {
prop1: this.prop1(),
prop2: this.prop2()
};
};
Example 3:
The PASTE_CUSTOM_DATA request accepts data, but doesn’t have to return anything:
// listen for PASTE_CUSTOM_DATA request
SitesSDK.subscribe(SitesSDK.MESSAGE_TYPES.PASTE_CUSTOM_DATA, pasteCustomDataListener);
Along with:
// Handle Paste Style (apply customSettingsData from the clipboard)
self.pasteCustomDataListener = function(data) {
...
};
SitesSDK.Utils
The SitesSDK.Utils namespace has utility functions that can be called by all endpoints of an Oracle Content Management component. This namespace is available for the Settings panel for a remote component, but not for the inline local component.
Caution: These functions are not officially supported by Oracle. They are intended as sample implementations. Use them at your own risk.
Command | Task |
---|---|
SitesSDK.Utils.addSiteThemeDesign(cssUrl) | Adds the current site theme design to a component. |
SitesSDK.Utils.Logger | Returns the logger object being used by the Sites SDK. The log
level can be set to one of these: - debug - log - info - error - warn |
SitesSDK.Utils.getStyle(elem,styleProp) | A utility method that calculates the height of the inline frame. |
SitesSDK.Utils.addSiteThemeDesign(cssUrl)
This function creates a link element in the current page HTML
<head>
tag. The source is set to the path of
cssUrl
.
Caution: The functions in the Utils namespace are not officially supported by Oracle. They are intended to serve as sample implementations. Use them at your own risk.
Name | Type | Description |
---|---|---|
cssUrl |
String | URL path of the current theme design.
Use only with remote components. Local components (realized in an iframe) must fetch properties from the page instead of the URL. |
This function is typically used in conjunction with fetching the current theme design from the host site, as shown in this sample code:
// fetch current theme design from host site and then add it to the page
SitesSDK.getSiteProperty('theme',function(data){
// check if we got an url back
if ( data.url && typeof data.url === 'string' ) {
if ( data.url !== '') {
// theme is loaded so dynamically inject theme
SitesSDK.Utils.addSiteThemeDesign(data.url);
}
}
});
SitesSDK.Utils.Logger
This function returns the logger object being used by the Sites SDK.
Caution: The functions in the Utils namespace are not officially supported by Oracle. They are intended to serve as sample implementations. Use the Utils functions at your own risk.
The log level can be set to debug
, log
,
info
, error
, or warn
.
Sites SDK for Oracle Content Management
F81863-01
May 2023
Copyright © 2021, 2023, Oracle and/or its affiliates.
Primary Author: Oracle Corporation