Open Source | Technology | Web

Front-end strategy in eZ Publish. Part 2: AJAX

Asynchronous JavaScript And XML techniques are very useful and famous technologies. They allow us to create web applications that provide a method for exchanging data asynchronously between browser and server while avoiding full page reloads.

The first part of this article defined some ideas about how to use eZ JS Core extension generally.

This blog post will describe best practices for using AJAX within eZ Publish.

AJAX in action

Let’s build a web page to search ez content objects using the ezjscore extension..

Configuration
1. First create an extension, for example nxc_ajax_search_example, where all examples will be placed. (There you can find tutorial how to create extensions: http://share.ez.no/learn/ez-publish/an-introduction-to-developing-ez-publish-extensions)

https://github.com/nxc/nxc_ajax_search_example

2. Second, create design

Allow designs in our extension.
https://github.com/nxc/nxc_ajax_search_example/blob/master/settings/design.ini.append.php

Create the main template (can be empty for now) for design ajax_example
https://github.com/nxc/nxc_ajax_search_example/blob/master/design/ajax_example/templates/pagelayout.tpl

3. Create siteaccess to use created design

https://github.com/nxc/nxc_ajax_search_example/blob/master/settings/site.ini.append.php
https://github.com/nxc/nxc_ajax_search_example/blob/master/settings/siteaccess/ajax_example/site.ini.append.php

4. Activate the extension:

settings/override/site.ini.append.php

Source code    
  1. [ExtensionSettings]
  2. ...
  3. ActiveExtensions[]=nxc_ajax_search_example

5. And clear caches

Source code    
  1. php ./bin/php/ezcache.php --clear-all

6. Now we can test it by accessing the web page.

http://example.site/ajax_example

If you see parsed html from pagelayout.tpl then everything is ok.

MVC Implementation

Now that general configurations are complete we can focus on think search ing content objects with ajax.

Model

To process actual searching we will use standard eZ Publish functionality:

Source code    
  1. $searchResult = eZSearch::search( $keyword, $params );

View

1. Prepare pagelayout:

https://github.com/nxc/nxc_ajax_search_example/blob/master/design/ajax_example/templates/pagelayout.tpl

Source code    
  1. <html>
  2.     <head>
  3.         {ezcss_load()}
  4.         {ezscript_load()}
  5.     </head>
  6.     <body>
  7.         {$module_result.content}
  8.     </body>
  9. </html>

$module_result.content – this will return result data from module.

ezcss_load – template operator that loads css files
ezscript_load – another template operator to load javascript files.
These operators will produce proper includes of provided files in header of the page.
By default it does nothing, to use it need to call ezscript_require or ezcss_require operators.

2. To illustrate mechanism of using ezjscore handler we override standard and base template to view nodes, for example purposes.

Create https://github.com/nxc/nxc_ajax_search_example/blob/master/design/ajax_example/templates/node/view/full.tpl

This template will contain following elements:
– Input element to enter a text
– Button to proceed
– And a block where search result will be stored.

3. To create binds and handle ajax calls create a javascript file.

Lets name it search.js (can be empty now):
https://github.com/nxc/nxc_ajax_search_example/blob/master/design/ajax_example/javascript/search.js

4. Next to add this file to our page somehow.
For this purpose eZ JS Core provides ezscript_require template operator.

So just add this to our template:

Source code    
  1. {ezscript_require( array( 'ezjsc::jquery', 'ezjsc::jqueryio', 'search.js' ) )}

Just as an example we use jQuery also YUI can be used there.

As a result full.tpl contains:

Source code    
  1. {ezscript_require( array( 'ezjsc::jquery', 'ezjsc::jqueryio', 'search.js' ) )}
  2. <input name="q" class="text"/><button class="search">Search</button>
  3. <div class="result"></div>

5. Time to test it. If you open the page http://example.site/ajax_example you should see html like:

Source code    
  1. <html>
  2.     <head> 
  3.         <script type="text/javascript" src="/var/site/cache/public/javascript/70d9a012346dc40d81637fbb2efc7e63.js" charset="utf-8"></script>
  4.     </head>
  5.     <body>
  6.         <input name="q" class="text"/><button class="search">Search</button>
  7.         <div class="result"></div>
  8.     </body>
  9. </html>

As you can see all scripts are packed to one file.

Controller

To code javascript handlers for gui purposes we need to think how we are going to access the data. It must be by ajax.

But how should its controller look?

Basically there are at least 2 ways
1. Module/View, also can be combined with eZ Publish layouts, for example /layout/set/custom_ajax_layout/nxc/ajax or /layout/set/custom_ajax_layout/content/view/full/999
2. eZ JS Core: for example using jQuery.ez()

Module/view controllers

Usually developers prefer to use first way to create custom module/view.

Lets see how it will look for our task.

1. Create module
https://github.com/nxc/nxc_ajax_search_example/blob/master/settings/module.ini.append.php

And view:
https://github.com/nxc/nxc_ajax_search_example/blob/master/modules/ajax/module.php

2. Prepare view and implement the controller logic:
https://github.com/nxc/nxc_ajax_search_example/blob/master/modules/ajax/search.php

Implementation of logic is extremely simplified:
– Get requested keywords
– Do searching
– Print list of found nodes.

3. The last step is to implement ajax calls.

https://github.com/nxc/nxc_ajax_search_example/blob/master/design/ajax_example/javascript/search.js

Please take a look to bindModuleView() function.

Summary

This method of building controllers is pretty common, but it has few weaknesses:

1. There is a need to create additional module/view for each call when we want to access the data.
2. After that “raw” js is produced for ajax calls and have to take care about urls and format in requests/responses per each call.
3. It is quite hard to use TDD and create unit test cases for this kind of controller.
4. eZ Publish module view requires to use a hack like eZExecution::cleanExit(); to terminate the execution.
5. A developer has to take care about urls, for example if ajax url does not include siteaccess some templates can be not found and no result data will be available. This error is not easy to catch because the developer always has to check that all templates are accessible.

eZ JS Core controllers

It allows us to fix problems from previous methodology and provides techniques to increase quality of the web application in generally.

1. Define eZ JS Core server
https://github.com/nxc/nxc_ajax_search_example/blob/master/settings/ezjscore.ini.append.php

2. Implement searching
https://github.com/nxc/nxc_ajax_search_example/blob/master/classes/ajaxSearch.php

3. Create javascript handlers for this controller
https://github.com/nxc/nxc_ajax_search_example/blob/master/design/ajax_example/javascript/search.js
Please take a look to bindJSCore() function.

4. Regenerate autoloads

Source code    
  1. php ./bin/php/ezpgenerateautoloads.php -e

Summary

This is built in and default ajax methodology in eZ Publish and usually it is quite good idea to use the same way on your custom solutions.

- This method does not require additional coding and configurations. Like ini settings (expect eZ JS Core Servers), or if we copy content of ajaxSearch::search() function to module:
https://github.com/nxc/nxc_ajax_search_example/blob/master/modules/ajax/search.php

It standardizes all calls and format of data and allows us to use TDD techniques and OOP features. This decreases development and debugging time because it allows us to do unit, functional and regressions testing automatically. It also keeps your code clean and documentable with the ability to easily modifify it later.

LINKS

http://blog.nxcgroup.com/2013/front-end-strategy-in-ez-publish-part-1-cascading-style-sheets-and-javascript/

http://en.wikipedia.org/wiki/Ajax_(programming)

http://en.wikipedia.org/wiki/Test-driven_development

http://en.wikipedia.org/wiki/Model–view–controller

http://blog.nxcgroup.com/2012/testing-ez-publish-extensions-using-phpunit/

http://share.ez.no/learn/ez-publish/an-introduction-to-developing-ez-publish-extensions

Print this post

0 Responses to "Front-end strategy in eZ Publish. Part 2: AJAX"

Post a Comment:

Get latest news