Develop Custom Section Layouts with APIs

You can develop custom section layouts in Oracle Content and Experience with the Section Layout API, which includes Rendering APIs and Editing APIs.

For starter files to look at, see Create a Section Layout. The starter files for section layouts include comments with details about the structure of section-layout files.

Rendering APIs

The Rendering APIs, loaded from the render.js module, are used in Site Builder and at runtime.

Rendering API Description Input Parameter(s) Return Result
(Constructor) Initializes the Section Layout rendering module.

A JavaScript object that contains the following properties:

  • sectionlayoutData (Object) : The section layout data found in the page model.

  • componentId (String): The componentId value of the section layout, typically a GUID.

  • renderMode (String, optional): The render mode for the rendering operation.

  • customSettingsData (Object): A copy of the customSettingsData found in sectionLayoutData.

The Section Layout Rendering APIs are initialized.
render

Emits DOM elements appropriate for the section layout to the page, including container DIVs for child components.

container (Element) : The DOM element into which the section layout’s markup should be rendered.

After this method returns, child components will be rendered.

You can identify child components by finding child div[id]elements

addComponent

Used with content list components to dynamically add child components to a section layout.

This function is optional.

container (Element): The DOM element into which the new component should be rendered.

componentId (String): The ID of the new component to add to the section layout.

After this method returns, the element whose ID matches the componentId input will be rendered.

Editing APIs

The edit.js module is loaded if the hasEditHandlers property is set to true in the appinfo.json file associated with the section layout.

The Editing APIs are used in Site Builder.

All of the functions in this module except the Constructor are optional.

Editing API Description Input Parameter(s) Return Result
(Constructor) Initializes the Section Layout editing module.

A JavaScript object that contains the following property:

  • componentId (String): The componentId value of the section layout, typically a GUID.

The Section Layout Editing APIs are initialized.

getCapabilities

Returns an object describing the editing capabilities of the section layout.

A JavaScript object that describes the editing capabilities of the section layout.

Upon input, the default capabilities will be provided to the function. The function can modify the Capabilities object as needed.

The Capabilities object can include the following capabilities:

  • title (String): The title of the section layout to display to the user.

  • settingsTitle (String): The title to display in the Settings Panel dialog.

  • hasSettings (Boolean): Indicates if the section layout supports a Settings Panel.

  • allowMove (Boolean): Indicates if the section layout allows child items to be moved.

  • allowDelete (Boolean): Indicates if the section layout allows child items to be deleted.

  • isHidden (Boolean): Indicates if the section layout is currently hidden in response to user options.

  • dropTarget (Boolean): Indicates if the section layout is the target for drag and drop operations.

  • customMenuOptions (Array): Custom menu options to add to the Section Layout context menu. Each menu-option object has the following properties:

    • label (String) : The display text of the menu item.

    • action (Function): The function to invoke when the menu item is clicked.

    • disabled (Boolean): Indicates that the menu item should display in a disabled state.

    • icon (String): The URL to display alongside the label in the menu item. (This property is reserved for future use.)

    • checkmark (Boolean): Indicates that a checkmark should appear alongside the label in the menu item.

    • subMenuItems (Array): Menu options to display in a submenu.

(Object): The capabilities for the section layout.

getCaptionContent

Returns the section layout display name, which will appear in UI elements.

None.

(String): The display name of the section layout.

filterCapabilities

Allows the section layout to modify the Capabilities object before menus are displayed to the user.

You can use this API to adjust or remove menu options. (See also getCapabilities.)

A JavaScript object that describes the editing capabilities of the section layout. On input, the default capabilities will be provided to the function.

(Object) The capabilities for the section layout.
onDragOver Called during a Drag and Drop operation to indicate if the dragged item can be dropped on the section layout.

eventObject (Event Object): An event object that holds information about the drag event.

dataTransfer (DataTransfer Object): A DataTransfer object that holds information about the item being dragged over the section layout.

(Boolean) A value indicating if the dragged item can be accepted by the section layout.

Returns true if the section layout can accept the dragged item, false otherwise.

onDrop Called during the drop portion of a Drag and Drop operation to indicate that the dragged item should be placed inside the section layout.

eventObject (Event Object) : An event object that holds information about the drop event.

dataTransfer (DataTransfer Object) A DataTransfer object that holds information about the item being dropped on the section layout.

(Boolean) A value indicating if the drop operation was handled by the section layout.

Returning true bypasses the default logic.

onAddComponent Notifies the Section Layout that a Drag and Drop operation added an item in the section layout.

eventObject (Event Object): An event object that holds information about the drag event.

dataTransfer (DataTransfer Object): A DataTransfer object that holds information about the item being dropped on the section layout.

componentId (String): The componentId value of the newly added item.

Section layout notification.
onMoveComponent

Notifies the section layout that a Drag and Drop operation moved an item in the section layout.

eventObject (Event Object): An event object that holds information about the drag event.

dataTransfer (DataTransfer Object): A DataTransfer object that holds information about the item being dropped on the section layout.

componentId (String): The componentId value of the moved item.

Section layout notification.
getSettingsData

Allows the section layout to change the Settings data before the Settings Panel is displayed.

settingsData (Object): The default settings data computed for the Section Layout

(Object) The settings data for the section layout.
updateSettings

Allows the section layout to change its settings after the Settings Panel has been closed.

This API is called just before the settings are stored in the page model.

parameters (Object): The raw parameters object returned from the Settings Panel.

sectionLayoutData (Object) : The section layout data that will be stored. Default data will be generated from parameters (Object) and passed to the function in this parameter.

(Object) The section layout data to store in the page model.
dispose

Allows the editing module to free memory, detach events, and deallocate resources associated with the edit handlers.

This API is called when the section layout needs to completely redraw, as in the case of an Undo/Redo operation.

None. Redrawing the section layout is enabled.