Layouts interact with codeframes to help determine the overall structure of a page as well as supply common content. Before reading this help, please refer to the following pages that describe codeframes and layouts.
Layouts Extend Codeframes
Internally, codeframes are implemented as php classes which control the overall structure of a document that is based on the codeframe. Codeframes usually contain empy placeholders that need to be filled. These empty containers generally take one of the following forms:
So the main role of a layout is to supply common content that will be built into pages that use the layout. Note that these same containers can also be set within site_settings. If the content pertains to all or most of the pages in your site you will want to supply this content within the site_setting definition. You can then override or supplement this content within the layout if needed. If the content is specific to pages that are linked to a certain layout, then it is best to define this within the layout rather than defining it within site_settings.
Linking to a codeframe
Every layout must be linked to exactly one codeframe.
Since codeframes define the structure of content (and usually not the content itself), it is common to define these within the pseudo site named system so that they can be shared by all of your sites. You can use the magnifying glass icon to search for a codeframe to be used by your layout. If this is drawn from system, enter FRAMEWORK as the Codeframe Location. If your codeframe is defined within the current site, enter SITE as the Codeframe Location. You can even choose a codeframe from another site from which you want to inherit.
The layout can be assigned a type. This is used to allow the site_settings definition to populate content for only certain layouts. Recall that there is only one site_settings specification per website. Nevertheless, a site can utilize many different layouts. By setting several different layouts to the same type, you can populate content for only these layouts within the site_settings definition. The alternative would be to repeat the same content in several layouts which would make your site more difficult to maintain since changes might need to be repeated across several different layouts.
Importing Codeframe Information
In order for the layout to update placeholders (containers, objects, etc.) within the codeframe it needs to fully understand what containers are available to be populated. The purpose of the Import Codeframe button is to "pull" container information out of the codeframe. Here we see an example of what the Layout Properties grid might look like after we imported the codeframe.
This shows us that there are only two tags within the codeframe having properties that we can override, that is the "html" tag and the "body" tag. Although, technically the grid allows you to insert rows, there is no reason to do so unless the codeframe is changed to support more tag properties.
Notice that the default action after importing the codeframe is "Do Nothing". Unless this action is changed to one of the other action, the information you add on the row will not have any effect.
Let's suppose that we want to fire an onload event for all pages that link to this codeframe. This could be done by changing the above definition to something like:
Notice that, in addition to supplying the content to be added to the body property we set the Merge/Override option to Append. This option is important when multiple sources are loading containers. For example, these same properties could also be populated within site_settings (before the layout is loaded). The Merge Option tells the framework whether to place the layout properties after or before the site_settings properties. Using the merge option you can also override or clear the default properties and the site_settings properties.
Updating Layout Tags
Most codeframes used for html content will contain tags and tag properties that can be updated. Here we see an example showing how a layout is going to populate a banner tag that is defined within the codeframe in order to add a logo and a navigation menu to the banner. The layout also adds some content to the right_panel div and overrides the properties of that div.
Notice that the codeframe has defined a footer tag of type footer but the codeframe does not show any default content for this tag and the layout has not added anything to this tag. Assuming that the footer tag is not populated within the site_settings or via direct calls to the framework, the footer tag will not actually be generated into the page. That is, empty tags that exist within the codeframe are ignored if no component decides to populate the tag with some content.
Codeframe definitions can contain conditional rows that are only generated when certain conditions evaluate to true. By changing the values of these condition variables within the layout definition you can trigger the generation or removal of these conditional rows. For example, if we don't want the main body div to be generated for pages linked to our layout and we want the message location to be below the banner we could apply the following settings within the layout.
Here we list some condition codes that are supported by certain codeframes:
Layout Config Settings
Some components allow rendered content to be controlled by config settings. Often these settings are applied to site_settings since they pertain to the entire site. Occasionally you may want to set or override these within the layout. The codeframe message_area object allows developers to control whether messages are to be popped up or shown on screen. Therefore, by adding the following row to the layout config setting, we can change the message behaviour for pages linked to this layout.
Within the message_area class, the code can request the value of this field by calling the framework's site object as shown here:
In large websites, not all pages will look the same. Often the home page may have a special structure that is distinct from internal pages. Certain internal pages may have unique requirements such as the need for a side menu or special banner or footer. Layouts make it easy to define groups of pages having different structure or common content than other pages.
Most of the pages of your site will likely use the default layout defined within site_settings. Make sure the layout you specify there is the one that will be used by the greatest number of pages in your site. This will reduce the number of pages that need to override the layout setting.
Occasionally, you may want a page to use a different layout than normal. For example, suppose you have an information page that contains a menu, header, footer, etc. Suppose you want to pop up this page in a small window in order to provide help from another page. Generally, you would not want the popup version of this page to have a menu, etc. To achieve this, you can pass an alternate layout in the query string when you pop up the page. For example, $link(material,layout=simple,Learn about our material,,_blank) will create a link to the material page while overriding the layout used by that page.