Wiki source for ArrayToList


Show raw source

=====Generating a List from an Array=====
//Installed to support [[WikkaBetaFeatures alpha features]] on this server as of 2005-06-12.//

>>See also:
~-ArrayToColumns
~-AdvancedBacklinksAction
~-AdvancedCategoryAction
>>This page presents new code for the [[Docs:WikkaCore Wikka Core]] to generate well-structured lists from an array of items to be presented.

====Why?====

In many cases we get an array back from some procedure and want to display the result in the form of a list. In several places in the Wikka code this now happens "manually" in that each uses its own code to build the HTML to present the list. This is not only inefficient, but also leads to inconsistent and sometimes not even well-structured code. (Example: the TextSearch produces a numbered list of matching page names - but it is not only not sorted, it is not even an ordered list.)

Using a standard way to generate lists is more efficient, can ensure consistent code and makes it easier to write methods (or actions or handlers) that need some kind of list as output.

====How?====

Two separate methods were written to make it easy to generate well-structured lists with 'hooks' for styling: the first does nothing but generate a list from an array (with an id); the second wraps that in a bit of code with a heading and a bit of text instead of the list if the array happens to be empty.

====The Code====

===Constants===
The methods make use of some constants (limits and texts used for error messages, ready for internationalization) that should be defined in the constants section in ##wikka.php##.

Find the following line (line nr. as in version 1.1.6.0 release):
%%(php;42)define("WAKKA_VERSION", "1.1.6.0");%%---
and insert the following block after it:
%%(php;1)
/**#@+
* Numeric constant. May be made a configurable value.
*/
/**
* Length to use for generated part of id attribute.
*/
define('ID_LENGTH',10); # @@@ maybe make length configurable
/**
* Maximum indent level to use for generated lists.
*/
define('MAX_LIST_INDENT',20); # @@@ maybe make max indent configurable)
/**#@-*/
/**#@+
* User-interface constant (ready for internationalization).
*/
define('STRUC_LIST','list');
define('STRUC_COLS','columns');
define('STRUC_ARRAY','array');
/**
* Error message.
*/
define('ERR_CANNOTGEN','Cannot generate %1$s: %2$s required');
/**#@-*/

