Getting started with eZ Publish - First steps after installation

This article is second in a series about eZ Publish CMS. It continues our exploration where the article about installation left off. It will deal with the first steps after eZ Publish installation.

We'll customize our site a bit and alter it's appearance. To do that we'll first do some basic eZ Publish configuration and then we'll create a new eZ Publish extension.

Preparing for work

Because you're reading a Web Development category blog post, I'm betting you already have your environment set up and eZ Publish installed. And if you don't, you should have. :) If you need help with this take a look at my previous blog post about eZ Publish.

In order to be able to develop PHP applications, you should have a PHP editor. It would really be best if you used a PHP IDE, such as Eclipse or NetBeans, but in the end, you can use any text editor that's capable of editing PHP files, like Notepad++, for example.

For PHP development I use Eclipse with PDT plug-in, so I'll show you how to create a eZ Publish Project in Eclipse.

Open Eclipse, then go to File -> New -> PHP Project. You can also select New -> Project ... and then choose PHP from a list of available Eclipse projects.

Select the option "Create project at existing location (from existing source)". Choose the folder where you extracted eZ Publish. For PHP Version you can leave the "Use default PHP settings" radio button active and select the "Enable JavaScript support for this project" and click Next.

Here you can configure files to be included in the project, but we don't need to do that for eZ Publish project so just click Next. On the next screen we can configure the build path, but we don't need to do that. Simply click Finish.

The wizard will finish and our new project will open. Now, let's configure eZ Publish.

Configuration for Development

eZ Publish has features that improve site's performance, like Template Caching and View Caching. This means eZ Publish stores Template and XHTML code in the cache directory and reuses it to display the page faster. However, this feature can interfere with development as eZ Publish will cache our templates, meaning we would need to clear the cache manually to see the changes we made.

So, first, let's disable ViewCaching and TemplateCache. Also, let's configure some other settings used for development.

In Eclipse switch to the PHP Explorer or Navigator and expand the /settings/override folder. Open a file named site.ini.append.php.

At the end of the file append these lines:

[DebugSettings]
DebugOutput=enabled
 
[TemplateSettings]
TemplateCache=disabled
TemplateCompile=disabled
 
[ContentSettings]
ViewCaching=disabled
StaticCache=disabled

The first line enables the debug output. Debug output shows you various information about eZ Publish templates, code and resources used to display the page. It's a very useful feature to have during development. Try to activate the option "List of used templates".

NOTE: If you use the toolbar to activate/deactivate debug options you'll need to enter your email and password you configured at installation. Of course, you can enable/disable all the options in the site.ini.append.php file.

[TemplateSettings] block refers to the eZ Publish template system. TemplateCache=disabled option disables the caching of eZ Publish templates. TemplateCompile=disabled means eZ Publish will interpret each template.

View cache means eZ Publish stores HTML output and uses that to display the page. We disable it in the development to force eZ Publish to render templates on request.

Pages that always look the same and don't contain content from a database can be stored completely in HTML. This is called Static cache. By default it's disabled. We'll hopefully get into it into another blog post because it can greatly improve the speed of your site.

Basic Visual Modifications

If we take a look at the source of the page, we'll see the CSS files used. The main CSS file is called site-colors.css and is located in: /var/storage/packages ... directory. To change the design we could simply change that CSS file, or the files inside the extension folder. But that isn't exactly clean.

The most elegant solution is to make our own design. That way we can update to the new version of eZ Publish without problems, because we won't be touching original eZ Publish files.

Open folder extension. There you'll see list of extensions for our eZ Publish installation. Open ezwebin folder and take a look at the structure of folders inside it. This is used for current page design.

To verify this is true, we can for example change the core.css file we find in the extension/ezwebin/design/ezwebin/stylesheets. Let's simply put another value for a body background:

body /* These becomes the initial settings for most other elements */
{
    font-family: Arial, Helvetica, sans-serif;
    font-size: 0.8em;
    color: #535548;
    background-color: #000;
    background-image: url(../images/body_bg.png);
    background-repeat: repeat-x;
    text-align: center; /* IE method for centering page if it has fixed width */
    margin: 0;
    padding: 0;
}

Refresh our eZ Publish page to verify. You'll see that the result isn't pretty:

So, to change the site design the best solution is to create our own extension. Let's do just that:

Creating a custom design

Create a new folder inside the extensions folder and call it "customdesign". In Eclipse, you can right-click on extensions folder and choose New -> Folder.

Using the same Eclipse methodology from above, inside customdesign folder create the design and settings folders.

Inside the design folder create the customdesign folder, and inside that create the stylesheets folder. It maybe sound complicated, but we're just basically duplicating the folder structure of ezwebin extension.

