## Plugins

Put bluntly, with Cjax, you can literally execute Javascript from PHP, and with Cjax Plugins you can execute your own custom Javascript Code through PHP. This makes it handy dandy, for you to consolidate solid functionality through your application, and easily execute without having to get your hands dirty with chunks of javascript everywhere.
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
  `
  $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.
  `
  $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 Code used to call plugin:
`<?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)
--- | --- | --- | --- | ---

`
this.importFile()
`

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.

`
this.importFile('css/style.css');
this.importFile('js/myFile.js');
this.importFile('js/myFile2.js', function() {
alert('script loaded');
//do something with the loaded file
});
`

` this.base ` | Variable | - | Returns the full base path url to your plugin directory location. | ` alert('Directory: '+this.base); `
` this.file ` | Variable | - | Returns file name, eg. myPlugin.js | ` alert('File: '+this.file); `
` this.ajaxFile ` | Variable | - | Returns the default path to ajax.php | ` alert('File: '+this.ajaxFile); `

`
this.prevent()
`

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
$ajax->yourPlugin();
$ajax->call("ajax.php?controller/functions");
?>`
in your js plugin...
`
var func = this.prevent();
//it prevented $ajax->call() from being executed.
//now you have the control of when it should be executed
func();
` you may prevent more than one.

` this.serialize() ` | Function | $form_id - require string | Get all values in a form. | ` //c/f = controller/function this.post(this.AjaxFile+'?c/f', this.serialize('form1')); `

`
this.call()
`

Function

$mix_url - require mixed [string, object]
$mix_item - optional mixed [string, object]

Create ajax requests

`
//c/f = controller/function
this.call('ajax.php?c/f');
this.call('ajax.php?c/f', 'container_id');
this.call('ajax.php?c/f', function(response) {
});
this.call({
url: 'ajax.php?c/f',
data: 'a=1&b=2&c=3',
success: function(response) {},
error: function(error_status) {}
});
`

`
this.get()
`

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.

`
this.get('ajax.php?c/f');
this.get('ajax.php?c/f', 'container_id');
this.get('ajax.php?c/f', function(response) {
});
`

`
this.post()
`

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.

`
this.post('ajax.php?c/f','a=1&b2&c=3');
this.post('ajax.php?c/f','a=1&b2&c=3', function(response) {
});
this.post('ajax.php?c/f', function(response) {
});
`

`
this.overLayContent()
`

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.

`
//1
this.overLayContent('Content Here');
//2
this.overLayContent('Content Here', {
top: '200px',
left: '200px',
transparent: '50%',
color: '#333',
});
`

`
this.overLay()
`

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.

`
//1
this.overLay('http://url/to/ajax.php?controller/function');
//2
this.overLay('http://url/to/ajax.php?controller/function', {
top: '200px',
left: '200px',
transparent: '50%',
color: '#333',
});
//3
//triggers crossdomain ajax
this.overLay('http://url/to/remote/location', {
remote: true
});
`

` this.message() ` | 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. | ` this.message('Test'); `
` this.success() ` | Function | message - string [default 'Success!'] seconds - optional [default 3] | Makes use of this.message() to display a success formatted message. | ` this.success(); `
` this.warning() ` | Function | message - string [default 'Invalid Input'] seconds - optional [default 3] | Makes use of this.message() to display a warning formatted message. | ` this.warning(); `
` this.error() ` | Function | message - string seconds - optional [default 3] | Makes use of this.message() to display an error formatted message. | ` this.error('Error!'); `

### Scope

All 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
  class YourPlugin {
  }
  ?>`
- Add a function __construct
  `<?php
  class YourPlugin {
  function __construct()
  {
  }
  }
  ?>`
- Call your plugin
  `
  $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)
--- | --- | --- | --- | ---
` $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. | ` $myPlugin->import('file.js'); $myPlugin->import('file.css'); $myPlugin->import('file2.js'); `
` $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. | ` $myPlugin->imports('file.js','file2.js','file3.js'); `

`
$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.

`
//Setting Paratemers
$myPlugin->set('a','this is parameter one in your script');
$myPlugin->set('b','this is parameter two in your script');
--access parameters
function myPlugin(a,b) {
}
//Setting Variables
$myPlugin->set('test1','this is a variable');
$myPlugin->set('test2','this is another variable');
--access variables in your plugin
function myPlugin(a,b,c) {
alert(this.test1);
alert(this.test2);
}
`

`
$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.

`
$myPluing = $ajax->myPluing($arg1, $arg2);
//plugins/myPlugin/myPlugin.php
class myPlugin extends plugin {
function onAjaxLoad($arg1, $arg2)
{
}
}
`

`
$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.

`
$myPluing = $ajax->myPluing($arg1, $arg2);
//plugins/myPlugin/myPlugin.php
class myPlugin extends plugin {
function onLoad($arg1, $arg2)
{
}
}
`

`
$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.

`
$myPluing = $ajax->myPluing($arg1, $arg2);
//plugins/myPlugin/myPlugin.php
class myPlugin extends plugin {
function onAjaxLoad($arg1, $arg2)
{
}
}
`

` $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. | ` $myPluing->save('my_variable','the_value'); `
` $myplugin->get() ` | Function | $setting - required string | Get setting that has been saved with save() function. | ` $myPluing->get('my_variable'); `

`
$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.

`
//plugins/myPlugin/myPlugin.php
class myPlugin extends plugin {
function filter($cache)
{
return $cache;
}
}
`

© Cj Galindo