8 Custom Elements

This section covers the following topics:

8.1 About Custom Elements

A custom element is a user-defined Site Studio element. In addition to the other productized Site Studio elements, the custom element provides a way to extend the Site Studio product to suit individual business needs.

From a code perspective, custom elements are essentially full HTML type files (for example, htm, hcsp, jsp, and so forth) that reside within an IFRAME in the contributor form. A custom element uses an API and implements a hand-full of callbacks in order function correctly as a Site Studio element.

8.2 Element API

In order for a custom element to function properly in a contributor form, a custom element must utilize an API and implement a hand-full of callbacks. The ElementAPI object is a JavaScript object explicitly loaded into the custom element page that facilitates communication between the Contributor form and the custom element. The ElementAPI provides methods for custom elements to communicate to the Contributor form and a callback mechanism for the Contributor form to pass notifications to the custom element.

This section contains the following topics:

8.2.1 Loading the Element API

Before the ElementAPI and its supporting libraries can be used; the ElementAPI must first be loaded into the Custom Element page. After the ElementAPI is loaded, the Custom Element should continue with page initialization and notify the Contributor form that the Custom Element is loaded.

<html>
<head>
   <title>Default Custom Element Form</title>
   <script type="text/javascript">
      function Initialize()
      {
    //===========================================================================
    // TODO: ElementAPI is loaded. Place Custom Element initialization code here.
    //===========================================================================

    // Let the Contributor Form know that this Custom Element is loaded and ready.
    ElementAPI.Ready();
     }

    // Load the ElementAPI and its supporting libraries - then call Initialize()
    // Parameter 1: The Custom Element's window object. This parameter uniquely
    //  identifies the Custom Element to the Contributor Form.
    // Parameter 2: A function pointer. This function will be executed after the
    // ElementAPI and its supporting libraries are loaded.
    try {
      window.top.WCM.InitializeCustomElement(window, Initialize);
      } catch(e) { }
   </script>
</head>
<body>
   <h3>Default Custom Element Form</h3>
</body>
</html>

8.2.2 Element API Dependent Scripts

When the ElementAPI is loaded into the Custom Element page, so are the ElementAPI dependent scripts. These scripts contain most of the JavaScript WCM library and is also available to use in authoring custom elements. The following is a list of script files loaded into a custom element.

  • wcm.js

  • ./base/wcm.dhtml.js

  • ./base/wcm.get.js

  • ./base/wcm.http.js

  • ./base/wcm.popup.js

  • ./sitestudio/wcm.contentserver.popup.js

  • ./form/elements/wcm.elementapi.js

  • ./sitestudio/elements/wcm.sitestudio.elementapi.js

  • ./sitestudio/wcm.idc.js

  • ./form/elements/element/wcm.element.js

  • ./form/elements/custom/wcm.custom.js

As with other custom scripts, you can modify any of these as you need and place the modified script in the /custom directory.

8.3 Custom Elements within Contributor

The contributor form communicates to a custom element by executing functions implemented by the custom element. As part of the initialization process, a custom element needs to register these functions by passing their function pointers to the contributor form.

This section contains the following topics:

8.3.1 Communication from a Contributor Form to a Custom Element

The contributor form communicates to a custom element by executing functions implemented by the custom element. As part of the initialization process, a custom element needs to register these functions by passing their function pointers to the contributor form.

The following is a list of functions that can be registered with the contributor form. None of these functions need to be implemented by the custom element; however, a few of them are required if the intention is to collect and save data from a Contributor user. Furthermore, all of these functions except the IsDirty() function, when executed, will be passed a callback function pointer to execute when the task is complete. This allows for asynchronous communication if a custom element needs to perform an asynchronous task during execution.

Function Description
CanCloseElement(callback); The contributor form will execute this method when the contributor updates information within the element. The implementation of the function should calculate whether the custom element can be safely closed. For instance, if the data does not pass validation, then the custom element should indicate that it cannot be closed.
GetElementContent(callback); The contributor form will execute this method when the contributor updates information within the element. The implementation of the function should pass back string content to be saved.
Hide(callback); The contributor form will execute this method whenever the form performs a DHTML task that overlays a HTML element over the custom element. For instance, this method will be executed when the metadata tab is activated and the contributor elements are obscured.

This method was introduced specifically for the Ephox-based elements, because Java applets always have top z-index. All other elements (HTML-based elements) can ignore this method.

Show(callback); The contributor form will execute this method whenever the form performs a DHTML task that removes an overlay that makes custom elements reappear.

This method was introduced specifically for the Ephox-based elements, because Java applets always have top z-index. All other elements (HTML-based elements) can ignore this method.

