You’ve heard about eZ publish 3.1, the latest version of the open-source Content Management System (CMS) from eZ Systems. You’ve also heard that it’s a lot different from version 2.2. How different? Well, in this tutorial we’ll see.
Let’s build a site using version 3.1 step by step, so you can quickly get a taste of the power under the hood in the new version.
Why eZ publish?
If your client wants to create a site that will help them build a community, with news, forums, mailing lists, current headlines, and an on-line store, then you should take a look at eZ publish. Check out a few sites powered by eZ publish here. eZ publish lets your customers maintain the content of the site, freeing you up to build ever cooler and more powerful features for them.
Advantages of eZ publish
- All editing and content functions are Web-based. Thus, distributed groups can work on the content of the Website without having to synchronize files or coordinate.
- Sophisticated time-based publish and retract requiring no admin intervention. Some CMS products will do this, but only at publish time.
- PHP-based open source — you are free to modify the program as you see fit — which can be both dangerous and powerful.
- Support for international Websites with content and layouts in multiple languages and formats.
- Lots of room to grow — it has all the features of a full CMS – so it’s hard to imagine outgrowing eZ publish.
- A powerful object-oriented template-driven rendering system makes it easy to customize your site exactly the way you want it.
Disadvantages of eZ publish
- Setup in the real world is complex. Unless you have root level access to a Web server on the Internet, it’s very difficult to get a hosting provider to set up eZ publish for you. One exception is Marlabs, which has made a business of hosting eZ publish — note that they support both 2.2 and 3.1.
- It will take a while to customize your site, especially if you’re not a PHP guru.
- Documentation is extremely limited, especially for version 3.1.
- A rather steep learning curve.
If you don’t need the multi-user, Web based editing and management of eZ publish, I highly recommend the commercial product CityDesk by Fog Creek Software. There’s a free introductory version that allows you to develop small sites, and the more powerful versions of the software are moderately priced.
2.2 or 3.1: What’s Your Poison?
The question is not whether to choose eZ publish, but which version will you choose: trusty version 2.2, or the fancy new version 3.1? It’s a critical choice that will affect your Website for years to come. Unfortunately, there’s currently no way to migrate your 2.2 site to 3.1.
Tried & True — Version 2.2
Harry Fuecks’ article, eZ publish: PHP’s Killer App provides an excellent introduction to version 2.2 of the product, which offers these benefits:
- It’s functional straight “out-of-the-box.”
- It has a nice default layout, and caters for articles and headlines, discussion forums, mailing lists, user management, and even an on-line poll module.
- If you don’t like something, it’s a pretty straightforward process to code up your own modules to add to the functionality.
- It’s well supported by the user community, and the documentation is more mature.
Powerful & Complex — Version 3.1
Version 3.1 has come out only recently, and it’s a lot different from version 2.2. In fact, in terms of actually getting your Website up quickly, it almost takes a step backwards. eZ publish 3.1:
- Doesn’t provide a generic set of templates for the average user to start with.
- Focuses on the fundamental framework that a content management system needs, rather than “out-of-the-box” functionality. There’s no on-line poll built in here. But you could create a powerful one if you wanted to.
- Is based on an excellent object-based rendering model that allows for flexible, dynamic sites.
In the long term, version 3.1 brings critical improvements that will make it a great foundation for fully-featured, content-based Websites. Unfortunately, with little “out-of-the- box” functionality that made 2.2 so appealing, it’s a hard sell in the short term. But if you’re planning a large, complex site (or one that you hope will become so), version 3.1 has the power and flexibility to help your site develop over the years to come.
If you want an in-depth comparison of eZ publish 2 vs. 3, check out Sebastiaan van de Vliet’s article, eZ publish Evaluation: Version 2 Vs. Version 3. If you want to be the judge of whether eZ publish 3.1 is ready for prime-time, keep reading.
Building The Site
Let’s get started. I’m going to assume that, like me, you don’t know much PHP, but that you aren’t afraid to code from scratch, nor to modify existing code. I’m also going to assume that you’ll try out eZ publish on your own computer (self-hosting), under Windows NT/2000/XP, as this is the system I used. If you’re running 95/98/Me, the process is similar.
I’ll also assume you’re not running any other Web server, such as IIS, on your machine. If you are, you should disable it. If you’re not sure, open a browser and visit http://localhost — if you get a network error, then you don’t have a local Web server running.
Thankfully, the folks at eZ Systems have provided an installer that automates the setup and install processes associated with eZ publish and the various open source technologies that support it, including Apache, MySQL, and PHP. This is a godsend — you can get going very quickly. And if you screw anything up royally, you can always uninstall and reinstall the product quickly and easily.
Note also that I’ve provided for your use a code archive that contains all the files we’ll work on in this tutorial.
Installing eZ publish 3.1 for Local Hosting
- Go to the eZ publish 3 release page. Click “Windows 2000/NT/XP Installer” under “eZ publish 3.1 installers” and download the .EXE that’s there. Note that it’s 20+ mg.
Essentially, every browser is supported, as the system produces straight, dynamically generated HTML.
Check out the example from the content side (http://localhost/index.php), and you’ll quickly get an idea of how powerful this tool is. There’s a nice three-column news headline page (note that “news,” “corporate,” “intranet,” are essentially the same), the online shop, a gallery, and a forum section. If you don’t like the layout, organization, or color choices, of the sample site, don’t panic — you can change almost everything.
I’m not going to spend too much time on organizing content; instead, we’re going to focus on making the Website look the way you want. Check out the eZ publish users’ guide for details on how to add, modify, and delete content.
A Quick Directory Tour
It’s important to understand the directory structure of eZ publish. Under the directory where you installed eZ publish (typically “C:Program FileseZ systemsezpublish”), you’ll find a number of directories. The ones that you’ll be working in are “design” and “settings” — keep out of the others.
The “design” directory is the most important — most of you work goes on in here. This directory contains the files that specify how your Website looks.
The “settings” directory contains the files that control the behavior of eZ publish. You’ll make occasional visits to this area.
Turn off the Cache
eZ publish generates pages dynamically. In other words, when you ask for a page, it does a bunch of database queries and generates the HTML Web page when the visitor requests it. This is one of the reasons that eZ publish Web pages take longer to load — the system needs to figure out what to show you. In order to speed this up, eZ publish “caches” pages that it has made recently, in case somebody else asks for them. After all, it doesn’t make much sense to dynamically render the same front page over and over and over again. Essentially, eZ publish takes a snapshot of the page it generates, and when somebody asks for it next, it just sends the snapshot.
Normally, this works just great — Websites really don’t change all that quickly, and caching greatly enhances performance. However, as you build the site, you’re going to be changing it a lot. So it’s best to disable this cache thing until you’re happy with your site.
Turning Off the View Cache
- Go to the directory where eZ publish was installed. Typically, this is “C:Program FileseZ systems” if you went with the default installation. Look in the “ezpublishsettings” subdirectory for a file called “site.ini” For future reference, in this article, I’ll give the path to this file as “[Install]ezpublishsettingssite.ini”
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
- 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.
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
- 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.
#?ini charset="iso-8859-1"?
# eZ publish configuration override file.
#
[SiteAccessSettings]
RequireUserLogin=false
[DesignSettings]
SiteDesign=mydesignThis file overrides the “[Install]ezpublishsettingssite.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.
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:
- Add “mydesign” to the list of active sitedesigns,
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.
- Open the “[Install]ezpublishsettingssite.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.
Tell eZ publish to Duplicate the Default pagelayout.tpl Template
- 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.”
Check out your new template — it’s at “[Install]ezpublishdesignmydesignoverridetemplatespagelayout.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]ezpublishdesignmydesignoverridetemplates” with it. Now,
- Go to the “[Install]ezpublishdesignmydesign” directory, and create a directory called “image”. This is the directory where eZ publish expects to find your .gif, .bmp, and .jpg image files.
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.
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
- 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.”
code archive, and replace the one in “[Install]ezpublishdesignmydesignoverridetemplates”.
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]ezpublishdesignmydesignoverridetemplatesarticle.tpl”. Lastly, download the template file://article.tpl, and replace the one in “[Install]ezpublishdesignmydesignoverridetemplates”.
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
- Open “[Install]ezpublishsettingssite.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.
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
- 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.
[SiteSettings]
IndexPage=/content/view/full/17Visit http://localhost/. You should see the mydesign sitedesign, and it’s pointing to the “News” directory.
Style Sheets
Earlier, you probably noticed that, though we referred to style sheets in our layout templates, we never bothered to actually define the style sheets. This gives our Website a decidedly “bland” look and feel.
You could insert the formatting attributes throughout your Website, but it makes maintenance a nightmare. For instance, let’s say you wanted to use Web color #99FFCC throughout your site, but after putting it into 365 different bgcolor attributes across global templates, you wake up and realize that that’s a really ugly color. You’d have to go back and fix them all! It’s not such a big deal when you’ve got global search and replace, but if you want to play with different options, it’d be nice to be able to change the color setting in one place, and have all 365 attributes change.
Enter: style sheets. There’s a lot of hype, but really what style sheets let you do is name a group of characteristics, such as size, alignment, color, font, etc., and reference that name in your HTML using the “class” attribute. It’s a great shortcut while you’re developing and maintaining your site. There are plenty of places where you can learn more about Cascading Style Sheets (CSS), so I won’t belabor the point. Visit SitePoint’s CSS category and HTML Help for good tutorials on CSS. Here, I’ll just show you how to attach style sheets to your sitedesign.
Attaching a Style Sheet to Your Sitedesign
- If you’re only going to have one style sheet (and for simple sites, that’s probably all you need), you can just reference it in your pagelayout.tpl file.
<head> tag.<link rel="stylesheet" type="text/css" href={"stylesheets/mydesign.css"|ezdesign} />Visit http://localhost/. You should see the effects of your style sheet.
Sections
There’s a bit of an elephant in the room, which we haven’t talked about yet. Several times in the eZ publish interface, you probably heard mention of “sections.” It’s an important concept to understand as you develop with eZ publish, though in your first eZ publish site, you probably won’t use them.
Sections divide your site up into different content “zones” that have a different appearance and behavior from other sections. For instance, the “news” and “corporate” areas in the demo site are different sections, and they look different from each other — different color scheme, banner graphics, page layout, etc. Content can be assigned to any section. Unfortunately, the user interface for assigning content to sections is obscure, at best.
Assigning Content to a Section
- We’re going to reassign “My Company” to the “News” section, and look at the effects on the demo site (viewed through the demo sitedesign).
Note that this procedure doesn’t move the content in the Website — that’s driven by the content’s location in the folders. It just affects which templates are used.
Well, I don’t know about you, but for most of the sites that I’m interested in creating, I really only need a single section. Building sites with multiple sections is really beyond the scope of this article.
Wrapping it All Up
There is a lot to eZ publish. Here, we’ve barely scratched the surface — we’ve only focused on one area, which is creating content-based sites that look the way you want them to. eZ publish 3 is a lot more flexible and powerful than eZ publish 2.2, but it’s a lot more difficult to use, especially as there aren’t any useful default templates to get you started.
Hopefully, this introduction will get you on your way to creating awesome eZ publish 3.1 Websites!
Rob PurserRob founded Owl Control Systems, LLC in 1994, which builds software for the semiconductor industry. He builds Websites for non-profit and professional organizations, and maintains Relicis, a site focusing on software development, design, and management.
