Karma's Nucleus DevBlog

In this post, I'll try to explain what the showlist function in ADMIN.php is for, and how it works. Next to that, I'll also explain what the ENCAPSULATE, BATCH and NAVLIST are for. I'm not exactly sure if I did a good job explaining this in a clear way, but at least I tried :)

How batch operations work, is a topic for a future article.

General Idea

The idea behind all of this is simple: provide an easy way to include dropdowns or tables based on the result of a query. Suppose one wants to include the list of users in a dropdown. There would be two ways to do this:

1. Execute the SQL query and then walk through all values, spitting out the HTML code needed for a dropdown.
2. Call showlist($sqlQuery, 'select', $aExtraInfo).

The advantage of the second solution is that it can be re-used for all dropdowns (users, categories, ...). Next to that, the showlist function also renders tables.

If you're familiar with ASP.NET, you could sort of compare this to adding a DataGrid or DropDownList control, and using databinding to attach an SQL query to it.

The showlist function

This method has been in Nucleus ever since the admin area was created. If you would look at the code of Nucleus v0.70, you would find it. The code has changed a little since then, though. This post talks about the implementation in Nucleus v3.1.

Let's start with an example, which might help you to follow more easily.

$query =  'SELECT mname as text, mnumber as value'.
         ' FROM '.sql_table('member');
$template['name'] = 'memberid';
$template['tabindex'] = 10000;
$template['current'] = 1;
showlist($query, 'select', $template);

Three arguments are given as input to the showlist function:

1. $query - This can be either an SQL query, or an array of values. In the case of an SQL query, the method will walk through all the query results. For an array, it will walk through all of its values (which should be objects).
2. $type - This can be one of two values: select (HTML dropdown) or table (HTML table).
3. $template - an associative array, containing extra info on how to render things. See below.

The keys of the $template array for a select type list are as follows:

• name - name-attribute for the HTML select element.
• tabindex - tabindex-attribute for the HTML select element.
• javascript - extra javascript code to be included in the HTML select element. (e.g. onclick="alert('foo')")
• selected - value of the currently selected item. (used to put the selected="selected" attribute on the correct HTML option element)
• shorten - Maximum length of displayed text
• shortenel - Ellipsis text to use when displayed text is shortened
• extraval & extra - Allows to add an extra list entry at the very start of the dropdown.

Note that for the entries to show up, the $query is expected to be of the format SELECT foo as text, bar as value FROM table.

The keys of the $template array for a table type list are as follows:

• content - Type of table content. Examples are memberlist, teamlist, etc. These map to functions with names like listplug_table_teamlist. (see further down)
• tabindex - tabindex-attribute for any HTML formfield elements within the table cells.
• now - current time (used when content is set to itemlist)
• canAddBan - Indicates if a member is allowed to add IP bans (used when content is set to commentlist)
• superAdmin - Indicates if a member is a super-admin (used when content is set to bloglist)

So, how does it work?

Basically, the showlist function comes down to this

1. Execute query. Return 0 when no results.
2. Call listplug_type($template, 'HEAD')
3. For each query result, copy it's object in $template['current'] and call listplug_type($template, 'BODY')
4. Call listplug_type($template, 'FOOT')
5. Return the amount of displayed items.

The type part in listplug_type can be either select or table. This means that you'll find functions called listplug_select and listplug_table. The first is quite trivial (each call outputs the appropriate part of the dropdown HTML), the second (listplug_table) is not.

The listplug_table method outputs the outer parts of the HTML tables (table and tr elements), and delegates the generation of its td tags to the listplug_table_content function (content being one of itemlist, memberlist, ...). The listplug_table_content do their magic using the $template['current'] object.

The ENCAPSULATE/BATCH/NAVLIST classes

The ENCAPSULATE class is the base class for two classes:

1. BATCH - Displays a list of items that can be selected for batch operations (such as on itemlist, commentlist, ...). The BATCH class wraps a form around the list, and adds the batch action bar at the bottom of the list.
2. NAVLIST - Displays a list of items (using the BATCH class above), and adds a navigation bar on the top and bottom (unless there were no items displayed).

The ENCAPSULATE has as only purpose to call some function (showlist), while buffering the output. If showlist returns 0 (=no data rows in the table), an error message is displayed and the buffered output is discarded. On the other hand, if showlist returned something larger than zero, the output is displayed, in between a header and a footer (this header and footer are generated by NAVLIST or BATCH)

Some examples

Some small code examples of how to use all this:

$navList = new NAVLIST('itemcommentlist', $start, $amount, 0, ...);
$navList->showBatchList('comment',$query,'table',$template,_NOCOMMENTS);

In the showBatchList call, you'll recognize the parameters that are normally passed to showlist ($query,'table',$template). The _NOCOMMENTS parameter is the string that needs to be displayed when no comments are available. The very first parameter ('comment') gives info about what type of batch list is displayed. The BATCH class uses this info to determine which actions it should show in the dropdown.

// show list of members with actions
$query =  'SELECT *' FROM '.sql_table('member');
$template['content'] = 'memberlist';
$template['tabindex'] = 10;
	
$batch = new BATCH('member');
$batch->showlist($query,'table',$template);

This code was taken from the admin area memberlist page. I think the code speaks for itself.

I hope you got any wiser from this article. If you're still seeing fog all around, try browsing through the actual code.