Get Start a new eZ Publish project – Part II

In the part I, we started create the siteaccesses and set all the configuration values for the siteaccesses to work correctly. However, there are still other things to do, such as set up and configure the site design and svn version control tool for the project. So, let’s continue.

Before we dig into how to set up a design extension, we have a little bit setting to do in the template.ini.append.php file. Let us make sure the template character set is in correct setting.
In the global site access override file template.ini.append.php, make sure this exists:
[CharsetSettings]
DefaultTemplateCharset=utf-8

Design Extension
Recall when we set up the SiteDesign for our site access, we want to put the Design in extension. An extension essentially can be mean just a sub folder under the /extension folder; just create a new folder under the extension folder and you can activate it in the Administration Interface. Of course, an empty folder doesn’t do much; we need add some stuff to tell the system what our extension has. In eZ Publish, every extension has similar folder structure like the root of the eZ Publish; there is a “settings” folder for example.

Extension settings
There is a missing documentation which resides in the comments of online eZ Publish technical manual: http://ez.no/doc/ez_publish/technical_manual/4_x/concepts_and_basics/configuration/site_management.

1.The system settings information reading order
In the end, the system read the settings information according to following order:

Voila, we have a “Design Extension”. Well, we are not exactly finished yet. What we have here is indeed a ready to go “Design Extension”, but we don’t have the site design yet. What we can do now is that we can create a “design” sub folder in the multiline extension folder; then this folder has the same privilege as the “design” folder under the root of the eZ Publish.

Create the two sub directories in this design folder: mybilingual and myindependent. This means we have two site designs now. In each of the site design folder, it should house following sub folders: images, javascript, stylesheets, templates and override; and it seems a conversion that under the override folder should directly exists a templates folder in which you will put your override templates in.

The final step is to activate the extension; this can be done through the Administration Interface or edit the site.ini.append.php directly. Through the Administration Interface, you can activate an extension as system wide extension ( at the Setup->Extensions ); by edit the site.ini.append.php manually, you have one more option to make an extension only available for a certain site access.

For activate the system wide extension, add these code in the global override: /settings/override/site.ini.append.php file [ExtensionSettings] section:

in [ExtensionSettings] section:ActiveExtensions[]=multiline

For activate the extension for a specific site access, you need add this line instead, not in /settings/override/site.ini.append.php this time:

still in [ExtensionSettings] section:ActiveAccessExtensions[]=multiline

And there is no point to add this to the global override site.ini.append.php file, because the system would not know which siteaccess this extension is activated for. Just go to the site access you want to this extension available, and add this line to the corresponded site.ini.append.php file.

There are pros and cons for each of these two options regarding set the extension settings, especially on the override.ini.append.php settings. See Extension configuration files considerations section of this article. For our example project, I will activate the extension as the system wide extension just for the convenience of the administrator.

3.Test your Design Extension
We have done a lot of settings changes, so if you didn’t ever clear your cache yet. Do it now. To test your Design Extension to see if it is correctly set up, create a template file, pagelayout.tpl under the site design’s templates folder. Put this line in the pagelayout.tpl:

{$module_result.content_info|attribute(show,1)}

Open your browser to access the web site, www.mybilingual.com and www.myindependent.com. If everything goes well, you should see a list of out put indicating the current node ( which is the root node for the current web site, such as the mybilingual or myindependent ) been viewing. Verify that the node_id is the correct root node id you wrote done before. And, at the bottom of the debug info on a series listed templates, verify the loaded pagelayout.tpl template file is the correct one.

Extension configuration files considerations
As we see now that under the extension settings folder, it can contain all the legitimate configuration files, such as site.ini.append.php, design.ini.append.php, override.ini.append.php and so on.

4.A setting file for the extension its own
Often, most of your work on a project will reside in one extension. There would be the case that you need some special configuration value for this project, a special node id should be recorded for example; this kind information better to put into a centralized configuration file. The good news is that you can just make your own a new configuration file just for the extension.

Create a file named, multiline.ini.append.php file. If you want it can be accessed from Administrator Interface ( at Setup=>Ini settings ), put it in the /settings/override/ folder; otherwise, you can just put it in the /extension/multiline/settings/ folder.

