root/plugins/ysfDimensionsPlugin/branches/1.0/README

= ysfDimensionsPlugin =

ysfDimensionsPlugin allows you to customize the behavior of your symfony application based on any runtim factors.  You can adjust the configuration, template selection, and action behavior based on a combination of dimensions chosen by you.  For instance, you can have a different navigation structure based on the country of the user or a cobrand, or a different logo URL based on the current skin.  These factors that affect the behavior (in this case, the country of the user and the skin selected) are the dimensions, and you may define as many as you wish.

Dimensions work by adding another level of cascading configuration, as well as by altering the location of the template or altering the name of the action class. All of this is made easy due to the forward thinking flexibility of symfony.

== Installation ==

This is not a standard plugin and installation should not be automated since core files are altered. You must manually install this plugin by following these easy steps:

'''1. Download the plugin via subversion'''

This plugin can be downloaded and installed into the plugins directory of your project.

{{{
cd path/to/your/project/plugins/
svn export http://svn.symfony-project.org/plugins/ysfDimensionsPlugin
}}}

'''2. Backup Files'''

The most important part of installing this plugin is backing up your original installation. First find out where symfony is installed (in pear or in your project) and then backup the following files:

{{{
cp /your/path/to/symfony/lib/config/sfLoader.class.php /your/path/to/symfony/lib/config/sfLoader.class.php.original
cp /your/path/to/symfony/data/config/constants.php /your/path/to/symfony/data/config/constants.php.original
}}}

'''3. Override Files'''

Now you can safely replace the core symfony files:

{{{
cp /path/to/your/project/plugins/ysfDimensionsPlugin/lib/config/sfLoader.class.php /your/path/to/symfony/lib/config/sfLoader.class.php
cp /path/to/your/project/plugins/ysfDimensionsPlugin/config/constants.php /your/path/to/symfony/data/config/constants.php
}}}

== Configuration ==

Now that the sfDimensions hooks are in place, you need to configure your application, by following the steps below:

'''1. Defining Available Dimensions'''

First we need to define the different dimensions a page may have and define all available values for each dimension in project/config/dimensions.yml:

{{{
dimensions:
    culture:          [en, fr, it, de]
    theme:            [classic, corporate]
}}}

'''2. Setting the Current Dimension'''

Next, you need to edit your project's config.php and add the following changes below the $sf_data_dir/$sf_lib_dir definitions:

{{{
/**
 *
 * Logic for determining dimensions
 *
 * Remember this file is called very early on in the symfony bootstrap process
 * so there are no symfony utilities available,
 *
 */

// For now static values
$culture = (!empty($_REQUEST['culture'])) ? $_REQUEST['culture'] : 'en';
$theme = (!empty($_REQUEST['theme'])) ? $_REQUEST['theme'] : 'classic';

// define dimensions
$dimension = array('culture' => $culture, 'theme' => $theme);

// no autoloading available this early in bootstrap, so require absolutely
require_once(dirname(__FILE__).DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.'plugins'.DIRECTORY_SEPARATOR.'ysfDimensionsPlugin'.DIRECTORY_SEPARATOR.'lib'.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'sfDimensions.class.php');

// set dimensions
sfDimensions::setDimension($dimension);
}}}

For now we're just setting the theme and culture based on a request parameter.
You will likely not want to base the dimension off raw user input, but of
something else, like the host name or stored user preferences.

== Examples ==

So what's really going on here?  We need to vary the site behavior based upon
various parameters.  Above, we're using the culture of the request as the
parameter, but we can use other settings like theme or colo as parameters as
well.  We can then specify several aspects of the symfony experience by means
of these dimensions.  For instance, we can specify different site logos
depending on the theme, or different servers depending on the culture, or
different page content based on the culture (for example, language translations
of a page).  We can also inherit functionality between settings, so if culture
=> fr is almost the same as the generic configuration, it can inherit the
settings and just specify the changes it needs. We will go more into how this
works later, first lets explain the dimension configuration.

