Step 1: Create a simple Hello World website

The first step of these instructions will guide you through creating a basic Hello World website. You will create a folder structure, URLs, and a basic design.

The folder structure

Matrix sites are made up of many assets of different types. Assets are usually organized into folders of similar types to make them easy to access. By convention, display and control assets are separated from content assets. Read Working with assets to learn more about the different types of Matrix assets.

In this example, you will create a folder called Configuration, which houses everything that makes up the site template and any integrations or back-end functionality built with assets. This is where developers and site builders collaborate on the site functionality, rendering, and content editor experience.

You will also create a folder named after the website. This folder will be used to contain the site and its content. This is where content editors, subject matter experts, and approvers collaborate on the content of the site.

You will create a structure that looks like the image shown below. In this example, the folder containing the site template is called Configuration, and the content folder is called Content. This folder structure is used for a clear separation of functions and also to make it easier to apply permissions or re-use the template on multiple websites.

matrix example site structure

You can use the binoculars icon to find out where your current asset appears in the structure. Select Find in asset tree button to highlight the entire path to your asset in the asset tree.

binocular action

How to set up your folder structure

To set up your base folder structure in the Matrix UI:

  1. Choose a high-level parent asset from your asset tree.

  2. Create a parent folder for your site under the high-level parent with the name of your project, for example, Test Site.

    1. Right-click on the high-level parent folder.

    2. Select Create new…​  Folder.

    3. Enter the name.

    4. Select Create.

      This folder should be named after your website, but for this example it will be called Test Site.
    This image shows the test site folder created as a child of the test folder asset.
  3. Create a folder called Configuration as a child of Test Site

  4. Create a folder called Content as a child of Test Site.

This image shows a high-level folder called Test Folder

Populate the configuration folder

Set up the structure underneath the Configuration folder.

Create the following assets as children under the Configuration folder:

  1. A site asset called Designs.

    1. To create a site asset in the Configuration folder:

      1. Right-click on the Configuration folder.

      2. Select Create new…​  Web  Site.

      3. Enter Designs as the site name.

      4. Select Create.

  2. A folder called Paint Layouts. Paint Layouts are inner page templates.

    1. To create a folder in the Configuration folder:

      1. Right-click on the Configuration folder.

      2. Select Create new…​  Folder.

      3. Enter the folder name.

      4. Select Create.

  3. A folder called Metadata Schemas. Metadata schemas are used for all structured content and custom content models within Matrix, as well as for HTML metadata.

  4. A folder called Components. Components are used for modular templates that can be added as a page section.

  5. Create the following assets as children of the Designs site asset:

    1. A folder called Designs. This is where your main template files will be stored.

    2. A folder called Design nesters. This is where includes for your template will be stored.

    3. A folder called CSS. This is where the CSS files are stored.

    4. A folder called JS. This is where any JavaScript code is stored.

    5. A folder called SSJS. Server-Side JavaScript - used for custom server-side logic is stored here.

    6. A folder called Images. Any images that are included in the global design will be stored here.

  6. At the end of these steps, you will have a structure like the one shown below:

This image shows the Configuration folder child folders created in the preceding steps. The child folders are: Designs

Populate the content folder

Set up assets under the Content folder.

You can call the Content folder anything you want, such as the friendly name of your website. It is called the Content folder here for ease of reference.

To create a site asset called Test Site:

  1. Right-click on the Content folder.

  2. Select Create new…​  Web  Site.

  3. Type Test Site as the site name.

  4. Select Create.

This image shows a site asset called website created as a child of the Content folder.

Add URLs to the site assets

The main URL of your site can be a new domain, for example, www.example.com, or you can use the base URL of your Matrix instance with a suffix. An example of the base URL of the Matrix instance with a suffix added is <organisation-name>.matrix.squiz.cloud/test-site/.

This is usually the fastest way to get started when testing a new site. The Designs site asset should use the same URL, with a _designs suffix. For example, <organisation-name>.matrix.squiz.cloud/test-site/_designs/.

