# ZajoPlugin

=== *unobtrusive javascript the easy way* ==

The `ZajoPlugin` offers helpers that integrate the [Jquery](http://www.jquery.com/) Javascript framework **unobtrusive way**

  *Warning*: This plugin is in Alpha state. Syntax is subject to change.

## Maintainer

Please report all bugs to Vojto Rinik <vojto[at]rinik[dot]net>

## License

This plugin is licensed under the MIT license. For the full copyright and license information, please view the LICENSE file that was distributed with this source code.

## Introduction

ZajoPlugin is new plugin for unobtrusive adding of javascript. 

There is already a plugin for unobtrusive javascript with jQuery, it's called sfUJSPlugin. 

This one also uses jQuery, but it uses also something new, called jQuery Enchant. That means you can create nice effects like with Script.aculo.us very easily.

As of now, there is not too much functionality. You can use basic helpers **link_to_function**, **link_to_remote** and **form_remote_tag**. These are static methods of **ZajoHelper class**, if you use helper **ZajoHelper** than you can use it as helper functions.

The another part is Enchant. There is **ZajoEnchantHelper** class, which provides methods for generating visual effects. In **ZajoHelper** there are helper functions for these methods too.

## How it works

When you call **link_to_function** method, a new zajoID is generated. It is assigned to the **a** element, and the association between the zajoID and javascript function is stored into session. 

The Helper automatically attaches javascript file (with PJS), which is generated from session of these associations.

### How Enchant works

Enchant is different. There is no ZajoID, and there is no association. It's just code in attached pjs-javascript. That means you cannot do Enchant effect on event. These functionality is going to be implemented.

Enchant is created to work like Rails-RJS. If you write Enchant helpers into AJAX response, Zajo's filter will generate script with the code.

## Installation

Let's install it!

  * Install the plugin 

    
    $ symfony plugin-install http://plugins.symfony-project.com/ZajoPlugin
    

  * Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's `plugins/` directory

  * If it is not installed yet, install the [sfPJSPlugin](/plugins/sfPJSPlugin), which is necessary to run this plugin

  * Copy all the files from **/plugins/ZajoPlugin/web/js** to your **/web/js** folder

Now it's time to do some configuration.

  * Enabled **Zajo module** in your **settings.yml** file.

    
    all:
      .settings:
        enabled_modules: [sfPJS, Zajo](default,)
    

  * Add **ZajoFilter** to your **filters.yml** file. This configuration is not necessarily needed, but it takes care of attaching JavaScript to your Ajax responses. If you don't enable this, you cannot use it in your Ajax responses. 

    
    # generally, you will want to insert your own filters here
    
    ZajoFilter:
      class: ZajoFilter
    

  * Clear cache
    
    $ symfony cc
    

  * In your template, use the ZajoHelper

    
    <?php use_helper("Zajo") ?>
    

Now the plugin should be ready to use. Let's try it in this mini-tutorial.

## Tutorial

This is a small demonstration of principle of ZajoPlugin. 

  * If you don't have one, create a new project, application and module.

    
    $ mkdir zt
    $ cd zt
    $ symfony init-project zt
    $ symfony init-app a
    

  * Install the plugin according to instructions. When you're done, create a new module.

    
    $ symfony init-module a test
    

  * Open generated actions.class.php, remove code inside executeIndex (leave it empty)

  * Open generated indexSuccess.php, add

    
    Hello World!
    

  * Navigate your browser to /web/a_dev.php/test. You should see Hello World message.

  * Now add ZajoHelper, and create a new H1.

    
    <?php use_helper("Zajo") ?>
    <h1>Hello World!</h1>
    

  * If you have everything done properly, there should be no errors now. Let's try an effect.

    
    <?php use_helper("Zajo") ?>
    <h1>Hello World!</h1>
    
    <?php hide("h1", "drop", array("direction" => "up")) ?>
    

  * Reload your page, and the title should disappear! This was jQuery Enchant effect called Drop. 

  * Now let's try something cooler. Let's create a simple form.

    
    <?php use_helper("Zajo") ?>
    <h1>Hello World!</h1>
    
    <div id="r"></div>
    
    <?php echo form_remote_tag(array('url' => 'test/send', 'update' => '#r')) ?>
    
    <input type="text" />
    
    <input type="submit" />
    
    </form>
    

  * So this is very simple form. The url is **test/send** so we have to create send action. Open actions.class.php and add an empty **executeSend** method. Then add **sendSuccess.php** template, and write something like this:

    
    <?php use_helper("Zajo") ?>
    <?php hide("form", "drop", array("direction" => "up")) ?>
    Comment posted.
    

  * This hide effect won't work as the drop effect couldn't be loaded. All effects are loaded automatically when you call them, but when you call an effect from Ajax response, it couldn't be added to the header of page. So you need to add it manually into **indexSuccess.php**:

    
    <?php use_enchant("drop") ?>
    

  * Now if you try to post this form, it should display message 'Comment posted.', and the form should disappear.

## Conclusion

You can discover all the functions of this plugin by checking source code. 

## TODO

ZajoPlugin is not finished yet. It has only those three basic Ajax functions, and visual effects functions (show, hide, toggle, effect). 

  * Implement the rest of Ajax functions
  * Implement whole jQuery UI
  * Create new visual effect helpers, not for direct changing the document, but to use with like 'before' => visual_effect