{{{
dimensions:
    culture:          [en, fr, it, de]
    theme:            [classic, corporate]
}}}

Our dimensions.yml file describes two levels of dimensions. The first named
'culture' that has four possible values: 'en, fr, it, de', and a second
dimension named 'theme' that has two possible values 'classic' and 'corporate'.

Any request can be for any combination of the dimensions culture and theme.
Here we have configured eight posssible unique dimensions (en_classic,
en_corporate, fr_classic, fr_corporate, it_classic, it_corporate, de_classic,
de_corporate). Dimensions function by looking in special directories for
configuration or template files. For example, if the current dimension was set
as culture => en, theme => classic, then symfony would form the dimension
string 'en_classic'. When symfony looks for a configuration or template file it
will insert a new order of precedence: first it will load files from
'en', then 'corporate', and then 'en_corporate'.  Regardless of the dimension
all of these will look in the generic (non dimension-specific) location for
settings last.  This means that if you don't want to specialize your behavior
at all, you can put settings in the same locations in symfony as you did before
using the ysfDimensionsPlugin.

There are three parts of the system that are configured by these settings:
configuration, templates, and actions.  All dimensions-specific files live
underneath a dimension-specific directory.  For app-level configuration, the
directory is in apps/<app>/modules/[config, templates]/<dimension>/*.  For
module-level configuration, it's in apps/<app>/modules/<module>/[actions,
config, templates, validate]/<dimension>/*

Let's talk a little about each of these.


=== Configuration ===

symfony makes great use of configuration files to set up your web site.  These
files live in various config/ directories.  The settings largely end up in the
sfConfig object where you can fetch them from your application.

We handle the settings.yml, app.yml, routing.yml, databases.yml, module.yml, view.yml,
security.yml, mailer.yml, cache.yml, i18n.yml, and validate/*.yml as well.

You should put the dimension-specific files in a dimension-specific
subdirectory. For instance, we would put the 'app.yml' for the dimension
'culture => en, theme => corporate' in apps/myapp/config/en_corporate/app.yml,
and module.yml in apps/myapp/modules/mymodule/config/en_corporate/module.yml.

As with all of these settings, configurations are searched for in the order
specified by the original dimensions.yml file.  Any setting not specified in
one file will cause us to look in the subsequent files down the list. The order
is determined by applying a cartesian iteration, thus culture => en, theme =>
corporate ends up as a dimension 'en_corporate'. The search order will be from
most specific to generic: 'en_corporate', 'corporate', 'en', generic.  If
multiple configuration files are found in multiple paths, they will be merged
with the most specific values having precedence.

Let's try this.  Let's create a setting 'site' that we'll echo for a new 'test'
action.  Put this into apps/myapp/modules/mymodule/templates/testSuccess.php
(the generic location):

{{{
<h1>mymodule:test</h1>
<p>We are in the test template now.  Site setting is <?php echo $site ?>.</p>
}}}


Now add the action:

apps/myapp/modules/mymodule/actions/actions.class.php


{{{
<?php
class mymoduleActions extends sfAction
{
  public function executeTest()
  {
    $this->site = sfConfig::get('app_site');
  }
}
?>
}}}


Now we just need to establish the setting itself.  This is an app-level setting
(app_) so it belongs in the app.yml file.  Let's create a base value.  Create
apps/myapp/config/app.yml:


{{{
all:
  site: base
}}}


Now clear the cache (for now you'll need to do this whenever you add new action
code) and load the page at http://example.com/mymodule/test (change the
hostname for your box). You'll see the base setting.  Now hit
http://example.com/mymodule/test?culture=fr.  The setting is still base even
though you're in the fr culture.  Let's make a fr-specific setting.  Create
apps/myapp/config/fr/app.yml:


{{{
all:
  site: fr
}}}


Now clear your configuration cache (symfony cc) and reload the last page.  What about
a theme?  Try this URL:
http://example.com/mymodule/test?culture=fr&theme=corporate.  It still says fr
because the fr_corporate site inherits the fr settings.  Let's override this
value again.  Create apps/myapp/config/fr_corporate/app.yml:


{{{
all:
  site: fr_corporate
}}}


Clear the cache, and reload.  There you go.  If you go back to the previous
URLs pages you'll see that they each show the appropriate value, overriding the
base where necessary.

Here are the configuration files that are specialized to handle dimension-specific configuration.

The application configuration files that can be overridden are:

{{{
app.yml
factories.yml
filters.yml
settings.yml
cache.yml
security.yml
view.yml
routing.yml
databases.yml
}}}

The module level configuration files that can be overridden are:

{{{
cache.yml
module.yml
security.yml
view.yml
}}}

For each one, symfony will load all of the dimension-specific configuration files given
the specialization path specified by dimensions.yml (e.g. en_corporate, corporate, en,
generic) with the earlier files' settings overriding the later ones.  Otherwise, the
configurations work just as they did before the dimension-specific specialization. See
[http://www.symfony-project.org/book/trunk/05-Configuring-Symfony the symfony book] for
more information about these files.

=== Templates ===

Dimension-specific templates are placed in the templates/<dimension>/
directory.  They are searched for in the order specified by the dimensions.yml
file, and the first found of the appropriate name is used.

Let's add some dimension-specific templates for our new action.
apps/myapp/modules/mymodule/templates/fr/testSuccess.php:


{{{
<h1>mymodule:test for fr</h1>
<p>We are in the test/france template now.  Site setting is <?php echo $site ?>.</p>
}}}

apps/myapp/modules/mymodule/templates/fr_corporate/templates/testSuccess.php:


{{{
<h1>mymodule:test for fr/corporate</h1>
<p>We are in the test/france/corporate template now.  Site setting is <?php echo $site ?>.</p>
}}}


Now try the URLs from above, for base, fr, and fr_corporate settings.  You
should see all three templates, each showing the setting from the previous
section as well.

=== Actions (*not yet implemented*) ===

Dimension-specific actions are placed in the actions/<dimension>/ directory.
Since actions are specified in classes and classes need to have unique names,
you need to append the standard class names with the dimension.  So
mymoduleActions for the en_corporate configuration would be
mymoduleActions_en_corporate.  This class would go in the
actions/en_corporate/actions.class.php file.  The same is true for individual
action classes as well.  fooAction_en_corporate class would go in the
actions/en_corporate/actions/fooAction.class.php file.  Actions can inherit
functionality from other actions and don't need to 'require' them.  You could
have '''mymoduleActions_en_corporate extends mymoduleActions''' if you want to
share some behavior between all sites but override a specific action for
'en_corporate' dimension.

For example, let's just override the action for the all sites with the
dimension 'fr_corporate'.

apps/myapp/modules/mymodule/actions/fr_corporate/actions.class.php:

{{{
<?php
class mymoduleActions_fr_corporate extends mymoduleActions
{
  public function executeTest()
  {
    parent::executeTest();
    $this->site = 'override('.$this->site.')';
  }
}
?>
}}}


You'll need to clear the cache.  Now reload the 'fr_corporate' url from above
and you will see that we've overridden the site value on this page, while
inheriting the behavior of the base action.


=== Performance ===


Installing the ysfDimensionsPlugin adds little overhead to your project. The only overhead
comes from looking for the same configuration files in multiple places. This is minimized
significantly as the configuration files are still compiled and cached.


== Todo ==

   * add lookup sequences, to determine order of dimension lookup via cartesian expression
   * add action overriding / extensions / chaining
   * apc caching + performance tweaks
   * more documentation with examples
   * more unit tests, full functional test
   * cleaner integration into symfony core
   * dimension validation via dimensions.yml
   * better caching for each dimensions (only overridden files)