%%---
(this should include a blank line as the start and at the end to separate it from the version number and the ##getmicrotime()## function.

(The funny comment blocks are docblock "templates" to be used for documentation generation.)

===##""makeList()""##===
This method does the hard work of creating an unordered or ordered list. It requires the ##""makeId()""## method to be already present - see GenerateUniqueId.

Add the following code in the ##""//MISC""## section right after the ##""makeId()""## method:

**##""makeList()""##**
%%(php;1) /**
* Build a list from an array.
*
* Given an array, this method builds a simple unordered or ordered list
* with an id.
* Only a (simple) array is required which will generate an
* unordered list; optionally id, class, type of list and an indent level
* can be specified. For type 'menu' an unordered list is generated but
* with an id in group 'menu' instead of 'ul' or 'ol': this enables the
* list being styled as a menu.
*
* @author {@link http://wikka.jsnx.com/JavaWoman JavaWoman}
* @copyright Copyright © 2005, Marjolein Katsma
* @license http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License
* @version 0.8
*
* @todo - support for nested lists (same type)
* - support for definition lists
*
* @access public
* @uses makeId()
*
* @param array $array required: flat array with content items
* @param mixed $id optional: id for the list, will be treated with makeId()
* or FALSE which suppresses id (for multiple-use elements)
* @param string $class optional: class for (extra) styling
* @param string $type optional: type of list to generate; default: ul
* @param integer $indent optional: indent level
* @return string generated list
*/
function makeList($array,$id='',$class='',$type='ul',$indent=0)
{
static $validate = TRUE; # need to validate input
// definition
$aTypes = array('ul','ol','menu'); # (menu generates ul) @@@ add dl later
// validate/treat input
if ($validate)
{
if (!is_array($array))
{
return '<p class="error">'.sprintf(ERR_CANNOTGEN,STRUC_LIST,STRUC_ARRAY).'</p>'."\n";
}
$type = (!in_array($type,$aTypes)) ? 'ul' : $type;
$class = trim(strip_tags($class)); # minimum protection for user-supplied input
$indent = min(MAX_LIST_INDENT,abs((int)$indent)); # positive integer no larger than MAX_LIST_INDENT
$validate = FALSE; # validation done: no need to repeat for recursion
}
// build element
$tag = ('menu' == $type) ? 'ul' : $type;
$ind = str_repeat("\t",$indent);
$attrId = (FALSE !== $id) ? ' id="'.$id = $this->makeId($type,$id).'"' : '';
$attrClass = ('' != $class) ? ' class="'.$class.'"' : '';
$out = $ind.'<'.$tag.$attrClass.$attrId.">\n";
foreach ($array as $item)
{
$out .= $ind.' <li>';
if (!is_array($item))
{
$out .= $item;
}
else
{
# @@@ add recursion for nested lists
$out .= 'nested list not yet supported'; # @@@ temporary string until recursion is implemented
}
$out .= "</li>\n";
}
$out .= $ind.'</'.$tag.">\n";
// return result
return $out;
}
%%

===##""makeMemberList()""##===
This method is a wrapper around the ##""makeList()""## method: it wraps the output in a div and adds a heading or outputs a paragraph of text in case the array turns out to be empty. It's meant for cases where items are to be presented as "members" of a collection; the heading is used to indicate the number of members.

There is deliberately no 'outer' div with an id: this is so a wrapper div may be created with a single heading containing several occurrences of the output of this method. Such a wrapper should be generated in the calling code.

Add the following code in the ##""//MISC""## section right after the ##""makeList()""## method:

**##""makeMemberList()""##**
%%(php;1) /**
* Display members of a collection in a list. Wrapped in a div with a heading;
* alternatively output is just a paragraph of text in case the
* array provided turns out to be empty.
*
* There is deliberately no 'outer' div with an id: this is so a div may be
* created with a single heading containing several occurrences of the
* output of this method. Such a wrapper should be generated in the calling code.
*
* @todo - allow suppression of the heading
*
* @author {@link http://wikka.jsnx.com/JavaWoman JavaWoman}
* @copyright Copyright © 2005, Marjolein Katsma
* @license http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License
* @version 0.6
*
* @access public
* @uses makeId()
* @uses makeList()
*
* @param array $array required: flat array with collection items
* @param string $hd required: heading for the list;
* should contain a %d placeholder for the number of items
* @param string $hdid required: id for the heading (should be a constant,
* because the heading itself has variable content)
* @param string $id required: id for the list itself
* @param string $txtnone required: text to display when the array is empty
* @param string $type optional: type of list to generate; default: ul
* @param integer $level optional: level of the heading to generate; default: 6
* @return string div containing heading and list, or paragraph
*/
function makeMemberList($array,$hd,$hdid,$id,$txtnone,$type='ul',$level=6)
{
// validate/sanitize input
if (!is_array($array))
{
return '<p class="error">'.sprintf(ERR_CANNOTGEN,STRUC_LIST,STRUC_ARRAY).'</p>'."\n";
}
$level = max(min((int)$level,6),3); # make sure level is in range 3-6
// initializations
$count = count($array);
$out = '';
// build structure
if ($count > 0)
{
$out .= " <div>\n";
$out .= ' <h'.$level.' id="'.$this->makeId('hn',$hdid).'">'.sprintf($hd,$count).'</h'.$level.'>'."\n";
$out .= $this->makeList($array,$id,'',$type,2);
$out .= " </div>\n";
}
else
{
$out .= ' <p>'.$txtnone.'</p>'."\n";
}
// return result
return $out;
}
%%


====When and where to use====

In general, you can use these methods anywhere you get (or build) an array and want to display the result as a list - for instance for use in a sidebar as a navigation menu. (When the list is generated with id group 'menu' this can be used as a hook for a special 'menu' style in the stylesheet.)

Several current actions and handlers could take advantage of these methods, for example:
~-The [[Docs:BacklinksActionInfo Backlinks action]] simply lists pages in an unstructured list; it could use a structured list or columns like the category action instead.---//The AdvancedBacklinksAction already uses it - see WikkaBetaFeatures.//
~-The [[Docs:CategoryActionInfo Category action]] which can list category contents either as a list or columns.---//The AdvancedCategoryAction already uses it - see WikkaBetaFeatures.//
~-As noted above, the [[TextsearchActionInfo Textsearch action]] produces an unstructured numbered list which would be better if structured as an ordered list.

Updates for these (and possibly others) taking advantage of these new methods will soon be published on this site!

====Status====

As can be seen from the @version numbers and @todo items in the docblocks, the code is far from "finished".

Still, **code as published here //will// change** as it's being refined - so keep an eye on the page!

----
CategoryDevelopmentCore
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki