7 Manage Custom Components and Layouts

As a developer, you can create and manage custom components and layouts. As a site contributor, you can register third-party components (apps) and component groups.

Custom components include component groups you create in the editor, and local and remote components you create using options described in this section. Custom layouts include section layouts for arranging components in a slot on a page and content layouts for arranging the fields in a content item.

• Understand Custom Components

• Understand Layouts

• Use Custom Components and Layouts

• Register Remote Components

• Create Local Components, Layouts, Content Field Editors, or Content Forms

• Export or Import Components or Layouts

To learn how to use components with your site, see Arrange Page Content.

For information about using individual components, see Use Built-In Components.

For details about how to create your own components, see Develop Components.

Understand Custom Components

Components are the individual parts of a web page. When you look at a web page, what do you see? You probably see a few titles, some paragraphs of text, and several links to other pages in the site. You might also see images, buttons, dividers, maps, and galleries. Each of these items is a component.

To add a component to a page, make sure that is set to Edit, click and choose which type of component you want to use.

Drag the component from the panel and drop it into a slot on the page. That’s it. Drag and drop titles, paragraphs, images, and other components where you want them on a page.

You can easily register and incorporate remote components (apps) and even create your own components using options in the component manager. Click Developer and then click View All Components.

Click Create and select the associated option to create a new local component or register a remote component. Components you create and share in this way are listed in the custom components panel in the editor.

For details about how to create your own components, see Develop Components.

Remote Components

If you have a third-party component (app) that you want to use, just register it and use it in your site. It’s that easy.

When you register a remote component, you specify the URL for the remote component itself and a second URL for any settings that a web author can specify for the remote component.

After you register a remote component, you can share it with other users. Any registered remote components that you own or that are shared with you are listed in the Custom Components panel in Site Builder.

You can change the properties for a remote component within the editor the same way you do for any other component. Just click the menu icon and choose Settings. The Custom button opens the settings URL you specified when you registered the remote component.

Note:

Because remote components are hosted on a server other than the one hosting Oracle Content Management, they’re enclosed in an inline frame (using an iframe element) for security purposes. Not all remote components can be enclosed in an inline frame. Check with the provider to find out if it can be enclosed.

Local Components

Developers can create components with access to the same features and capabilities as those provided by Oracle Content Management. You can insert the component directly into the page or enclose it in an inline frame with the iframe element.

When you click Create to create a local component, a fully-functional sample component is added to the list of components with a name you specify and a unique identifier. As a developer, you can modify the sample to create your own solutions.

For details about how to create your own components, see Develop Components.

Understand Layouts

A page layout arranges slots and content on a page. A section layout arranges content within a slot. A content layout arranges the fields in a content item.

In general, a layout specifies the presentation of content, but not the content itself. Separating the content from its presentation makes it easier to present the same content in different ways or to change the presentation without having to touch the content.

Page Layout

When you add a page to a site, you select a layout to use for that page. Each layout has areas on the page, called slots, where a contributor can drag and drop content. A page layout defines the number and position of slots on the page. A layout can also include content that is predefined and positioned on the page. This content can be static and not editable, such as a company logo, or it can be minimally editable, such as heading text that a contributor can change, but the position or appearance of which they can’t.

Page layouts are stored in the theme. Themes can have one or more page layouts. As a developer, you can copy and modify an existing theme to create a new theme. See Develop Layouts.

Description of the illustration theme_page.png

Section Layout

A section layout automatically organizes content added to it, making it easy for a contributor to add content without spending time formatting it on the page. For example, a section layout can automatically organize content into multiple columns or into a vertical list. A site contributor can add one or more section layouts to a slot to organize content.

Description of the illustration section_layout.png

In addition to the layouts provided, a developer can create additional section layouts to solve particular layout problems or to simplify authoring for contributors. A theme designer can even build section layouts into a slot in a page layout. See Develop Layouts.

Content Layout

If you are an enterprise user, you can create and use content items based on content types and layouts provided for you. Content structured in this way makes it possible for you as a contributor to assemble the content for a content item outside of Site Builder. Multiple content layouts associated with the content type make it possible for the site designer to display the content item in different contexts without having to touch the assembled content. As a developer, you can create new layouts from the default layout provided. See Develop Layouts.

Description of the illustration content_item_layout1.png

Use Custom Components and Layouts

As a developer, you can create and manage custom components and layouts. As a site contributor, you can register third-party components (apps) and component groups.

Custom components include component groups you create in the editor, and local and remote components you create using options described below. If you have a third-party app (remote component) that you want to use, just register it and use it in your site. Developers can also create local components with access to the same features and capabilities as those provided by Oracle Content Management.

Custom layouts include section layouts for arranging components in a slot on a page and content layouts for arranging the fields in a content item.

Use options on the menu bar or right-click menu on the Components page to perform the following tasks.

