History: Ajax

Related: ((No Javascript)), ((jQuery))

''These notes are currently being updated (July 2010).''

! Features benefiting from AJAX

* ((Toolbar|Toolbars)) (formerly known as Quicktags)
*((Menus)) administration
* ((Modules)) administration
* ((Inter-User Messages))
* ((Calendar))
* ((Application Wiki|wiki))
** Editing pages
** tiki-listpages.php
** save draft feature
** ((auto save))
* ((File Gallery))
* ((Trackers))
* ((Webmail)) / ((GroupMail))

---
!+ Wishlist
!!+ Open
{wishes filtervalue="148" status="o"}
!!- Pending
{wishes filtervalue="148" status="p"}
!!- Closed
{wishes filtervalue="148" status="c"}


---
!- Using AJAX in Tiki

{BOX()}
__THIS SECTION IS MOSTLY OR COMPLETELY OUTDATED.__
{BOX}
The AJAX infrastructure is mostly implemented in tiki-jquery.js ( $.fn.loadService, $.fn.tikiModal and functions ajaxLoadingShow() and ajaxLoadingHide()). The backend part is in tiki-ajax_services.php and the Service_Broker class. db/config/controllers.xml maps AJAX controller names to the classes implementing them.

''Old notes - needs updating''
!! Getting started

__To use ajax in tiki:__

In php file, after including tiki-setup.php:

^ ''require_once("lib/ajax/ajaxlib.php");''^

this will import xajax and declare in global scope $ajaxlib, an instance of TikiAjax, that's an extension of xajax class.

Before calling $smarty->display("tiki.tpl"):

^ ''$ajaxlib->processRequests();''^

you don't need to worry about assigning getJavaScript() to smarty or any client-side declaration, everything is already handled by tiki.

To declare and register ajax functions in server, create a php file in lib/feature called feature-ajax.php. In this file, declare the functions and register them with $ajaxlib->registerFunction(). If you need a javascript file, create file lib/feature/feature-ajax.js to hold these functions.

!! Ajax development guidelines

Ajax applications don't work for everybody. It breaks accessibility, don't work with some alternative or old browsers. Considering that, tiki ajax development guidelines aim to:

# keep it simple to preserve tiki funcionality and layout with and without ajax
# avoid forking code

!!! 1 - Template-based common layout

The look & feel of a page must always be the same with or without ajax, and defined by template. Changing the template should change both modes at once as long as html element ids are preserved.

!!! 2 - Load content statically first time

If you are delivering empty containers with smarty and then have a document.onload() to load data, then you're likely to be breaking directive #1. Load content as if there was no ajax, and then when user request more content you update html element's properties.

!! Tutorial - make a region dynamic

!!! 1- Identify template component

find in your template the block of code that you want to be dynamic. 

cut that code, paste in a new template ($includeFile in this example) and include inside an html element:

{CODE()}
<div id="elementId">
   {include file=$includeFile}
</div>
{CODE}

!!! 2- Change your tpl to use {ajax_href} block in links

Now, edit your template and change links like this:

 ^''<a href="tiki-feature.php?param=value..">''^

to

 ^''<a {ajax_href template=$includeFile''
''htmlelement=$elementId}tiki-feature.php?...{/ajax_href}>''^

where $includeFile is the template to be loaded, and $elementId is the id of element in which template will be loaded.

^__ tip__: use doc/devtools/make_ajax_template.pl to apply a regular expression to the template. edit the file and set correct parameters, then make a backup and call

 ''./doc/devtools/make_ajax_template.pl templates/tiki-something.tpl''
^

!!! 3- Modify php file to process requests

in beginning of php file, after tiki-setup.php, put:

 ^''require_once("lib/ajax/ajaxlib.php");''^

and at end, before $smarty->display() or any output, register the templates you want to be loaded dynamically and process requests:

 ^''$ajaxlib->registerTemplate($template);''
 ''$ajaxlib->processRequests();''^

that's all!

! Todo

* --remove lib/cpaint and ajax/ after community approval--

* reimplement --tiki-admin_quicktags.php-- and tiki-listpages.php without splitting files

* configure a frequence for each module to be dynamically updated
*Rewrite this page's Using AJAX section