sfDojoPlugin plugin
===================
The `sfDojoPlugin` is a symfony plugin that neatly integrates the awesome [dojo
toolkit](http://dojotoolkit.org/) with its built system into symfony.
Features
--------
* Neat integration of the dojo build system into symfony
* Distinguishes between prod/dev environment
* Automatic versioning of JS/CSS after each build
* Automatic namespacing
* Other plugins are able to register Dojo components
* Easy way to make PHP variables (i.e. sf-routes) available to JS
Installation
------------
* Install the plugin
$ ./symfony plugin:install sfDojoPlugin
* Setup the plugin to create necessary folders
$ ./symfony dojo:setup
* Clear the cache to enable the autoloading to find the new classes:
$ ./symfony cc
* [Download the dojo sources](http://dojotoolkit.org/downloads) (not the
gzipped version) and put them to `web/js/dojo/src`
* Overwrite the `sfCommonFilter` filter in `filters.yml`
[yml]
common:
class: sfDojoCommonFilter
* Add base "app.main" dojo component to `view.yml`. Alternatively you can
include it with the other javascript adding mechanisms
[yml]
# view.yml
javascripts: [app.main]
Using the power of the plugin
-----------------------------
### Build system
Put all your dojo requires to the `main.js` (with
`dojo.require("app.MyWidget");`) located in the `web/js/dojo/src` folder.
For debugging and changing code (in `dev` environment), each dojo components is
loaded within an own xhr-request (utilized by `dojo.require()`).
For running one a live server (`prod` environment) this plugin provides an own
task to build all components together. Use it with:
$ ./symfony dojo:build-for-prod
### dojo source directories and namespaces
There is a simple namespace convention:
Directory Description dojo namespace (by convention)
-----------------------------------------------------------------------------------------------------------------------
web/js/dojo/build the built javascript lies in here for prod
web/js/dojo/devel your dojo components lie in here app
web/js/dojo/src the dojo sources itself
plugins/sfDojoPlugin/web/js/dojo-devel the dojo components sfDojoPlugin provides sfDojoPlugin
plugins/[sfYourPlugin]/web/js/dojo-devel the dojo components [sfYourPlugin] provides [sfYourPlugin]
so all dojo/dijit components defined by yourself reside in `web/js/dojo/devel`
and use the namespace `app` by definition.
### Publish a plugin's dojo codebase
To make a plugin's dojo-directory available to the rest of the application,
simply call `sfDojoRegistry::enablePlugin()` from the publishing plugin's
configuration.
[php]
# plugins/sfYourPlugin/config/sfYourPluginConfiguration.class.php
class sfYourPluginConfiguration extends sfPluginConfiguration
{
public function configure()
{
sfDojoRegistry::enablePlugin('sfYourPlugin');
}
}
The namespace for all dojo components under
`plugins/sfYourPlugin/web/js/dojo-devel` must be `sfYourPlugin` by definition.
### Registring PHP variables in javascript
Simply add php variables to the `sfDojoRegistry` configuration to make them
available in your html/javascript code.
[php]
sfDojoRegistry::addToConfiguration('routes', array(
'login' => url_for('@login'),
'logout' => url_for('@logout'),
));
// access this configuration in templates with:
# anytemplateSuccess.php
<script>
console.log(sfDojoConfig.routes.login, sfDojoConfig.routes.logout);
</script>