eZ publish 3.1: Take It For A Spin

Sitedesigns

In order to customize the appearance of your Website, you need to provide code that generates the HTML. eZ publish calls these "Sitedesigns". Sitedesigns are like a "window" onto the content. Imagine looking out a window onto a mountain scene. Now, change the window frame in your mind to one with square window panes, then to one with diamond shaped window panes. The scene stays the same, but the foreground changes. You can do the same with eZ publish.

Examine the Same Content Through Different Sitedesigns

1. Make sure you're logged in as the administrator. Go to the admin interface at http://localhost/index.php/admin, log in as user "admin" password "publish" (no quotes), and click Login. Some of the sitedesigns require you to be logged in as admin, which is why this step is important.

2. Go to the opening page of the demo site at http://localhost/index.php/demo/content/view/full/24/. You're now looking at the content through the "demo" sitedesign.

3. Next, let’s look at it through the "standard" sitedesign: http://localhost/index.php/standard/content/view/full/24/. Suddenly, everything is different. The same content appears, but all the window dressing is gone. In addition, a number of controls have appeared. The only reason you had to log in is that the standard sitedesign requires you to.

4. Now, look through the "user" sitedesign (which is also very basic): http://localhost/index.php/user/content/view/full/24/.

Sitedesigns are chosen through the URL – in the item right after the "index.php". Rather than changing the existing sitedesigns, we'll create our own, called "mydesign".

Creating a New Sitedesign

1. First, check out what happens when you try to access the mydesign sitedesign before you create it -- visit http://localhost/index.php/mydesign. You'll see that you end up at the login interface (if you aren't logged in). This is eZ publish's standard answer to bad URLs.

2. In the "[Install]\ezpublish\settings\siteaccess" directory, you'll see a folder for each of the different sitedesigns. Create a new one called "mydesign”.

3. Create a file called "site.ini.append" in the "mydesign" directory, and insert the following:

   #?ini charset="iso-8859-1"?  
# eZ publish configuration override file.  
#  
 
[SiteAccessSettings]  
RequireUserLogin=false  
 
[DesignSettings]  
SiteDesign=mydesign

   This file overrides the "[Install]\ezpublish\settings\site.ini" file when you use the "mydesign" sitedesign. You've told eZ publish that you don't want the user to have to log in, and that you're going to specify a sitedesign in the "mydesign" directory.

4. Save and close the file.

5. Go back and try to access the mydesign sitedesign. Visit http://localhost/index.php/mydesign. You'll see that now you can see the content, which looks suspiciously like the standard sitedesign. If you don't provide a design, the standard sitedesign is substituted by default.

Now that we've got a site design, let's change a few things and make it look the way that we want it to. To do that, we need to create and modify templates.

The Page Layout Template

Templates define what your content will look like when viewed through your site design. Half the trouble with eZ publish lies in figuring out which template to modify in order to accomplish your specific design goal. I've never found a complete list of these templates. However, I'm trying to compile one, and if anybody has one, I'd love to see it.

Quite frankly, I'm not sure what the difference is between "overriding" a template, and simply creating one in your directory. So far, I've accomplished everything I want by overriding. If I ever figure it out, I'll let you know.

Now we're going to override "pagelayout.tpl" for mydesign, which controls basic page layout and design. To achieve this, we'll need to do three things:

1. Add "mydesign" to the list of active sitedesigns,

2. Tell eZ publish to duplicate the default template, and then

3. Modify it to our new design.

We'll also modify a second template to complete our work.

Add "mydesign" Sitedesign to the List of Active Sitedesigns

Note: You only need to do this the first time you create a sitedesign. You don't need to do it every time you want to override a template.

1. Open the "[Install]\ezpublish\settings\site.ini" file and look for a series of entries that read: "AvailableSiteAccessList[]=demo" Add a line afterwards for your new "mydesign" sitedesign, "AvailableSiteAccessList[]=mydesign". Save and close the file.