Now inside the stylesheets folder create a new CSS file named core.css. You can do this using Eclipse. Right-click on the stylesheets folder and choose New -> CSS File.

In the dialog box you can click Next or Finish. If you click Next, you'll be able to choose a Eclipse CSS template. But there's no need for that. Simply click Finish.

The file will open. Insert a following CSS:

body {
    background: #fff;
    color: #000;
    font-family: Arial,Helvetica,sans-serif;
    font-size: 0.8em;
    margin: 0;
    padding: 0;
    text-align: center;
}

Now, let's create a CSS file for site colors. Inside the stylesheets directory create a site-colors.css file with the following content:

div#usermenu {
    background-color: #ea3131;
    background-image: none;
    height: 23px;
}
 
div#usermenu a {
    border-left: medium none;
    color: #fff;
    font-size: 10px;
}
 
div#header {
    background: #cc0000;
    border-bottom: 1px solid #b91414;
    height: 117px;
    padding: 0;
}
 
div#languages, div#links {
    background: none;
}

Now let's make a few eZ Publish settings modifications so that our new design is used.

In the extension/customdesign/settings folder create a design.ini.append.php file. You can even copy/paste it from extension/ezwebin/settings folder. Inside our new file set the following settings:

<?php /* #?ini charset="utf-8"?
# eZ publish configuration file for modules
 
[ExtensionSettings]
DesignExtensions[]=customdesign
 
[StylesheetSettings]
SiteCSS=extension/customdesign/design/customdesign/stylesheets/site-colors.css
 
*/ ?>

At the same location create the site.ini.append.php. Same deal, you can also copy it from extension/ezwebin/settings directory. After you create it it should contain the following settings:

<?php /*
 
[FileSettings]
VarDir=var/customdesign
 
*/ ?>

Now open our site.ini.append.php file that's located inside the settings/siteaccess/eng folder.

Find the [DesignSettings] block and change it to use our new design:

[DesignSettings]
DesignLocationCache=enabled
SiteDesign=customdesign
AdditionalSiteDesignList[]
AdditionalSiteDesignList[]=base

We also need to enable our extension. We'll do that by simply adding the extension name to the ActiveExtensions[] array in the [ExtensionSettings] block. Entire block should look something like this:

[ExtensionSettings]
ActiveExtensions[]
ActiveExtensions[]=ezjscore
ActiveExtensions[]=ezwt
ActiveExtensions[]=ezstarrating
ActiveExtensions[]=ezgmaplocation
ActiveExtensions[]=ezwebin
ActiveExtensions[]=ezie
ActiveExtensions[]=ezoe
ActiveExtensions[]=ezodf
ActiveExtensions[]=customdesign

Now clear the cache. You can do it via the Admin interface or manually delete the cache directory located inside var. Now refresh the page.

If you take a look at our site source you'll see the following css files used:

<style type="text/css">
    @import url("/extension/customdesign/design/customdesign/stylesheets/core.css");
 
    @import url("/design/base/stylesheets/site.css");
 
    @import url("/extension/customdesign/design/customdesign/stylesheets/site-colors.css");
    @import url("/design/base/stylesheets/classes.css");
  
    @import url("/var/storage/packages/eZ-systems/ezwebin_design_blue/files/default/file/classes-colors.css");
    @import url("/design/standard/stylesheets/debug.css");
</style>

First file should be clear. It's the core.css we created. Second file "/design/base/stylesheets/site.css" comes from a "base" design, because eZ Publish didn't find site.css inside our customdesign extension and AdditionalSiteDesignList[]=base lists that "base" is a additional site design.

If we now created a file named site.css inside our extension that file would be used instead of the one from a base design.

So, basically we used a eZ Publish feature called automatic fallback. We created the custom design and used it as a main design. Then we configured eZ Publish to use the built-in "base" design as an additional site design. This way, if eZ Publish doesn't find a "design-specific" file it automatically searches for the file in the additional designs.

This enables us to simply create the custom design with only needed changes and let eZ Publish use the default files for stuff we don't need to have custom built/designed.

Summary

In previous post we managed to obtain eZ Publish and install it on Apache or IIS and did some basic configuration to have URL rewrite. In this post we took a look at options for creating our custom design for an eZ Publish site and created our custom design extension. Next step in exploration of eZ Publish will be to add a new siteaccess so we can have our content in multiple languages on the same site.

Also, if you'd be interested in a tutorial series that start from a blank eZ Publish installation and in a few posts demonstrates how to create a custom blog website from scratch let me know by the use of comments.

Thanks for reading! Be sure to return to the site from time to time for more eZ Publish, Web Development in general, Web Design and Networking posts.

Comments are closed