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 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 11:01 am)
Comments