Revision history for ArrayToList


Revision [18506]

Last edited on 2008-01-28 00:11:42 by JavaWoman [Modified links pointing to docs server]
Additions:
>>This page presents new code for the [[Docs:WikkaCore Wikka Core]] to generate well-structured lists from an array of items to be presented.
~-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.//
Deletions:
>>This page presents new code for the [[WikkaCore Wikka Core]] to generate well-structured lists from an array of items to be presented.
~-The [[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 [[CategoryActionInfo Category action]] which can list category contents either as a list or columns.---//The AdvancedCategoryAction already uses it - see WikkaBetaFeatures.//


Revision [9158]

Edited on 2005-06-12 18:57:52 by JavaWoman [adding links, ref to alpha features]
Additions:
//Installed to support [[WikkaBetaFeatures alpha features]] on this server as of 2005-06-12.//
~-AdvancedBacklinksAction
~-AdvancedCategoryAction
~-The [[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 [[CategoryActionInfo Category action]] which can list category contents either as a list or columns.---//The AdvancedCategoryAction already uses it - see WikkaBetaFeatures.//
Deletions:
~-The [[CategoryActionInfo Category action]] which can list category contents either as a list or columns. //The AdvancedCategoryAction already uses it.//
~-The [[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.//


Revision [8993]

Edited on 2005-06-08 11:52:19 by JavaWoman [adding links to advanced actions]
Additions:
~-The [[CategoryActionInfo Category action]] which can list category contents either as a list or columns. //The AdvancedCategoryAction already uses it.//
~-The [[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.//
Deletions:
~-The [[CategoryActionInfo Category action]] which can list category contents either as a list or columns.
~-The [[BacklinksActionInfo Backlinks action]] simply lists pages in an unstructured list; it could use a structured list or columns like the category action instead.


Revision [8924]

Edited on 2005-06-07 17:28:19 by JavaWoman [some todos done]
Additions:
===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.)
* @todo - support for nested lists (same type)
$aTypes = array('ul','ol','menu'); # (menu generates ul) @@@ add dl later
return '<p class="error">'.sprintf(ERR_CANNOTGEN,STRUC_LIST,STRUC_ARRAY).'</p>'."\n";
$indent = min(MAX_LIST_INDENT,abs((int)$indent)); # positive integer no larger than MAX_LIST_INDENT
$out .= 'nested list not yet supported'; # @@@ temporary string until recursion is implemented
* @version 0.6
* @param string $type optional: type of list to generate; default: ul
* @param integer $level optional: level of the heading to generate; default: 6
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
// build structure
$out .= ' <h'.$level.' id="'.$this->makeId('hn',$hdid).'">'.sprintf($hd,$count).'</h'.$level.'>'."\n";
$out .= $this->makeList($array,$id,'',$type,2);
As can be seen from the @version numbers and @todo items in the docblocks, the code is far from "finished".
Deletions:
* @todo _ make maximum indent configurable
* - support for nested lists (same type)
* - support for internationalization (replace hard-coded strings)
if (!defined('MAX_INDENT')) define('MAX_INDENT',20); # @@@ make max configurable)
$aTypes = array('ul','ol','menu'); # @@@ add dl later (menu generates ul)
return '<p class="error">Could not generate list: array required</p>'."\n"; # @@@ i18n
$indent = min(MAX_INDENT,abs((int)$indent)); # positive integer no larger than MAX_INDENT
$out .= 'nested list not yet supported'; # @@@ i18n;
* - allow specification of list type (uses hardcoded 'menu' now)
* @version 0.5
function makeMemberList($array,$hd,$hdid,$id,$txtnone)
$out .= ' <h6 id="'.$this->makeId('hn',$hdid).'">'.sprintf($hd,$count).'</h6>'."\n";
$out .= $this->makeList($array,$id,'','menu',2);
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.


Revision [8916]

Edited on 2005-06-07 14:19:58 by JavaWoman [adding When and where]
Additions:
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 [[CategoryActionInfo Category action]] which can list category contents either as a list or columns.
~-The [[BacklinksActionInfo Backlinks action]] simply lists pages in an unstructured list; it could use a structured list or columns like the category action instead.
~-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!
Still, **code as published here //will// change** as it's being refined - so keep an eye on the page!


Revision [8911]

Edited on 2005-06-07 11:26:10 by JavaWoman [minor]
Additions:
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.
Deletions:
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.


Revision [8910]

Edited on 2005-06-07 11:24:19 by JavaWoman [adding status note]
Additions:
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.


Revision [8904]

Edited on 2005-06-07 10:30:53 by JavaWoman [adding code]
Additions:
===##""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 _ 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
if (!defined('MAX_INDENT')) define('MAX_INDENT',20); # @@@ make max configurable)
// definition
$aTypes = array('ul','ol','menu'); # @@@ add dl later (menu generates ul)
// validate/treat input
if ($validate)
{
if (!is_array($array))
{
return '<p class="error">Could not generate list: array required</p>'."\n"; # @@@ i18n
}
$type = (!in_array($type,$aTypes)) ? 'ul' : $type;
$class = trim(strip_tags($class)); # minimum protection for user-supplied input
$indent = min(MAX_INDENT,abs((int)$indent)); # positive integer no larger than MAX_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'; # @@@ 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()""##**
%%(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
* - 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)
{
$count = count($array);
$out = '';
if ($count > 0)
{
$out .= " <div>\n";
$out .= ' <h6 id="'.$this->makeId('hn',$hdid).'">'.sprintf($hd,$count).'</h6>'."\n";
$out .= $this->makeList($array,$id,'','menu',2);
$out .= " </div>\n";
}
else
{
$out .= ' <p>'.$txtnone.'</p>'."\n";
}
return $out;
}
%%
====Status====


Revision [8900]

The oldest known version of this page was created on 2005-06-07 09:41:08 by JavaWoman [adding code]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki