Revision [8910]
This is an old revision of ArrayToList made by JavaWoman on 2005-06-07 11:24:19.
Generating a List from an Array
See also:
This page presents new code for the 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 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
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()
- /**
- * 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 _ make maximum indent configurable
- * - support for nested lists (same type)
- * - support for definition lists
- * - support for internationalization (replace hard-coded strings)
- *
- * @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
- // validate/treat input
- if ($validate)
- {
- {
- return '<p class="error">Could not generate list: array required</p>'."\n"; # @@@ i18n
- }
- $validate = FALSE; # validation done: no need to repeat for recursion
- }
- // build element
- $tag = ('menu' == $type) ? 'ul' : $type;
- $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>';
- {
- $out .= $item;
- }
- else
- {
- # @@@ add recursion for nested lists
- $out .= 'nested list not yet supported'; # @@@ i18n;
- }
- $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()
- /**
- * 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
- * - allow specification of list type (uses hardcoded 'menu' now)
- *
- * @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.5
- *
- * @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
- * @return string div containing heading and list, or paragraph
- */
- function makeMemberList($array,$hd,$hdid,$id,$txtnone)
- {
- $out = '';
- if ($count > 0)
- {
- $out .= " <div>\n";
- $out .= $this->makeList($array,$id,'','menu',2);
- $out .= " </div>\n";
- }
- else
- {
- $out .= ' <p>'.$txtnone.'</p>'."\n";
- }
- return $out;
- }
When and where to use
Status
As can be seen from the @version numbers and @todo items in the docblocks, the code is far from "finished". An additional idea that just came up on TheLounge #wikka is to be able to specify the level of the heading generated by makeMemberList() (given that a page should already contain a h1 and h2 heading, only 3-6 should be allowed). However, the methods are quite functional to use as is.
CategoryDevelopmentCore