IsDirty(); The contributor form will execute this method whenever the form popup is closed. The custom element should calculate whether or not unsaved changes exist and then notify the contributor if there are unsaved changes.

The following is a JavaScript code snippet of how a custom element can register functions with the contributor form:

function CanCloseElement(callback)
{
  // No data validation in this sample - just pass back a true value.
  callback({canClose: true});

  // Here is an example of passing a false value
  // callback({canClose: false, reason: 'Failed validation. Use only lowercase
  // letters.'};
}
 
function GetElementContent(callback)
{
  // Pass back some sample content for demo purposes.
  callback('This is my Custom Element Content.');
}
 
function Show(callback)
{
  // Just handle this notification by executing the callback.
  callback(); 
}
 
function Hide(callback)
{
  // Just handle this notification by executing the callback.
  callback(); 
}
 
function IsDirty()
{
  // This Custom Element is never dirty - so pass a false value.
  return {isDirty: false}; 
}
 
// Set callback methods for the Contributor Form to send notifications to this Element.
ElementAPI.SetCallback('CanCloseElement', CanCloseElement);
ElementAPI.SetCallback('GetElementContent', GetElementContent);
ElementAPI.SetCallback('Show', Show);
ElementAPI.SetCallback('Hide', Hide);
ElementAPI.SetCallback('IsDirty', IsDirty);

8.3.2 Communication from a Custom Element to a Contributor Form

A custom element initiates communication with the contributor form by using the ElementAPI JavaScript object. The following is a list of available ElementAPI methods.

Function Description
ElementAPI.GetDefaultData(); Retrieves the default content stored in the data file.
ElementAPI.SetHostHeight(height); Sets the height of the elements containing IFRAME.
ElementAPI.SetRequiredIndicator(isRequired); Toggles the Required graphic indicator in the Contributor Form UI.
ElementAPI.GetSite(options); Displays the Choose Website picker UI.
ElementAPI.GetSection(options); Displays the Choose Website Section picker UI.
ElementAPI.GetColor(options); Displays the Color picker UI.
ElementAPI.GetFont(options); Displays the Get Font picker UI.
ElementAPI.GetSearchResults(options); Displays the Oracle Content Server's Get Search Results page.
ElementAPI.GetQueryText(options); Displays the Get Query Text UI.
ElementAPI.CaptureQuery(options); Displays the Oracle Content Server's Capture Query page.
ElementAPI.GetHyperlink(options); Displays the Hyperlink Wizard UI.
ElementAPI.FocusForm(options); Focuses the parent window thereby blurring the Element window.

8.4 Legacy Custom Element Compatibility

All custom element forms created with Site Studio releases 10gR3 (10.1.3.3.2) and earlier are not compatible with Site Studio 11gR1 and will need to be manually upgraded (re-authored). The primary reason for not maintaining backward compatibility is Site Studio's prior dependency upon Internet Explorer's proprietary window.external functionality. The window.external functionality of custom elements used in Site Studio release 10gR3 and earlier is blocked at the point of code execution and is not easily duplicated in a cross-browser and cross-platform DHTML solution.

The upside to breaking backward compatibility is that current custom elements are much more flexible, and better integrated into the Contributor application architecture (in addition to being a cross-browser and cross-platform solution).

This section contains the following topics:

8.4.1 Detecting Legacy Custom Element Forms

A custom element form created using Site Studio 10gR3 (10.1.3.3.2) or earlier (that is, a legacy custom element form), if loaded into the Contributor application with the SSValidateCustomElements flag is set to true, will be detected. An error message will be displayed in its place within the contributor form.

The Contributor application does this by first downloading the custom element form, parsing the source code, and determining whether or not the custom element form is compatible with the new Contributor application.

The functionality and overhead to detect legacy custom element forms is unnecessary on production installations and is turned off by default. To turn on legacy custom element form detection, add the following line to Oracle Content Server's config.cfg file and restart the server:

SSValidateCustomElements=true

8.4.2 Upgrading Legacy Custom Elements

Any custom element forms created using a Site Studio release up to 10gR3 (10.1.3.3.2) are not compatible with Site Studio 11gR1. They must be manually upgraded and re-authored. The primary reason for not maintaining backward compatibility is Site Studio's prior dependency on Internet Explorer's proprietary window.external functionality (due to the ActiveX control used for the legacy Contributor application). This functionality was removed from Site Studio as a result of the browser-independent, JavaScript-based Contributor application that is used in Site Studio 10gR3 (10.1.3.3.3) and higher (including 10gR4 and 11gR1).