Get Start a new eZ Publish project – Part I

In the past, I wrote a post briefly introduced the eZ Publish CMS. In these two series post, I will get into the technical details on how to actually start a new eZ Publish project. We are going to set up a starting point of eZ Publish project, named “Multiline”. This project will contain two independent web sites under the same installation. The two web sites, one of which will be accessed via a single domain with language switch between French and English, and another will accessed by a different domain with only the French language available. At the end of this article, you will learn how to get eZ Publish ready for different projects requirements, include: multi-sites, multi-language, different access method and SVN integration.

The set up :Plain site
For me, it seems there is a misunderstanding among novices ( and maybe also veterans alike? ) that the eZ Publish is the “eZ Web Interface”( or “eZ Flow”, sometimes). I once got answer the question like:”Hey, you said you used the default templates for the this page, but why this page doesn’t look like the default page at all?” ( Then, the person will show you a page on eZ Web Interface page side by side with the page of your project ) The reason being is that eZ System uses “eZ Web Interface” in various articles and tutorials, plus, in the set up wizard of eZ Publish, it says “eZ Web Interface” provides most common CMS website needs. But, the “eZ Web Interface” is really just a DEMO. For my opinion, for every new project, it is better to start from an empty site, thus the “Plain Site”. Actually, if you read the manual, you will know, these things are called “site package”; “eZ Web Interface”, “eZ Flow” and “Plain Site” are just different site packages. So, “why Plain Site” you may ask; I think the single reason that “Because in eZ Publish, template files and content types are tired together” is sufficient enough to make this decision. eZ Publish template file contains eZ Publish template code which will indicate attributes or properties of the defined content types for each particular project —- just think about how many times you will use content class identifier and content object attribute identifier in you template code —- eZ Web Interface comes with a set of predefined content classes, but I don’t think it will really suit for every project as the wizard page indicates; after all, if it does, what is the point of the powerful eZ Publish content engine (*1).?

eZ Publish site package

So, when you are walking through the set up wizard, at the following screen, choose “Plain Site” And continue.

Multi-language
The project we are demonstrating, called “multiline”, which will have two languages and two separated web sites. One called “mybilingual” accessed by www.mybilingual.com/index.php/fre for French version and www.mybilingual.com/index.php/eng for Englsih version; another one called “myindependent”, accessed by www.myindependent.com. Set the multi-languages up can be done through either the set up wizard or in the Administration Interface later on:

eZ Publish language selection

Here we choose French and English, and set the French is the default/Main language.

Set up eZ Publish language

Just click [Add language] button to add new languages.

Multi-site
Since we will have two separated web sites on the same installation, which means, we will have two sets of the content for each web site but under the same content node tree so we can manage the two separated web sites’ content in a single back end. We will have two nodes directly under the “content root node” to serve as the root node for each of the website.
In order to set this up for the Frontend Public sites work correctly, we will have to make some changes on the specific site.ini.append.php files. But we need set up our “site-access-es” first, because after run the wizard, we will only have one public site access available, that is the “multiline” ( of course, plus the administration site access, multiline_site_admin, we are already in ).

Site.ini.append.php
Create siteaccess manually. So, here are the site-access-es we need to add: fre, eng and myindependent.
1.Copy the configuration file over.
Create these three sub directories under /settings/siteaccess: fre, eng and myindependent. Then copy the site.ini.append.php file from the multiline access over to each of the directories.

2.SiteSettings.
First, we need add some site access into the [SiteSettings] section:

In the global site access override, /settings/override/site.ini.append.php, get following settings ready:

In order to make the multi-sites work, we will need set the match order and access rules in the global override site.ini.append.php file. The order of the value for MatchOrder is important, the “uri” must be the first, the followed by the “host”; this way, the system will try to match or load site access configurations according to the uri first then according the domain name (*2).

4.Root node, path prefix
In order to set up two different root nodes for each public web sites, we need change the configuration in the site.ini.append.php file for each of the site access. Write down the node ID of the root node for each of the web site. Then, if you have following settings in the [SiteSettings] of the file /settings/override/site.ini.append.php, remove it first:

[SiteSettings]
RootNodeDepth=1

then, for each siteaccess, except the multiline_site_admin, site.ini.append.php file, set these value in the [SiteSettings] section ( take siteaccess fre for example, /settings/siteaccess/fre/site.ini.append.php):

set this value in the [SiteAccessSettings] section ( again, take siteaccess fre for example, /settings/siteaccess/fre/site.ini.append.php ):

[SiteAccessSettings]
PathPrefix=mybilingual

