HerbIgniter User Guide Version 1.7.2

AJAX Helper

The AJAX Helper file contains functions that assist in working with AJAX. AJAX means requests are sent from the browser to repopulate areas, retreive data, etc. It is used to create more advance graphical / interactive user interfaces. There are a couple of terms that HerbIgniter uses to describe what's going on.

JSID: A javascript "id" -- that is to say, literally a piece of a function name (something that does not begin with a number) that is used to differentiate atomic AJAX code.
AJID: An AJAX "id" which is really the id attribute of a piece of HTML that is attached to a <div>, <span> or other tag.

To make this Helper easier to use, we've made transparent functions that make these special strings. The strings are then passed to, or generated within, the atomic AJAX functions provided. This makes it possible to avoid using Javascript while developing basic AJAX-enabled widgets and other remote-HTTP functionality such as triggering other "headless" PHP scripts.

You would use this helper to: create an area in the page that refreshes when clicked, create an area in a page that expands a region when clicked, refresh results in a particular page region based on form input, automatically update an area of a page with fresh results at a given time interval.

Since AJAX is a late-comer to web functionality, we have done our best to provide stability over minification. We assume if you are using a browser that uses AJAX, that your machine was built after 1996 and can handle a few extra bits over your network pipe. Some of the JS it generates is minified. It requires the /js/ folder that comes with HerbIgniter, and it also provides some simple script.ac.ul.us wrappers. More jQuery-type stuff is handled in the Projax Helper.

The AJAX Helper (optionally, and preferably) uses the Page object.

This helper addresses the following types of AJAX operations:

  1. AJAX that is triggered by link
  2. AJAX that is triggered by a form submit
  3. AJAX that is called on regular time intervals
  4. AJAX that is triggered by a jQuery-type drag-and-drop operation or other event.

Loading this Helper

This helper is loaded using the following code:

$this->load->helper('ajax');

The following functions are available:

init_ajax()

You only want to call this function if you want to see a basic AJAX example Javascript, or if you want to write your own AJAX controllers around this function.
Provides code for the Javascript function GetXmlHttpObject(), with compatability for Firefox, Opera 8.0+, Safari and IE.

Example:

$code = init_ajax(); // returns js for GetXmlHttpObject()

unique_ajid( prefix='' )
get_ajid( prefix='' )
unique_jsid( prefix='' )
get_jsid( prefix='' )
unique_ajax( prefix='' )
get_ajax( prefix='' )

This function group is totally optional, and is useful when generating links or other visual interface objects that might activate the AJAX. When you call unique_*() it generates either explicitly AJID, JSID or both. When you call get_*() it returns the last generated ID. These IDs are used for DOM elements and AJAX function names. Each AJAX object (flipper, updater, ajax_div, ajax_element, table, toggler) is assigned a unique AJID and JSID. The global counters for these IDs make each AJAX unique on the page. To route a link to a specified AJAX function, you will need to store the ID of the AJAX function and use it to call with javascript:func_name(). If you want to assign a name to the element, which is sometimes useful when debugging, you can optionally provide a 'prefix' that must remain consistent for referring to both the AJID and JSID of a particular object. The 'prefix' should contain only letters just to be on the safe side, and they shouldn't match the IDs themselves.

Example:

// Generate a unique AJAX object ID. This is called automatically by the AJAX objects toggler(), flipper(), etc
$ajax_id = unique_ajax();

// Generate a unique AJAX object ID with the prefix "hotel" :
$hotel_ajax_id = unique_ajax( "hotel" );

// The most common use of the get_ functions, to create links that trigger the region to repopulate:

