assetPackagesPlugin - 0.9.4

Add the ability to group stylesheet and javascript calls in packages with a simple dependency system

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source

assetPackagesPlugin

The assetPackagesPlugin is a symfony plugin that provides you the ability to group stylesheet and javascript calls into packages that you can easily organise through a simple yaml config file.

The plugin developpement is driven by two rules:

  • The logic and the configuration file should be simple enought for integrators
  • The plugin implementation should be rock solid, with a full test suite

A logic chain of packages can be automatically called through a simple package depency system.

Installation

  • Install the plugin (via a package)

    symfony plugin:install assetPackagesPlugin
    
  • Install the plugin (via a Subversion checkout)

    svn co http://svn.symfony-project.com/plugins/assetPackagesPlugin/trunk plugins/assetPackagesPlugin
    
  • Activate the plugin in the config/ProjectConfiguration.class.php

    class ProjectConfiguration extends sfProjectConfiguration
    {
      public function setup()
      {
        $this->enablePlugins(array(
          'sfDoctrinePlugin', 
          'assetPackagesPlugin',
          '...',
        ));
      }
    }
  • Copy the plugins/assetPackagesPlugin/config/asset-packages.yml file in the projetPath/config directory.

Packages declaration

Edit the asset-packages.yml file in the projectPath/config directory.

packages:
 
  foo:              # the package name
    require:
      - bar         # the bar package styles and scripts will be automatically called
    stylesheets:
      - foostylesheet1     # calls /css/foostylesheet1.css
      - foostylesheet2     # calls /css/foostylesheet2.css
    javascripts: fooscript # calls /js/fooscript.js
 
  bar:
    stylesheets:
      - barstylesheet1     # calls /css/barstylesheet1.css
    javascripts: myscript  # calls /js/myscript.js

More options are available for script and stylesheet calls ; see the config sample at the end of this page.

Package call

Call from a template

It's the most common use for package calls.

Inside your template file, load the AssetPackages helper and call the use_package() function:

<?php use_helper('AssetPackages') ?>
<?php use_package('foo') ?>
 
<p>the template html...</p>

You can also call several packages at once:

<?php use_package(array('foo', 'bar')) ?>

You can call packages from templates, partials or component.
But be carefull with the caching, no php will be run (and no package will be loaded) in a cached partial/component.

Call from an action

Use the response->addPackage() method:

public function executeIndex(sfWebRequest $request)
{
  $this->response->addPackage('foo');
}

The plugin comes with a debug panel

The assetPackagesPlugin debug panel

Link a package to a form or a widget

Link a package to a widget

Once a package is linked to a widget declaration, related assets are automatically called when the widget is rendered with all packages added with the "require" option.

Usage samples:

  • a phone field with a dedicated stylesheet
  • a password field with a js+css plugin that displays the prompted password strength to the user

You can add your packages to your form widegts through the "packages" option.

If you build your own form widget class:

class myWidgetForm extends sfWidgetForm
{
  protected function configure($options = array(), $attributes = array())
  {
    parent::configure($options, $attributes);
    $this->addOption('packages', 'foo');
  }
}

If you use an existing widget class:

class myForm extends BaseForm
{
  public function configure()
  {
    // ...
    // ...
    // ...
    $this->widgetSchema['field_name']->addOption('packages', 'foo');
  }
}

Link a package to a form

Use the sfForm->addPackage() method:

class myForm extends sfForm
{
  public function configure()
  {
    $this->addPackage('foo');
  }
}

Call packages linked to a form

Call use_packages_for_form() in the template where the form is rendered.

<?php use_stylesheets_for_form($form) ?>
<?php use_javascripts_for_form($form) ?>
<?php use_helper('AssetPackages') ?>
<?php use_packages_for_form($form) ?>
 
<form action="<?php echo url_for('@form_handler_route') ?>" method="post">
  <table>
    <?php echo $form ?>
  </table>
  <p><input type="submit" value="Submit" /></p>
</form>

 

PS: Hey symfony developpers! I'm still looking for a way to add a ->addPackage() method to all widgets, but unfortunatly, sfWidget extends no BaseWideget class and no 'widget.method_not_found' event is notified. I'm stuck. Any idea?

[INTEGRATOR CHEATSHEET] Package declaration config file:

projectPath/config/asset-packages.yml

packages:
 
  layout:
    stylesheets: common           # loads /css/common.css
 
  jquery:
    javascripts: jquery           # loads /js/jquery.js
 
  form:
    stylesheets: form             # loads /css/form.css
 
  foopage:
    require:
      - layout
      - jquery
      - form
    stylesheets:
      - foo: ~                    # loads /css/foo.css
      - foo-print: {media: print} # loads /css/foo-print.css with the "print" media
      - foo-ie: {condition: IE6}  # loads /css/foo-ie.css wrap with <!--[if IE6]>...<![endif]-->
    javascripts: form-contact

The yaml syntax documentation.

CSS options Supported values Comments
position "first" or "last" Move the asset call at the beginning/end of the list
condition any condition string inserted the condition tag wrapper. Eg: {condition: "lge IE9"} will render <!--[if lge IE9]>
absolute true The file path called shoud be absolute
raw_name true Symfony won’t try to complete the filename
href any absolute or relative path Skip the symfony asset path generator
media "all", "sreen", "print"...
JS options Supported values Comments
position "first" or "last" Move the asset call at the beginning/end of the list
condition any condition string inserted the condition tag wrapper. Eg: {condition: "lge IE9"} will render <!--[if lge IE9]>
absolute true The file path called shoud be absolute
raw_name true Symfony won’t try to complete the filename
src any absolute or relative path Skip the symfony asset path generator