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(
        array("ListedModel.id"),
        array("ListedModel.value"),);
    // 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());
}

The new list can be accessed from the URL:http://server/your-app/controller/list. If you'd like to change the name of the function that renders the list, just change the list() function's name (but leave the others as they are :-).

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

Columns

The $columns variable is an array of arrays. Each entry in the top array described a column. Each column entry is an array itself. The is the general format is the following:

$columns = array(
    array(<Model.column 1>[, <Column Name 1>[, <CSS width of column 1>[, <column 1 type>> [, column 1 type parameters]]]]),
    array(<Model.column 2>[, <Column Name 2>[, <CSS width of column 2>[, <column 2 type>> [, column 2 type parameters]]]]),
    [ etc...],
    );

• Model.column - The CakePHP column id, in the format Model.column. This corresponds to the table.column format of the SQL database. This is the only required column in the column array entry, but it must be inside the an array, even if it's the only one.
• Column Name - The column name will be displayed to the user. It is used in the table headers, as well as the search-by-field descriptions. If this field is left out, the user will see the Column.id instead.
• CSS width of column - This entry is applied to inside the tableColumn.style.width CSS property of each column. By default, the value "auto" is used, which means that all columns are equally spaced. I would like to recommend that:
  • The exact width be defined for all columns, but one. That is, leaving one column (who's entries are the lonest) as auto will give the best consistent look of the table as its data changes.
  • Use "em" units for to define column widths. "em" are about the size of 1 text line height at present zoom level, and scale better than inches of pixels. Example "10em".
• Column Type - This field describes the type of data entered. Depending on the type, Ajax List may do some processing of data, or display it in a different way, or tie and action to it. The default type is "string", which is inert. The possible types are
  • string - The basic type. The value is display just like it appears in the database.
  • number - Specifies a numerical value. In the present implementation, it acts like a string, but Ajax List could be extended in the future to search for greater or lesser numbers instead of just equivalents . So it's a good idea to specify numerical columns are "number" and not as "string".
  • map - this is a dictionary look-up type. It takes the column entry to be a key, and look it up in an associative array. This array is passes as a Column Type Parameter, following the column type. For example, the following is used in the users controller to translate entries like "A", "S", and "I" to "Admin", "Student", and "Instructor", respectively.
    • array("User.role", "Role", "6em", "map", array( "A" => "Admin", "I" => "Instructor", "S" => "Student")),
    • The general format for this column is: array(<Model.column>, <Column Name>, <CSS width of column>, <column type>, array(<key1> => <meaning1>, <key2> => <meaning 2>, etc...),
    • An extra feature of the map is that the JS AjaxList client also creates a drop-down filter for it. In this way, the end-user can choose to selectively view the mapped types, or all the types at once. In the iPeer's users controller this is used to switch the view between Admin's, Instructors, and Students.
    • If the column contents is not a valid key in the supplied dictionary, the entry is listed, and unknown keyword appears beside.
  • hidden - this type simply defined a column whose data are passed to the client, but not displayed in any way. For example, if you'd like to pass the entry ID to the client, for use in actions, but would not like the user to see it, you could define the column like this:
    • array("ListedModel.id", "", "", "hidden),
    • There are a few reasons to do this, If you'd like to use this column's data:
      • In an action (explained bellow), but don't want the data itself to show up.
      • In data post-processing. The column which do not appear in the columns array are not present when the data is given to the custom post-processing function.
  • action - Display the cell contents as a link, which, when clicked by the user, performs the action specified. The Type Parameter field is the Action's Name (the first value in the actions array).
  • link - the entry is a link, which will be display either as a text link, or a link icon. If the Column Type Parameter is specified, it should be the name of the icon file inside the {webroot/img/icons folder, and if it's left out, the link is displayed as text. An example column entry from iPeer's courses controller:
    • array("Course.homepage", "Web", "4em", "link", "home.gif"),

Actions

The Actions array is an array-of-arrays that lets you define a set of actions for each entry in the list. These will be accessible when the user right click an action item. The general syntax for the actions array is:

$actions = array(
   array(<action name>, [warning message], [restrictions array], [controller], [parameter 1 [, parameter 2[, parameter 3 etc...]]]

Extra Filters

Join Tables

Join Table Filters

Data Post Processing

Example list

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