Customizing master layouts

Master layouts are important building blocks in the construction of your Wild Apricot site. A website theme can contain multiple master layouts, each of which defines the broad outline of a page, and contain some of the graphical elements common to the theme. For example, you may have three master layouts in your system – one with a sidebar, header and footer, another with a header and footer but no sidebar, and one for landing pages, with nothing except a single content area. Master layouts form the basis for page templates, in the same way that page templates form the basis for pages.

Within a master layout – and consequently, within the page templates based on it – the areas in which content can be placed are defined by placeholders. Placeholders are special areas that serve as containers into which gadgets and layouts can be dropped when editing a page template or page.

Defining master layouts

Master layouts are defined for each theme in the MasterLayouts/LayoutsConfig.cfg file. For each master layout, you can specify the name of the layout (as it will be displayed to administrators), the layout identifier for the page model, and a description of the master layout. You can also define which layout should be used as the default layout.

<Layouts>
  <DefaultLayoutId>LayoutMain</DefaultLayoutId>
  <Layout>
    <ID>LayoutMain</ID>
    <Title>Main Layout</Title>
    <Description></Description>
  </Layout>
  <Layout>
    <ID>LayoutPlain</ID>
    <Title>Plain layout</Title>
    <Description></Description>
  </Layout>
  <Layout>
    <ID>LayoutLegacy</ID>
    <Title>Legacy Layout</Title>
    <Description></Description>
  </Layout>
</Layouts>

In the example above, we have defined three layouts: main, plain and legacy, and set the main layout as the default.

Creating a new master layout

To create a new master layout, follow these steps:

1. Create a new master layout template file (.tpl) within the MasterLayouts folder.
2. Within the template file, define placeholder areas for gadgets and layouts. For instructions, see Defining placeholders (below).
3. Add a reference to the new master layout in LayoutsTemplate.tpl.
4. Add a reference to the new master layout in LayoutsConfig.cfg.
5. If needed, add placeholder settings to be displayed on the Colors & Styles screen (see Customizing Colors and Styles options for themes).

Modifying an existing master layout

To modify an existing master layout, follow these steps:

1. Find the name of the master layout you want to modify. You can view a list of master layouts when modifying page template settings.
2. In the LayoutsConfig.cfg file, find the ID for the master layout.
3. In the LayoutsTemplate.tpl file, find the <$if ... $> for your master layout and note the name of the .tpl file.
4. Open the appropriate .tpl file and make the required changes.

Defining placeholders

Placeholders are the areas in the which gadgets and layouts can be dropped when editing a page or page template. In master layout files, placeholders are defined using the following format.

<$Area Name="AreaName" ClientId="areaClientId" ClassName="areaClassName"$>

For example, in your MasterLayouts/LayoutLegacy.tpl file you might use a string like this:

<$Area Name="Footer" ClientId="idFooterContentHolder" ClassName="footerContentHolder cnFooterContentHolder"$>

This will define a placeholder area – a special DIV structure recognized by Wild Apricot – with the name Footer, an ID of idFooterContentHolder, and classes of footerContentHolder cnFooterContentHolder. You can access the DIV later from your CSS by ID or using the specified classnames.

Using master layouts

The currently selected master layout is defined in the main theme template file – MainTemplate.tpl – using the special <$MASTER_LAYOUT$> directive. When the template engine encounters the <$MASTER_LAYOUT$> entry, it loads MasterLayouts/LayoutsTemplate.tpl.

The currently selected layout is passed to the current page's page model as <$PageModel.Layout.LayoutName$> and parsed in LayoutsTemplate.tpl, as follows:

<$if (PageModel.Layout.LayoutMain)$>
	<$MasterLayouts/LayoutMain()$>
<$endif$>

<$if (PageModel.Layout.LayoutLegacy)$>
	<$MasterLayouts/LayoutLegacy()$>
<$endif$>

<$if (PageModel.Layout.LayoutPlain)$>
    <$MasterLayouts/LayoutPlain()$>
<$endif$>

<$if (PageModel.Layout.LayoutSecondary)$>
    <$MasterLayouts/LayoutSecondary()$>
<$endif$>

In the code above, the system checks all possible PageModel.Layout.LayoutNames and loads the template file for this specific selected layout. For example, if PageModel.Layout.LayoutLegacy is validated as true, the template engine loads the MasterLayouts/LayoutLegacy.tpl file.