eZ publish 3.1: Take It For A Spin

Rendering Objects

All the content in eZ publish is contained in objects. Objects are things like folders, articles, articles, forums, photos, etc. When we display an object, such as an article, eZ publish renders it into HTML for us. It looks at the data, such as the publication date, the teaser text, the text of the article, etc., and then applies a template to it to make it appear the way we want. Here, we're going to render two types of objects -- a folder and an article -- to give us some basic functionality. In a full blown Website, you'd probably render lots of different objects.

Visit http://localhost/index.php/mydesign/content/view/full/24. You'll see two articles listed -- "A weekend in the Mountains" and "Food for the soul". It's a very basic display. In the object oriented world, each object is responsible for rendering itself into HTML. Essentially, when the folder goes to list its contents, it asks the objects within it to display themselves. In this case, they’re being asked to render themselves in a "line" format -- i.e. each object has multiple short summary lines, which can be clicked on to see the full version. So, what we need to do is override the standard templates that govern the line display of articles in our sitedesign.

Overriding the Article Object Line Template

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

2. Select "mydesign" from the drop down list, and click "Create New”.

3. Set the template name to "line_article" (there's nothing magic about this name), choose the "article" class, leave the section on "Any", and the node blank. Select "Copy of default template" and click "Create”.

4. Check out your new template at "[Install]\ezpublish\design\mydesign\override\templates\line_article.tpl" There's only enough code to render a single line about a single article. Copy the template file "line_article.tpl" from the
   code archive, and replace the one in "[Install]\ezpublish\design\mydesign\override\templates”.

5. Visit http://localhost/index.php/mydesign/content/view/full/24 again. As you'll see, the articles are rendering themselves more pleasingly, along with a teaser and a small thumbnail from the article.

We can repeat this process for the render of the main article (called the "full" format). If you click on "A weekend in the Mountains", you'll get an ugly render of the article. You can override the article’s full template by repeating the steps for the article object line template (above), changing a couple as needed: choose the "/node/view/full.tpl"template, and set the template name to "article".

Your new template will appear as "[Install]\ezpublish\design\mydesign\override\templates\article.tpl". Lastly, download the template file://article.tpl, and replace the one in "[Install]\ezpublish\design\mydesign\override\templates".

Refresh the "A weekend in the Mountains" story, and you'll see it's a lot more pleasing to the eye. If you visit various articles, you’ll see they all use this new template. One of the more interesting effects can be seen if you visit the "Sport" folder, under "News" -- http://localhost/index.php/mydesign/content/view/full/25. There, the article "We did it again" does not have a thumbnail.

However, even though our template explicitly expects the thumbnail, the system doesn't give us any trouble. Why not? Because eZ publish automatically deletes the code associated with the thumbnail -- there's isn't even a vestigial <table> tag!

I leave it to you to figure out how to render folders. As a hint, remember that you'll need to override both the line.tpl and full.tpl of the folder class. You can learn more from the tutorial at the eZ publish site. Or, if you want, steal my template. In the code archive, you'll find the files: file://line_folder.tpl and file://folder.tpl.

Localizing Your Site

If you’re in America, you'll notice that when you visit an article, such as http://localhost/index.php/mydesign/content/view/full/62/, "A weekend in the mountains", the date lists the day before the month, European and UK-style. eZ publish has elaborate support for multi-lingual sites, the discussion of which is beyond the scope of this article.

By default, the eZ publish installation selects Great Britain English as the default for localization settings. To change this, you'll need to change the site.ini file to tell it which localization settings are appropriate:

Setting a Default Language

1. Open "[Install]\ezpublish\settings\site.ini"in a text editor, and search for the entry that reads "Locale=eng-GB" in the "[RegionalSettings]" section. Change it to "Locale=eng-US" (no quotes), then save and close it.

2. Visit http://localhost/index.php/mydesign/content/view/full/62/ "A weekend in the mountains". Hey -- it didn't change! It turns out there's a bug in eZ publish. They've got the American localization values for dates wrong. It's easy to fix, though…

3. Open "[Install]\ezpublish\share\locale\eng-US.ini" in a text editor, and search for an entry that reads "ShortDateFormat=%d/%m/%Y". Change this to "ShortDateFormat=%m/%d/%Y" -- you'll probably want to make a similar change to DateFormat, DateTimeFormat, and ShortDateTimeFormat while you're here.

4. Visit http://localhost/index.php/mydesign/content/view/full/62/ "A weekend in the mountains". Now the date appears the way Americans expect.

But, Where Do I Start?

It's all fine and good for us to customize things, but I really don't want a visitor to have to start at the Root Directory when they want to visit my site, and you and I don't want them to have to know that we want them to use "mydesign". We probably want them to be able to type "http://localhost/" and leave it at that! It’s a reasonable request.

Fortunately, we can set a default sitedesign and start page quite easily in eZ publish.

Setting a Default Startup Page and Sitedesign

1. If you haven't already, go back to the first part of the article, and modify the apache settings to allow you to skip the "index.php" part of your URL.

2. Visit http://localhost/. You should see the demo sitedesign on the "Frontpage" directory.

3. Open "[Install]\ezpublish\settings\site.ini"in a text editor, and search for the entry that reads "DefaultAccess=demo" -- change it to "DefaultAccess=mydesign" (no quotes), save it and close it.

4. Visit http://localhost/. You should see the mydesign sitedesign, but you’ll note it's still pointing to the "Frontpage" directory.

5. Open "[Install]\ezpublish\settings\mydesign\site.ini.append", which we created earlier in a text editor. Remember that this file overrides the "[Install]\ezpublish\settings\site.ini" file when we use the "mydesign" sitedesign. Add the following to the file:

   [SiteSettings]    
IndexPage=/content/view/full/17

6. Save and close the file. You've just told eZ publish that you want to have it default to the full view of object #17 (which is the news directory).

Visit http://localhost/. You should see the mydesign sitedesign, and it's pointing to the "News" directory.