PluginManager
What is this ?
The PluginManager class is the class that will help you to deal with external javscript plugin. In the framework, a plugin can be Scriptaculous or a modal window class for example. This is a singleton class. So you will call it by using PluginManager.getInstance().
You can take a look at the Scriptaculous plugin and at the GoogleMap plugin.
How do I declare a plugin to the Framework ?
The easiest way to declare a plugin to the framework is to do it directly in the head part of your HTML file using the declarePlugin() method.
<head>
...
<script type="text/javascript" src="http://localhost/js/WZFwk/libs/prototype/1.6.0.3.js"></script>
<script type="text/javascript" src="http://localhost/js/WZFwk/libs/prototype/extends.js"></script>
<script type="text/javascript" src="http://localhost/js/WZFwk/compress/compress.js"></script>
<script type="text/javascript">
var initializer = new Initializer();
initializer.init("http://localhost/js/application/conf.xml");
PluginManager.getInstance().declarePlugin("Validation", "validation1.5.4.1/validation.js", "Validation");
PluginManager.getInstance().declarePlugin("WZLightWindow", "lightwindow/compress/lightwindow.js", "lightwindow");
</script>
...
</head>
As you can see the declarePlugin() method has three arguments. The first one is the ID of your plugin. The second one is the url of the plugin. The framework will add the prefix you complete in the framework configuration file. The third one is a name of a Class, value or whatever declared in your plugin. This argument is for compatibility with Internet Explorer.
The best practice is that the id and the third parameter is set to the same value.
Another way to declare plugin is to include it directly like a script in the head. Example :
<head>
...
<script type="text/javascript" src="http://localhost/js/WZFwk/libs/prototype/1.6.0.3.js"></script>
<script type="text/javascript" src="http://localhost/js/WZFwk/libs/prototype/extends.js"></script>
<script type="text/javascript" src="http://localhost/js/WZFwk/compress/compress.js"></script>
<script type="text/javascript">
var initializer = new Initializer();
initializer.init("http://localhost/js/application/conf.xml");
</script>
<script type="text/javascript" id="Validation" src="http://localhost/js/WZPlugin/validation1.5.4.1/validation.js"></script>
...
</head>
The PluginManager class will detect that this is a plugin because it is included in WZPlugin. The id of the script will be used as the first and the third parameter of the declarePlugin() method.
<script type="text/javascript">
PluginManager.getInstance().declarePlugin("Validation", "validation1.5.4.1/validation.js", "Validation");
</script>
is equivalent to
<script type="text/javascript" id="Validation" src="http://localhost/js/WZPlugin/validation1.5.4.1/validation.js"></script>
The advantage of the first method is that the plugin will be load on demand. So if the only module which need the plugin is loaded dynamicaly, you will be able to load the plugin on the fly. That will speed up the initialization of your application.
How do I load a plugin ?
This a really simple. You do that using the module configuration file. Let's say you need a Validation plugin for a module. You just need to tell the framework your module require this plugin. Example :
<?xml version="1.0" encoding="utf-8"?> <conf model="ModuleModel" controller="ModuleController" view="" dynamicLoad="true" folder="application/module/" version="0.1" type="simple" compressed="false" > <bind id="button" attribute="innerHTML" propertie="buttonValue"/> <bindAsListener id="button" event="click" handler="buttonClickHandler"/> <plugin id="Validation" /> </conf>
When the framework will parse the file, it automatically load the Validation plugin for you.
Do NEVER use document.write() in a plugin !
Plugins are loaded on the fly. If you use document.write() in one of them. That will result as a blank page. Restart your browser will be your only chance to restart your page. More information on developper.mozilla.org.
PluginManager method
declarePlugin(id, src, className, version, w3cStandard, loaded)
As we just see the declare plugin method will help you to declare a plugin to the framework.
First parameter is the unique id of your plugin.
Second parameter is the url of your plugin. If the url is not absolute, the framework will look at it in the pluginFolder item of the framework configuration file. If not, the framework will simply loads it.
Third parameter is a class or string that is used in your plugin.
var Plugin = Class.create({});
Here, you will be able to pass Plugin as a className.
version will be used to kill client cache and will be aded at the end of the src when loading it.
Load : validation1.5.4.1/validation.js?v=0.1
w3cStandard will replace & by & if you set it to true. It is useful if you want your HTML file to be valid with the W3C. For example with the GoogleMap plugin.
PluginManager.getInstance().declarePlugin('GMap', 'http://maps.google.com/maps?file=api&v=2.x&key=myWebsiteKey // \n
&c&async=2&callback=', 'GScript', '', true);
The framework will load :
http://maps.google.com/maps?file=api&v=2.x&key=myWebsiteKey&c&async=2&callback=
The loaded parameter let the PluginManager know if the plugin is already loaded or not.
apply(id)
If you wish to load a plugin directly in a controller or model helper. You can use this method.