For example, since in our project, the root node for public site is not the top level content tree root node anymore, we may want to record the root node id in this configuration file like this:< ?php /* #?ini charset="utf-8"?
[mybilingual_site_settings]
root_node_id=66
[myindependent_site_settings]
root_node_id=77
*/ ?>

Assume the root node ids for the two separately site access are 66 and 77 respectively. Later on in your template code, you can get the value like this:

Translation Extension
We should now get the idea that to make an x extension is start from create a suitable *.ini.append.php file, fill in the correct settings, sort of make the extension declare itself to the system that it contains what sort of functionalities ( such as design, translation, modules and so on ). So, to make a Translation Extension is no different, it is fairly simple: create a site.ini.append.php file under the /extension/multiline/settings folder, put this content in it:

Save the file, clear the cache and you are done. Make a folder translations under the /extension/multiline/ folder, and for each language code ( to be precise, the IETF language tag ), create a sub folder using the code as the folder name, for example, fre-FR for French, and put the translation file, translation.ts, under this folder. In eZ Publish, the default source language is eng-GB; so if you site English language is for United States, then you should, first make sure the American English language is added to the system and create a translation for the U.S. English; if you don’t create the translation language file, the system will fall back to the eng-GB version.

The override.ini.append.php
The all important override.ini.append.php file houses the template override rules. If you tried eZ Flow, you will know that in the extensions, it comes with their own set of override rules in override.ini.append.php under the extension’s settings folder. Since we now have the knowledge of The system settings information reading order as outlined above, we know that extension settings can including Active extension siteaccesses settings ( at priority order 2 ) or Active extensions settings ( at priority order 4 ). The important thing is that normally, the extension settings are filled at the global settings level, in the location: /extension/*/settings/*.ini.append.php; this might cause some conflict with the normal site access settings under the /settings/siteaccess/[name_of_siteaccess]/*.ini.append.php.

In the case that you want to provide override templates for the Administration Interface, and also provide your own design for your public site access, it is no problem; an design extension can contain many site designs, you just create a series designs in the “design” folder, in this case, you just create the folders of admin, mybilingual and myindependent, which will house all your design related material and template files.

There are two considerations here: Decomposition and Maintenance. Decomposition means that we want our extension decoupled from other components of the system, so an extension is a single unit on it own, which leads to the desire that if a design extension requires a set of the template override rules in the override.ini.append.php to work, it should be placed in the extension settings folder, which has two possible ways to put them according the system settings information reading order section of this article, the Active extension siteaccesses settings and the Active extensions settings . Maintenance means we want to keep everything in order, especially come to the eZ Publish configuration files. By default, the override.ini.append.php files are under each of the site access folder; most of the time, we just have different language site access using the same site design, this means we need duplicate the exact override.ini.append.php file for each of the language site access and keep tracking and updating them during development.

If we adopt the Active extensions approach we can element this problem. However, more than often, we will have different page layout for public site access home page. Since we activated the extension as the system wide extension, after the override rule take effect on home page of the system, the public site will look nice ,but when you log into the Administration Interface, the best thing will happen is that the system error log file will filled up quickly since it tries to locate the override version of the template, the worst thing will happen if your Administration Interface site access has additional site designs to fall back to, there may be countless Administration Interface pages rendered unusable in the case another site design just happens provided an override version of a template loaded according the override rule.

So, it seems sometimes hard to achieve both Decomposition and Maintenance; use the Active extension siteaccesses settings we can achieve the Decomposition purpose nicely, but we still need to maintain multiple copies of the same override.ini.append.php files. At least the goal of Decomposition is always feasible, even though I found that move the override.ini.append.php file out of the main settings folder, the /settings/siteaccess/ folder, might require some time to get used to.

Take some considerations on how to set up the extension settings file before start each project according the specific project needs is worthy doing only if the benefit of optimized arrangement of the configuration files exceeds the trouble of adapting it. Generally, as in our example projects, we will just follow the mainstream; put the override.ini.append.php and other configuration files in the /settings/siteaccess/ folder.

The core.css and the debug.css
There is another issue related to the design, that is the core.css and debug.css file. The core.css file contains a series of css rules for the default templates in the standard design.

The situation is that it governs the styles set by the online editor; for example, in the Administrator Interface, when you edit an article field of xml block type, the online editor provides a nicer interface to let you set the text format, such as alignment. In the source code the online editor generates, it actually add a css class like “text-center” on the out html

which will make the alignment work in the browser. The problem being, in most projects, we will have our own design specifically made for the client requirements, and it most likely will not make use any of the rules in the core.css file until we found that the online editor seem doesn’t work anymore. The same situation is on the debug.css, it contains a set of the css rules make the html table displaying the debug information correctly. But, there are times the custom design’s css rule will not fit well with the debug css rules, just image what if the page background was set to black the you can’t see any debug out put information anymore because it is black text on black background. For the core.css situation, you can of course provide your own default templates for every imaginable xml tags, but it is not seem practicable. The solution is to provide you own default core.css and debug.css file in our custom site design; we can just start from make a copy of the core.css and debug.css into the /extension/multiline/design/mybilingual/stylesheets/ and the /extension/multiline/design/myindependent/; then removing and modifying those css rules to make them live peacefully with our own custom design css rules.

SVN set up
Ok now, our task of preparing the eZ Publish system ready for our new project is pretty much finished; before we really start the development business, there is one more step: put everything in to a version control system because in reality, an eZ Publish project probably is an enterprise portal site or some like that, we probably have a team of developers work on each project ( even thought you are the only one, we still want everything nice and clean right? ). In our project, we will use the SVN version control system.

There is already countless discuss on how to set up and use a SVN repository; on the eZ Publish front, there is an excellent article, Using Subversion with eZ Publish If you read the article, basically, there seem no good ways to manage the environment related settings file, particularly, the site.ini.append.php files. So, my suggestion is to ignore these files in SVN.

This is article, I will not waste time on introduce the basic concept of SVN. I assume that we will only concern the trunk of the repository, our proejct located at /var/www/multiline/, and the url to the project trunk is, https://www.yousvnserver.com/ezpublish/multiline/trunk/.

About Database backup strategy
One special note I want to make is that the database is not under the version control. But, it doesn’t mean we shouldn’t make the backup of the database often. I think, there are two possible ways to do:

1.Use the traditional, or normal, or existing backup strategy to take care of the database. For example, on the database server, there are backups for everyday.

The pros for this are that, we don’t need to think about if the task on the hand will be impact on the database.
The cons for this are that it doesn’t have the version control advantage. The backup of the database depend on the time at which the backup made, not depend on at which task changes made to the database.

2.Also use the version control to manage the backups of the database.
The pros for this are: everything, including the database, is in the repository.
The cons are:
A. There is actually no simple way to do it. One possible way is that every time we export the database out, and then store it under some folder (maybe the doc folder under the eZ Publish root). Afterward, you should remember to commit in the database backup file into the repository.
B. The developer should have knowledge to decide when is appropriate to export the database, which is different from person to person.
But, database backup is very important. Here is what I think when you should backup the database:

Before doing class definition changes in the backend — for some critical class, and the template for this class is already exists.

Before importing something use the package file through the backend. There is a standard way for importing and exporting data from the eZ Publish: use the packages. You can actually create & export a package for class definitions, content objects, and extensions.

Before run the php scripts under the bin/php. For example, before run the updateniceurls.php script.

When install some third-party extensions. Read the install or readme file, if it needs backup the database, backup the database.

3. About the “var” Folder
Now, we are normally put the “var” folder, under version control. Whether or not this folder should put in version control can be discussed in the future: for example, for my point view, I would strongly recommend today not storing the var directory in Subversion at all; but if you have a separated web test team and they need input test content to test the implemented template file with the same database, it means they will need always create/edit all the content they test.

There is also a good extension called ezsvn can be used for SVN management. It will always update the eZ Publish system to the latest/HEAD version of the official trunk. This means it is ensured that the currently system is up-to-date, but not the official release stable version. And, also, the extension will require special server configuration and server arrangement. Take considerations for yourself to see if this is suit for your project(s).

Okay! In these two articles, we have walked through the initialization of a new eZ Publish project. We are looked mainly how to configure the site.ini.append.php file to make a mutli language, multi sub sites work under single eZ Publish installtion; we learned how to create design extensions and initialize the SVN version control system.Alone the way, I have also posted some questions and considerations for other situations which may arise in different projects. After read this article, new users come to eZ Publish should have a fairly firm ground on get start an new eZ Publish project.

(*4) On *nix server, if any abnormal things happens, trying to check the files permission on the file system, especially check if the web server has the read permission on the settings file and has the write permission to “var” folder files.