Step 10: Use Nested Components with In-Line Editing

Oracle Content Management components are implemented using KnockoutJS component architecture. This means that if you are using KnockoutJS to implement your components, you can include Oracle Content Management built-in components directly into your template.

Note:

Because Oracle Content Management built-in components can only run in the Oracle Content Management page, you can't use nested components if your component is rendered in an inline frame.

To leverage nested components:

1. Implement your component using KnockoutJS.

2. Use RequireJS to include your component and use the same Knockout "ko" instance variable that is created by Oracle Content Management.

   This is required because Oracle Content Management extends Knockout with components and these components won’t be available if you use your own instance of KnockoutJS.

In this step you will review how the Oracle Content Management Image, Paragraph, and Title components are rendered in your custom component. A user will be able to edit it directly within the page and access the Settings panel for the nested component.

To see how these components are included in your template, edit the render.js file and look at the sampleComponentTemplate object. The default section that is rendered is shown here:

'<!-- ko if: alignImage() !== \'right\' -->' +
'<div style="display:flex;">' +
'<div data-bind="attr: {style: imageStyle, \'data-layout\': alignImage()}, click: imageClicked">' +
'<scs-image params="{ scsComponent: { \'renderMode\': mode, \'parentId\': id, \'id\': \'imageId\', \'data\': imageData } }"></scs-image>' +
'</div>' +
'<div data-bind="attr: {style: paragraphStyle}">' +
'<scs-title params="{ scsComponent: { \'renderMode\': mode, \'parentId\': id, \'id\': \'titleId\', \'data\': titleData } }"></scs-title>' +
'<scs-paragraph params="{ scsComponent: { \'renderMode\': mode, \'parentId\': id, \'id\': \'paragraphId\', \'data\': paragraphData } }"></scs-paragraph>' +
'</div>' +
'</div>' +
'<!-- /ko -->' +

Looking at the <scs-image> nested component, you will see the following entry:

'<scs-image params="{ scsComponent: { \'renderMode\': mode, \'parentId\': id, \'id\': \'imageId\', \'data\': imageData }}"></scs-image>' +

The scsComponent data passed to the params template binding includes the following:

• renderMode: This refers to the mode Site Builder is in. You can use this to enable and disable features. For example, when used by the <scs-title> component, it adds the rich text editor when running in edit mode.

• parentId: This is required so the Oracle Content Management component knows that it is rendering as a nested component. All changes to the nested component will be saved in the data for the custom component.

• id: A unique ID for the nested component. This will be further namespaced by the ID for the custom component.

• data: Initial data for the nested component. If the component isn't further modified, it will render with this initial data.

The referenced id and mode values are passed in to your custom component in the SampleComponentViewModel object, so you don't need to modify the object to get these values:

// Store the args
self.mode = args.viewMode;
self.id = args.id;

The syntax for all the other supported nested components follows the same pattern as for <scs-paragraph>; for example: <scs-image>, <scs-title>, <scs-button>.

Check the Results for Step 10

1. Refresh your page in your site so Site Builder can pick up changes to the component.

2. Take the page into Edit mode.

3. Drag and drop your component onto the page.

4. Click the As a page author, you can edit. . . text in your component and update the description using the rich text editor.

5. Switch to Preview mode to see your update.

6. Switch back to Edit mode.

7. Bring up the Settings panel against your component.

8. Click the Components link that now appears, because it found your nested component.

9. Click Paragraph, which is the nested component it found.

You can now update the properties against the Paragraph component within your component.

Note:

Until the component has been instantiated, Oracle Content Management does not know about any nested components that may exist in the template. To tell Oracle Content Management about hidden nested components, you can use the SitesSDK.setProperty('visibleNestedComponents', []); API. To have hidden nested components show-up by default, you must update the "nestedComponents": [] array in the component registration.

Continue to Step 11: Support Different Layouts.