ezjscore: eZ Publish JavaScript and Ajax framework

YUI 3.x

YUI 3 is Yahoo!'s next-generation JavaScript and CSS library. It was a complete re-design from YUI 2 to be lighter, faster, and easier to use. The new code style enables you to accomplish more with less code. In the new sandboxed approach, all loaded YUI modules are bound to the YUI instance when called with use(); this protects against changes that might happen later in the page’s life cycle. ezjscore provides easy access to the YUI 3 instance within templates. One difference in the ezjscore integration as compared to YUI 2 is that ezjscore includes a wrapper for a more abstracted server call from YUI 3. Let's take a look at a practical example.

First, we need to load the YUI 3 seed:

{ezscript_require( 'ezjsc::yui3' )}

This will provide a basic YUI 3 loader, which is used to load any module in the library on the fly. It also generates a global YUI3_config variable that tells YUI where to load the scripts from based on settings in ezjscore.ini.

Now that the script is available, we can start using YUI 3 immediately. We use YUI's "node" utility for DOM manipulation:

<script type="text/javascript"> 
<!-- {literal} 
  YUI( YUI3_config ).use('node', 
                         function( Y ) 
                         {
                           Y.on( "contentready", 
                                 function( e )     
                                 {         
                                   // What to do, what to do..   
                                 }); 
                         });
//--> 
</script>

YUI3_config can be used to load custom YUI scripts or CSS files that are required for the current instance. For full configuration information, see the YUI 3 loader documentation [http://developer.yahoo.com/yui/3/yui/#loader]

For IO operations such as Ajax calls, ezjscore provides a handy wrapper for the YUI 3 IO component [http://developer.yahoo.com/yui/3/io]. The wrapper has a pre-configured path to the eZ Publish router that receives calls and returns the output; the default output is a parsed JSON object since the default request is for the JSON format.

The following template code, taken from the ezjscore_demo extension, demonstrates the use of the IO wrapper in performing a simple search call:

{* On demand require some custom css *} 
{ezcss_require( 'ezjscdemo.css' )}  

{* 
  Some simple html where we want to 
  load some content from server 
*}
<div id="hello-world-id" class="my-custom-css-class"> 
  Waiting for ezjscore ajax call... 
  (See FAQ if you get script error and / or nothing happens! hint: permissions ) 
</div>

{* 
  On demand require YUI 3.0 loader file 
  and ezjscore's YUI.io.ez 
*}
{ezscript_require( array( 'ezjsc::yui3', 'ezjsc::yui3io' ) )}

Notice the ezjsc::yui3io item in the array. This is the io-ez YUI 3 module provider, which we must also load. This is done by adding the io-ez parameter in the use() function.

{*
  Use more or less standard YUI 3.0 code, only custom ezjscore bits are:
  YUI3_config : global yui configure object as dynamically created "ezjsc::yui3"
                based on cdn and script location settings in ezjscore.ini
  YUI.io.ez   : Simple wrapper for YUI.io created dynamically by "ezjsc::yui3io"
                so you don't have to deal with the url to the server.
*}
<script type="text/javascript">
{literal}
YUI( YUI3_config ).use('node', 'io-ez', function( Y )
{
    Y.on( "contentready", function( e )
    {
        // Parameters can be sent as post data ('arg1=hi!') or as 
        // call parameter (eg: "ezjscdemo::search::hello" )
        // Use post for string values to not end up reaching url path limit..
        Y.io.ez( 'ezjscdemo::search', {
            data: 'arg1=hi!',
            on: {success: function( id,r )
                { 
                    if ( r.responseJSON.error_text )
                        Y.get( '#hello-world-id' ).setContent(
                            r.responseJSON.error_text
                        );
                    else
                        Y.get( '#hello-world-id' ).setContent(
                            r.responseJSON.content
                        );
                }
            }
        });
    }, '#hello-world-id' );
});
{/literal}
</script>