Ajax Framework For CodeIgniter

Cjax is a very basic but powerful Ajax Framework that complements Codeigniter.

Download here:

[url=http://code.google.com/p/ajax-framework-for-codeigniter/downloads/list]Download From Google Code[/url]

Cjax separates your ajax controllers from your regular controllers. While your normal controllers reside in application/controllers, your ajax controllers will reside in application/response.

Install

Download and unzip the Ajax Framework package, then just overwrite everything from the zip into your CodeIgniter base installation (will not replace any of your files)

Test

just go to: http://yoursite.com/ajax.php?controller=test&function=test

(replace http://yoursite.com with the base directory where your CodeIgniter installation resides)

To this point you are done, successfully installing and using Cjax, if the test above prints "Ajax View..". You can find this text inside file application/views/test.php, and its controller in application/response/test.php.

Friendly URLS

Full support for friendly URLS.

Friendly URLS are supported, but not required to use Cjax. You may access your controllers in any of the following ways; these examples make use of controller file application/response/test.php.

[code] //ajax.php?controller=$controller&function;=$function ajax.php?controller=test&function=test //ajax.php?$controller/$function ajax.php?test/test //ajax/$controller/$function #This one requires mod_rewrite ajax/test/test [/code]

The last url above, will require you to enable mod_rewrite in your server and rename the accompanied file htaccess.txt File:htaccess.txt to .htacccess

Creating Controllers

Creating controllers works the same way as your regular controllers, except the class name of ajax controller start with the keyword "controller_". For example, if you want to create a controller named test, then your class name would be "controller_test".

Example

application/response/test.php [code]class controller_test extends CI_Controller {

function test()
{

}

} [/code] You may use your ajax controller the same way you would use any other CI controller including the creation of any dependencies.

Passing Parameters

Cjax uses URL query string to pass parameters into the controller by using function parameters. You can pass alphabetic letters as parameter order to your methods inside the controllers. There is more than one way to pass parameters, depending on the way you are using the URL.

Example of passing parameters in followed order.

URL: [code] ajax.php?test/test/arg1/someID // this also applies to mod_rewrite urls such as: ajax/test/test/arg1/someID [/code] The above URL is passing two parameters arg2 and someID, test/test indicates the controller and the method. To access these parameters use function arguments:

Example

application/response/test.php [code]class controller_test extends CI_Controller {

function test($arg1, $arg2)
{
    echo $arg1;
    echo "<br />";
    echo $arg2;
}
//prints  arg1
//        someID

} [/code]

You can pass unlimited number of parameters, and access them through function parameters in the same order they are passed.

Alphabetic order Parameters

A less Organized way to pass parameters that may accept any order within the URL:

URL: [code]ajax.php?controller=test&function=test&a=Hello&b=World&c=Hello World[/code]

The previous URL, makes use of common URL, and passes three parameters to the controller.

This methods accepts any alphabetic letter in respective order to pass parameters. You may pass: a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, which will be accessible through function parameter. Using this method also allows you to pass any other parameters through outside of the function parameter scope.

Example

application/response/test.php [code]class controller_test extends CI_Controller {

function test($a, $b, $c)
{
    echo $a;
    echo "<br />";
    echo $b;
    echo "<br />";
    echo $c;
}
//prints  Hello
//        World
//        Hello World

} [/code]

Advanced Usage

Bellow are some more advanced ways to use this ajax framework. The level of expertize required is advanced intermediate, if you feel confident, do read through it.

Using Ajax Framework JavaScript Library

So far you have experienced the basic power of this framework through a php environment, but this framework also offers a taste of JavaScript.

To initialize the JavaScript library included with Cjax, include file in the head of your HTML document: [code]cjax/core/js/cjax.min.js[/code]

Event Request

The purpose of this section is to illustrate how to use utilities included within the framework, and how they are executed, not necessarily how to use ajax.

The js Lib, offers two event request types, which are executed when page first loads and each time you make an ajax request.

You may use this Framework to create ajax requests or you may use any other method, but we recommend either using this framework or using Jquery. See at the bottom of this page how to integrate this framework with any other ajax request application or method.

Framework Usage of JavaScript

This framework does not make use of JavaScript directly. It does however uses the js lib indirectly, by creating XML or Json commands that are later passes to the interpreter which executes the XML commands which fires functions included in the js library (cjax.min.js).

This allows you to create all your ajax framework code in a php environment, rather than a JavaScript one.

Create ajax request

Within your main controller, include file ajaxfw.php

in your main controller: [code]$this->load->file(FCPATH.'ajaxfw.php');[/code]

Then you can make full use of the ajax framework in a local scope within your controller.

You may instantiate ajax by using the following method:

[code]$ajax = ajax();[/code]

[b]Important:[/b] As of Cjax version 4.1RC1 you may instantiate Cjax as Follows: [code]$ajax = ajax();[/code]

If you are using a previous version, you will need to do it this way: [code]$ajax = CJAX::getInstance();[/code]

Hello Application

Now lets make some anchors fire an ajax request, and handle the hello request with the server.

[code]$ajax->Exec('achor1',$ajax->call('ajax.php?test/test/Hello'));[/code]

The above line will create an event listener ajax request attached to click event to a DOM element with id 'anchor1'.

In your view file.. lets add that anchor:

views/test.php [code] <body> Anchor 1 </body> [/code]

When you click On the link, it will fire the ajax request directed to: ajax.php?test/test/Hello.

Server Side

Now that the ajax request has fired, it will trigger method test() inside class controller_test in application/response/test.php.

We'll show a message in the screen, see below a list of messaging types.

[b]Messaging API:[/b]

• success
• error
• info
• warning

At this point we are within within the ajax server side scope, so we do not need to include any files, we just need to instantiate the ajax class.

[code]class controller_test extends CI_Controller {

function test($hello)
{
    $ajax = ajax();
    $ajax->success($hello);
}

} [/code]

The word [b]Hello[/b] is passed through the ajax call parameter, and we make use of the ajax messaging api to display a success message in the middle screen.

Each message function is pre-configured to stay on the screen for three seconds, but you may change that with a second parameter, lets try 10 seconds:

[code]$ajax->success($hello, 10);[/code]

You may use any of these messaging API functions:

Try them.. one at a time. [code] $ajax->success($hello);

$ajax->error($hello);

$ajax->info($hello);

$ajax->warning($hello); [/code]

You cannot use more than one message API at the same time because the next message will remove the previous, and you will not be able to see them, except the last one.

Cjax has a handy function that allows you to by pass this behavior, tha wait() function. You may call wait() each time one of them is fired as follow: [code] $ajax->success($hello);

$ajax->wait(3);

$ajax->error($hello);

$ajax->wait(3);

$ajax->info($hello);

$ajax->wait(3);

$ajax->warning($hello); [/code]

You will be able to see each one of the message for three seconds. There is no real world use for this, but it is a demonstration of the usage of timeouts. You may use timeouts for most API functions within the framework.

Overlays

One of the fancy features of Cjax is how easy is to create overlays without much code foot print. Lets take our [b]Hello[/b] Application and use it instead of the messaging.

Basic use of OverlayCotent()

[code]class controller_test extends CI_Controller {

function test($hello)
{
    $ajax = ajax();
    $ajax->overlayContent($hello);
}

} [/code]

Above is the raw basic use of an overlay, you may pass any html or template in the first parameter, and it will show it in the overlay.

Now lets show some configuration and customization:

You may control, how transparent the overlay is, color, and position within the screen, top and left positioning.

Overlay using Options

[code]class controller_test extends CI_Controller {

function test($hello)
{
    $ajax = ajax();
    
    $options['transparent'] = 10;
    $options['color'] = '#425769';
    $options['top']  =  200;
    $options['left'] = "50%";
    
    $ajax->overlayContent($hello, $options);
}

} [/code]

You may also format the dialog message within the overlay as follows (you maybe still pass the options if desired.):

Overlay using formatting

[code]class controller_test extends CI_Controller {

function test($hello)
{
    $ajax = ajax();
    
    $html = $ajax->dialog($hello,"Hello Application");
    
    $ajax->overlayContent($html);
}

} [/code]