This series is a collaboration between the eZ Publications team and eZ Partners. Peter Keung from eZ Systems wrote the first article in the series. eZ Partners will write articles that build on the site developed in the first article, adding advanced functionality and explaining eZ Publish concepts and features.
Prerequisites
To follow this tutorial, you should have:
-
A newly installed version of eZ Publish 3.9.2 with the following settings:
- Primary language: English (American); secondary language: French (France)
- Site template: ezwebin (Website Interface)
- Site access configuration: URL
- Access to the (eZ Publish) files on the file system.
- Basic knowledge about HTML and CSS.
Installation documentation is available on the eZ Publish documentation site.
Keep in mind that the buttons and interfaces (and the resulting screenshots and procedures) will vary from those found in this article if you use a version other than eZ Publish 3.9.2 and the Website Interface 1.2. In most cases these variations will be minor and we encourage you to work with the latest version.
Scenario
Let's assume that you are in charge of creating a website for a tennis club appropriately called “eZ Tennis Club”. This is a community tennis club that wants to use its website to distinguish itself from other competing clubs. The site must serve the needs of local members but also include features that attract an international audience. The website must provide club information, worldwide tennis news, a webshop to sell tennis equipment and clothing and features that encourage community interaction.
The articles in this tutorial series will cover topics like basic setup and design tweaks; installing and using extensions; using RSS and workflows, and so on.
After installation, our eZ Publish site looks like this:
Default ezwebin site package skin
The first step is to apply a skin to make the visual elements of the site unique to our organization.
Applying a skin
In the article How to Skin an eZ Publish Now Site, Bertrand Maugain explained how to create a skin for an eZ Publish site. We will use the skin from that tutorial for our eZ Tennis site. To install the skin, follow these steps:
1. Download the skin package from the How to Skin an eZ Publish Now Site article.
2. Log in to the default Administration Interface siteaccess (in our case http://tennisdemo.ezsystems.ca/index.php/ezwebin_site_admin/) using the username and password that you specified during installation (in our case “admin” / “publish”)
3. Access the Setup tab, then click on the Packages link, then click on the Import new package button. Import the site package file downloaded in the first step via the web form.
4. Activate the skin through the Administration Interface by clicking on the Design tab, then clicking on the Look and Feel link, then clicking on the Edit button. Scroll down to the Sitestyle section and select “empower_enterprise”, then click the Send for publishing button at the bottom of the page. (Alternatively, log in to the Website Interface via the front-end of your site, then click on the Site settings link in the top right. Then, follow the same instructions as for the Administration Interface.)
The site should now look like this:
Site with a new skin
Site settings during development
During development, it is useful to enable the debug output feature. This is done in the [DebugSettings] section in an INI file, as explained below. Debug output is a built-in mechanism in eZ Publish that provides detailed information for troubleshooting. Debug output provides valuable information about response time, SQL queries, template processing and more. (When developing designs, it is recommended that you disable debug output.)
During development, it is also useful to disable the template caching and view caching features of eZ Publish (which improve performance on live sites by storing and reusing template code and XHTML output). This is done in the [TemplateSettings] and [ContentSettings] sections in an INI file, as explained below. During development, it is preferable to force complete page regeneration in order to instantly see the effects of site changes. Otherwise, you must manually clear the caches whenever you make a change during the development process. To manually clear the caches, either use the Clear cache window on the right side of the Administration Interface or purge the var/cache and /var/example/cache directories (where "example" is the name of a siteaccess).
Site settings are stored in INI files located in the settings/ folder of eZ Publish. When you change a setting in an INI file, you should use an override file and leave the original INI file intact. Override files work on two levels – global overrides (in the settings/override/ folder) and siteaccess overrides (in the settings/siteaccess/[name_of_siteaccess] folder). Both types of overrides have the file name of the original INI file with “.append.php” appended to the file name.
eZ Publish reads basic settings from the original INI files, which are overriden by any settings in the specific siteaccess overrides, which are overridden by settings in the global override files. The illustration below shows the override order for the main site settings INI file:
Site settings override order
In our case, we want to override settings for all siteaccesses, so we will edit settings/override/site.ini.append.php.
Open settings/override/site.ini.append.php in a text editor and add the following code above the last line of the file:
[DebugSettings]
DebugOutput=enabled
[TemplateSettings]
TemplateCache=disabled
[ContentSettings]
ViewCaching=disabled
Remember to disable the debug output and re-enable the template caching and view caching when your site goes live.
By default, eZ Publish URLs are constructed by using the domain name, then appending “index.php”, then appending the siteaccess name (which is often a language indicator), and finally appending the path to a specific node.
For more user-friendly URLs when using the URL site access configuration (used in our example as stated in the introduction*), you can remove the “index.php” from all addresses, provided that you are using the default mod_rewrite settings in your Apache .htaccess file and that mod_rewrite is enabled in your Apache httpd.conf file.
(*The URL site access configuration is the quickest and easiest site access configuration to set up, which is why it is used in this article. However, the virtual host site access configuration is recommended as the most secure option, as explained in the documentation. In the virtual site access configuration, each siteaccess can be assigned an individual hostname, such as admin.tennisdemo.ezsystems.ca for the admin siteaccess, and "index.php" is already omitted from the site-generated URLs.
In settings/override/site.ini.append.php, add the following code under the [SiteAccessSettings] block:
ForceVirtualHost=true
By default, eZ Publish URLs include a language indicator. To remove the language part of the URL for the default siteaccess, add the following code under the same [SiteAccessSettings] block:
RemoveSiteAccessIfDefaultAccess=enabled
Now, instead of http://tennisdemo.ezsystems.ca/index.php/eng/solutions as the address for a top-level page, it is http://tennisdemo.ezsystems.ca/solutions, which is much easier for visitors to remember.
The French siteaccess is named “fre” by default. For our purposes, we will rename it to “fr” as that is shorter and easier for visitors to remember. To do so, we must make four modifications:
- Rename the folder /settings/siteaccess/fre to /settings/siteaccess/fr
Modify the reference to the French siteaccess in settings/override/site.ini.append.php in two places:
[SiteAccessSettings]
AvailableSiteAccessList[]=fr
[SiteSettings]
SiteList[]=fr
You must also modify the related siteaccess list in each of the siteaccesses' site.ini.append.php files, such as settings/siteaccess/eng/site.ini.append.php. The related siteaccess list is used by the view caching mechanism to clear the cache of all related siteaccesses that share the same database, whenever a content object is created or updated.
[SiteSettings]
RelatedSiteAccessList[] = fr
(If all of your siteaccesses use the same database, as is the case in this example, you can enter the list of all siteaccesses in RelatedSiteAccesstList[] in settings/override/site.ini.append.php, which will negate the need to edit the INI file each individual siteaccess.)
- Modify the anonymous user access permissions in the Administration Interface.Access the User accounts tab, then click on the Roles and policies link on the left menu. Edit the role for the Anonymous user, then edit the user/login policy that is now blank, in order to add the new siteaccess name “fr”. Click the OK button to save your changes.
- Edit the Anonymous role
- Edit the top left language links. We will describe this later in this article, as these links are currently hidden in our imported site design.
We will also rename the Administration Interface siteaccess to make it easier for site administrators and editors to remember. To do so, we must perform the same first two steps from when we renamed the French siteaccess, but change “ezwebin_site_admin” to “tennis_admin”.
There is an additional setting that must be changed in the site.ini.append.php file for both the English and French siteaccesses (in settings/siteaccess/eng/ and settings/siteaccess/fr/). Under the [SiteSettings] block is the setting for the form redirection whenever someone logs in through the front-end of the site and marks the Log in to the eZ Publish Administration Interface checkbox.
This setting must be changed in site.ini.append.php for both language siteaccesses:
AdditionalLoginFormActionURL=http://tennisdemo.ezsystems.ca/index.php/ezwebin_site_admin/user/login
Remove the “index.php” part of the URL and rename the Administration Interface siteaccess as is appropriate:
AdditionalLoginFormActionURL=http://tennisdemo.ezsystems.ca/tennis_admin/user/login
We will now perform some minor tweaks to the appearance of the site. These modifications are a simple introduction to the template system and the CSS organization in eZ Publish.
Adding a link to the home page on the horizontal menu bar
By default, clicking on the company logo on any page brings visitors to the site’s home page. However, for added browsing convenience, we will add a link to the home page on the horizontal menu bar.
To do so, we must first add a link object in the root of our content node tree through either the Website Interface or the Administration Interface. Enter “Home” for the name and “/” for the URL. After publishing the link, we must add the Link class to the list of allowed classes on the top menu. This is found in settings/override/menu.ini.append.php:
[MenuContentSettings]
TopIdentifierList[]
TopIdentifierList[]=folder
TopIdentifierList[]=feedback_form
TopIdentifierList[]=gallery
TopIdentifierList[]=forum
TopIdentifierList[]=article
TopIdentifierList[]=frontpage
TopIdentifierList[]=link
The link now appears on the horizontal menu bar, but is in the middle of the items:
Home link in the middle of the menu
To move the Home link to the far left, set its priority level in the Administration Interface to be lower than all of the other top-level objects.
Update priority levels
The link now appears first on the left, but we must make one final modification. Notice that if you click on the “Home” link on the top menu, it opens in a new window or tab. The desired behavior is for it to open the home page in the same window or tab.
We must locate the appropriate template that generates the XHTML for the horizontal menu bar. We will begin our search by examining the pagelayout template. The pagelayout is the main template that dictates the overall look of the site. For the Website Interface, the pagelayout template is located at /extension/ezwebin/design/ezwebin/templates/pagelayout.tpl
Within pagelayout.tpl, notice the following code, which indicates where the code for the top menu is located:
<div id="topmenu">
{include uri='design:menu/flat_top.tpl'}
</div>
In flat_top.tpl, we find the following code, which populates the menu item if it is an object of the Link class:
<li id="node_id_{$item.node_id}"{if $item_class} ")}"{/if}><div><a href={if eq( $ui_context, 'browse' )}{concat("content/browse/", $item.node_id)|ezurl}{else}{$item.data_map.location.content|ezurl}{/if} target="_blank"{if eq( $ui_context, 'edit' )} onclick="return false;"{/if}>{$item.name|wash()}</a></li>
We remove target=”_blank”, which caused the Home link to open in a new window.
Adding a logo
We will replace the “COMPANYLOGO” image that appears on every page with our eZ Tennis logo:
eZ Tennis Club logo
We can upload the new logo in the Site settings page in the Website Interface. However, the system will automatically resize the image to a size that is smaller than we would like. Therefore, we must change the setting that controls how much eZ Publish will scale down the image.
In settings/eng/image.ini.append.php and settings/fr/image.ini.append.php, change the [logo] block to be as follows:
[logo]
Reference=
Filters[]
Filters[]=geometry/scaledownonly=199;74
Now we can upload the logo as described and it will be resized as indicated.
CSS modifications
After changing the default size of the logo, our top menu needs to be moved down slightly. This is accomplished by editing one of the CSS files from the skin site package in /var/storage/packages/local/empower_enterprise/files/default/file.
By looking at the XHTML page source (by selecting "View... Page Source" in Firefox, or a similar function in other browsers), we see that the top menu is contained in a div called “topmenu”. As a result, we must locate the CSS file that dictates the style for that div.
As was explained in the article How to Skin an eZ Publish Now Site, site-colors.css overrides the styles for the global pagelayout (not related to content), and classes-colors.css overrides the styles specifically related to content classes.
Therefore, we will edit site-colors.css and remove the “margin-top” style in the topmenu div:
div#topmenu
{
margin-top: -20px;
padding-left: 0.5em;
background-color: #FFFFFF;
}
Also, as mentioned earlier, the language links are hidden in this skin. We will reveal them by removing the section in site-colors.css that refers to the languages div (which can also be identified in the XHTML page source):
div#languages
{
background-image: none;
display: none;
}
Changing the URL for the language links
Now that the language links are shown in the top left of the page, we must update them to reflect the siteaccesses that we simplified earlier. This can be done in the Look and feel page in the Design tab of the Administration Interface or on the Site settings page of the Website Interface.
The site URLs should be “tennisdemo.ezsystems.ca” and “tennisdemo.ezsystems.ca/fr”; siteaccesses should be “eng” and “fr”; and, the language names can remain the same, as they represent the text displayed for each link. You can optionally change the French language name to “Fr” to be consistent with the renamed siteaccess.
Edit the language links
Note that you must make these changes in both the French and English siteaccesses. In the Administration Interface, this means that you must edit the Look and feel page in both French and English. In the Website Interface, this means that you must access the Site settings page via both the French and English siteaccesses.
The last step required in our setup is to add the base content for the front page of our tennis site! The main content modifications we made are:
- Changed the banner
- Added some relevant news for the section on the right
- Added some relevant photos for the gallery
- Edited the introductory text directly below the banner
- Removed the content below the photos
All of the content modifications were made by adding or editing content objects through the Website Interface or Administration Interface.
The screenshot below shows the result:
Site after content modifications
In this article, we have begun to set up the fictional eZ Tennis Club site using eZ Publish. You should now have some experience using the following eZ Publish elements:
- Website Interface
- Administration Interface
- INI settings files
- Template files
- CSS files
- Site packages (importing a new skin)
Subsequent articles in this tutorial series will explain how to make use of RSS to syndicate content from other websites, how to add an extension and more!
References