Testing layouts locally

After creating your layout files (page-layout.yaml and markup.hbs), test them locally to confirm that they work as expected before deploying them to the Squiz DXP.

Preparing for local testing

When your layout is deployed to the Component Service in the Squiz DXP and accessed in the Page Builder, it has access to components to be inserted into the content zones in the layout, as well as the website design.

When testing locally, these are not available. It is necessary, therefore, to provide material for each content zone and include the CSS that the website design provides when running local tests.

Zone content

Content zones require content to render.

Map HTML files to each zone using the --zones option.

Any valid HTML file — such as component output snippets, test content, or a manually created file containing the bare minumum to be valid HTML — can verify the layout structure.

The zones option uses the format ZoneName:FilePath:

--zones=zone1:content1.html --zones=zone2:content2.html

You can combine multiple zone mappings into a single option by separating them with commas:

--zones=zone1:content1.html,zone2:content2.html

You can use either : or = as the separator between the zone name and file path. Using : avoids confusion when the file path contains = characters.

If your content files are in a subfolder, include the path:

--zones=zone1:path/to/content1.html

CSS stylesheet

Include the CSS file that your website design provides, or at least the CSS classes used in your layout template.

Specify the stylesheet using the --stylesheet option:

--stylesheet path/to/stylesheet.css

If your website design uses a CSS framework (for example, Bootstrap), include the framework’s CSS file. If your website design uses custom CSS, include your custom stylesheet.

Running the local development server

Use the dxp-next page layouts dev command to start a local development server.

$ dxp-next page layouts dev --help
Usage: dxp-next page layouts dev [options]

Start a development server for page layouts

Options:
 --config <string>    File path to the page layout config file (default: "./page-layout.yaml")
 --port <number>      Port to run the development server on (default: "4040")
 --no-open            Do not automatically open browser
 --stylesheet <path>  Path to CSS file to include
 --zones <items>      Zone content mappings (default: {})
 --options <items>    Layout options (default: {})
 -h, --help           display help for command

The following options are available:

--config <string>: Specifies the layout configuration file path.

If you use the default filename of page-layout.yaml in the current directory, you can omit this option.
--zones <items>: Maps content files to each zone defined in your layout configuration.

Each mapping uses the format ZoneName:FilePath.
--stylesheet <path>: Specifies the path to the CSS file to include when rendering the layout.
--port <number>: Specifies the port number for the development server.

The default port is 4040.
--no-open: Prevents the browser from opening automatically when the server starts.
--options <items>: Specifies layout options (default: {}).

Command example

The following example shows a complete command with all options:

$ dxp-next page layouts dev --config page-layout.yaml --zones=main:Mock/main.html --zones=lhs:Mock/lhs.html --zones=rhs:Mock/rhs.html --stylesheet Mock/bootstrap.min.css

This starts a local development server on port 4040 and opens a browser to display the layout with the specified content and stylesheet.

Layout preview showing three columns with placeholder content

Figure 1. Local development preview

Auto-reload

The local development server monitors the layout files and zone content files for changes. When changes are detected, the server automatically reloads the layout and refreshes the browser.

This feature lets you make changes and see their effects without stopping and restarting the development server.

Help Center

Menu