Testing layouts locally

After creating your layout files (manifest.json and markup.hbs), test them locally to confirm that they work as expected. Do this 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. It also has access to the website design. When testing locally, these are not available. Therefore, provide material for each content zone. Include the CSS that the website design provides when running local tests.

Zone content

Content zones require content to render.

The zones option uses the format ZoneName:FilePath. Using a space instead of an equals sign matches the system’s usage screen and is recommended for consistency.

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. Note the space after --zones.

--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.

Faking zone content

When testing locally, you do not have access to live components or text blocks from the Squiz DXP. To test your layout’s structure and responsiveness, you must provide "fake" content for each zone.

For example, if you have a three-column layout with lhs, main, and rhs zones, you can create simple HTML files, for example, lhs.html and main.html. These files contain placeholder text or mock components to simulate how the real page will look.

CSS stylesheet

Include the CSS file that your website design provides. Alternatively, include 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: "./manifest.json")
  --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: {})
  --properties <items>  Layout properties (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 manifest.json 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.

--properties <items>

Specifies layout properties. To provide multiple properties, repeat the flag for each one.

--properties showSidebar:true --properties sidebarWidth:25

Command example

The following example shows a complete command with all options:

$ dxp-next page layouts dev --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. It 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 the server detects changes, it automatically reloads the layout and refreshes the browser. This feature enables you to make changes and see their effects. You can do this without stopping and restarting the development server.

Help Center

Menu