root/plugins/sfPJSPlugin/README

= sfPJS plugin =

The `sfPJSPlugin` provides a MVC way to include JavaScript generated by PHP code. It also provides a new JavaScript view class and relies on .pjs templates.

== Installation ==

  * Install the plugin
  
    {{{
      symfony plugin-install http://plugins.symfony-project.com/sfPJSPlugin
    }}}

  * Enable the `sfPJS` module in your application `settings.yml`
  
    {{{
      all:
        .settings:
          enabled_modules:        [default, sfPJS]
    }}}

  * Replace the following lines in `web/.htaccess`

    {{{
      # we skip all files with .something
      RewriteCond %{REQUEST_URI} \..+$
      RewriteCond %{REQUEST_URI} !\.html$
      RewriteRule .* - [L]
    }}}
  
    by

    {{{
      # we skip all files with .something
      RewriteCond %{REQUEST_URI} \..+$
      RewriteCond %{REQUEST_URI} !\.html$
      RewriteCond %{REQUEST_URI} !\.pjs$
      RewriteRule .* - [L]
    }}}

  * Clear you cache

    {{{
      symfony cc
    }}}

  * You're done.

== Usage ==

To link to a dynamic JavaScript file generated by a symfony action, use the following syntax:

{{{
  <?php use_helper('PJS') ?>

  <?php use_pjs('targetModule/targetAction?name=fabien') ?>
}}}

The `targetModule/targetAction` will be executed by symfony, so it can contain any usual action code:

{{{
  class targetModuleActions extends sfActions
  {
    ...

    public function executeTargetAction()
    {
      // Business logic here, as usual
      $this->name = $this->getRequestParameter('name');

      // Let's store the time
      $this->time = time();
    }
  }
}}}

The `targetAction` view has the layout disabled by default and the response content type is automatically changed to `application/x-javascript`.

Unlike normal actions, PJS actions look for a template ending with `.pjs` instead of `.php`. For this example, the default rendered template is `targetActionSuccess.pjs`:

{{{
  alert('Hello <?php echo $name ?>, it is already <?php echo date('d/m/Y', $time) ?>');
}}}

== Alternative syntaxes ==

You can also include the dynamic JavaScript in one of the following ways:

{{{
  <?php sfPJSHelper::use_pjs('targetModule/targetAction?foo=bar') ?>

  <script type="text/javascript" src="<?php echo pjs_path('targetModule/targetAction?foo=bar') ?>" />

  <script type="text/javascript" src="<?php echo sfPJSHelper::pjs_path('targetModule/targetAction?foo=bar') ?>" />
}}}

== Known limitations ==

 * Internet Explorer is known to cache JavaScript files regardless of HTTP headers. This is means that your template changes, the client will never see it.
   To bypass this limitation, you should add a `version` parameter to each call to the PJS helpers.

   {{{
     <?php use_pjs('targetModule/targetAction?name=fabien&version=1') ?>
   }}}

   Change the version each time you change the template.

   If your template relies on session parameters, you must use a random / incremental version to forbid client side caching completely.

   {{{
     <?php use_pjs('targetModule/targetAction?name=fabien&version='.time()) ?>

     <?php use_pjs('targetModule/targetAction?name=fabien&version='.uniqid()) ?>

     <?php use_pjs('targetModule/targetAction?name=fabien&version='.rand(1000, 9999)) ?>
   }}}

  * This is an experimental plugin and as such, the API can change.

== Changelog ==

=== Trunk ===

  * gordon: closed #2273 in changeset #6338
  * gordon: closed #2086

=== 2007-04-24 | 0.2.0 beta ===

  * fabien: initial release