eZ publish: PHP’s Killer App – Parts 1-3

If you’ve ever trawled the PHP listings over at Hotscripts in search of a content management system to save you from writing your own, you’ve probably run into eZ publish, a PHP-based CMS application, and thought "Wow!" Jubilant, you tried to install it… to no avail. Desperately you tried reading the code, only to discover it made no sense whatsoever. Finally you skulked away to a quiet corner to lick your wounds, resorting to PHP Nuke instead.

This series is all about eZ publish and why it deserves the title of "PHP’s killer app". We’ll start from the ground up: first, we’ll install eZ publish in your development environment. Then, we’ll learn how to make use of its features, and customise it to your specific needs. Finally, we’ll take a look under the hood, to discover what makes eZ publish tick: how eZ publish is in fact a powerful tool to help you build your own Web-based applications.

By the end, you’ll be able not only to set up and customise your own eZ publish Website, but to build your own applications to run within eZ publish.

Here’s the lowdown…

Part 1 – an introduction to eZ publish, where we explore, download, and install the required files.

Part 2 – we get right into eZ publish, learning how to customize it to your requirements — in terms of both looks, and functionality. We’ll build our own small site and implement eZ article.

Part 3 – we discuss how you can create your own eZ publish module, taking a look under the hood to explore just how and why building your own modules is so simple with eZ publish.

Let’s get started!

Part 1

On the menu in this, the first article in the series, is:

1. Introducing eZ publish: the warm-up before we start on the real work
2. Installing eZ publish: get eZ publish up and running ready for article 2 in the series
3. Homework: tough discipline

Introducing eZ publish

eZ publish is (on the surface) a Website content management system, written in PHP by eZ systems, a Norwegian company. Launched in 2000, eZ publish has come on in leaps and bounds, having been successfully put into action on sites like Webservices.org, the Austrian National Tourist Office and Simplicity Networks (more sites using eZ publish here), and gaining support from IBM and Siemens, among other business partners. eZ publish is now even included in the Debian Linux distribution.

Content management systems, as you probably know from Kevin Yank’s famous tutorial, allow you to publish dynamic content on your Website in manner that’s easy to maintain and update. eZ publish takes that model close to perfection. Firstly, it allows you to store content in a database (eZ publish 2.x currently supports MySQL and PostgreSQL, with support for other databases like Oracle coming in version 3.x). On top of this database, a set of PHP applications provides a powerful administration interface for site maintenance, while a wealth of front end modules allow eZ publish to be rapidly implemented as anything from a news and community site like SitePoint or an online shop, to a B2B portal or even a corporate Intranet. In other words, it’s the solution to all your Website needs!

What’s more, eZ publish already has a foot in the door of the Web services arena, with a commercially licensed Desktop Edition that allows you to update an eZ publish site using a C++ Windows client communicating with an XML-RPC server interface.

Good news for paupers like me and you is eZ publish has a dual licensing scheme. It provides both a GNU open source license, and (for those wishing to do things like resell or rebrand eZ publish), a Professional license. For what is at heart an Open Source project, eZ systems are an excellent example of how to turn publicly-licensed software into a commercial success.

What’s on Offer?

So, blurb aside, what does eZ publish actually have to offer? The easiest way to get answers is to visit the demo site at http://publishdemo.ez.no/, and then login to the back end administration system by heading to http://admin.publishdemo.ez.no/ using:

username: admin
password: publish

Once you’ve logged in, you’ll see the demo site control panel with a row of icons along the top (time to have a play!). Each of these corresponds to an eZ publish module, which provides a range of functionalities for the front end of your Website.

Among the modules you’ll find:

• eZ article: this the "main" module, allowing you to publish articles or "static" pages on your site
• eZ trade: a powerful shopping cart application you’ll find in action over at MyGold.com
• eZ filemanager: a great tool for intranets and file distribution, providing an online filesystem for your visitors to browse
• eZ forum: forums for your site, similar to (although not as powerful as) VBulletin, the software behind the SitePoint Forums

…and many more that are described in detail in the User Manuals. In other words, eZ publish gives you all you need to build your very own version of the SitePoint Network! You’ll notice on both the demo site and the main site that even the URLs are similar to SitePoint’s. For example:

http://developer.ez.no/article/articleview/367

and

http://www.webmasterbase.com/article/228

Of course there’s a long way to go from building a site that works like SitePoint and convincing all the SitePoint fans to pay you a visit, but you get the point.

Yet another CMS?

"OK", I hear you say, "another content management system. Big deal."

What makes eZ publish special is not the impressive list of features, but what’s going on behind the scenes. eZ publish is in fact an application development framework, providing PHP developers with a structure in which to build applications and, from there, rapidly deploy them into a live environment, saving you many hours of coding.

