Step 7: Create component templates

In this part of the tutorial, you will introduce component templates to enable your content editors to create complex pages. The component will appear as an option on content pages.

For more information about component template features, read the Component templates documentation.

This tutorial will step you through creating a simplified version of the hero-image component available in the Squiz marketplace.

Create a component asset

Create a new component asset called Hero Image :

  1. Right-click on the Configuration > Components folder.

  2. Select Create new…​  Design & Layout  Component Template.

  3. Name the component Hero image component.

  4. Select Create.

Configure the component asset

  1. Edit the Details page of your component asset:

    1. Right-click on the component asset.

    2. Select Details.

    3. Select Edit.

  2. Select a color and icon for your component:

    1. Select a color in the Icon section of the Details screen.

    2. Select an icon in the Icon section

    This image shows the Icon section of the Component template details screen. There is a row of colored dots and a grid of basic icons.
  3. Switch on Enable custom edit layout interface in admin mode by clicking the toggle.

  4. Set the Allowed Root Nodes field to the Site asset. Enter the asset ID of the Site asset or use the asset picker. This controls which content assets in your Matrix system will be allowed to use this component template.

    The allowed root nodes field containing the Site Asset details.
  5. Select Save.

The component will now be available on all of your pages when you select Add a component.

This image shows the properties pop-up for page content. It shows the Hero Image component available under the component template section.

Create a metadata schema for the component

Create a metadata schema for the component to control the hero image contents and when it is displayed.

  1. Right-click on the Hero image component.

  2. Select Create new…​  Metadata  Metadata Schema.

  3. Name the metadata schema Hero image schema.

  4. Select Create.

Configure the metadata schema

Add fields to the metadata schema for the component.

  1. Right-click on the metadata schema for the component.

  2. Select Details.

  3. Select Edit.

  4. Scroll down to Create New Section.

  5. Name the section details.

  6. Select Save.

  7. Add the following fields to the schema:

    1. Select Add field.

    2. Enter the details.

    3. Repeat for each field.

  8. Select Save.

    Key Friendly name Field type

    bgImage

    Background Image

    related asset

    btnText

    Button text

    text field

    btnLinkUrl

    URL link

    text field

This image shows the component metadata fields entered as described.

Apply the new metadata schema to the component

You must now tell the component about the metadata schema.

  1. Right-click on the Hero image component asset.

  2. Select Details.

  3. Select Edit.

  4. In the Metadata Schemas field, enter the asset ID of the hero image schema or use the selector to assign it.

  5. Select Save.

Load a hero image into Matrix

Load an image that you can use as your hero image.

  1. Right-click on Content  Test Site  Images.

  2. Select Create new…​  Files  Image.

  3. Enter the Title of your image.

  4. Select Choose file.

  5. Navigate to the image file you want to import.

  6. Select the file.

  7. Select Open.

  8. Enter a brief description of the image in Alt Text.

  9. Select Create.

Configure the hero image using the metadata

Use the metadata schema you have just created to configure the hero image.

  1. Right-click on the Home page.

  2. Select Content.

  3. Select Edit.

  4. Add the Hero image component:

    1. Select the + sign.

    2. Select the Hero image component.

  5. Select Save.

  6. Configure the hero image.

    1. Enter the asset ID of the image you loaded earlier into the Background image field or use the asset picker function.

    2. Add Select here to the Button text field.

    3. Enter http://www.example.com/ to the URL link for the button field.

      The paint layout field on the site asset showing Hero image layout.
    4. Select Save

Create a paint layout

Create a paint layout for the Component template.

  1. Right-click on the component.

  2. Select Create new…​  Design & Layout  Select Paint Layout.

  3. Enter the name Hero image layout.

  4. Select Create.

  5. Edit the type format asset and add some code.

    1. Expand the Hero image layout asset.

    2. Right-click on Default Format.

    3. Select Content.

    4. Select Edit.

    5. Replace the existing text with the following code:

    <div class="hero-image full-width-section p-5 m-5%"
    style="background-image: linear-gradient(#00000080, #00000080), url(%asset_metadata_bgImage^as_asset:asset_url%);"> (1)
    <div class="container">
    <div class="text-center p-0 p-md-5">
    <div class="text-light">
    %asset_contents% (2)
    </div>
    <a class="btn btn-md btn-outline-light" href="%asset_metadata_btnLink^as_asset:asset_url^empty:{asset_metadata_btnLinkUrl}%">
    <span class="ml-1" >%asset_metadata_btnText%</span> (3)
    </a>
    </div>
    </div>
    </div>
    1 Inline styles in the hero-image div, which include a keyword that prints the URL of the background image as the CSS background image of the div.
    2 The %asset_contents% keyword which prints the content of the component.
    3 Links that have two keywords that print the URL and the text of the call to action link.
  6. Select Save.

