Solution: Overriding the eZ Web Interface (ezwebin) with custom designs

The original source for most of this material comes from a blog post by an eZ publish developer.

If you've installed 3.9.0 with the eZ Web Interface (hereinafter referred to as ezwebin) but need to customize your siteaccess to differ from the demo design, your first step is to get your hierarchies organized to override the default ezwebin design on a per-siteaccess basis.

Note: pay careful attention to order of ActiveExtensions in following two examples. In case of CSS your extension has to be listed below ezwebin, but for templates above it.

To Modify CSS (Without Modifying Templates)

1. Go to your /extension/directory and replicate the structure of ezwebin for your own design name. For example, if your siteaccess is "my_siteaccess" and your desired design is "my_design" then you'll create a structure as follows:

extension
| -ezwebin
| -my_design
| | -- design
| | | --- ezwebin
| | | |---- images
| | | |---- stylesheets
| | | |---- templates
| | -- settings

Note that you want to leave the original ezwebin directory intact, but merely mimic its' structure. Also, note that in the my_design/design directory, the correct name of the child is ezwebin (for 3.9.0) as this is where your CSS overrides will be placed and seen by the system.

2. Next, you'll want to initialize your design in the system. Go to extension/my_design/settings/ and create a new file named "design.ini.append.php" Inside, specify the following settings:

<?php /*
[ExtensionSettings]
DesignExtensions[]=my_design
*/ ?>

3. Now is the best time to copy the CSS files and templates from extension/ezwebin/design/ezwebin into your newly created extension/my_design/design/ezwebin so you can modify their contents to suit your design needs.

4. Next, you'll need to make the system aware that your new "extension" (conceptually) exists. To do that, go to settings/override/site.ini.append.php and open it for editing. Find the section for [ExtensionSettings] and active your extension LAST (in order) as follows:

[ExtensionSettings]
ActiveExtensions[]
ActiveExtensions[]=ezwebin
ActiveExtensions[]=ezdhtml
ActiveExtensions[]=ezodf
ActiveExtensions[]=my_design

5. Last, you'll need to edit the settings/siteaccess/my_siteaccess/site.ini.append.php to make it aware that your extension design exists. Add your design FIRST (in order), although it may seem a little counter-intuitive at first glance.

[DesignSettings]
SiteDesign=my_design
AdditionalSiteDesignList[]=ezwebin
AdditionalSiteDesignList[]=base

6. You're done. Login to your Admin view and clear *all* cache. Voila, your new CSS files will be used.

NOTE: At this time, there appears to be a bug. CSS file are honored by the system (but templates are currently not honored).

To Modify Templates (Without Modifying CSS)

1. Go to your /extension/directory and replicate the structure of ezwebin for your own design name. For example, if your siteaccess is "my_siteaccess" and your desired design is "my_design" then you'll create a structure as follows:

extension
| -ezwebin
| -my_design
| | -- design
| | | --- ezwebin
| | | |---- images
| | | |---- stylesheets
| | | |---- templates
| | -- settings

Note that you want to leave the original ezwebin directory intact, but merely mimic its' structure. Also, note that in the my_design/design directory, the correct name of the child is ezwebin (for 3.9.0) as this is where your TPL overrides will be placed and seen by the system.

2. Next, you'll want to initialize your design in the system. Go to extension/my_design/settings/ and create a new file named "design.ini.append.php" Inside, specify the following settings:

<?php /*
[ExtensionSettings]
DesignExtensions[]=my_design
*/ ?>

3. Now is the best time to copy the CSS files and templates from extension/ezwebin/design/ezwebin into your newly created extension/my_design/design/ezwebin so you can modify their contents to suit your design needs.

4. Next, you'll need to make the system aware that your new "extension" (conceptually) exists. To do that, go to settings/override/site.ini.append.php and open it for editing. Find the section for [ExtensionSettings] and active your extension ABOVE ezwebin (in order) as follows:

[ExtensionSettings]
ActiveExtensions[]
ActiveExtensions[]=ezdhtml
ActiveExtensions[]=ezodf
ActiveExtensions[]=my_design
ActiveExtensions[]=ezwebin

5. Last, you'll need to edit the settings/siteaccess/my_siteaccess/site.ini.append.php to make it aware that your extension design exists. Add your design FIRST (in order), although it may seem a little counter-intuitive at first glance.

[DesignSettings]
SiteDesign=my_design
AdditionalSiteDesignList[]=ezwebin
AdditionalSiteDesignList[]=base

6. You're done. Login to your Admin view and clear *all* cache. Voila, your new TPL files will be used.

NOTE: At this time, there appears to be a bug. TPL file are honored by the system (but stylesheets are currently not honored).

To Modify Both CSS and Templates (Special Case)

You must consider your implementation of eZ publish. This workaround is valid if 1) you have only one frontpage/user view (non-admin view) siteaccess OR 2) if all your frontpage/user view (non-admin view) siteaccesses will use the CSS changes. This work around is not valid if you have multiple siteaccesses which must use different stylesheets.

The strategy here is to setup template overrides in the method recommended by eZ Systems, then to craft a workaround so CSS overrides are used (across all non-admin siteaccesses).

1. Go to your /extension/directory and replicate the structure of ezwebin for your own design name. For example, if your siteaccess is "my_siteaccess" and your desired design is "my_design" then you'll create a structure as follows:

extension
| -ezwebin
| -my_design
| | -- design
| | | --- ezwebin
| | | |---- images
| | | |---- stylesheets
| | | |---- templates
| | -- settings

Note that you want to leave the original ezwebin directory intact, but merely mimic its' structure. Also, note that in the my_design/design directory, the correct name of the child is ezwebin (for 3.9.0) as this is where your TPL overrides will be placed and seen by the system.

2. Next, you'll want to initialize your design in the system. Go to extension/my_design/settings/ and create a new file named "design.ini.append.php" Inside, specify the following settings:

<?php /*
[ExtensionSettings]
DesignExtensions[]=my_design
*/ ?>

3. Now is the best time to copy the CSS files and templates from extension/ezwebin/design/ezwebin into your newly created extension/my_design/design/ezwebin so you can modify their contents to suit your design needs.

4. Next, you'll need to make the system aware that your new "extension" (conceptually) exists. To do that, go to settings/override/site.ini.append.php and open it for editing. Find the section for [ExtensionSettings] and active your extension ABOVE ezwebin (in order) as follows:

[ExtensionSettings]
ActiveExtensions[]
ActiveExtensions[]=ezdhtml
ActiveExtensions[]=ezodf
ActiveExtensions[]=my_design
ActiveExtensions[]=ezwebin

5. Last, you'll need to edit the settings/siteaccess/my_siteaccess/site.ini.append.php to make it aware that your extension design exists. Add your design FIRST (in order), although it may seem a little counter-intuitive at first glance.

[DesignSettings]
SiteDesign=my_design
AdditionalSiteDesignList[]=ezwebin
AdditionalSiteDesignList[]=base

6. Place your modified CSS files in extension/my_design/design/ezwebin/override/stylesheets (reminder: this will affect all your non-admin siteaccesses which use the eZ Web Interface).

7. Place any images need by your CSS files into extension/my_design/design/ezwebin/overrides/images

8. You're done. Login to your Admin view and clear *all* cache. Voila, both your new TPL files and your new CSS will be used on all siteaccesses which use the ezwebin (eZ Web Interface).

To Modify Both CSS and Templates (Universal Method)

There is not currently a verified workaround strategy which will allow targeting of individual siteaccesses for both modified CSS and Templates. The bug report contains some suggested methods, but they are not yet verified as working (please note eZ Systems has asked no further discussion on the bug report itself, so please discuss this issue either on the eZ forums or IRC (Freenode #ezpublish).