If you’ve ever written you own PHP Website from scratch, you’ve probably found yourself wishing there was an easier way to do things. You¡¦re confronted with a multitude of issues: where to place the scripts for your site, how to build an integrated site navigation system, how to prevent reproducing the same blocks of code for every page of your site¡K and a whole host of other problems (meanwhile, your social life packs up and heads to Hawaii).The long-awaited completion of a site can often feel like a miracle… then someone comes up with a great idea for some new features and you’re re-writing the entire site again, weeping quietly to yourself.

An application development framework eradicates the burdens of building Websites. By conforming to its rules and guidelines, you’ll find the maintenance and expansion of your site a breeze. A good framework should make 90% of the design and development decisions for you. Solutions to issues such as naming conventions, where to place your scripts within your Website file system, how to design and structure your code, and all those other fine details you struggle with, are simply a matter of following a set of clear guidelines. And what about all that code you used to waste hours on, such as database connection and query functions, the work you reproduced over and over again for every new site? All that should be available within the framework for you to re-use as needed.

This is what eZ publish really offers: the chance to make your life as a developer a carefree and pleasant one.

PHP Coder General’s Warning:

Developing with eZ publish means writing Object Oriented code!

Much as we all love to write "hacked" scripts using procedural code (perhaps with a few PHP functions included only when we really have to), the truth is, if you want to have any hair left a year or two from now, you need object orientation. Writing object oriented code in PHP is not just about saving time: it allows you to solve coding problems that simply cannot be solved by procedural code. Once you’ve got two or three PHP classes working together in an application, you’ll realise you never want to go back. And then you’ll be able to hack away like you’ve never hacked before!

Put another way, object orientation give us the means to write re-usable code and integrate different applications and functionality into a single whole. For example, you may already have run into difficulties on one of your sites, where you implemented a user authentication system and signed loads of people up. You’re now scratching your head as to how to integrate it with a forum application like VBulletin or phpBB without forcing your users to sign up again. If we all wrote more object oriented code, at least half these problems would be solved.

In general, the way eZ publish functions in tying together its various modules, is conceptually similar to the Fusebox approach. This strategy for building Web applications was conceived by developers working with Coldfusion, and has now made its way to PHP at Bombusbee.com. The basic concept behind a fusebox-like site is to have a single script (usually index.php in the Web root) that acts as "traffic cop" for the site, all pages being served "through" index.php. For further details on the Fusebox approach, try the Fusebox Newbie Guide. From an application design perspective, eZ publish loosely conforms to the Fusebox approach, so it may help to read about Fuseboxes in preparation for the third article in this series. But don’t panic! We’ll leave further discussion of object orientation and application design until the third article in this series.

Back to eZ publish! To whet the appetite of those who know your way around PHP classes, have a look at the eZ publish Class Index. Then wander over to the eZ publish sdk currently in development for eZ publish v.3.

Hopefully by now you’re at least sold on the idea that eZ publish is worth your effort. In that case, it’s time to roll up our sleeves and get installing! eZ publish, here we come.

Installing eZ publish

In setting up a working version of eZ publish, I’ll dare to assume you use Windows and are willing to set up a demo on your own machine. The installation process used here can very easily be applied to a LAMP (Linux, Apache, MySQL, PHP) virtual host environment common to many Web hosts.

It’s recommended you have at least PHP version 4.0.6 installed (even better if it’s PHP 4.1+) under Apache 1.3x as well as MySQL 3.23 or later. If you don’t have those installed, look no further than Firepage’s phpdev, an install set that gives you Apache, PHP and MySQL in one tidy package (plus a few other nice things like PHP-GTK and phpMyAdmin). The current phpdev5 beta3 is very stable but to save yourself some headaches, it’s recommended you use Apache 1.3.x rather than 2.x (phpdev5 beta 3 comes with both).

The version of eZ publish used in this article series is 2.2.6. The install process may vary for different versions, and be aware that eZ publish is very sensitive to the correct php.ini settings. If you have any problems with the instructions used in this article, please drop your questions in the SitePoint Forums discussion at the end of this article. Otherwise, you’ll find plenty of people willing to help at http://developer.ez.no/developer/forums/.

Down to Business

eZ publish 2.2.6 can be found from the filemanager at http://developer.ez.no/filemanager/list/85/. Download and unzip to somewhere under your local Apache or PHP Web server — with phpdev5, this will probably be something like "C:phpdev5wwwpublic".

Note: an eZ publish Windows installer exists — it also installs Apache, PHP and MySQL. However, we’ll do things little differently, so that we can re-use the install process on our live LAMP virtual server.

Having unzipped eZ publish, you’ll now have a directory that looks something like C:phpdev5wwwpublicezpublish_2_2_6 (I’ll call this directory your "eZ publish Root" from now on). Under there you’ll find an installation directory, which contains a file called INSTALL.pdf — Chapter 3 of this document is the method we’ll be using to install eZ publish.