5.The RootNodeDepth
Set the RootNodeDepth to 2 instead the default value 1, will take care the problem related in the $module_result.path array. Thus, you can write the breadcrumb navigation links in your template code as normal.

6.The PathPrefix
This is the value of siteaccess fre or siteaccess eng root node url alias. This setting will take care the problem of the search engine return the content nodes above the root level in the search result list.

Add RootNodeDepth=1 back into the /settings/multiline_site_admin/site.ini.append.php file under the [SiteSettings] section.

7.Database settings
Normally, one project will only has single database; if you have a team of developers, it is also more convenient for all the eZ Publish instance on their developer machine share the same database. By default, eZ Publish put the database settings in each of the siteaccess’ site.ini.append.php file. This is ok, but if you use the same database for all your site access, you could move the settings to the global override for easier maintenance. Just remove following settings in each of the site.ini.append.php file and put them into the /settings/override/site.ini.append.php file:

These settings should already available if you run through the set up wizard; just delete, cut and paste them into the correct location.

8.SiteAccessSettings
Above, we have already set one value in the [SiteAccessSettings] section. Since we are manually created the siteaccess from scratch, there are few more values need modified or added.

Please note the “RelatedSiteAccessList” settings. The point here is that site access fre and eng are belonging to the same domain site and site access myindependet belong to another, so they are not related to each other.

9.The session handler
For our multi-domain sites to work on the single eZ Publish installation, there are still one important setting needs to satisfy. It is the “SessionNameHandler” under the [Session] section in the site.ini.append.php. This time, we just put it in the global override:

In /settings/override/site.ini.append.php, put:

[Session]
SessionNameHandler=custom

10. The site design
We need set the configuration value of the SiteDesign under the [DesignSettings] which will indicate which site design the corresponding site access will use. Since there are probably two of site designs for this project, one for each of the web site, so again the site.ini.append.php file for myindependent has different setting values.

for site access fre and eng
[DesignSettings]
SiteDesign=mybilingual
AdditionalSiteDesignList[]=base

for site access myindependent[DesignSettings]
SiteDesign=myindependent
AdditionalSiteDesignList[]=base

The two site designs, mybilingual and myindependent, will be set up in an extension. It is sometimes surprise that most users don’t know how to create a “Design Extension”, or don’t know what is a “Design Extension”, if you fall into this category, don’t worry, I will get into it in just a minute.

11.Regional Settings
The regional settings are important in order to make the multi-language work correctly. Here we have each site access with different language, my preferable way to set the language up is for each site access has a single language and for the administration site access has all the available languages. So, for example, for the site access fre, put following settings under the [RegionalSettings]:[RegionalSettings]
Locale=fre-FR
ContentObjectLocale=fre-FR
SiteLanguageList[]=fre-FR
TextTranslation=enabled
ShowUntranslatedObjects=disabled

It is the same for the site access myindependent, because it also has only the French language. For the site access of administration, multiline_site_admin, site access, there are slightly different:[RegionalSettings]
Locale=eng-GB
ContentObjectLocale=fre-FR
ShowUntranslatedObjects=enabled
SiteLanguageList[]=eng-GB
SiteLanguageList[]=fre-FR
TextTranslation=enabled

A word on the “ShowUntranslatedObjects”: If this setting is “enabled”, the “Unstranslated Objects” means those content objects have the language not in the “SiteLanguageList” array, so it is not just for the “Main Language”. And another important point is that this will need work in tandem with the settings set on the content object in the Administration Interface, if the “Use the main language if there is no prioritized translation.” check box is checked in the “Translations” block of a content object, then as long as there is a language version of the object available, the object will not be recognized as “Unstranslated Objects”.

eZ Publish set main language

The Local value will determine the locale system to use, such as the currency and date format, and the static text loaded through the language file. The ContentObjectLocale indicates the default language for content objects. Since we are sure the main language for the system is the French, and we want to ensure that when a content object created or edited, it better has the French version as soon as possible, so I set the ContentObjectLocale in Administration Interface to French even though the interface itself will be in English —- cause honestly, I am really not good at French at all.

12.Enable Regional Settings development mode
It is a best practice to enable the “DevelopmentMode” in the [RegionalSettings] section. According to the comment information in the default site.ini file, this will result “all untranslated texts translated using the bork rules”; it just means if the system can’t find a translated text, the text will shown in brackets, [], with some funny text. By enable this, it is easier to find those static text has not been translated yet ( *3 ).
In global override, /setings/override/site.ini.append.php:[RegionalSettings]
DevelopmentMode=enabled

