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.

Developers

License

Copyrights for code authored by Yahoo! Inc. is licensed under the following terms:

MIT License

Copyright (c) 2006-2008 Yahoo! Inc. All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Changelog for release 1.1.0 - 27/05/2008

Other releases

Release 1.4.0 - 19/04/2010

Release 1.1.0 - 27/05/2008

Release 1.0.1 - 14/03/2008

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.

Getting Started

For setting up ysfDimensionsPlugin for use with symfony 1.0 projects, please see http://trac.symfony-project.com/browser/plugins/ysfDimensionsPlugin/branches/1.0/README.

Requirements

ysfDimensionsPlugin uses APC by default and it should be enabled in the command line.

Installation

1. Install the plugin via the symfony cli

symfony plugin:install ysfDimensionsPlugin

2. Clear symfony cache

symfony cache:clear

Configuration

1. Configure your project and application configuration to use this plugin

// manually require class since not part of symfony core
require_once(dirname(__FILE__).'/../plugins/ysfDimensionsPlugin/lib/config/ysfProjectConfiguration.class.php');

Then change the parent class from sfProjectConfiguration to ysfProjectConfiguration.

// manually require class since not part of symfony core
require_once(dirname(__FILE__).'/../../../plugins/ysfDimensionsPlugin/lib/config/ysfApplicationConfiguration.class.php');

Edit apps/example/config/exampleConfiguration.class.php changing the parent class from sfApplicationConfiguration to ysfApplicationConfiguration.

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

2. Defining Available Dimensions

First we need to define the different dimensions a page may have and define all allowed values.
The ysfDimensionsPlugin is configurable via the dimensions.yml configuration file in project/config/dimensions.yml.

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.

allowed:
culture: [fr, it, de](en,)
theme: [corporate](classic,)

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//modules/templates//. For
module-level configuration, it's in apps//modules//[actions,
config, templates, validate]//

Let's talk a little about each of these.

Extending 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.

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/frontend/config/en_corporate/app.yml,
and module.yml in apps/frontend/modules/demo/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/frontend/modules/demo/templates/testSuccess.php
(the generic location):

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

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/frontend/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/demo/test (change the
hostname for your box). You'll see the base setting. Now hit
http://example.com/demo/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/frontend/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/demo/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/frontend/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.

For all configuration files, 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
the symfony book for
more information about these files.

Extending Views

Dimension-specific templates are placed in the templates//
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/frontend/modules/demo/templates/fr/testSuccess.php:

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

<h1>demo: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.

Extending Controllers

Dimension-specific actions are placed in the actions// 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
demoActions for the en_corporate configuration would be
demoActions_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 demoActions_en_corporate extends demoActions 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'.

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.

Tests

For a complete example of how to test applications with dimensions,
please see the functional test project in plugins/ysfDimensionPlugin/test/fixtures/project.

License

Please see the packaged LICENSE file for the details of the MIT license.