.. _site.ini [ExtensionSettings] ActiveAccessExtensions: http://ez.no/doc/ez_publish/technical_manual/3_10/reference/configuration_files/site_ini/extensionsettings/activeaccessextensions
.. _site.ini [ExtensionSettings] ActiveExtensions: http://ez.no/doc/ez_publish/technical_manual/3_10/reference/configuration_files/site_ini/extensionsettings/activeextensions
.. _site.ini [DesignSettings] SiteDesign: http://ez.no/doc/ez_publish/technical_manual/3_10/reference/configuration_files/site_ini/designsettings/sitedesign
.. _site.ini [DesignSettings] AdditionalDesignList : http://ez.no/doc/ez_publish/technical_manual/3_10/reference/configuration_files/site_ini/designsettings/additionalsitedesignlist
.. _site.ini [DesignSettings] StandardDesign: http://ez.no/doc/ez_publish/technical_manual/3_10/reference/configuration_files/site_ini/designsettings/standarddesign

=================
Current situation
=================

Currently, there are three different orders in which the design directories are search through for design elements:

- $tpl->fetch( 'design:template.tpl' ); and {include "template.tpl"}
- {stylesheets/style.css'\|ezdesign} in templates
- {'image.jpg'\|ezimage} in templates

The following settings play a role:

- `site.ini [ExtensionSettings] ActiveExtensions`_
- `site.ini [ExtensionSettings] ActiveAccessExtensions`_
- site.ini [ExtensionSettings] DesignExtensions, extensions are supposed to add themselves to this list in their own settings/site.ini.append.php if they contain design
- `site.ini [DesignSettings] SiteDesign`_, further referred to as SiteDesign
- `site.ini [DesignSettings] StandardDesign`_, further referred to as StandardDesign
- `site.ini [DesignSettings] AdditionalDesignList`_: whenever we mention "for each additional design" further in this document, it will be in the order as in this setting, unless explicitly mentioned otherwise.

The site.ini [ExtensionSettings] DesignExtensions setting is used to retrieve a list of the enabled design extensions. However, be aware that the extensions in [ExtensionSettings] ActiveAccessExtensions[] are listed there first, in **reverse** order, and the extensions in [ExtensionSettings] ActiveExtensions come afterwards, as well in **reverse** order. When we refer to "for each design extension" further in this document, it will be in another order, which is considered as the correct order: the **reverse** of [ExtensionSettings] DesignExtensions.

$tpl->fetch()
-------------

$tpl->fetch(...) finally uses the priorities of design directories as coded in eZTemplateDesignResource::overrideArray(), which is the following (from higher to lower priority, please note that the reverse order is used in eZTemplateDesignResource::overrideArray() because all templates need to be searched for on the file system):


1) for each design extension:

   a) SiteDesign in extension
   b) SiteDesign override in extension
   c) for each additional design:

      1) additional design in extension
      2) additional design override in extension

   d) StandardDesign override in extension
   e) StandardDesign in extension
2) SiteDesign
3) SiteDesign override
4) for each additional design:

   a) additional design
   b) additional design override
5) StandardDesign override
6) StandardDesign

As you can see, there are some inconsistencies:

- normal templates can be placed in override directory, and override templates can be placed in normal directory
- StandardDesign's override is used first instead of normal templates
- additional design and StandardDesign in extensions have more priority than SiteDesign in main design folder

There's a cache, "enabled" or disabled by site.ini [OverrideSettings] Cache setting. The path to the finally used templates (base_dir and template key in the cached array) will be cached in this cache file when it is enabled, regardless if there are overrides defined or not. Override settings, including path to the finally used template, are also cached in this cache file (custom_match key in the cached array). The way how override templates are currently searched for is not optimal, because it will do a file_exists starting from the design directory with lowest priority and keep doing this until the design directory with the highest priority. It should start with design directory with highest priority so the loop can stop as soon as a matching template has been found, and the order of 'tried files' in debug output will then be correct as well.


ezdesign
--------

ezdesign uses the order as coded in eZTemplateDesignResource::fileMatchingRules() (called in eZURLOperator::modify()), which is the following (from higher to lower priority):

1) for each design extension in **reverse** order:

   a) SiteDesign override in extension
2) SiteDesign override
3) for each additional design:

   a) for each design extension in **reverse** order:
      additional design override in extension
   b) additional design override
4) for each design extension in **reverse** order:
   StandardDesign override in extension
5) StandardDesign override
6) for each design extension in **reverse** order:
   SiteDesign in extension
7) SiteDesign
8) for each additional design:

   a) for each design extension in **reverse order**:
      additional design in extension
   b) additional design
9) for each design extension in **reverse order**:
   StandardDesign in extension
10) StandardDesign

ezdesign does not uses any type of caching, it uses eZOverride::selectFile() (kernel/common/ezoverride.php), which uses an old-style overriding mechanism by inserting design keys and values ( "_$matchKeyName" . "_$matchKeyValue" ) in the file name right before the file extension suffix and doing a file_exists (it does this only in the override directories, not for the normal design directories).


ezimage
-------

ezimage uses the order as coded in eZTemplateDesignResource::allDesignBases() (called in eZURLOperator::modify()), which is the following (from higher to lower priority):

1) SiteDesign
2) for each design extension in **reverse** order:
   SiteDesign in extension
3) for each additional design:

   a) additional design
   b) for each design extension in **reverse** order:
      additional design in extension
4) StandardDesign
5) for each design extension in **reverse** order:
   StandardDesign in extension

ezimage does not use any type of caching, it uses its own code to loop over the design directories and do a file_exists call for every image it needs to include (also when the same was included before in the same page load). Overrides are not possible.


================
Proposed changes
================

Overrides can only be placed in override/templates, not in templates,
and normal templates only in templates, not in override/templates.

The 1 and only correct order used for $tpl->fetch, ezdesign and ezimage
will be:

1) for each design extension: SiteDesign in extension
2) SiteDesign
3) for each additional design:

   a) for each design extension: additional design in extension
   b) additional design
4) for each design extension: StandardDesign in extension
5) StandardDesign

Obviously, template overrides also use this order.

The file name based ezdesign override possibility will be removed completely. There won't be a possibility to override elements handled by ezdesign or ezimage. This can be added later.