AdminLists

Introduction

Geeklog 1.4 has an engine to create tables/lists from data. This engine can be used to make sure that all tabular information looks similar all over the site. It is also helpful to reduce the amount of code that has to be written for a table, including template files.

To use this function, you have to choose between two main differences: Simple & Complex lists. The main difference is that the simple lists need an array of data and the complex lists need an SQL string of data. So if you do not have your data in a database table, you will need to use a simple list. Also, the simple lists only can be displayed several times on a page (such as used on the moderation and statistics screens).

Generally it is recommended to take any of the existing lists and changing the details. This makes sure that you use the required set of data for a complete table.

Simple Lists

The header

The first element of a list is the header, the line where you can read what the information below represents. To define those use an array, each of the elements of the array define one column:

$header_arr = array(
    array(                         // Column 1
        'text' => $LANG10[1], 
        'field' => 'title', 
        'width' => '90%', 
        'header_class' => 'stats-header-title'
    ),
    array(                         // Column 2
        'text' => "", 
        'field' => 'stats', 
        'header_class' => 'stats-header-count', 
        'field_class' => 'stats-list-count'
    ),
);

You can see that you need to create a multi-dimensional array with several fields, most of which are optional. Required are the first two.

Field/Array Name	Content	Data Type	Required
text	The text that the user sees on top of the column	string	Yes
field	The field in the data-array that is used to show the data	string	Yes
header_class	The CSS class that should be assigned to the header field	string	No
field_class	The CSS class that should be assigned to the data fields below	string	No

Text fields & Settings

Then, you need a text-array, defining some other details of the table:

$text_arr = array(
    'has_menu' => false,
    'title' => $LANG10[1],
);

Field/Array Name	Content	Data Type	Required
has_menu	If set to true	boolean	Yes
title	The title of the table. Since the table will be in a block, the block needs a title	string	Yes
help_url	The url that shows help for the block	string	No
form_url	The form used in case the menu is there	string	if has_menu=true
icon	An Icon to be displayed	string	No
instructions	Some text to explain how the table works. This only shows if has_menu = true	string	no
no_data	The string that is shown in case the table is empty. If this is not given, $LANG_ADMIN['no_results'] is shown	string	No

The Menu

In case the $text_arr stats has_menu = true, you need to give the following array for the menu details:

$menu_arr = array(
    array(                         // Menu Item 1
        'text' => $LANG10[1], 
        'url' => 'http://...'
    ),
    array(                         // Menu Item 2
        'text' => $LANG10[2], 
        'url' => 'http://...'
    ),
);

This pretty straight-forward Array gives a text to display and a url to link for each desired menu item. The next array is called $form_arr and is optional:

Additional Form Fields

$form_arr = array(
    'top' => '<input type="hidden" name="text" value="text">',
    'bottom' => '<input type="hidden" name="text" value="text">'
);

This optional array allows you to display additional information above and below the table, specifically for form elements such as extra buttons, dropdowns, explanatory texts etc, since the tables have a form around them. Please take a look at the templates under /layout/professional/admin/lists/list.thtml to understand what you can do with them. Those forms are used for example in moderation.php.

The Data

The actual data is given through an array that holds one element for each cell.

$data_arr = array();
$data_arr[] = array(
    'title' => $LANG10[2], 
    'stats' => COM_NumberFormat ($totalhits)
);

This would create one line in the table. You can extend the array as you wish, but each field must match the fields given as 'field' the $header_arr().

Manipulating data during display

If you display data, you might want to manipulate it, depending on other data, accessrights, add buttons instead of values etc. For this, you can name a function and include the name in the call of the list. You could of course process the data beforehand. This function allows you however to skip the iteration of each field in the array. You simply define the rules and the list-creator does all for you. The function will be called for each single field in the array.

$fieldfunction = "plugin_getListField_mypluginname";

Then, you write a plugin function and name it as before, the function variables MUST be the same as below:

/**
* Function used to manipulate fields in admin lists
*
* @param    string  $fieldname      (column-) Name of the currently processed field in the table as defined in the $header_arr
* @param    string  $fieldvalue     Value of the currently processed field
* @param    array   $A              array with the complete current table line
* @param    array   $icon_arr       array with html of std. icons, edit, copy, list
* @return   string                  output of new fieldvalue
*
*/
function plugin_getListField_mypluginname($fieldname, $fieldvalue, $A, $icon_arr) {
    global $_CONF, $LANG_ACCESS;

    $retval = '';
    // lets get the current accesrights the field has assigned
    $access = SEC_hasAccess($A['owner_id'],$A['group_id'],$A['perm_owner'],$A['perm_group'],$A['perm_members'],$A['perm_anon']);
    if ($access > 0) {
        switch($fieldname) {
            // lets make a link to edit the current entry
            case 'edit':
                if ($access == 3) {
                    $retval = COM_createLink(
                        $icon_arr['edit'],
                        "{$_CONF['site_admin_url']}/plugins/mypluginname/index.php?mode=edit&id={$A['id']}"
                    );
                }
                break;
            case 'access':
                if ($access == 3) {
                   $retval = $LANG_ACCESS['edit'];
                } else {
                   $retval = $LANG_ACCESS['readonly'];
                }
                break;
            case 'title':
                // create a link to an item from the url in the data
                $retval = COM_createLink(stripslashes($A['title']), $A['url']);
                break;
            default:
                // otherwise simply output the value as is
                $retval = $fieldvalue;
                break;
        }
    }
    return $retval;
}

Calling the function

You can call the function as follows:

echo ADMIN_simpleList($fieldfunction, $header_arr, $text_arr, $data_arr, $menu_arr, $options, $form_arr);

The returned HTML will include the full list with all the options that you selected before.

... To be continued