Should we be virtuous?

As you saw at the start of this article when we looked at the online demo of eZ publish, there were two separate URLs: one for the main site and another for the back end admin interface:

http://publishdemo.ez.no/ and
http://admin.publishdemo.ez.no/

This is accomplished by some clever tricks with Apache’s virtual host features, described in Chapter 2 of INSTALL.pdf. Trying to install eZ publish this way can be extremely complex — if not impossible — on a typical Web host, which is why we’re taking the alternative option where no Apache configuration is required. Having said that, installation by the easier path will change slightly the way eZ publish behaves:

• http://www.yourdomain.com/index.php is your main page
• http://www.yourdomain.com/index_admin.php is your admin interface

Also, where eZ publish URLs usually look like:

• http://www.yourdomain.com/article/articleview/3/

using the easier approach, the URLs will look like:

• http://www.yourdomain.com/index.php/article/articleview/3/

That’s the trade-off, but it’s minor compared to the pain you’ll experience if you take the Virtual Hosts route for your first eZ publish installation.

Image Magick

The other piece of software we need is Image Magick, a powerful set of command line image manipulation tools that come in very handy when our PHP scripts need a little extra "oomph" in the graphics arena. eZ publish uses Image Magick to control image sizes, to allow them to be rendered consistently.

The file we need to install Image Magick can be found at ftp://ftp.nluug.nl/pub/ImageMagick/binaries/ (or one of the mirrors). The file you’re looking for will be called ImageMagick-5.4.9-xp.exe, or something similar. Once you’ve downloaded and run the executable, install Image Magick to the directory C:Imagemagick.

Ready for Action

You’ll need to take the following steps to get eZ publish up and running.