Task	Description
Register a remote component	When you register a remote component, you specify the URL for the remote component itself and a second URL for any settings that a web author can specify for the remote component. Before you can create a component, your administrator must enable the options in the Create menu. If you don’t see the Create menu on the components page, contact your administrator. Click Create and select the associated option to register a remote component. See Register Remote Components.
Create a local component or layout	When you create a local component or layout, you are given a fully-functional sample component or layout that you use as a basis for creating your own component or layout. Before you can create a component or layout, your administrator must enable the options in the Create menu. If you don’t see the Create menu on the components page, contact your administrator. Click Create and select the associated option to create a new local component or layout. See Create Local Components, Layouts, Content Field Editors, or Content Forms. For information about other ways to create components, see Develop Components.
Copy a component or layout	You can create a new component or layout by copying an existing component or layout and making changes to the copy. Note: You can’t change the name of a component or layout after you create or register it. You can copy a component or layout and specify a different name for the copy. All the other registration information, including the key value for remote components, are preserved. Sharing information is independent from registration information and isn’t copied. Right-click the component or layout you want to copy and choose Copy. Enter a name and click Copy. You can use letters, numbers, underscores (_), and hyphens (-). If you enter a space, it's automatically replaced with a hyphen.
Create Content Field Editor	You can create a content field editor that can be promoted and used when creating a content type to control the appearance of the data field. All data types are supported except Media and Reference. The component must be promoted before it is available for use when creating a content type.
Share a component or layout	You can share your component or layout with other Oracle Content Management users. You can share a component or layout if you’re the owner or if you’re assigned the Manager role. When you share a component or layout, you must assign a role to the user defining what the user can do with the component or layout. Right-click the component or layout you want to share, choose Share, and click Add Members. Enter one or more user names or email addresses, and assign one of these roles: Viewer: Viewers can see and use the component or layout in the list of custom components and layouts in the editor. They can also view the folders and files of the theme, but can’t change things. Downloader: Downloaders can also download files and save them to their own computer. Contributor: Contributors can also edit the component or layout, upload new files, delete files, and delete the component or layout itself, provided it is not in use in a site. Manager: Managers can also add users and assign their roles. The creator of a component or layout (the owner) is automatically assigned the manager role.
Edit a component or layout	If you’re a web developer, you can download and modify individual component or layout files or you can use the desktop app and synchronize any changes you make on your local system. You can also export a component or layout individually or as part of a template package, which includes the any custom components and section layouts, and work with it offline in your preferred development environment. If you make changes to a component or layout, you must publish the component or layout for those changes to be reflected by the sites that use the component or layout.
Export or import a component or layout	You can export a component or layout to modify it offline and then import it either as a new component or layout or to replace the existing component or layout. You can also export a component or layout to move it to another instance and import it there. You can export a component or layout individually or as part of a template package, which includes any custom components and layouts. When you export a component or layout, you copy the component or layout to a folder as a single .zip file. You can download the component or layout package directly from the folder to unpack and work with the individual files. When you’re done working with the component or layout files, create a .zip file that contains the component or layout package, import it, and overwrite the original component or layout or create a new one. See Export or Import Components or Layouts.
Publish a component or layout	If a site uses a new, unpublished component or layout, the component or layout is automatically published with the site when you place the site online for the first time. If you make changes to a component or layout and want to update online sites to show the changes, you must explicitly publish the component or layout. You can publish a component or layout if you’re the owner or if you’re assigned the Manager role. Select the component or layout in the list and click Publish (or Republish for previously published components or layouts) in the menu bar. A published icon is displayed next to the component or layout in the list.
Delete or restore a component or layout	If you have the appropriate permissions, you can delete a component or layout folder and its contents. When you delete a component or layout, the component or layout folder and all its associated folders and files are moved to the trash. You can delete or restore a component or layout if you created the component or layout (you’re the component or layout owner) or if someone shared a component or layout with you and gave you the manager role. Note: You can’t delete a component or layout if it’s used by any site or update, including sites or updates in the trash. To delete a component or layout, right-click the component or layout you want to delete and choose Delete. You’re prompted to move the component or layout to the trash. A deleted component or layout stays in the trash until: You restore the component or layout. You permanently delete the component or layout. Your trash quota is reached. The trash is automatically emptied based on the interval set by your service administrator. The default value is 90 days. To restore a component or layout, click Trash, then right-click the component or layout from the list and choose Restore.

Register Remote Components

To use a remote component in a site, you must first register it in Oracle Content Management.

You can register third-party remote components and remote components that you developed.

Note:

Before you can register a remote component, your administrator must enable the options in the Create menu. If you don’t see the Create menu on the components page, contact your administrator.

To register a remote component for use in Oracle Content Management:

1. Click Developer and then click View All Components.
2. Click Create and choose Register Remote Component.
3. In the Register Remote Component window, enter or select information including:

   • Name: Name of the component that users will see.

   • Description: Description of the component that users will see.

   • Component URL: The end point used in an iframe to render component content in a page. It must be HTTPS.

   • Settings URL: The end point used in an iframe to render the settings of a remote component added to a page. It must be HTTPS.

   • Settings Width: Sets the default width of the component settings panel in pixels.

   • Settings Height: Sets the default height of the component settings panel in pixels.

   • Key: A 192–bit AES key associated with the remote component and used to create a signed hash token when the component is provisioned. It’s used to encrypt and ensure component settings are read and written securely.

