Download Developer Sample Plugins
Developer/Example Plugin - Samples Codes and documentation API, on how to create plugins.Developer/Basic Plugin - very basic example on how to create plugins with Javascript (without php).
Creating Plugins
Steps for creating a plugin
- Create a Javascript file under cjax/plugins/YourPlugin.js
Or you may also create a directory inside plugins directory like so: cjax/plugins/YourPlugin/YourPlugin.js, In case you want to add additional css, images, or other media, etc.
- Add a function YourPlugin in YourPlugin.js
function YourPlugin() {}
- Call your plugin PHP
$ajax->YourPlugin()
- Replace "YourPlugin" with the name you would like your plugin to have
- Pass parameters
-
You may pass strings or arrays through function parameters through your php plugin call.
PHP$ajax->YourPlugin('pass strings', array('pass'=>'arrays'))
Acess parameters in your JavaScript Plugin:
//cjax/plugins/YourPlugin.js
function YourPlugin(string, array) {
alert(string);
//alerts all the items in your array.
for(item in array) {
alert(item+ ' '+array[item]);
}
}
-
Arrays are converted to Json objects, that is how you would access them.
Hello World Sample Plugin
Hello World Plugin
PHP
<?php
$ajax->hello_world('hello', 'world!',array('test'));
?>
This is what hello_world.js looks like:
function hello_world(a,b,c)
{
//sample of importing javascript into the scope
this.importFile('http://cjax.googlecode.com/svn/trunk/_extra/test_unit/plugins/js/test.js');
//sample of importing css to the page
this.importFile('http://cjax.googlecode.com/svn/trunk/_extra/test_unit/plugins/css/test.css');
console.log('File base:', this.base);
console.log('This file:', this.file);
console.log('Paramters Passed:', a, b ,c);
}
Plugins JavaScript API
API | type | Params | Description | Example(s) |
---|---|---|---|---|
|
Function |
path - required string
$callback - optional callback function |
Import and caches JavaScript or CSS files. You may use relative path to your plugin, eg: just "myfile.js" or "js/myfile.js". You may also import remote CSS or JavaScript. You may use the callback as an indicator that the script/css is fully loaded. |
|
|
Variable | - | Returns the full base path url to your plugin directory location. |
|
|
Variable | - | Returns file name, eg. myPlugin.js |
|
|
Variable | - | Returns the default path to ajax.php |
|
|
Function | $count - optional integer [default 1] | Allows you to intercept the execution of $ajax object APIs. It returns a function which you can use to trigger the intercepted APIs. If $count is specified, you may place how many APIs you want to prevent after the execution of the plugin API. |
in your controller...
PHP
<?php in your js plugin...
you may prevent more than one.
|
|
Function | $form_id - require string | Get all values in a form. |
|
|
Function |
$mix_url - require mixed [string, object] $mix_item - optional mixed [string, object] |
Create ajax requests |
|
|
Function |
$url - require mixed [string] $mixed - optional mixed [string, object] |
Create ajax requests with get. $mixed can be a container id where the response html is sent to or it can be a callback function which returns the response. |
|
|
Function |
$url - require mixed [string] $mixed - optional mixed [string, object] |
Create ajax requests with post. $mixed can be a container id where the response html is sent to or it can be a callback function which returns the response. |
|
|
Function |
content - required [string] options - optional mixed [object]
top - position from top of the page
left - position from left transparent - from 1 to 100 level of background transparency. color - color of the background |
Displays a lightbox overlay window with supplied content. |
|
|
Function |
content - required [string] options - optional mixed [object]
top - position from top of the page
left - position from left transparent - from 1 to 100 level of background transparency. color - color of the background remote - If it is an external url |
Displays a lightbox overlay window with supplied url. |
|
|
Function |
message - string seconds - optional [default 3] |
Displays supplied text/content on the screen in form of message. if $seconds is provided, that is how long the message will last on the screen before it disappears, 0 would remove time limit. |
|
|
Function |
message - string [default 'Success!'] seconds - optional [default 3] |
Makes use of this.message() to display a success formatted message. |
|
|
Function |
message - string [default 'Invalid Input'] seconds - optional [default 3] |
Makes use of this.message() to display a warning formatted message. |
|
|
Function |
message - string seconds - optional [default 3] |
Makes use of this.message() to display an error formatted message. |
|
ScopeAll plugins APIS apply to local scope to each plugin within plugin contructor function. |
Plugins PHP API
A Plugin can stand on its own without a php class - and does not require one. However if you require more power in your plugin
extra functions or ajax controllers, Or to overwrite plugin core functionality to customize your plugin even more
then you might be interested in using a php class in your plugin.
Some of the functions in plugin PHP APIs are available to all plugins even if they don't have class.
These are: save, get , set, import, imports.
Creating a PHP Class for plugin
Steps for creating a PHP class for your plugin
- Create a PHP file under your plugin directory, name it YourPlugin.php
- Add a class YourPlugin in YourPlugin.php PHP
<?php
class YourPlugin {
}
?> - Add a function __construct PHP
<?php
class YourPlugin {
function __construct()
{
}
}
?> - Call your plugin PHP
$ajax->YourPlugin()
-
When you call your plugin, the contructor is automatically triggered, all parameters
passed in your plugin will be passed in the constructor as well.
There are more trigger functions that trigger themselves, look in the PHP plugin API below. - Replace "YourPlugin" with the name of your plugin
Ajax Controllers for plugins
Firstly to start using Ajax Controllers in your plugin, you'd need to create a "controllers" directory in your plugin. Then you are ready to go. The ajax framework through ajax.php automatically detends your plugin if you pass the plugin name as controller. For example: ajax.php?myPlugin/funtion1 will automatically go into your plugin and look for controllers/myPlugin.php. Class name is controller_myPlugin and function funtion1 (or any function name you pass through second parameter in the URL).
Plugins PHP API
API | type | Params | Description | Example(s) |
---|---|---|---|---|
PHP
$myplugin->import()
|
Function |
$url - required string
$load_time - optional integer milliseconds |
Import and caches JavaScript or CSS files. You may use relative path to your plugin, eg: just
"myfile.js" or "js/myfile.js". You may also import remote CSS or JavaScript.
$load_time - Import scripts are loaded asynchronously, when importing multiple scrips it is possible that a second script could load before the first one, if it is smaller. You may give extra milliseconds to your import to ensure that it doesn't load too fast or too slow in comparism with others. The range should be from 50 to max 400 (4th of a second), depending how big the script is. If you experience issues with one script loading in mixed order use imports() function instead. |
PHP
|
PHP
$myplugin->imports()
|
Function |
$files - required array
|
Import and caches JavaScript or CSS files. You may use relative path to your plugin, eg: just
"myfile.js" or "js/myfile.js". You may also import remote CSS or JavaScript.
This function first waits for the previous file to be fully loaded before loading the next one. |
PHP
|
PHP
$myplugin->waitfor()
|
Function | $file - required string | Wait for javascript file to be loaded before firing plugin. Currently this function only accounts with scripts loaded with import() or imports(). $file is the filename of the javascript file which the plugin depends on, if there are more than one, enter the last file required. |
PHP
|
PHP
$myplugin->set()
|
Function |
$setting - required string
$value - require mixed string |
Updates plugin parameters and variables of your JavaScript plugin. You may use a,b,c,d,e,f etc. If you don't use alphabetic letters to update parameters, any other variable name will also be accessible within your plugin as eg: this.variable_name. |
PHP
|
PHP
$myplugin::__construct()
|
Function | - | Trigger Function - This function is a type of constructor function. Is Automatically called at the initiation of your plugin. The paratemers passed when you call your plugin, will be passed through this function in the same order. |
PHP
|
PHP
$myplugin::onLoad()
|
Function | - | Trigger Function - This function is a type of constructor function. Is Automatically called at the initiation of your plugin in controller (none Ajax Mode). The paratemers passed when you call your plugin, will be passed through this function in the same order. |
PHP
|
PHP
$myplugin::onAjaxLoad()
|
Function | - | Trigger Function - This function is a type of constructor function. Is Automatically called at the initiation of your plugin in an Ajax Controller. The paratemers passed when you call your plugin, will be passed through this function in the same order. Thi function is optional. |
PHP
|
PHP
$myplugin->save()
|
Function |
$setting - required string
$value - required mixed string |
Save plugin settings in session or cookie. You may access this data in the plugin's ajax controllers. |
PHP
|
PHP
$myplugin->get()
|
Function | $setting - required string | Get setting that has been saved with save() function. |
PHP
|
PHP
$myplugin->prevent()
|
Function |
$call_id - required integer $count - optional integer [default 1] |
This function is capable of intercepting APIs and prevent them from being fired, and return them in callback function. Due to asynchronicity there are times the actions are ran before they can be intercepted in the existing plugin's this.prevent() function. This method is added to PHP to ensure that APIs can be catched before they are fired. If simply this.prevent() can't catch the APIs you might want to use $ajax->prevent($this->_id); (inside a php plugin class). More than one API can be prevented if $count is incremented. If used outside a plugin use $id = $ajax->lastId(); ajax->prevent($id);, you may also retrieve the functions/actions in js by using CJAX.callback_cache[id_here] (id_here - the id passed) |
PHP
|
PHP
$myplugin->filter()
|
Function | - |
Triger Function - This function is automatically called at the end of the processing.
It passes the raw data being sent from your plugin.
$cache variable holds all the raw data being sent from the plugin, you may make careful changes still. return the $cache, if you don't return anything no changes will be made. |
PHP
|