Overriding the default Create Record template

This article covers how to override the default settings of the arcade-games-create template.

In this article we will cover some of the ways in which you can override the arcade-games-create template that was auto-generated when we created the Arcade Games object. All of the components you can use to customize your pages can be found on Storybook.

The default template

The default arcade-games-create template that was generated for the Arcade Games object contains the following:

{% extends "base-recordcreate" %}

{% set resource_name="Arcade Games" %}
{% set validation_schema="ArcadeGamesCreate" %}

As covered in the system-generated pages article, this means that the arcade-games-create template extends the base-recordcreate template, and tells us the name of the resource and the validation schema.

On the base template, the content is split into header, body, and footer blocks. To change the content within any of these blocks, you need to add the relevent tags to your template and then add components you want to change between them.

Before overriding any of the default template’s content, the following page is rendered in Platform:

Create Record page before customisation

This article will take you through the process of configuring the default arcade-games-create page so that it renders in a more user-friendly way, for example:

Create Record page after customization

Overriding the header

The content of the header is defined in the header block in the base-recordcreate template.

  {% block header %}
      <sp-header style="margin-bottom: 0">
          <sp-column>
              <sp-heading size="2xl" level="1">
                  {% block title %}
                      Create New {{ resource_name }}
                  {% endblock title %}
              </sp-heading>
              <sp-row style="--sp-row-spacing: var(--sp-spacing-3); color: var(--sp-color-neutral-750)">
                  <sp-icon icon="details"></sp-icon>
                  <span>{{resource_name}}</span>
              </sp-row>
          </sp-column>
      </sp-header>
  {% endblock header %}    

This header block renders as follows (where Arcade Games is the resource_name):

Create Record page header

You can override any of the details in this block by adding the {% block header %}{% endblock header %} tags to your template and entering the components you want to include between them.

Title

The title of the Create Record page is generated from the title block of the base template and pulls in the resource name. Enter the following between the {% block header %}{% endblock header %} tags, and then modify the text between the {% block title %}{% endblock title %} tags to change the title, for example from Create New Arcade Games to Arcade Game Machines.

<sp-header style="margin-bottom: 0">
  <sp-heading size="2xl" level="1">
    {% block title %}
      Arcade Game Machines
    {% endblock title %}
  </sp-heading>
</sp-header>

The header now renders as follows:

Create page header title only

Subtitle

To add a subtitle to your header, you need to add the span element to your template below the sp-heading element. Enter your subtitle between the tags.

{% block header %}
  <sp-header style="margin-bottom: 0">
    <sp-heading size="2xl" level="1">
        {% block title %}
          Arcade Game Machines
        {% endblock title %}
    </sp-heading>
      <span>Enter the machine's details</span>
  </sp-header>
{% endblock header %}

The header now renders as follows:

Create Record page header with subtitle

Adding an icon

To include an icon in the subtitle, you need to add the sp-icon element to your template. A list of the currently available icons can be found in Storybook.

The icon page in storybook

For example, to add a pencil icon to your subtitle, add the following line, <sp-icon icon="edit"></sp-icon>, beneath the heading element.

{% block header %}
  <sp-header style="margin-bottom: 0">
      <sp-heading size="2xl" level="1">
          {% block title %}
            Arcade Game Machines
          {% endblock title %}
      </sp-heading>
    <sp-icon icon="edit"></sp-icon>
    <span>Add new record</span>
  </sp-header>
{% endblock header %}

This renders as:

Header with new icon

Header layout

Add the sp-column and sp-row elements to your header in order to adjust the layout of the header content.

{% block header %}
    <sp-header style="margin-bottom: 0">
      <sp-column>
        <sp-heading size="2xl" level="1">
            {% block title %}
                New Machine
            {% endblock title %}
        </sp-heading>
            <sp-row style="--sp-row-spacing: var(--sp-spacing-3)">
                <sp-icon icon="edit"></sp-icon>
                <span>Add new record</span>
            </sp-row>
        </sp-column>
    </sp-header>
{% endblock header %}

In the example above: - the sp-row element ensures the icon and subtitle are laid out in a row with equal spacing between the sp-icon and span elements. The spacing is defined by overriding the --sp-row-spacing CSS variable. - the sp-column element ensures the title and subtitle rows are laid out in a column with spacing between them.

The header now renders as:

Create Record page layout adjusted

For more information about spacing and alignment, see the Flex layout section in Storybook.

Changing the color

On the default Create Record page, the color of the subtitle is gray (--sp-color-neutral-750). This is defined in the sp-row element. To change the color of the subtitle on your modified page, add the --sp-color variable to the row element. A list of the available colors can be found on Storybook.