4. Click Register.
   When the remote component is created, the name appears in the list of components. You can explore the files used to register the component by clicking the component name in the list of components.

The component registration information is stored in the catalog used by sites created in the same Oracle Content Management instance, but the component remains a remote service.

As the component owner, component icon is added to the Custom Components panel in the editor with the name you assigned to the component. You can share the component with other users and they will see the component in the Custom Components panel in the editor.

Create Local Components, Layouts, Content Field Editors, or Content Forms

As a developer, when you create a local component or layout, you are given a fully-functional sample that you can modify for your own site or business requirements.

Before you can create a component or layout, your administrator must enable the options in the Create menu. If you don’t see the Create menu on the components page, contact your administrator.

As a developer, you can create components with access to the same features and capabilities as those provided by Oracle Content Management.

To create a sample local component or layout:

1. Click Developer and then click View All Components.
2. Click Create, and select the type of component or layout you want to create.
3. Enter a name for the component or layout. You can’t use a name used by another component or layout.

   You can use letters, numbers, underscores (_), and dashes (-). If you enter a space, it’s automatically replaced with a dash.

   Don’t use the following names for site templates, themes, components, sites, or site pages: authsite, content, pages, scstemplate_*, _comps, _components, _compsdelivery, _idcservice , _sitescloud, _sitesclouddelivery, _themes, _themesdelivery. Although you can use the following names for site pages, don’t use them for site templates, themes, components, or sites: documents, sites.

4. Optionally, enter a description for the component or layout.
5. For component type, select one of the following options:

   Option	Description
   Mustache	Renders with a Mustache template.
   Preact	Renders with a JSX template.
   React	Renders with a JSX template.
   Knockout (Sandboxed)	Renders with Knockout in an inline frame using an iframe element.
   Knockout	Renders with Knockout and contains nested components. The component is inserted directly into the page.

   Note:

   If selecting one of the template options (Mustache, Preact, or React), the local component is not Knockout-based and so cannot use nested components when placed on a page. For example this means that editing title or body text must be done through custom settings in the settings panel of the component, rather than selecting the component text as displayed on the page.
6. Click Create.
   A progress bar shows the creation status. When the component, layout, or form is created, the name appears in the list of components. You can explore the folders and files that make up the component or layout by clicking the component or layout name in the list of components.
7. To select an icon other than the default icon assigned to the component or layout:
   1. Select the component or layout from the list.
   2. Click Properties.
   3. Click the Component Logo tab.
   4. Click a logo from the gallery of logos and then click Done.

For detailed information about how to create your own components, see Develop Components.

After you have customized your component, layout, content field editor or content form, you can share it with others or promote it so they can use it in the following ways:

• Custom Component: When you use Site Builder, the component icon is added to the Custom Components panel in the editor with the name you assigned the component.

• Section Layout: When you use Site Builder, the section layout icon is added to the Section Layouts panel in the editor with the name you assigned the layout.

• Content Layout: A content administrator can assign the layout to one or more content types, either as the default view or added to a list of layouts that a site designer can select in Site Builder to specify how a content item of that type is displayed on the page.

• Content Field Editor: To make a content field editor available for use when creating content types, select it and click Promote, then confirm and click OK. Once promoted, content field editors are available to control the appearance of all data fields except Media and Reference when creating content types.
• Content Form: To make a content form available for use when creating content types, select it and click Promote, then confirm and click OK. Once promoted, content forms are available for use with all content types and asset types.

Export or Import Components or Layouts

You can export a component to modify it offline and then import it either as a new component or to replace the existing component. You can also export a component to move it to another Oracle Content Management instance and import it there.

Exporting

When you export a component, you essentially copy the component to a folder in the Oracle Content Management as a single .zip file. You can download the component directly from the folder to unpack and work with the individual files. When you are done working with the component files, create a .zip file that contains the component folders and files, import it, and overwrite the original component or create a new one.

Note:

When you export a component, sharing information for the component isn’t included.

To export a component:

1. Click Developer and then click View All Components.

2. Select a component or layout and choose Export from the menu bar or the right-click menu.

3. Navigate to a folder or create new folder by clicking New, providing a name and an optional description, and clicking Create. To open a folder, click the folder icon or the folder name.

4. Select a folder by clicking the checkbox for the associated folder and click OK.

   A component or layout package file is created in the selected folder with the component or layout name and a .zip extension.

Importing

Before you can import or create a component, layout, or content field editor, your administrator must enable the options in the Create menu. If you don’t see the Create menu on the components page, contact your administrator.

To import a component, layout or content field editor:

1. Click Developer and then click View All Components.

2. Click Create and choose Import component. Choose this option to import a component, a section layout, or a content layout.

3. If you uploaded the component or layout package, navigate to the folder that contains the component or layout and open the folder. If you haven’t uploaded the package yet, go to the folder where you want to upload the component or layout or create a new folder. Click Upload, then find the component or layout package and click Open.

4. Click the checkbox next to the component or layout file name and click OK. A new component or layout is created and added to the component list. If the component or layout name or ID already exists, you’re prompted to resolve the conflicts. You may need to create a new component or layout or you can overwrite the existing component or layout with the imported version.