13.The VarDir
Since in eZ Publish, all the content related binary files ( images, docs, PDFs and so on ), cache files and log files are stored under the var sub directory of the eZ Publish system root, it is better to indicate the name of the VarDir folder on per project basis. Right now, the system automatically set the VarDir to “var/plain_site”, we can change it to better maintenance.

Put this settings in the global override /settings/override/site.ini.append.php:[FileSettings]
VarDir=var/multiline

14.Disable “ShowXHTMLCode” in [TemplateSettings]
Some browsers made by Microsoft seem always have problems to display web page correctly. For example, when you enable the debug output in the browser for eZ Publish, in Internet Explorer, some design of the web sites will suddenly become a mess. This is because by default, eZ Publish will display a comment in the rendered output of the browser for each time a new template is loaded; and these added html comment cause problems with Internet Explorer, so it is best to disable this if you test your web page in various browers.

[TemplateSettings]
ShowXHTMLCode=disabled

15.URLTranslator
Right now, eZ Publish support three different url TransformationGroup: urlalias, urlalias_iri and urlalias_compat. The urlalias_iri is nice for its utf-8 support. However, in reality, I found it sometimes cause problems related to the image alias path. It also has something to do with the Operate System file system. For every image, eZ Publish will generated the storage location according the path information of the image in the node tree ( normally, under the media library top level node ) . If, for example, in the path to the actual image contains a parent node, such as a folder, whose name includes some special characters ( this case is very common in French, since the letters like ” ´, é, á” are very common ), then, the resulting folder name in the file system which will store the actual image will be in a mysterious state: depend on the OS file system character encode supporting situation, the final folder name sit on the hard disk is more likely contain some un-recognizable characters. And, if this is the case, when the eZ Publish system need read the image back in to show it in browser, it will not correctly decoding the path information for the image. Tracking down this kind problem will cost much time, because you will spend much time on the wrong direction and the actual cause is on the other side of the wall.

So, for my opinion, it is better to avoid use the urlalias_iri before a thorough analysis.

16.The cache
Of course, during the development, it is advised to disable the cache altogether for convenience. We need set following settings in the global override, /settings/override/site.ini.append.php:

Wow, we covered a lot in the settings of the site.ini[.append.php] files. This might seem quite daunting to remember all of this settings at first, it will become your second natural alone the way with your experience. Nonetheless it provide a good reference for understanding the site.ini[.append.php] setting in real projects.

(*1) Yes, there are a tutorial on “How to Skin an eZ Publish web site based on the Web Interface“. Of course it is a usable approach, if your organization has a fully dedicated team including members of designer, web designer/html/css integrator and developer. Building everything from Web Interface will require much more deeper knowledge on the output information, such as: html div tags, css classes and ids, of the template system, maybe some conversions made by the Web Interface, excellent css skills and very efficient communication between designers and developers. And still, all this requires time. But, I think starting from the “Plain Site” suit for most organizations, even if you have everybody in place; and this approach should be more flexible and cost effective.

(*2) I have made the assumption that you have already set the web server and DNS up. For example, both domains, www.mybilingual.com and www.myindependent.com should be point to the same eZ Publish system root, for the virtual host www.myindependent.com configuration, you can consult the manual on “Set up virtual host“. This should be already the case if you already fired up the set up wizard.

(*3) Why not the “LanguageSwitcher”? If you even wonder why I didn’t mention any of the settings related to “LanguageSwitcher” settings, it is because according to the commentating documentation: “# NOTE: The LanguageSwitcher settings are not frozen, meaning they might still change.” So, it means it is not stable yet, I think it is better to avoid it for now.

[…] Get Start a new eZ Publish project – Part I November 29th 2009 7:07am In the past I wrote a post briefly introduced the eZ Publish CMS In these two series post I will get into the technical details on how to actually start a new eZ Publish project We are going to set up a starting point of eZ Publish project named 8220Multiline8221 This project will contain two From: readtheweb.info […]

Thanks for this article, very interesting and to the point when beginning with ez publish.

If I may, I’d like to point you out on a user access problem I had.
In fact after everything’s set up, I had to modify the Anonymous Role policies and set “user – login – SiteAccess(any)”. And then it works like a charm.

Hi. yeah! That is the case for me too. We anonymous Role policies has to be changed if you have your own set of siteaccesses. Thanks for point that out!

By the way, we have figured out a way to manage SVN with various settings. In the end, only one file under the global override site.ini should be ignored out of the SVN for most normal projects. Maybe I can post an other article on how to do this. 🙂