For example, to change the color of the subtitle to gray, add color: var(--sp-color-neutral-600) to your row element.

The header block in the arcade-games-create template now looks as follows:

{% block header %}
    <sp-header style="margin-bottom: 0">
        <sp-heading size="2xl" level="1">
            {% block title %}
                Arcade Game Machines
            {% endblock title %}
        </sp-heading>
        <sp-row style="--sp-row-spacing: var(--sp-spacing-3); color: var(--sp-color-neutral-600)">
            <sp-icon icon="edit"></sp-icon>
            <span>Add new record</span>
        </sp-row>
    </sp-header>
{% endblock header %}

This renders as:

Header with new colour


Overriding the body

The main body of the Create record page is defined by the body block in the base-recordcreate template.

  {% block body %}
      <sp-responsive-columns style="border-top: var(--sp-border-divider);">
          <div>
              <platform-component package-name="recordpage" name="ValidationBanner"></platform-component>
              <platform-component package-name="recordpage" name="AutoForm"></platform-component>
          </div>
      </sp-responsive-columns>
  {% endblock body %}

The custom fields that you added to your object are rendered on the Create Record page by the AutoForm component. The AutoForm component waits for a validation schema to be parsed and then auto renders any relevant FormField elements. The ValidationBanner ensures a message banner is displayed if the form doesn’t validate correctly.

To override the appearance of the content in the body of the Create record page, add the {% block body %} and {% endblock body %} tags to your template and then add your customizations between them.

Reordering the fields

Autoform renders the fields in the sequence in which they appear on the validation schema. To reorder the fields, we can override this by adding the individual AutFormField components for each field between the {% block body %} and {% endblock body %} tags.

For example, to reorder how the fields are displayed on the Arcade Games Create page, enter the following between the {% block body %} and {% endblock body %} tags in the arcade-games-create template, where the ptr value is the field’s name:

{% block body %}
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/name" label-position="top" placeholder="Enter a name"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/Id" label-position="top" placeholder="Enter a product ID"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/style" label-position="top" placeholder="Select a style"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/category" label-position="top" placeholder="Select a category"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/make" label-position="top" placeholder="Enter a make"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/theme" label-position="top" placeholder="Enter a theme"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/costperday" label-position="top" placeholder="Enter a cost"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/linkurl" label-position="top" placeholder="Enter a url"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/imageurl" label-position="top" placeholder="Enter an image url"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/maintenancedue" label-position="top" placeholder="Date annual maintenance is due"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/repairhistory" label-position="top" placeholder="Enter pertinant repair history and engineer notes"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/lastseenby" label-position="top" placeholder="Who was the last engineer to see the machine?"></platform-component>
  <platform-component package-name="recordpage" name="AutoFormField" ptr="/status" label-position="top" placeholder="Maintenance status"></platform-component>
{% endblock body %}

This renders as:

create page fields reordered

Splitting the page into columns

