[[PageOutline(2-7, Table of Contents, floated)]]
== 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.[[br]]
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:
{{{
#!php
// 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);
}
}}}
{{{
#!php
// 2) Processes an Ajax request from the client.
function ajaxList() {
    // Set up the list
    $this->setUpAjaxList();
    // Process the request for data
    $this->AjaxList->asyncGet();
}
}}}
{{{
#!php
// 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:
{{{
#!php
$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:
{{{
#!php
$actions = array(
   array(<action 1 name>, [warning message 1], [restrictions array 1], [controller 1], <function>, [param 1 [, param 2am 3 etc...]]]),
   array(<action 2 name>, [warning message 2], [restrictions array 2], [controller 2], <function> [, param 1 [, param 2 etc...]]]),
   [etc...]
);
}}}
 * '''Action Name''' - The name of the action shown to the user. Best to decide on one, and leave it be, since this name is referred to by some other parts of Ajax List (Action-type columns, for example). Required.
 * '''Warning Message''' - A message that will show up, asking the user to confirm the action. Enter {{{""}}} if unused.
 * '''Restrictions''' - An array containing any restrictions on the action based on the entry's map column types, more on this bellow. Enter {{{""}}} if unused.
 * '''Controller''' - If the target controller is ''not'' the same as the controller this Ajax List is in, specify it here. Otherwise, enter {{{""}}}.
 * '''Function''[ - The name of a function to execute in the present controller on the action. Required.
 * '''Param 1,2,3''',etc... - The parameters passed to a controller function. If you specify a {{{Model.column}}} type string, Ajax List will try to substitute that entry's column for this parameter, meaning that you can specify actions based item id's in the list. If the column is not found, the string will be given at the parameter literally.

===== Action Restrictions =====
If an action is restricted for an item, if will be greyed out and disabled when the user right-clicks the action menu. Now, this doesn't mean that the user can't manipulate the URL to try and execute this function anyways, so it's a very good idea to put some access restrictions in the controller functions themselves.
The access restriction array is (again :-) an array or array, and has the following general format
{{{
#!php
   $actionRestrictions = array(
      <Column ID 1> => array (
         <map entry 1> => <true / false>,
         <map entry 2> => <true / false>,
         <map entry 3> => <true / false>,
         [etc...]
         "!default"  => <true / false>),
      <Column ID 2> => array (
         <map entry 1> => <true / false>,
         <map entry 2> => <true / false>,
         <map entry 3> => <true / false>,
         [etc...]
         "!default"  => <true / false>),
     [etc...]
);
}}}
Every column ID corresponds to a map-type column. When the column's entry (raw, not yet translated), marched the map entry's in the above structure, then the boolean true or false varible will deterime wherether the user is allowed to perform an action. The "!default" map entry takes effect when the column's cell contents don't match any of the other entries. For example, the following real example is taken from the user's controller, designed to allow instructors to only edit students, and not other user types
{{{
#!php
   $actionRestrictions = array(
      "User.role" => array (
         "S" => true,              // Allow modification of students
         "!default" => false));    // Dis-allow modification for all other user types
}}}
==== Extra Filters ====
The extra filters variable can either be an array or a string. If it's a string, it's put in literally, and after the WHERE clause in an SQL statement, along with other filters in the list.
If the extra filters is an array, it is put in as:[[br]]
{{{WHERE key1=value1 AND key2=value2 AND key3=value3 AND etc...}}}[[br]]
for an array like:[[br]]
{{{ $extraFilters = array(key1 => value1, key2 => value2, key3 => value3);}}}

==== Join Tables ====
Joining in table in Ajax List lets you bring in other relevant data into your list. You can look up course name by their id's or check with classes the student is enrolled in.

All joins are LEFT JOINs. One-to-one joins are supported the best, and can be used to look up a name using an id, and so forth. One-to-many joins a little more complex, since number on items in the list won't increase to accommodate the "many" entries". However, an extra filter or a join filter (bellow) can be used to isolate items of interest from the join. Otherwise, a {{{GROUP by Model.id }}} statement is issued  to automatically group those "many" items back into one item per original list entry.

If simply joining in tables, without join filter, the $joinTable array contains an array for each table joined in:
{{{
#!c
$joinTables = array(
   array( "joinTable" => "table_name", // The name of the table to be joined in
          "joinModel" => "Group",
          "localKey" => "group_id"
}}}

==== Join Table Filters ====

==== Data Post Processing ====

=== Example list ===
The following example demonstrates most of the features of Ajax List.