[eZ publish] Get Start a new eZ Publish project--Two

URLTranslator
Right now, eZ Publish support three different url TransformationGroup:urlalias, urlalias_iri and urlalias_compat. The urlalias_iri is nicefor its utf-8 support. However, in reality, I found it sometimes causeproblems related to the image alias path. It also has something to dowith the Operate System file system. For every image, eZ Publish willgenerated the storage location according the path information of theimage in the node tree ( normally, under the media library top levelnode ) . If, for example, in the path to the actual image contains aparent node, such as a folder, whose name includes some specialcharacters ( this case is very common in French, since the letters like" ´,  é,  á"  are very common ), then, the resulting folder name in thefile system which will store the actual image will be in a mysteriousstate: depend on the OS file system character encode supportingsituation, the final folder name sit on the hard disk is more likelycontain some un-recognizable characters. And, if this is the case, whenthe eZ Publish system need read the image back in to show it inbrowser, it will not correctly decoding the path information for theimage. Tracking down this kind problem will cost much time, because youwill spend much time on the wrong direction and the actual cause is onthe other side of the wall.

 

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

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

[TemplateSettings]
TemplateCache=disabled
TemplateCompile=disabled
TemplateOptimization=disabled
TemplateCompression=disabled
DevelopmentMode=enabled

[ContentSettings]
ViewCaching=disabled
StaticCache=disabled

And of course we need to remember not to add this to a live site.

Template.ini.append.php
We have pretty much prepared the site access for now. Before we rushinto create the "Design Extension", let us make sure the templatecharacter 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 forour site access, we want to put the Design in extension. An extensionessentially can be mean just a sub folder under the /extension folder;just create a new folder under the extension folder and you canactivate it in the Administration Interface. Of course, an empty folderdoesn't do much; we need add some stuff to tell the system what ourextension has. In eZ Publish, every extension has similar folderstructure like the root of the eZ Publish; there is a "settings" folderfor 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

The system settings information reading order
In the end, the system read the settings information according to following order:
1. Default configuration settings (/settings/*.ini)
2. Active extension siteaccesses (/extension/*/settings/siteaccess/[name_of_siteaccess]/*.ini.append.php)
3. Siteaccesses (/settings/siteaccess/[name_of_siteaccess]/*.ini.append.php)
4. Active extensions (/extension/*/settings/*.ini.append.php)
5. Global overrides (/settings/override/*.ini.append.php)

Make a "Design Extension"

Here is how to make a "Design Extension":
.Create a folder named multiline in the extension folder, so we created an extension called "multiline".
.Create a folder named settings in the multiline folder we just created.
.Create a file named design.ini.append.php in the settings folder we just created.
.Open this newly created file, put the following information:

<?php /* #?ini charset="utf-8"?

[ExtensionSettings]
DesignExtensions[]=multiline

*/ ?>

Voila, we have a "Design Extension".  Well, we are not exactly finishedyet. What we have here is indeed a ready to go "Design Extension", butwe 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 designfolder: mybilingual and myindependent. This means we have two sitedesigns now. In each of the site design folder, it should housefollowing sub folders: images, javascript, stylesheets, templates and override;and it seems a conversion that under the override folder shoulddirectly exists a templates folder in which you will put your overridetemplates in.

The final step is to activate the extension;this can be done through the Administration Interface or edit thesite.ini.append.php directly. Through the Administration Interface, youcan activate an extension as system wide extension ( at theSetup->Extensions ); by edit the site.ini.append.php manually, youhave one more option to make an extension only available for a certainsite 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 overridesite.ini.append.php file, because the system would not know whichsiteaccess this extension is activated for. Just go to the site accessyou want to this extension available, and add this line to thecorresponded site.ini.append.php file.

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

<?php /* #?ini charset="utf-8"?

[mybilingual_site_settings]
root_node_id=66

[myindependent_site_settings]
root_node_id=77

*/ ?>

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

{def$mybilingual_root=fetch('content', 'node', hash('node_id',ezini("mybilingual_site_settings","root_node_id","multiline.ini.append.php")))}

Translation Extension
 
We should nowget the idea that to make an x extension is start from create asuitable *.ini.append.php file, fill in the correct settings, sort ofmake the extension declare itself to the system that it contains whatsort of functionalities ( such as design, translation, modules and soon ). So, to make a Translation Extension isno different, it is fairly simple: create a site.ini.append.php fileunder the /extension/multiline/settings folder, put this content in it:

<?php /* #?ini charset="utf-8"?
[RegionalSettings]
TranslationExtensions[]=multiline
*/ ?>

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, underthis folder. In eZ Publish, the default source language is eng-GB; soif you site English language is for United States, then you should,first make sure the American English language is added to the systemand 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 templateoverride rules. If you tried eZ Flow, you will know that in theextensions, it comes with their own set of override rules inoverride.ini.append.php under the extension's settings folder. Since wenow 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, theextension settings are filled at the global settings level, in thelocation: /extension/*/settings/*.ini.append.php; this might cause someconflict 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 extensioncan 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 relatedmaterial and template files.

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

If we adopt the Active extensionsapproach we can element this problem. However, more than often, we willhave different page layout for public site access home page. Since weactivated the extension as the system wide extension, after theoverride 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 willfilled up quickly since it tries to locate the override version of thetemplate, 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 pagesrendered unusable in the case another site design just happens providedan 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 Decompositionis always feasible, even though I found that move theoverride.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 filebefore start each project according the specific project needs isworthy doing only if the benefit of optimized arrangement of theconfiguration files exceedsthe trouble of adapting it. Generally, as in our example projects, wewill just follow the mainstream; put the override.ini.append.php andother 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 anddebug.css file. The core.css file contains a series of css rules forthe default templates in the standard design. The situation is that itgoverns 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 editorprovides a nicer interface to let you set the text format, such asalignment. In the source code the online editor generates, it actuallyadd a css class like "text-center" on the out html <p> tag. Inthe core.css file, there are rules like

p.text-center, td.text-center, th.text-center, *.text-center
{
text-align: center;
}

 

which will make the alignment work in the browser. The problem being,in most projects, we will have our own design specifically made for theclient requirements, and it most likely will not make use any of therules in the core.css file until we found that the online editor seemdoesn't work anymore. The same situation is on the debug.css, itcontains a set of  the css rules make the html table displaying thedebug information correctly. But, there are times the custom design'scss rule will not fit well with the debug css rules, just image what ifthe page background was set to black the you can't see any debug output information anymore because it is black text on black background.For the core.css situation, you can of course provide your own defaulttemplates for every imaginable xml tags, but it is not seempracticable. The solution is to provide you own default core.css anddebug.css file in our custom site design; we can just start from make acopy of the core.css and debug.css into the/extension/multiline/design/mybilingual/stylesheets/ and the/extension/multiline/design/myindependent/; then removing and modifyingthose css rules to make them live peacefully with our own custom designcss rules.