Apply the paint layout to your Component template

  1. Right-click on the Hero image component asset.

  2. Select Details.

  3. Enter the asset ID of the Hero image layout asset in the Paint Layout field, or use the asset picker function.

  4. Select Save.

    The paint layout field on the Hero image component asset showing Hero image layout.

Test your changes

Test your changes so far.

You can test your site in a browser in two ways:

  1. Copy the URL from the site asset and paste it into a browser.

  2. Right-click on the site asset and select Preview  In new window.

    This image shows the drop-down menu that appears when you right-click on the site asset. It shows Preview selected
  3. You will see your site in the new tab.

This image shows the home page with the hero image component applied. It shows a blank hero image in the top third of the page.

Create a custom edit layout

This step is optional.

Metadata is used to configure your site. Editors can use the raw metadata forms, or you can improve their experience by creating a formatted page to enter what they need. You create the formatted page using a custom edit layout.

To create a basic custom edit layout:

  1. Right-click on the Hero image component asset.

  2. Select Create New…​ > Design & Layout > Custom Edit Layout

  3. Enter the name Hero image edit layout.

  4. Select Create.

  5. Right-click on the Hero image edit layout asset.

  6. Select Content.

  7. Select Edit

  8. Replace the existing code with the following code:

    This code is a basic implementation of a custom edit layout and is not optimized for production.
    <style> (1)
    .hero-image_edit{
    width: 100%;
    height: 20em;
    background-size: cover;
    background-repeat: no-repeat;
    background-position: center;
    }
    .hero-image-field_edit{
    background: white;
    border-radius: 3px;
    padding: 0.3em 0.2em;
    margin: 1em 0;
    }
    .hero-image-list_edit{
    list-style-type: none;
    width: 29em;
    padding-top: 1em;
    }
    </style>
    <div class="hero-image_edit" style="background-image: linear-gradient(#00000080, #00000080), url(%asset_metadata_bgImage_asset_url%); " >
    <ul class="hero-image-list_edit"> (2)
    <li class="hero-image-field_edit">Background image: %metadata-F_XXXX%</li> (3)
    <li class="hero-image-field_edit">Button text: %metadata-F_YYYY%</li> (4)
    <li class="hero-image-field_edit">Button link URL: %metadata-F_ZZZZ%</li>
    </ul>
    </div>
    1 It uses a style tag to style your custom edit layout, which would preferably use a separate stylesheet so it can be re-used across many custom edit layouts.
    2 The code prints the HTML that will be rendered in the custom edit layout. You can add your own help text and descriptions here alongside the fields.
    3 Prints the background image metadata field as the background for the component in editing mode, so that editors can preview what the background image will look like after saving.
    4 Uses keywords in the form of %metadata-F_XXXX% to render the metadata form fields from the component, where XXXX is the asset ID of the metadata field.
    For a full list of keywords you can use in custom edit layouts, select view custom edit layout keywords link when editing the custom edit layout.
    This image shows the content edit page of the Hero image edit layout asset. It shows the View customer edit layout keywords link at the top of the page.
  9. Update the code to replace XXXX, YYYY, and ZZZZ with the asset IDs of the appropriate metadata field IDs.

    This image shows the metadata assets
  10. Select Save

  11. On the Hero image component  Details screen:

    1. Select Edit.

    2. Add the asset ID of your custom edit layout to the Custom Edit Layout field.

    3. Select Save.

  12. Edit your Home page again:

    1. Go to Home  Content

    2. Select Edit.

You should now see a more friendly editing interface.

This image shows the custom edit layout fields on top of the hero image.