To add URLs to the Test Site and Designs site assets:

Right-click on the site asset and then select URLs.
  1. Select Edit.

  2. Enter the domain name.

  3. Select the HTTPS check box.

  4. Select Save.

Create a home page

The next step is to create a home page for your site.

The home page is a standard page asset, with a special association with your site asset so that Matrix knows to serve this page as the home page.

To create a standard page under the site asset called Home:

  1. Right-click on the Test Site site asset.

  2. Select Create New…​  Pages  Standard Page.

  3. Type Home as the name.

  4. Select Hidden link to hide this page from navigation menus.

  5. Select Create.

To assign the Home page to the site asset as the index page:

  1. Right-click on the Test Site site asset and select Details.

  2. Scroll down to the Special page links section.

  3. Select bnt:[Edit].

  4. Add the asset ID of the home page to the Index page field.

    You can either enter the asset ID in the Index page field or use the asset picker to select the asset.
  5. Select Save.

    This gif shows how to assign a home page to the Index page field in the Details page of the Website site asset.

To edit the home page and add "Hello World" to the contents:

  1. Right-click on the Home asset.

  2. Select Content.

  3. Select Edit.

  4. Type the text "Hello World" into the Content tab.

  5. Select Save.

This image shows how to access the home page content. It shows the drop-down menu shown when you right-click on the Page Contents asset under the Home page. Content is highlighted.

Create a design asset

A design asset provides the global design layout for your site template. The main aspect of creating a design asset is to add a design parse file. This file is an HTML file that includes special Matrix tags. Matrix parses this file to create several hidden design assets under the hood.

The design asset for this example site is very simple. Read the design assets body area documentation for more information about what else you can do with the design asset.

To create a design asset as a child of the Designs folder under the Designs site asset:

  1. Expand the Designs site asset.

  2. Right-click on the Designs folder.

  3. Select Create new…​  Design & Layout  Design.

  4. Type Global design as the name.

  5. Select Create.

image::create-design-asset.png[This image shows the menu system used to navigate to create a design asset. It shows the menu presented when you right-click the Designs folder. The next level is the drop-down presented when you select Create New. The next level is the drop-down presented when you select Design & Layout. The Design selection is highlighted.]

The next thing to do is add default HTML structures to the parse file.

To define the default parse file structures for a design:

  1. Right-click on the Design asset and select Edit Parse File.

  2. Select Edit.

  3. Add this HTML structure to the parse file:

    <html> (1)
    <head>
    <title>%globals_asset_name% | %globals_site_name%</title> (2)
    </head>
    <body>
    <header class="bg-white border-bottom"> (3)
    </header>
            <div class="page-wrapper container"> (4)
                <div class="page-content mt-3">
                    <mysource_area id_name="body" design_area="body" /> (5)
                </div>
            </div>
        </body>
    </html>
    1 Global HTML tags (HTML, head, title).
    2 Keywords, that print the name of the page and the name of the site.
    3 A header to which you will add more features later in this guide.
    4 Divs that will be used to apply some Bootstrap 5 classes that will be used later in the guide for styling.
    5 The mysource_area tag, which is a special Matrix tag that tells Matrix to print the body of the page here.
    This is the basic parse file structure to which you can add other design elements.
  4. Select Save.

Apply your design to the site

To apply your design to the site:

  1. Right-click on the Test Site asset and then select Settings  Designs.

  2. Select Edit.

  3. Add Global design asset to the Design field under the System defined frontend design header. You can either enter the asset ID in the Design field or use the asset picker tool to select the asset.

    This gif shows the process required to assign the design to the site. Right-click on the site
If a design asset already exists in your Matrix site, it may be set as the System Defined Frontend Design by default. When you add your design, it will be overridden.

Test your site

Now that you have created a site, added URLs, and given it a home page, it is time to see your site in action.

You can test your site in a browser by using one of the following methods:

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

    OR

  • 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
    1. You will see your site in the new tab.

    This image shows a browser tab with the words Hello World in the top left corner.