Using Custom Components in Site Builder – Oasis Resource Center

Content Item Layout Builder

The Content Item Layout Builder is a tool that lets you visually design how a single content item appears on a page. It allows you to drag and drop standard components to create the layout, and automatically pulls values from your content type’s fields, placing them into the designed layout.

💡

Think of it as a “mini site builder” but specifically for one type of content, like a blog post, product listing or portfolio entry

Using the Layout Builder

Step 1: Navigate to the Item Layouts Page

Click Developer in the side menu then select Build Layout in the Item Layouts card.

Step 2: Create a New Layout

Click Create and enter the required information for the new layout: name, description (optional), and the content type the layout is for. Once created, the new layout will appear in the list. Click the Hammer icon to open the builder.

Step 3: Configure Layout Details

Similar to the the Site Builder, create a new update by clicking Edit. You’ll be prompted to define the size of your component canvas or choose from the list of preset sizes. Drag and drop different components onto the canvas and optionally map them to fields from your content type. After configuration is complete, promote the update to the base version of the item layout.

Step 4: Use the Layout on Your Site

There are two ways to use an item layout in the Site Builder:

Using the Item Layout Directly

In the Item Layouts tab, drag and drop the item layout onto your page and select the content item you want to display. The mapped fields will automatically populate with the selected item’s values.

Using a Content List

In the Components tab, drag and drop a Content List onto your page. In the Properties Panel, select the item layout you want to use. This dynamically generates the layout for all content items of the selected content type.

⚠️

Make sure the content type is added to the same repository as your site. Otherwise, you won’t be able to select content items for that content type

The Code Component

The Code Component is a standard component block that allows you to manually insert HTML, CSS, or JavaScript to add behavior or layouts the builder doesn’t natively support. Common use cases include:

Adding third-party scripts (forms, embeds, analytics)

Creating custom interactions or animations

Injecting advances layouts the editor can’t build

Writing custom JavaScript logic (dynamic content, sliders)

To use it, drag a Code Component onto your update’s canvas. Then, double-click the block to open the editor and add your code. The Code Component is injected into the builder-generated page, running in the same environment and sharing the same runtime as the builder’s code.

⚠️

HTML content can be added directly, however CSS and JavaScript code must be enclosed in <style> and <script> tags

Considerations Before Use

Code Components provide flexibility and power, but bypass many of the safeguards and conveniences of the visual editor. They should be used when necessary, and with care, to avoid layout, styling, or runtime issues. Keep in mind the following limitations:

Limited visual editor integration - Individual elements defined within the code cannot be visually edited, and the editor cannot validate or preview internal layout changes in the same way it does for native components

No automatic design system alignment - Custom code does not automatically inherit the builder’s predefined styles. Any required styling must be applied manually

Potential to introduce errors or conflicts -As custom code runs in the same environment as the builder’s code, mistakes can have wider effects. The builder cannot fully guard or sandbox custom code, so it’s the author’s responsibility to ensure it is correct and properly scoped