Layout management Foundation
Most websites have the same content in every page or in a large number of pages. Headers, footers and navigational elements are just a few examples. Site-wide scripts and stylesheets also fall into this group of resources. However, adding the same content to every page of your website and maintaining it this way is time consuming and error prone. If you want to change the appearance of the page header later, for example, you must edit each page. The correct solution for this problem is to use one or more layout pages.
A layout page serves as a template for all pages or views that refer to it. The pages that link to the layout page are called content pages. Content pages are not complete HTML pages with a body and a head. Instead, they contain only the content that varies from one page to the next. The following example code shows a very simple layout page:
What makes this page a layout page other than its filename is the @RENDER Body command. This command causes the result of the content page to be inserted at the same location. Content pages contain a relative reference to their layout page, which is defined using the layout directive. Below is an example of a content page using the simplesite.layout shown above.
Layout pages have the extension .layout. The extension prevents layout pages from being accessed directly. You can use the :hasLayout() method of your CXP page to check if your page has a layout associated.
You can find examples of different complexity levels illustrating layouts and their usage in the Xbase++ websamples collection.
The placement of the @RENDER Body command within the layout page determines where the content of a content page is rendered. In addition to rendering complete content pages, it is also possible to include only specific content provided by the content page within a layout. This is controlled by placing @SECTION <section-name> commands in your content page, and by rendering these sections with @RENDER <section-name> in the layout page. The following example adds a footer section to the content page and renders it in the layout page.
Below is the code of the layout page which renders the body as well as the footer sections from the content page using the @RENDER <section-name> command:
The rendering of a section can be made optional. Simply use the :hasSection() method as shown in the example below. This way, you can have optional sections in your global layout files, which only some CXP pages in your application generate content for. In the example below, we output some static content if the content page does not provide us with content for the footer section.
Layout pages can be nested. It is absolutely legal to reference another layout from a layout page. In fact, layout pages support all features of a CXP page, except that they can not be accessed directly. Instead, layouts need to be referenced in a CXP page for being executed.
A nested layout is a layout which refers to another (outer) layout. This approach is useful when a subset of pages require the same markup, as is often the case when certain sections of a website or web application need to appear slightly different from the others while retaining the same look and feel.
In the layout file below, we output the department description and the content of the content page. We also create a footer section to be rendered in the referenced layout company.layout.
The order of execution of your Xbase++ code is as follows: first, the development.cxp content page is executed. Afterwards, the referenced development.layout is called and the content created by the CXP page is rendered at the location of the @RENDER Body command. After the content of the development.layout page has been created, the referenced layout page company.layout is executed and again, the content of the inner layout is rendered using the @RENDER Body command. In addition the Footer section from our inner layout is rendered using the @RENDER Body command. In addition the Footer section from our development.layout page is also rendered using the @RENDER Footer command. The final content is then delivered to the client.
The following are some best-practice rules related to layout pages:
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.