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:

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.

Parameters
Name Type Description
componentAssets String Invokes list creator.
callback Function Callback function.
Usage 
// get/set list of assets
SitesSDK.getProperty('componentAssets', callback);
SitesSDK.setProperty('componentAssets', [assets]);  
  
// 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
SitesSDK.filePicker({options}, callback);
  
//
// 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.

Parameters
Name Type Description
propertyName String Name of the property.
callback Function Callback function.
Related Properties
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.
Usage 
SitesSDK.getProperty('customSettingsData', function (propertyData) {
        // store settings data
        self.configuration(
                {
                       'id': propertyData.id || self.id,
                       'url': propertyData.url || self.params.url,
                       'limit': propertyData.limit || self.params.limit
                            
                });
    });
Additional Related Properties Fetched From Rendering URL

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
Additional Properties Fetched from Settings URL

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.

Parameters
Name Type Description
propertyName String Name of the site property
callback Function Callback function to read the property value
Site Properties
Property Name Description Settings Render
theme URL of the current theme design n/a Yes
Usage 
SitesSDK.getSiteProperty('theme',function(data){
        console.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
                      SitesSDK.Utils.addSiteThemeDesign(data.url);
                }

        }
    });

SitesSDK.setProperty(‘componentAssets’, [assets])

This function updates the list of site assets stored on behalf of the custom component.

Parameters
Name Type Description
componentAssets String Creates list of component assets.
assets JSON object Returns list of selected assets.
Arguments
Name Description
filetypes List of supported file types.
multiSelect Select single or multiple files.
Usage 
// get/set list of assets
SitesSDK.getProperty('componentAssets', callback);
SitesSDK.setProperty('componentAssets', [assets]);  
  
// 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
SitesSDK.filePicker({options}, callback);
  
//
// 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.

Parameters
Name Type Description
propertyName String Name of the property.
propertyValue JSON object Value of the property.
Related Properties

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.
Usage 
// configuration that can be saved
var saveconfig = {
        //current settings id
        'id': self.appSettingsProperties['settingsId'],
        'url': self.url(),
        'limit': self.limit()
        };
// save property 'customSettingsData'
SitesSDK.setProperty('customSettingsData',saveconfig);

SitesSDK.filePicker({options}, callback)

This function returns a list of selected files.

Parameters
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.
Usage 
// get/set list of assets
SitesSDK.getProperty('componentAssets', callback);
SitesSDK.setProperty('componentAssets', [assets]);  
  
// 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
SitesSDK.filePicker({options}, callback);
  
//
// 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.

Usage 
SitesSDK.openDocumentPicker({
  selectable: "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.

Usage 
SitesSDK.openAssetPicker({
  select: "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.

Parameters
Name Type Description
messageType String Type of message
payload JSON object Message payload
Message Types

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.
Usage 
// raise trigger
SitesSDK.publish(SitesSDK.MESSAGE_TYPES.TRIGGER_ACTIONS,{
            '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.

Parameters

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 Types
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.
Usage

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.

Parameters
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.
Usage

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.