1. Copy the file htaccess-nVH from [eZ publish_root]installation to [eZ publish_root], rename the current file named .htaccess to htaccess_old and rename htaccess-nVH to .htaccess (note that, depending on your version, Windows Explorer may complain about beginning a file with a full stop (or "period"). In that case, you’ll need to rename the file using the DOS command line (see Kev’s Command Prompt Cheat Sheet).

   Change the eZ publish root directory and use rename htaccess-nVH .btaccess to rename the file. This step ensures the eZ publish installation is secure, and that site visitors can only access index.php.

2. Now head over to your MySQL database (I’m assuming you’ve got phpMyAdmin — if you’ve got phpdev5 running, it’s available at http://localhost/phpmyadmin) and create a database called "publish".
3. You now need to import the MySQL database for eZ publish. In phpMyAdmin (version 2.3.0+) you need to click on the SQL tab when viewing the publish database, and use the file upload box "Location of the textfile:" to select the file. The file you need is [eZ publish_root]sqlpublish_mysql.sql, which builds the eZ publish database structure. We also want some sample data to play with, so load the file [eZ publish_root]sqldata_mysql.sql, which will populate the database.
4. Rename the file [eZ publish_root]site.ini to [eZ publish_root]site.ini.php and edit it with your favorite editor. The reason for doing this is — again — security (files with a .php extension, apart from index.php, will be unavailable to visitors).

Now, in site.ini.php, you need to change the following settings to match your environment:

[site]    

SiteURL=localhost/public/ezpublish_2_2_6    

AdminSiteURL=localhost/public/ezpublish_2_2_6    

UserSiteURL=localhost/public/ezpublish_2_2_6    

...    

SiteTitle=phpPoint    

...    

SiteTmpDir=C:/Windows/temp    

...    

# Database settings set DatabaseImplementation to     

mysql|postgresql|informix.    

DatabaseImplementation=mysql    

Server=localhost    

Database=publish    

User=MySql_User    

Password=MySql_User_Password    

...    

ImageConversionProgram=C:Imagemagickconvert.exe

Save the file.

5. Edit the file sitedir.ini in eZ publish root and set the following variable:

$siteDir = "C:/phpdev5/www/public/ezpublish_2_2_6/";

6. Next, you need to create the directories eZ publish uses to cache pages (getting a good feeling about eZ publish yet?). Download the file at make_cache.zip. This contains a batch file make_cache.bat that will create the directories for you. Extract this to your eZ publish root and with a DOS command line, from the eZ publish root directory type make_cache. All the cache directories should now be created, such as [eZ publish_root]classescache. Make sure you delete make_cache.bat when you’re finished.
7. Finally, we need to make sure our php.ini settings are correct. Open the php.ini file (from your C:Windows directory) and check the following settings:
   • short_open_tag = On

     eZ publish often uses the <? echo($variable); ?> syntax rather than <?php echo($variable); ?>, hopefully something they’ll correct in version 3.x, to help with portability.

   • allow_call_time_pass_reference = On

   Passing variables by reference is a "bad practice" used commonly in XML parsing scripts — another item we hope they’ll get time to fix in eZ publish 3.x

   • error_reporting = E_ALL & ~E_NOTICE
   • register_globals = On

   Development of eZ publish 2.x began before the announcement that register globals would be switched off by default from PHP 4.2. As Kevin Yank warned us in Write Secure Scripts with PHP 4.2!, leaving register globals on is asking for trouble. Again, we hope this will be resolved in eZ publish version 3.x

   • magic_quotes_gpc = Off

   Magic quotes are evil! magic_quotes_runtime = Off should also be set.

   Those are the important settings. Save your php.ini and restart Apache.

The Magic Moment…

Head to http://localhost/public/ezpublish_2_2_6/index.php to view your site! To login to the admin interface, head to http://localhost/public/ezpublish_2_2_6/index_admin.php and login with:

userid: admin
password: publish

Don’t worry about the "failed to create image variation" images — this simply tells us that the images it expected weren’t available (they don’t come with the eZ publish installation zip). If, after you view the eZ publish homepage, you find that you’ve made mistakes in the eZ publish installation, and need to further alter site.ini.php after you make a change, you’ll need to delete any files you find in [eZ publish_root]classescache (where eZ publish caches your site.ini.php file). Otherwise, if you have any problems, don’t hesitate to ask around in the SitePoint Forums discussion at the end of this article.

Installing on Linux Hosts

If I can make yet another assumption — that you host your PHP site on a shared Linux server — the installation process will be very similar, but there are a few pitfalls. Here are a few tips to help you out.

• Make sure you have "ssh" access to your Website. On Windows, putty makes a great SSH client. SSH is a secure (encrypted) version of telnet. There are loads of resources on Google to help you out, and you Web host should be able to provide some good advice, too.
• When you transfer the eZ publish code to your site, be sure to transfer it as a complete zipped file. If you download it to your PC, unpack it, and then transfer the separate files to your site, you will have problems, due to file permissions. Either upload the entire archive in one go, or, when logged in with ssh, fetch it from eZ systems using the wget command line:

  wget http://developer.ez.no/filemanager/    
download/413/ezpublish_2_2_6.tar.gz

  Once you have the archive on your Web server, you can unzip it with the command:

  tar -zxvf ezpublish_2_2_6.tar.gz

  This will extract the lot to a new directory "ezpublish_2_2_6" below the directory where you typed the command.

• In step 7 of the Windows installation above, we used a DOS batch file to create the cache directories. The Linux equivalent is the file called modfix.sh, which you can run by changing the [eZ publish_root] on your server and typing:

./modfix.sh

Note this file also sets up security permissions on the cache directories which are not entirely secure (although the risk is low). And alternative secure_modfix.sh exists, but you’ll probably run into trouble if you use this in a typical shared Linux environment.

• To make use of Image Magick, the convert binary needs to be installed on the Web server. Time to beg your Web host for a favour (it’s not hard for them to install), and get them to tell you where they put it.

If you have any problems installing on your Web host, feel free to add your questions to the discussion at the end of this article.

Homework

eZ publish is now up and running! Before heading into the second part of this series, your mission, should you choose to accept it, is (when logged in as Admin):

ez Image Catalogue

• Delete the existing categories
• Create a new category called Logos to which only Admins and Article Authors can "Write" and "Upload"
• Below the Logos folder, create a category called "Software" with the same permissions as "Logos"
• Upload a couple of images to the Software folder, such as the PHP logo and the MySQL Logo.

ez Article

• This gets a little tougher: edit the "Article Tags Demo" article and see if you can get it to use the two logos you’ve added.
• The big one: learn about eZ article tags. If you download the eZ article documentation and read Adminguide.pdf, you’ll find full details — a more brief description is provided online at http://doc.ez.no/article/articleview/3/1/7/. It’s important for the next article that you’re comfortable with the eZ article module — grade A students will work out how the static page "Thank you for your feedback" relates to the eZ form module.

And if that’s not enough, have a look at the files in [eZ publish_root]/checklists — these are meant to help you test whether eZ publish is functioning correctly, but also serve as a nice series of exercises to get used to all the features. Oh, and don’t forget to have a look at the error.log file when you’re finished. You’ll find in your eZ publish root — it makes interesting reading!

In the next part of this series, we’ll assume you’re fairly happy using the modules, and move on to how to customize your eZ publish site to give it your own look and feel. Until then, may all your publishing be… well eZ, in fact!

Part 2

In Part 1 of this series, I introduced you to eZ publish and dared to dub it "PHP’s killer App". By the end of the last article, you’d installed eZ publish on your development system and of course, being extremely diligent, you’ve done all the homework set and know what eZ publish has to offer.

By now though, you’re probably wondering how to change that boring grey background and apply your own design. In this article, that’s exactly what I’ll explain: how to make eZ publish look and behave the way you want it to. I’ll be helping you create a fictional Website called "phpPoint" which will act as a demonstration of how you can customize eZ publish.

Today’s specials are:

• Fools rush in: pre-requisite knowledge about the eZ publish directory structure, the site ini file and the caching system.
• Going Global: how to modify the "global" design of eZ publish and how Sections are used to create multiple sites.
• Hitting the Module: here you’ll see how module customisation works. Concentrating on eZ Article, you’ll see how to use it’s "API", how to modify it’s templates and how to use static pages, URL translation and forms.
• phpPoint Finished: the happy ending!

By the time you’re finished, you’ll know all you need to build your own state-of-the-art eZ publish site using the existing modules.

Fools Rush In

Ok. Before you starting hacking away, there are a few things that are worth having a look at so you know where you are.

The eZ publish directory structure

If you open up your eZ publish installation directory C:phpdev5wwwpublicezpublish_2_2_6 (or wherever you installed it) with Windows Explorer you’ll see a long list of subdirectories. Most of these relate to eZ publish modules — they’re easy to spot because they all look like "ezsomething", for example: "ezarticle", "eztrade" and "ezforum". I’ll come back to module directories later, but first, let’s look at some other important directories and files:

• admin directory: This contains code and templates for the general look and feel of the eZ publish administration back end. Modules add further code for specific admin tasks, stored under their own directories (as you’ll see shortly). I’ll leave this directory alone though, as I don’t care so much what the admin interface looks like: it’s private after all. One thing to note is that any "intl" directories you might come across contain files that allow eZ publish to handle languages other than English — you’ll be seeing more of this later.
• checklists directory: If you really got stuck into the homework from the last article, you’ll already know that this directory contains a set of tests that you can run on the eZ publish modules. eZ publish still has some minor bugs, as you might expect with an application this big. If you run into any problems, and you’re sure it’s not your configuration, have a look at the eZ publish Bug Tracker.
• classes directory: This contains general PHP classes that are used throughout eZ publish, as described at http://developer.ez.no/doc/view/index. If you’re just interested in applying your own design, you don’t need to worry about these. I’ll look at them in more detail in the third article of this series. Underneath the classes directory you’ll also find the all-important cache directory. We’ll cover more on caching in a moment, but you need to be aware that this directory caches the global configuration files like site.ini.php.
• images directory: Contains images used throughout eZ publish. Further images appear under the module directories.
• sitedesign directory: This one is important, as it contains the files that determine the overall eZ publish design. We’ll look at this in depth shortly.
• site.ini.php file: This stores the global configuration options for eZ publish. More in a minute!
• sitedir.ini file: Used by eZ publish to locate itself for installations, as you saw in part one.
• cron.php file: A useful file that helps with scheduled updates to eZ publish while you sleep! Intended for the Unix Cron tool (it should also be possible to activate this using a Windows scheduling tool, such as the Task Scheduler).
• index.php file: This is the "traffic cop" of eZ publish, activating code as required. It should never need changing — any attempts to do so will probably break things unless you know what you’re doing.
• index_admin.php file: This is the "traffic cop" for the back end admin system. Again, best not to touch!
• index_xmlrpc.php file: This provides and XML-RPC interface to eZ publish, for use with their Desktop Edition. Not one you should need to interfere with.

site.ini

In Part 1 of this series you renamed this to site.ini.php and made some basic changes to get your site up and running. I’ll refer to it from now on as just site.ini, to stay in line with the eZ publish documentation.

This file contains global settings for the whole of eZ publish, as well as settings that apply to specific eZ publish modules. Given the size of the file, I’m not going to cover every setting, but rather highlight some important ones, and explain the mechanisms for updating site.ini. You should find most of the settings self-explanatory.

But first of all, make a backup and put it somewhere safe.

At the top of site.ini you’ll find settings that apply to the whole site. Let’s begin by modifying these.

# Meta content variable       

SiteAuthor=HarryF       

SiteCopyright=HarryF © 2002       

SiteDescription=PHP: Getting the point?       

SiteKeywords=PHP, Development, Tutorials, Articles

These determine HTML <meta> tags that appear on the top of each page. Note that eZ publish modules like eZ article may override SiteDescription and SiteKeywords with values you create with your articles: this is very useful if you want to tell Google all about an article you’ve written. The settings here amount to the default settings.

Let’s see some more:

DefaultPage=/article/frontpage/1/       

LogFile=error.log       

EnabledModules=eZArticle;eZTrade;eZForum;eZLink;eZPoll;eZAd;       

eZNewsfeed;eZBug;eZContact;eZTodo;eZCalendar;eZFileManager;       

eZImageCatalogue;eZMediaCatalogue;eZAddress;eZForm;eZBulkMail;       

eZMessage;eZQuiz;eZStats;eZURLTranslator;eZSiteManager;eZUser       

CacheHeaders=true       

...       

URLTranslationKeyword=section-standard;section-intranet;section-trade;       

section-news       

Sections=enabled       

DefaultSection=1

Ok, let’s go through this code step-by-step.

The DefaultPage determines what appears on your home page, i.e. http://localhost/public/ezpublish_2_2_6/index.php is, in this case, the same as http://localhost/public/ezpublish_2_2_6/index.php/article/frontpage/1/.

The log file you saw in Part 1 of this series is used to keep track of what administrators do to the site, and any application errors that occur. It’s very useful if you have a big site with many people working on it.

EnabledModules is self-explanatory.

CacheHeaders controls the browser caching headers delivered with the HTTP protocol (it determines whether a browser use its own, locally-stored copy, or fetches a new one from your site) -- best to leave this as it is.

URLTranslaterionKeyword you'll see more of when we get to eZ article -- essentially it helps make "pretty" URLs, so that, rather than http://localhost/public/ezpublish_2_2_6/index.php/forum/forumlist/1/ you could have http://localhost/public/ezpublish_2_2_6/index.php/forum/.

Sections allows you to have multiple "styles" for your site (a bit like skins), each with a different look and feel, offering access to different eZ publish modules. In conjunction with this, DefaultSection tells eZ publish which to use on the home page, or if it's uncertain which style to use at any point. I'll look more at sections shortly.

After this, the other settings you'll need to worry about apply to the modules, such as:

[eZAdMain]       

AdminTemplateDir=templates/standard/       

TemplateDir=templates/standard/ImageDir=images/standard/       

Language=en_GB       

DefaultCategory=1       

DefaultSection=1
You'll be seeing more of this soon. In each of the eZ publish module directories, you'll find a file called site.ini.txt, which gives the meaning of each of these variables.
Caching
Aside from the generation of HTTP headers that tell browsers what to do when caching Web pages, eZ publish has its own internal caching mechanism used to store "parsed" output. Once a page has been viewed, eZ publish can deliver the cached version rather than rebuilding the entire page, thereby improving overall performance. When you modify eZ publish's design, you'll need to be aware of how caching works -- otherwise you'll be wondering why you can't see your changes. The internal caching mechanism is used essentially in three ways:
The directory [ezPublish_root]/classes/cache/ is used to store PHP scripts and variables. The contents of site.ini will be found in parsed form here, along with variables that eZ publish has assigned for a whole range of operations. If you make changes to site.ini you'll need to delete the files in this directory for your changes to take effect.
In site.ini you'll find the following settings:
SiteCache=disabled       

SiteCacheTimeout=60
The SiteCache attempts to cache every page of eZ publish. This is only useful for sites where most of the content is static. For sites using the forum module, for example, it's best to leave this disabled. The SiteCacheTimeout tells eZ publish when a cached page can be regarded as having expired (in minutes) and requires re-creating.
For certain modules, such as eZ article, you'll also find a "PageCaching" setting in site.ini, which can also be enabled or disabled. When you work on the visual layout of a module like eZ article, it's a good idea to set this to "disabled", so you'll be able to see any changes as you make them. Also, if you publish an article and then make changes to it, you'll need to delete its cached version in [ezPublish_root]/ezarticle/cache/.
In the administration back end of eZ publish you'll find Cache Admin tool under the Site Manager section (second from far right). This works nicely if you've got eZ publish installed under Linux, but sadly not with Windows (you'll have to delete cached files manually with Explorer).


Going Global
Now you have an idea of how eZ publish fits together, it's time to get down to the nitty gritty of applying your own design (well, mine in fact -- but pretend it's yours!).
Before you start doing anything with eZ publish, you need a "sketch" of how you want your site to look. Subjecting you to my own personal bias, the first thing to do is download a copy of Opera from http://www.opera.com/download/. Why? Because, generally speaking, if your design looks right in Opera, it will look right in any other browser. If you're running Windows, the non-Java version is fine.

I've put together a simple HTML page and a style sheet that I want to "apply" to eZ publish. If you download sampler.zip, you'll find a simple design for how the site should look in HTML, with a CSS file alongside. The site is going to be very simple -- it'll make use of only the eZ article module. What you'll learn here, though, should be applicable to more complicated eZ publish sites. It's worth having sampler.html (from the ZIP) open while you read the rest of this article, to help visualise what's happening.
The Sitedesign Directory
The first move is to find the [ezpublish_root]/sitedesign/standard/ directory and make a copy of it, which you'll need to rename [ezpublish_root]/sitedesign/phppoint/. You'll keep all the design work in the phppoint directory. It's a good idea to leave the original directories untouched, to have examples to work from.
Next, from the administration back end, head to the site manager (second from far right). The default view is the "Section List". Delete the Intranet, Trade and News sections, as you don't need them, then edit the Standard Section, setting the name and Sitedesign to "phpPoint". Further down the edit page, you'll see a section called "columns". The aim is to have four articles appear at once on the "Frontpage", each taking the complete width of the page. So add a row, and then set them all to "1 Column Article" with the Category "All".
Now head to the URLTranslator (third from the right) and rename /section-standard to /section-phppoint, then delete the other three.
Finally, in site.ini, update the following variables:
SiteDesign=phppoint        

SiteStyle=ezpublish        

SiteTitle=phpPoint        

...        

EnabledModules=eZArticle;eZImageCatalogue;eZMediaCatalogue;        

eZForm;eZStats;eZURLTranslator;eZSiteManager;eZUser        

...        

URLTranslationKeyword=section-phppoint        

Sections=disabled
The SiteDesign variable points eZ publish at the directory I'll be putting my design in. SiteTitle is the title that appears at the top of the browser. SiteStyle I leave untouched, as this applies to the back end admin section. You need to make sure that only the modules you want are available using the EnababledModules variable. URLTranslation and Sections are discussed in more detail under "Sections" in a moment.
Lastly, clear out the cache in [ezpublish_root]/classes/cache/.
You're now ready to start hacking!
frame.php
In your [ezpublish_root]/sitedesign/phppoint/ directory, you'll find a file called frame.php. This file is basically the main template within eZ publish: more or less all your pages are generated by eZ publish through this template.
Before you go any further, if you'll allow me a momentary rant: this is what templating in PHP is really about. As you've seen in this discussion on the SitePoint Forums, any templating system that doesn't use PHP's own language structure and variables is a complete waste of time, memory and processing power. frame.php is a prime example of how templates should be constructed.
Now, looking at the contents of frame.php, you'll see HTML interspersed with PHP. Before you edit it, I'll introduce you to some examples of what you'll see there. First you have:
<title><?php        

// set the site title        

        

$SiteTitle = $ini->read_var( "site", "SiteTitle" );        

        

if ( isset( $SiteTitleAppend ) )        

    print( $SiteTitle . " - " . $SiteTitleAppend );        

else        

    print( $SiteTitle );        

        

?></title>
Here, the code first assigns the $SiteTitle variable, by fetching it from the $ini object using the read_var() method. If you're at all uncertain about the syntax used there, have a look at Kevin Yank's introductory tutorial on Object Oriented PHP.
After that, the code checks for a $SiteTitleAppend variable, which, if it exists, usually contains something like the title of an article. If this variable isn't found, the contents of the <title /> tag will be just the $SiteTitle variable you set in site.ini.
Moving further down the script, you have:
<img src="<? print $GlobalSiteIni->WWWDir; ?>/sitedesign/<?         

print ($GlobalSiteDesign); ?>/images/ezpublish-yourcontentmadeeasy.gif"         

height="20" width="290" border="0" alt="" />
Here's eZ publish builds an URL, fetching the URL of the site with:
$GlobalSiteIni->WWWDir
It's nice how these eZ publish classes work, isn't it? For anyone who's been looking at the Kevin Yank's articles on the .NET framework, you'll notice a remarkable similarity. As I mentioned in the first part of this series, eZ publish is also a framework designed specifically for building PHP applications. And this is one of the things a good framework is about: making your life easy, by providing a well designed class library you can reuse.


Anyway, back to business. Some of the variables used in frame.php are described at http://doc.ez.no/article/articleview/204/1/54/. To cut a long story short, here's the sampler file you saw earlier applied to frame.php. Note that I haven't literally copied and pasted everything. In particular, the left menu needs more work, which I'll get to when we look at the eZ article module.
<!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="no" lang="no">         

         

<head>         

<title><?php         

// set the site title         

         

$SiteTitle = $ini->read_var( "site", "SiteTitle" );         

         

if ( isset( $SiteTitleAppend ) )         

    print( $SiteTitle . " - " . $SiteTitleAppend );         

else         

    print( $SiteTitle );         

         

?></title>         

         

         

<?php         

         

// check if we need a http-equiv refresh         

if ( isset( $MetaRedirectLocation ) && isset( $MetaRedirectTimer ) )         

{         

    print( "<META HTTP-EQUIV=Refresh ".         

         "CONTENT="$MetaRedirectTimer; URL=$MetaRedirectLocation" />" );         

}         

         

?>         

         

<link rel="stylesheet" type="text/css"          

    href="<?          

        print $GlobalSiteIni->WWWDir;          

        ?>/sitedesign/<?         

            print ($GlobalSiteDesign);          

                        ?>/style.css" />         

         

<script language="JavaScript1.2">         

<!--//         

         

   function MM_swapImgRestore()         

   {         

      var i,x,a=document.MM_sr;         

      for(i=0;a&&i<a.length&&(x=a[i])&&x.oSrc;i++) x.src=x.oSrc;         

   }         

         

   function MM_preloadImages()         

   {         

      var d=document; if(d.images){ if(!d.MM_p) d.MM_p=new Array();         

      var i,j=d.MM_p.length,a=MM_preloadImages.arguments;         

      for(i=0; i<a.length; i++)         

          if (a[i].indexOf("#")!=0){         

              d.MM_p[j]=new Image; d.MM_p[j++].src=a[i];         

          }         

      }         

   }         

         

   function MM_findObj(n, d)         

   {         

      var p,i,x;  if(!d) d=document;         

      if((p=n.indexOf("?"))>0&&parent.frames.length) {         

        d=parent.frames[n.substring(p+1)].document; n=n.substring(0,p);         

      }         

      if(!(x=d[n])&&d.all) x=d.all[n];         

      for (i=0;!x&&i<d.forms.length;i++) x=d.forms[i][n];         

      for(i=0;!x&&d.layers&&i<d.layers.length;i++)         

        x=MM_findObj(n,d.layers[i].document);         

      return x;         

   }         

         

   function MM_swapImage()         

   {         

      var i,j=0,x,a=MM_swapImage.arguments; document.MM_sr=new Array;         

      for(i=0;i<(a.length-2);i+=3)         

      if ((x=MM_findObj(a[i]))!=null) {         

          document.MM_sr[j++]=x; if(!x.oSrc) x.oSrc=x.src; x.src=a[i+2];         

      }         

   }         

         

//-->         

</script>         

         

<!-- set the content meta information -->         

         

<meta name="author" content="<?php         

         

    $SiteAuthor = $ini->read_var( "site", "SiteAuthor" );         

    print( $SiteAuthor );         

         

?>" />         

<meta name="copyright" content="<?php         

         

    $SiteCopyright = $ini->read_var( "site", "SiteCopyright" );         

    print( $SiteCopyright );         

         

?>" />         

<meta name="description" content="<?php         

         

if ( isset( $SiteDescriptionOverride ) )         

{         

    print( $SiteDescriptionOverride );         

}         

else         

{         

    $SiteDescription = $ini->read_var( "site", "SiteDescription" );         

    print( $SiteDescription );         

}         

         

?>" />         

<meta name="keywords" content="<?php         

if ( isset( $SiteKeywordsOverride ) )         

{         

    print( $SiteKeywordsOverride );         

}         

else         

{         

    $SiteKeywords = $ini->read_var( "site", "SiteKeywords" );         

    print( $SiteKeywords );         

}         

         

?>" />         

<meta name="MSSmartTagsPreventParsing" content="TRUE" />         

         

<meta name="generator" content="eZ publish" />         

         

</head>         

         

<body bgcolor="#FFFFFF" topmargin="6"         

    marginheight="6" leftmargin="6" marginwidth="6">         

         

<table width="100%" border="0" cellspacing="0" cellpadding="0">         

<tr>         

<td class="sitetitle">phpPoint.com</td>         

</tr>         

</table>         

         

<table width="100%" border="0" cellspacing="6" cellpadding="6">         

<tr valign="top">         

<td width="15%" class="menuback">         

         

<!-- Left menu start -->         

         

<?         

$CategoryID = 0;         

include( "ezarticle/user/menubox.php" );         

?>         

         

<br />         

         

<table class="menu">         

<tr>         

<td class="menuitem">         

<a href="?PrintableVersion=enabled">Printable page</a>         

</td>         

</tr>         

<tr>         

<td class="menuitem">         

<a target="_blank" href="http://developer.ez.no">         

<img src="<?         

       print $GlobalSiteIni->WWWDir;         

     ?>/images/powered-by-ezpublish-100x35-trans-lgrey.gif"         

       width="100"         

       height="35" border="0" alt="Powered by eZ publish" /></a>         

</div>         

</td>         

</tr>         

</table>         

         

<!-- Left menu end -->         

         

</td>         

<td width="95%">         

         

<!-- Main content view start -->         

         

   <?         

   print( $MainContents );         

   ?>         

         

<!-- Main content view end -->         

</td>         

</tr>         

</table>         

         

<?         

// Store the statistics with a callback image.         

// It will be no overhead with this method for storing stats         

//         

         

$StoreStats = $ini->read_var( "eZStatsMain", "StoreStats" );         

         

if ( $StoreStats == "enabled" )         

{         

    // create a random string to prevent browser caching.         

    $seed = md5( microtime() );         

    // callback for storing the stats         

    $imgSrc = $GlobalSiteIni->WWWDir . "/stats/store/rx$seed-" .         

                $REQUEST_URI . "1x1.gif";         

    print( "<img src="$imgSrc" height="1"".     &oo@