Excercising the template override system in eZ Publish
Posted October 14th, 2008 by adminThe problem.
Much of the ez flow design and layouts is simple to comprehend by comparing the visual layout of pages, zones, and blocks accessed from the user interface, and referencing these views back to the layouts in the admin gui.
The “Global zone” in a default 4.0.1 install is different. Accessed from the “site map” in the user interface, then referenced from the admin interface in the content structure, it does not seem to follow the rules.
Viewed from the admin pages, Global zone appears to be a simple single page, single zone layout. Yet when it is displayed to end users, they see a complex two zone page layout. What gives? An even bigger problem, trying to figure this out from the documentation.
A Theory.
Since templates are responsible for displaying the content in eZ Publish, the theory is that this functionality is part of the template system. But how to test, where to start, or is it time to SToP (Study, Theorize, and/or Postulate) rather than keep digging into the available tools. I tried SToP’ing, it didn’t work for me.
Keep digging.
Much more fun than studying. Tried studying the docs, didn’t like it, didn’t make sense, not gonna do it if there is any other way. A mere mortal may be able to understand templates, or ini files, or file structures, or templating language or css, but this mortal can’t grasp the sum from all the parts looking at documentation alone. The eZ developers provide these pre-built examples, just have to learn enough to develop a system to take advantage of their examples.
In the admin interface, turn on debugging from the setup tab. In this case, turned on debugging for the “eng” site.
Clear all caches, reload the page, and find that pagelayout.tpl is the top level template responsible for displaying the “Global Zone” page. Specifically, for “eng” the /design/ezflow/templates/pagelayout.tpl is in charge.
There are six other pagelayout.tpl files in the default installation, not including anything in /var. Throw out iphone and admin, because both are specific siteaccesses, that leaves ezflow, ezwebin, standard, and base.
Some how, pagelayout and other templates override each other or fall back to defaults, using a mechanism well understood by eZ developers and well documented, somewhere. In this case, test the fallback mechanisms by successively removing the pagelayout.tpl files until the page no longer loads. A concrete example in other words.
Rename ezflow/templates/pagelayout.tpl to xpagelayout.tpl, clear the caches, clear the debug settings, and reload the page to see what displays.
Something akin to a default 3.xx version install of eZ, which uses the ezwebin extension by default. Verify the the pagelayout.tpl from the ezwebin extension is indeed the first fallback by setting up debug, clearing the caches, and reloading the page.
Rename the pagelayout.tpl in the ezwebin extension directory to xpagelayout.tpl, take off debug, clear caches, and reload the page.
The page is now being rendered using the /design/base/templates/pagelayout.tpl. Rename this pagelayout file, clear the caches, reload the page.
The page is now rendered using /design/standard/templates/pagelayout.tpl. At the very top of that pagelayout file is the text {* DO NOT EDIT THIS FILE! Use an override template instead. *}. And this file is the end of the line, rename it, the page fails to load.
The line counts in the files, standard - 82 lines, base - 170 lines, ezwebin - 300 lines, ezflow - 320 lines. Basically each overrides the previous and adds a little more to it. The overrides do not have to keep adding more “stuff”. They may just as easily simplify the layout. The iphone pagelayout.tpl for instance, is 76 lines.
Hopefully, this debugging experience explains a little more or a better how to begin using the power of eZ Publish. EZ will never be perfect, or the cms for everyone, but it is a whole lot more suited to a whole lot more tasks than most recognize. It is way too high on overhead when it comes to trying to explain the system in writing. Notice that .ini files were never mentioned in this post! No template language dissertations. Much easier to grasp one subject at a time, with real examples, before going on to the next. By digging into the differences in the pagelayout.tpl files, the methods for adding what appears to be a second zone to a single page layout will be revealed - another day.
Successively rename the files back to pagelayout.tpl, clear the caches, and reload the page to get back to the default view of the global zone page, with a better understanding of what is taking place, and how to discover what is taking place.
Tags: ez, eZ Publish, ez.no, override, templates