2. Go to the "[Install]\ezpublish\design" directory, and create a directory called "mydesign". Enter that directory, and create a subdirectory called "override". Enter that directory, and create a subdirectory called "templates". When you’re done, you’ll have an "[Install]\ezpublish\design\mydesign\override\templates" directory.

Tell eZ publish to Duplicate the Default pagelayout.tpl Template

1. Go to the admin interface: http://localhost/index.php/admin Log in (if needed) as user "admin" password "publish" (no quotes). Click on the "Set Up" tab at the top of the admin interface, and then the "Templates" tab on the left hand side. Click on "pagelayout.tpl" under "Most Common Templates.”

2. On the next page, choose "mydesign" in the drop down list, and click "Create New”.

3. On the next page, enter "pagelayout" in the text box, choose "Copy of default template", and click "Create”.

4. If you see an error, it's most likely that the directory for the template does not exist. Check to make sure that the "[Install]\ezpublish\design\mydesign\override\templates" directory you created exists.
   Check out your new template -- it's at "[Install]\ezpublish\design\mydesign\override\templates\pagelayout.tpl" Take a quick look at it -- you can see that it's a mixture of HTML and template commands, enclosed in curly brackets {}.

Now, let's be brutally honest. eZ publish wants you to create pretty, modular layouts where everything is neatly grouped together in a logical manner.

Unfortunately, having your design spread across half a dozen templates can be annoying when the time comes to update it. I'll grant you that people who are trying to create many sites that have reusable elements can leverage this characteristic of eZ publish well -- but for those who want to create fairly simple sites, it's just overwhelming.

Thus, I recommend that, for simple Websites, you pile almost all your elements into the pagelayout.tpl, and ignore the sub-templates. Not only does it make the life of the average Webmaster easier, but reducing the number of templates on each page from 8 to 1 can only improve eZ publish's rendering performance.

Having said this, let's modify the pagelayout.tpl template to create our pages using a simple layout, with a banner on top, a menu down the left side, and some content. We'll use the demo content, just to keep things moving along.

Modify pagelayout.tpl to Our New Design

Rather than putting the whole file into the text of the article, you can download it. Copy the file "pagelayout.tpl" from the code archive and replace the one in "[Install]\ezpublish\design\mydesign\override\templates" with it. Now,

1. Go to the "[Install]\ezpublish\design\mydesign" directory, and create a directory called "image". This is the directory where eZ publish expects to find your .gif, .bmp, and .jpg image files.

2. Copy the file "mytopline.gif" from the code archive to "[Install]\ezpublish\design\mydesign\image" -- if you'd like to substitute your own GIF file, go for it -- just call it "mytopline.gif”.

A few comments about my pagelayout.tpl:

• I've tried to keep the template stuff to a minimum, so it's mostly straight HTML, with a couple twists.
• It's actually XHTML -- that's what the <br /> stuff is about.
• You'll notice the img tag for the top banner isn't standard HTML: <img src={"mytopline.gif"|ezimage} /> The odd thing here is the reference used by the src attribute. It's enclosed in curly brackets, which causes the template manager to examine it, and substitute the result of the instructions. In this case, we're using the ezimage template operator, which finds and returns the location of the "mytopline.gif" image. You could also use the explicit (but relative) path to it: "/design/mydesign/images/mytopline.gif" -- it's functionally equivalent.
• I've put explicit links on the left hand nav items to folders within the demo installation. Technically, this is not ideal, however, if you try to use your directory structure to drive the layout automatically, you'll always find that there are items you need for a real Website, which you don't want to show up in a directory tree. Real Websites authors tend to end up using this method to make it look exactly the way they want it to.
• There are references to a style sheet, but I haven't defined one (yet) -- we'll get to that.
• What's {$module_result.content}? This renders the content in the main display, which we haven't customized yet. But we will in just a moment.

When you visit http://localhost/index.php/mydesign now, you'll see that most of the page layout is driven by the contents of the pagelayout.tpl file. The display of the content, though, still uses the standard design. We haven't yet customized the templates used to view various objects, so you'll get the default views when you look at content.