To split the page into columns, add the <sp-responsive-columns> element and then wrap the components you want to include in each column in a div element. For example, to split the Arcade Games create page into two columns, enter the following:

  <sp-responsive-columns>
      <div>
        {# Left Column #}
          <platform-component package-name="recordpage" name="AutoFormField" ptr="/name" label-position="top" ></platform-component>
          <platform-component package-name="recordpage" name="AutoFormField" ptr="/id" label-position="top" placeholder="Enter a product ID"></platform-component>
          <platform-component package-name="recordpage" name="AutoFormField" ptr="/style" label-position="top" placeholder="Select a style"></platform-component>
          <platform-component package-name="recordpage" name="AutoFormField" ptr="/category" label-position="top" placeholder="Select a category"></platform-component>
          <platform-component package-name="recordpage" name="AutoFormField" ptr="/make" label-position="top" placeholder="Enter a make"></platform-component>
          <platform-component package-name="recordpage" name="AutoFormField" ptr="/theme" label-position="top" placeholder="Enter a theme"></platform-component>
          <platform-component package-name="recordpage" name="AutoFormField" ptr="/costperday" label-position="top" placeholder="Enter a cost"></platform-component>
          <platform-component package-name="recordpage" name="AutoFormField" ptr="/imageurl" label-position="top" placeholder="Enter an image url"></platform-component>
      </div>  
      <div>
        {# Right Column #}
            <platform-component package-name="recordpage" name="AutoFormField" ptr="/maintenancedue" label-position="top" placeholder="Date annual maintenance is due"></platform-component>
            <platform-component package-name="recordpage" name="AutoFormField" ptr="/repairhistory" label-position="top" placeholder="Enter pertinant repair history and engineer notes"></platform-component>
            <platform-component package-name="recordpage" name="AutoFormField" ptr="/lastseenby" label-position="top" placeholder="Who was the last engineer to see the machine?"></platform-component>
            <platform-component package-name="recordpage" name="AutoFormField" ptr="/status" label-position="top" placeholder="Maintenance status"></platform-component>
      </div>
  </sp-responsive-columns>
{% endblock body %}

This renders as:

create page columns

Adding headings to the body

To add headings to the body block use the sp-heading element. For example, to add

{% block body %}
<sp-responsive-columns>
  <div>
     {# Left Column #}
        <sp-heading size="base" style="margin-bottom: var(--sp-spacing-4)">Summary</sp-heading>

        <platform-component package-name="recordpage" name="AutoFormField" ptr="/name" label-position="top" placeholder="Enter a name"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/Id" label-position="top" placeholder="Enter a product ID"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/style" label-position="top" placeholder="Select a style"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/category" label-position="top" placeholder="Select a category"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/make" label-position="top" placeholder="Enter a make"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/theme" label-position="top" placeholder="Enter a theme"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/costperday" label-position="top" placeholder="Enter a cost"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/imageurl" label-position="top" placeholder="Enter an image url"></platform-component>
  </div>
  <div>
     {# Right Column #}
        <sp-heading size="base" style="margin-bottom: var(--sp-spacing-4)">Maintenance details</sp-heading>

        <platform-component package-name="recordpage" name="AutoFormField" ptr="/maintenancedue" label-position="top" placeholder="Date annual maintenance is due"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/repairhistory" label-position="top" placeholder="Enter pertinant repair history and engineer notes"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/lastseenby" label-position="top" placeholder="Who was the last engineer to see the machine?"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/status" label-position="top" placeholder="Maintenance status"></platform-component>
  </div>
</sp-responsive-columns>
{% endblock body %}

This renders as:

create page subheadings

Adding a border

To add a border between the header and body, add "border-top: var(--sp-border-divider)" to the sp-responsive columns element. For example:

{% block body %}
<sp-responsive-columns style="border-top: var(--sp-border-divider)">
  <div>
     {# Left Column #}
        <sp-heading size="base" style="margin-bottom: var(--sp-spacing-4)">Summary</sp-heading>

        <platform-component package-name="recordpage" name="AutoFormField" ptr="/name" label-position="top" placeholder="Enter a name"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/Id" label-position="top" placeholder="Enter a product ID"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/style" label-position="top" placeholder="Select a style"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/category" label-position="top" placeholder="Select a category"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/make" label-position="top" placeholder="Enter a make"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/theme" label-position="top" placeholder="Enter a theme"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/costperday" label-position="top" placeholder="Enter a cost"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/imageurl" label-position="top" placeholder="Enter an image url"></platform-component>
  </div> 

  <div>
     {# Right Column #}
        <sp-heading size="base" style="margin-bottom: var(--sp-spacing-4)">Maintenance details</sp-heading>
    
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/maintenancedue" label-position="top" placeholder="Date annual maintenance is due"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/repairhistory" label-position="top" placeholder="Enter pertinant repair history and engineer notes"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/lastseenby" label-position="top" placeholder="Who was the last engineer to see the machine?"></platform-component>
        <platform-component package-name="recordpage" name="AutoFormField" ptr="/status" label-position="top" placeholder="Maintenance status"></platform-component>
  </div>
</sp-responsive-columns>

This renders as:

create page border


The footer of the template is defined by the footer block in the base template. For example:

{% block footer %}
    <sp-button-group slot="right">
         <a href="{{ back_url }}"><sp-button button-type="transparent">Back</sp-button></a>
         <platform-component package-name="recordpage" name="SaveButton" body="Create record"></platform-component>
    </sp-button-group>
{% endblock footer %}

Add the {% block footer %} and {% endblock footer %} tags to the bottom of your template in order to override the default content. For example, you could change the position of the button to the left or center of the footer, or you could change the text on the button.

To override the text on the button in the Create Record page footer, enter the following information between the {% block footer %} and {% endblock footer %} tags, where body= is the text that appears on the button:

{% block footer %}
    <sp-button-group slot="right">
         <a href="{{ back_url }}"><sp-button button-type="transparent">Back</sp-button></a>
         <platform-component package-name="recordpage" name="SaveButton" body="Create machine record"></platform-component>
    </sp-button-group>
{% endblock footer %}

Last modified May 4, 2022: added contents (d50d135)