Ajax List

The Ajax List component of iPeer is responsible for creating lists from data. It is implemented as a Cake PHP component, and works with cake-like formated data.
The advantages of Ajax Listinclude quick list control creation, with features default like filters, sorting, pagination, state retention, and search. The amount of initial set up is usually minimal. As Ajax List is a single component, any list-related bug in iPeer can be traced down to this component, and fixed. There are some mechanisms to extend the list's functionality, but moderate to highly custom features could require code modifications to Ajax List.

Requirements

• For best results, PHP 5.2 is recommended:
  • PHP 5.2 needs no extra configuration.
  • PHP version bellow 5.2 should compile, and enable the PHP JSON plugin to achieve best performance.
  • A much slower version of JSON parce is included with iPeer, and will be used if all the above are missing.
  • A session component is required to keep track of a list' state. Ajax List uses CakePHP's Session component.
  • If possible, the client's browser should leave the cookies enabled, so that Ajax List can keep track of what page number the client is on.

Files

Ajax List consists of 3 files.

• \app\controllers\components\ajax_list.php
  • Holds the PHP side of Ajax List code.
  • Contains functions to initialize the list, creation of SQL queries, code to query the database for the data to be listed, converting data to JSON for Javascript client, and general list state management.
• \app\views\elements\list\ajaxList.tpl.php
  • The elements that is inserted into the pages view where the list is to be created.
  • Passes the list data to the JS Ajax List component, making an initial ajax call unnecessary.
• \apps\webroot\js\ajaxList.js
  • The JavaScript component Ajax List. Interprets the JSON, and renders the list as a table, along with the search control, and etc..

Manual

Instantiation

There is usually a single list per controller in cakePHP. The first step should be to include the ajax List component into your controller, but declaring a $components variable, inside the controller class.

var $components = array('AjaxList');

If the $components variable already exists, just add the ajax list to the array:

var $components = array('ExistingComponenet1', 'AjaxList', 'ExistingComponenet2');

Next, add your model to the $uses array, in the same fashion as the components above: var $uses = array('ListedModel');

Next, create the following 3 functions in the controller:

// 1) Sets up the data for the ajax list.
function setUpAjaxList () {

    // Which columns to list, and include data from.
    $columns = array();
    // The available actions for each column
    $actions = array();
    // Any extra filtering to perform on the data from the database.
    $extraFilters = "";
    // Any tables to join in, and any extra filters to implement on those tables
    $joinTables = "";
    // Whether to fetch associated data or not ( (-1) means not at all ).
    $recursive = (-1);

    // Call the Ajax List components to fetch data and other list variables,
    //  and set them up for the view.
    $this->AjaxList->setUp($this->ListedModel, 
       $columns, $actions,
       "ListedModel.id",  // Initial Sorting Column
       "ListedModel.id",  // Initial Search-by column
       $joinTables, $extraFilters, $recursive);
}

// 2) Processes an Ajax request from the client.
function ajaxList() {
    // Set up the list
    $this->setUpAjaxList();
    // Process the request for data
    $this->AjaxList->asyncGet();
}

// 3) Creates the initial list to display by the client
function list() {
    // Set up the basic static ajax list variables
    $this->setUpAjaxList();

    // Set the display list for render by the view
    $this->set('paramsForList', $this->AjaxList->getParamsForList());
}

Bellow sections describe the variables that are defined in setUpAjaxList() function.

Columns

The $columns va

Actions

Extra Filters

Join Tables

Join Table Filters

Data Post Processing

Example list

The following example demonstrates most of the features of Ajax List.