$page->append_head( ajax_element_init( here()."/page/param/etc", ""<img src="loading_animated.gif">", "div" );
$page->append_body( ajax_element( ) );
$page->append_body( '<a href="javascript:' . get_ajax() . '()"><img src="refresh.gif" alt="Click to Refresh"></a>' );

ajax_div(page, id, someurl, loading, type='div' )

The parameter id must be unique. Generates Javascript code and places it inside the head of a Page object. Returns code to be placed in the body section. Example:

ajax_div($page,"javascript_function_key",here()."/object/params","Please wait . . .", 'div');

ajax_element_init( url, loading='Loading..', type='div', ajid='', jsid='', params='' )

Provides the javascript code for a <HEAD> section that is unique and provisory for a single AJAX element (usually <div> or <span), one for each region of functionality. You can call this function in a couple of ways. The easiest way is the first example, followed by subsequently more open versions.

Examples:

This example creates a single AJAX region, that is triggered by links and the <div> area is repopulated with content from a URL.

//Simplest way: creates a div, initializes the AJAX, uses a URL to gather data when a link is clicked:

$page->append_head ( ajax_element_init( here()."/page/param/etc" ) ); // Places AJAX initialization code into the head.

// Now that the element is initialized, you must then call this in the appropriate place on the page, but
// also right after you have initialized the element, or else it will be hooked into the wrong object, so it
// is best to keep these two functions paired (or you can call the function ajax( $page, $url ) to do both.

// This way is provided in case you are not using the Page object, but we are using the Page object.
// The Page object could be replaced with echo inside the <body> section.
$page->append_body( ajax_element( ) );
$page->append_body( ajax_element_link( '<img src="myicon.jpg" border=0>' ) );

//or you could do it yourself: $page->append_body();

The following example creates multiple AJAX regions, that are triggered by links and the <div> area repopulated with a URL. The initial link appears inside the area that is going to be repopulated, and is replaced by a new link that calls the reference function, by passing URL variables to the URL that repopulates the <div> area. In this example, we show you how to handle its unique ID in the context of a custom HTML code block, with a custom loading screen.

// Multiple AJAX regions repopulated by links which have parameters that are updated (such as for pagination)

for( $i=0; $i<10; $i++ ) {
$page->append_head( ajax_element_init( here()."/page/param/etc", ""<img src="loading_animated.gif">", "div" );
$page->append_body( ajax_element( ) );
$page->append_body( '<a href="javascript:' . get_ajax() . '()"><img src="refresh.gif" alt="Click to Refresh"></a>' );
}

ajax_element( id='', type='div' )

Provides HTML hooks for the element. You can do this manually (sometimes recommended) or you can use this function. See the above examples for more information. Optionally, you can supply the AJAX id acquired using unique_ajid() or get_ajid()

$page->append_body( ajax_element( ) );

// If you need to specify only the <HTML> element tag for the active AJAX object ids (the JSID and AJID):
$page->append_body( ajax_element( '', 'span' ) );

flipper( page, link, result, title="", action="press enter", cancel="cancel", form="the_form", modal=false )

Increments global JSID and AJID by one. Deploys an AJAX "Flipper" region that can be programmed in a few different ways. This is a two-stage Javascript-controlled section of the page and can be placed inside other structural elements. It is a form, so it uses HTTP post to post the entire page.

Example:

// You can do a couple of different things with the flipper:

// Put some lorem ipsum text in a box that says 'close'
flipper( $this->page, "", lorem_ipsum(5).'<br>', "the form" );

// deploy form flipper without cancel button
flipper( $this->page, "Submit Link Text", "<input type='text' size='50' value=''>", "Click to confirm", "", "" ); // <- Note! You must use "" for result parameter!

// deploy flipper with a form, cancel button and posted on <press enter>
flipper( $this->page, '&uarr; Upload A Track For ' . $album['name'],
"<form enctype='multipart/form-data' action='" . here() . "/band/manage' method='post' name='upload" . $n . "'>
Title<input type='text' name='title' size=50><br>"
. "Price <input name='Price' type='text' value='0.99'><br>"
. hiddens("album",$album['id'])
. "Description<br><textarea name='description' rows=4 cols=50></textarea><br>MP3 file: <input type='file' value='' name='mp3'></form>",
"Click to add a new track!", "Add Track", "cancel", "upload" );

toggler()

Create an AJAX controlled div region that contains a scripted AJAX call to toggle the status of a flag on a MySQL table and update the region to show resulting value (true or false)

Example:

define( SOME_BITVECTOR, 1 );
define( SOME_BIT_VECTOR, 2 );
define( SOME_OTHER_BIT, 4 );

toggler( $this->page, "users_table", "flags_field", SOME_BITVECTOR, "The switch is on.", "The switch is off.", "Flip Switch" );

updater( page, php, delay, type='div')

Establishes updatable visual area updated by a stacked, delayed javascript that calls $php

Example:

updater( $this->page, "echo 'test'", 500, 'span');