ibexa

Path

ez publish / technical manual / 3.8 / templates / the pagelayout

Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.

The pagelayout

The pagelayout is the main template. Among other things, it dictates the overall look of a site. The filename of the pagelayout template must be "pagelayout.tpl". It has to be placed inside the "templates" directory of a design. If eZ Publish is unable to find a pagelayout within the current design (specified by the siteaccess), it will attempt to use the pagelayout template that is provided by one of the fallback designs. The following illustration shows the location of the pagelayout template located in a design called "example".

The location of the pagelayout (main) template.

The location of the pagelayout (main) template.

The pagelayout contains the HTML, HEAD and BODY tags (the other HTML framework). In addition, it dictates the overall look of a site. Among other things, it is used to describe the visual structure (main layout, logo, main menu, footer, etc.) that will be presented for every page request. The following example shows what is considered to be the most basic pagelayout:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 
<head>
 
<style type="text/css">
    @import url({'stylesheets/core.css'|ezdesign});
    @import url({'stylesheets/debug.css'|ezdesign});
</style>
 
{include uri='design:page_head.tpl'}
 
</head>
 
<body>
 
{$module_result.content}
 
<!--DEBUG_REPORT-->
 
</body>
</html>

The document type

The very first line in the pagelayout is used to declare the document type of the pages that are generated by eZ Publish. Per HTML and XHTML standards, a DOCTYPE (short for "document type declaration") informs browsers and syntax validation engines about which version of (X)HTML that is used. This information should be included at the very top of in every web page, this is why it is the first part of the pagelayout.

The DOCTYPE declaration is one of the key components when it comes to proper rendering and compliant web pages. A DOCTYPE that includes a full URL tells the browser to render the page in standards-compliant mode, treating the (X)HTML, CSS, and DOM structures as they should be treated according to the standards. A missing, incomplete or outdated DOCTYPE throws most browsers into something called "Quirks" mode. In this mode, the browser assumes that the document was written using old-fashioned, invalid markup and code per the chaotic industry norms of the late 1990s. In other words, the page will most likely not be rendered according to the standards and it will certainly not validate.

The HTML tag

The HTML tags encapsulate the marked up contents of an actual web page. In addition to the tag itself, the HTML tag in the example above includes a URL to the XHTML specification. XHTML is a family of current and future document types and modules that reproduce, subset, and extend HTML 4. The XHTML family document types are XML based, which means that they are designed to work in conjunction with XML-based user agents.

In document processing, it is often useful to identify the natural or formal language in which the content is written. The "lang" and "xml:lang" attributes specify the language of the entire HTML element. The value of the xml:lang attribute takes precedence. The language values should be set to the language that is used throughout the site. The values of the attributes are language identifiers as defined by ISO 3166-1 (and the corresponding ISO 3166-1-alpha-2) standards.

The head tag

The head tag contains information about the document itself. The information contained here doesn't show up on the page displayed in a web browser. Only the contents of the title tag will be made visible (as the title of the browser window). The head tag typically contains information about which CSS files that should be used, a description of the document itself, keywords and so on.

Cascading Style Sheets

The pagelayout in the example above makes use of two CSS files: "core.css" and "debug.css". The code encapsulated by curly brackets is eZ publish specific code. What happens here is that the text within the quotes is piped into a template operator called "ezdesign". The operator prepends the text with the path to the current design directory (the one which is specified using the "SiteDesign" configuration directive). This technique assures that the path to the CSS files are always correct, regardless of the access method that is being used. For example, if the name of the current design is "my_design" and it includes a CSS file called "example.css", the following output will be produced:

@import url("/design/my_design/stylesheets/example.css");

The "core.css" and "debug.css" files are a part of the standard design that comes with eZ Publish. It is not necessary to have these CSS files in the "stylesheets" directory of a custom design. If eZ Publish is unable to find the files within the current/custom design, it will automatically use the ones that are in the standard design. Please refer to the description of the automatic fallback system for a detailed description of the fallback mechanism. Because of the fallback system, the style-part of the pagelayout presented above will most likely result in the following output:

...
<style type="text/css">
    @import url("/design/standard/stylesheets/core.css");
    @import url("/design/standard/stylesheets/debug.css");
</style>
...

The core stylesheet

The "core.css" file defines a standard set of basic styles (font styles, sizes, margins, etc.) for both general HTML elements and some eZ Publish specific classes. The eZ publish specific classes are used by the standard templates. A site that makes an extensive use of the default templates should always have the "core.css" file included in the pagelayout. Otherwise, the missing styles may cause the unexpected rendering of various elements.

The standard "core.css" file should never be changed. If there are basic styles in core.css that doesn't fit the visual environment of a site, a modified version of "core.css" may be placed in the custom design that the site uses. However, the recommended solution is to create a completely new CSS file that contains both custom classes and overrides for elements defined in "core.css".

The debug stylesheet

The "debug.css" file contains styles that are used to format the debug output which appears at the bottom of the page when debug output is enabled. The usage of the "debug.css" file is only necessary during the development of the site (typically when debug information is needed) and thus it can be removed or commented out before the site is launched.

Document information

The system is capable of automatically generating information about the page itself (title, meta tags, keywords, etc.). This can be done by the inclusion of the page head template ("page_head.tpl"), which is located in the templates directory of the standard design. If eZ Publish is unable to find the requested file in current/custom design, it will automatically fallback and use the file located in the standard design.

The body tag

The body tag defines the document's body, which contains the actual contents of the web page (text, images, etc.) marked up in an orderly fashion. At the minimum, an eZ Publish pagelayout should contain the result from the requested modules.

Module result

Upon every request, eZ publish automatically generates an array called "module_result". This array is available only in the pagelayout template. It contains all the necessary information about which module that was run, which view that was called, the output that was produced and so on. The actual output (for example the contents of a news article) can be included in the pagelayout by accessing the "content" element of the $module_result array, the syntax is:

{$module_result.content}

 

When the pagelayout is rendered, the {$module_result.content} part will be replaced with the actual output that the requested module produced. Please refer to the "Variables in pagelayout" page for an overview of the template variables that can be accessed from within the pagelayout.

Debug information

The last part of a typical eZ Publish pagelayout is an HTML comment that looks like this:

<!--DEBUG_REPORT-->

 

If the debug information is turned on, eZ Publish will replace this comment with the actual debug report when the pagelayout is processed. In other words, the debug report will be included as a part of the generated page and thus it will not cause invalid output by breaking the HTML structure. The debug reports that eZ Publish generates follow the XHTML 1.0 Transitional specification and thus the debug information validates.

Balazs Halasy (14/02/2005 9:26 am)

Ester Heylen (03/05/2010 10:54 am)

Balazs Halasy, Ester Heylen

Comments

  • Unique page layout per folder?

    Friday 02 December 2005 12:18:14 pm

    Charles

    Would it be possible to specify a different page layout for different folders on a site? For example, a different header image and style sheet that is used when displaying the folder as well as when displaying content items within the folder.

  • Question answered here:

    Sunday 04 December 2005 9:13:28 am

    Charles

    This question was answered for me in the forums:
    http://ez.no/community/forum/setu...out_for_different_folders/#msg104383

  • How do we put debug on ?

    Monday 25 June 2007 10:44:32 am

    Rahul Khanna

    How can we do a on/off on debug so that we can see the <!--DEBUG_REPORT--!>

  • php

    Friday 13 July 2007 4:41:35 pm

    pako

    how can i import a php file in a tpl file
    o how can i use php code in a tpl file