AJAX (jQuery) + eZ Publish: Demystified!

This is a short tutorial about using the powerful combination of AJAX (jQuery) and eZ Publish. Please note this was also originally released before the REST API was developed for the current community release of eZ Publish.

Original post:  http://blog.divdesigns.com/2011/02/ajax-jquery-ez-publish-demystified/

eZ Publish is by nature, easy to understand in the administration panel, adding and editing content. However, once you look under the hood it's like a complex maze of code, intricately designed, but still a maze. While the template code, based on Smarty I believe, is well documented there's no single source to figure out how things work in PHP land.  You just find out for yourself by looking through other extensions as well as the kernel code, ask other people or by just plain "elbow grease." Well here's some findings I came across fumbling around on a project as well as spare time.

Tutorial Skill requirements:

• JS
• eZ Publish
• PHP
• Extension/Module/View installation & configuration

If you need to head over to eZ Systems' site for more information on installing and configuring an extension

Discovery

I came across two main ways to implement AJAX (jQuery) with eZPublish.

• AJAX + a Custom Module
• AJAX + eZJSCore + a Custom Class (implementing a special type of ezjscore class)

Which offers the most flexibility?

• Both allow access to the eZ Publish class interface
• Module approach allows flexibility of having a view associated with the AJAX functionality thus allowing up to three avenues of functionality for the script to run as. (AJAX Post + Regular Post + View)
• Module approach allows access to the Module parameters array. (This allows one to use AJAX calls in an unconventional way using a post to /mymodule/param1/param2/param3 which isn't recommended)
• eZJSCore approach has cleaner, more concise code.
• eZJSCore approach allows for multiple functions in the class (don't forget to register your other functions in the INI files!) as opposed to a one-time run-through with the module approach. Although you can add other functions to a module, eZ Publish requires you to  add a separate PHP file.
• Anyone find something else I'm missing?

Show me the Code!

AJAX + Custom Module:

So obviously you need a module and a view (and thus an extension). By looking at the JavaScript you'll see the module and view names I used. You can use whatever you want.

The JavaScript:

var data_sent = { message: "testing!"};$.ajax({    url: "/mymodule/post",    type: 'POST',    data: ( data_sent),    dataType: 'json',    success: function( data ){        if( data.response == "ok" )        {            alert( data.message );        }    }});

The Module code:

In post.php I usually have something along the lines of this initial setup:

if ( $http->hasPostVariable( 'message'' ) && $http->postVariable( 'message' ) ){    $response = array( 'response' => 'ok');    print( json_encode( $response ) );    eZExecution::cleanExit();}

That's IT!

AJAX + eZJSCore + Custom Class:

This approach requires you have eZJSCore installed and working.

One of the first things you'll notice with this approach by looking at the code is there's a little more of it, but it looks cleaner in the JavaScript code.

To get eZJSCore setup add your custom class to ezjscore.ini (preferably in your extension's settings directory):

[ezjscServer]FunctionList[]=ajaxFunc[ezjscServer_myajax]Class=MyAJAXFile=extension/myextension/classes/myajax.phpFunctions[]=ajaxFunc

The JavaScript:

//You can keep going with the argsvar  dataSent = {arg1: "123", arg2: "456"};$.ez(  'myajax::ajaxfunc', dataSent, function( ezp_data ){    if ( ezp_data.error_text )    {        alert( ezp_data.error_text );    }    else    {        alert( ezp_data.content );    }}

Custom PHP Class setup:

class MyAJAX extends ezjscServerFunctions{    public static function ajaxFunc( $args )    {        if ( isset( $args[0] ) && isset( $args[1] ) && isset( $args[2] ) && isset( $args[3] ) )        {            $var1 = htmlspecialchars( $args[0] );            $var2 = htmlspecialchars( $args[1] );            $var3 = htmlspecialchars( $args[2] );            $var4 = htmlspecialchars( $args[3] );        }        else if ( $http->hasPostVariable( 'arg1' ) && $http->hasPostVariable( 'arg2' ) && $http->hasPostVariable( 'arg3' ) && $http->hasPostVariable( 'arg4' ) )        {            $var1 = htmlspecialchars( $http->postVariable( 'arg1') );            $var2 = htmlspecialchars( $http->postVariable( 'arg2') );            $var3 = htmlspecialchars( $http->postVariable( 'arg3') );            $var4 = htmlspecialchars( $http->postVariable( 'arg4') );        }        else        {            return $error['args'];        }        return "ok";    }}

Use for debugging via HTTP:

http://dev.server.com/ezjscore/call/myajax::ajaxfunc::val1::val2::val3::val4

eZ Find + AJAX = Lightning Fast?

eZ Find definitely has its advantages and it would be a good idea to use eZ Find for large data sets.

Until then, get used to using the template code outlined in Ivo Lukac's guide to using eZ Find. There you can also find the advantages and disadvantages of eZ Find.