Component Elements

December 2014

1.0

Component Registry

Each component is contained within their own folder in the components directory of a site/theme.
Simply adding/removing a folder for a component will remove the component from the site/theme.

2.0

Component Definition

The component definition is an index.json file stored in the top level of the component folder.
The file will contain:
Type
Display Name
Description
Icon
For example:
config: {
type': 'scs-title'
component
,'displayName': 'Title'
(translatable)
,'description': 'Choose the text you\d like to add to your site'
component (translatable)
,icon: icons/text.png
component palette
,settings: true
default is true
,edit: true
is true
,initialData: { }
data
}

// static identifier for the

// name for the component
// description for the
// used within the
// has a settings pane:
// has in-line edit capability: default
// object notation to seed initial

Both the Renderer & the Contributor need to have access to the config files for the components.

3.0

Component Elements & Communication

Oracle Confidential

Page 1

4.0

Edit Mode:
4.1
Component UI
The contributor will use the information from the components index.json file to list the
component appropriately within the component palette UI.

4.2
Component Drop
The component must implement a renderer plug-in to insert the component into the page.
This may extend a generic renderer plug-in that simply emits: < + componentName + -edit +
params=id: 1234, data: dataobject/> driven from the index.json config for the component.
4.3
Edit-View
The component must implement an edit view mode for when displayed, not edited, on the
page in edit mode.
This edit view implementation should be similar but may not be the same as the view mode
for the component. Eg: components such as videos may not automatically play when editing
the page.
A significant difference between the edit view mode and view mode is that edit view may
contain any number of dependent JS libs required for handling switching to other modes and
updates. The view mode should be as lightweight as possible.
4.4
Inline Edit
Each component may implement an in-line editor. Eg: For a Title component, this would allow
the user to directly modify the text and bring up an associated rich text editor.
Inline edit is invoked by an edit event passed to the component.
Changes made through in-line edit are immediately written back to the page model. Undo, and
dirty is handled by the renderer / contributor.
Changes made through in-line edit may also need to be synced with the settings pane.
Oracle Confidential

Page 2

When the component loses focus, the component switches back to Edit View mode.

4.5
Context Menu
The contributor will display a context menu for the component including elements such as Edit
and Settings defined by the index.json file for the component.
Selecting Edit will cause an Edit Event to be broadcast for the component.
Selecting Settings will cause the components settings pane to be displayed in the contributor
settings panel. This requires the component to broadcast its current data to be used by the
Settings Pane.
4.6
Settings Pane
If a component defines a Settings Pane it must implement a contributor plug-in for the
Settings Pane that will be hosted the settings pane within the Contributors Settings Panel.
The Settings Pane will handle Settings events and display the correct settings Pane passing in
the data received as the payload for the Settings event.
Any updates to the Settings Pane will cause a component Update Event to be sent to the
component. The component will immediately reflect the change.
Changes in the Settings Pane are immediate. Cancel just removes the settings pane but does
not remove any changes made through the pane. The changes to the component are handled
the same as inline editing and immediately written to the page model.

5.0

Preview Mode
5.1
Preview-View
All components must render as they would when only viewing the page.
Since this is still the contributor mode there are still no restrictions on the javascript libraries
included. The focus is fast switching between preview and edit of the page.
6.0

View Mode
6.1
View

The component must implement a view mode for when the site is running and not in edit mode. This
should be as lightweight as possible and not contain any code that deals with editing or otherwise
updating the component.

FAQ
1) How does the drop event work?
1. The Contributor identifies the location within the page for the drop target
a. Contributor knows the DOM and can identify slots within the DOM to provide feedback to
the user
i. Slots are identified via class in a div
b. Contributor can also identify existing components within slots to note where within the
slot to drop
i. Components are identified via class in a top level div within a slot
2. The Contributor raises the drop event
a. Once the location to drop has been identified, the Contributor raises a drop event for the
Renderer to handle
b. As part of the payload for the drop event:
i. Contributor will pass the following to the Renderer:

Oracle Confidential

Page 3

1. Slot
2. Location within the slot (options):
a. Component to come after
b. (row,col), which requires counting number of components in a row
3. The Renderer handles the drop event
a. It extracts the component, slot & location within the DOM from the payload
b. It inserts the component within the page
i. <Need to agree on how the component actual gets inserted with the above
information>
2) How is the location within the slot identified for dropping a component?
1. Slots are made up of a vertical stack of components (row)
2. Can add a component to the right of an existing one to have 2 components on one row
a. Need to define the responsive design for allowing multiple components on one row and
whether they are fixed on re-size or drop below the other
3) How is a component selected for move and context menu instead of edit?
4) How does the edit event work?
5) How does the settings event work?
7) How does the page save event work?

Appendix:
1) Knockout Component Architecture:
a. http://knockoutjs.com/documentation/component-overview.html

Oracle Confidential

Page 4