Revision history for ArrayToColumns
Revision [19033]
Last edited on 2008-01-28 00:13:47 by JavaWoman [Modified links pointing to docs server]Additions:
>>This page presents new code for the [[Docs:WikkaCore Wikka Core]] to generate columns of items from an array of items to be presented - without using a table for layout.
In many cases we get an array back from some procedure and want to display the result in the form of a number of easy to read columns. The current Wikka code now does this "manually" and generates a table layout which is not only not very structural code but also not very accessible. (Example: the [[Docs:CategoryActionInfo Category action]] can generate its output in "columns" but they need to be read horizontally rather than vertically - making it hard to "scan" so a particular name is hard to find - and the code generated is a layout table.)
~-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.//
In many cases we get an array back from some procedure and want to display the result in the form of a number of easy to read columns. The current Wikka code now does this "manually" and generates a table layout which is not only not very structural code but also not very accessible. (Example: the [[Docs:CategoryActionInfo Category action]] can generate its output in "columns" but they need to be read horizontally rather than vertically - making it hard to "scan" so a particular name is hard to find - and the code generated is a layout table.)
~-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.//
Deletions:
In many cases we get an array back from some procedure and want to display the result in the form of a number of easy to read columns. The current Wikka code now does this "manually" and generates a table layout which is not only not very structural code but also not very accessible. (Example: the [[CategoryActionInfo Category action]] can generate its output in "columns" but they need to be read horizontally rather than vertically - making it hard to "scan" so a particular name is hard to find - and the code generated is a layout table.)
~-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.//
Additions:
In many cases we get an array back from some procedure and want to display the result in the form of a number of easy to read columns. The current Wikka code now does this "manually" and generates a table layout which is not only not very structural code but also not very accessible. (Example: the [[CategoryActionInfo Category action]] can generate its output in "columns" but they need to be read horizontally rather than vertically - making it hard to "scan" so a particular name is hard to find - and the code generated is a layout table.)
Deletions:
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.//
~-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 [[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.//
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.//
~-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 [[BacklinksActionInfo Backlinks action]] simply lists pages in an unstructured list; it could use a structured list or columns like the category action instead.
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.
See ArrayToList for the code and where to insert it.
* @version 0.4
* - replace clear: both style at end with a class (?)
return '<p class="error">'.sprintf(ERR_CANNOTGEN,STRUC_COLS,STRUC_ARRAY).'</p>'."\n";
$cols = abs((int)$cols); # make sure we have a positive integer
* @version 0.6
* @param integer $level optional: level of the heading to generate; default: 6
function makeMemberCols($array,$cols,$hd,$hdid,$txtnone,$level=6)
// validate/sanitize input
return '<p class="error">'.sprintf(ERR_CANNOTGEN,STRUC_COLS,STRUC_ARRAY).'</p>'."\n";
$cols = abs((int)$cols); # make sure we have a positive integer
$level = max(min((int)$level,6),3); # make sure level is in range 3-6
// initializations
// build structure
As can be seen from the @version numbers and @todo items in the docblocks, the code is far from "finished".
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.
See ArrayToList for the code and where to insert it.
* @version 0.4
* - replace clear: both style at end with a class (?)
return '<p class="error">'.sprintf(ERR_CANNOTGEN,STRUC_COLS,STRUC_ARRAY).'</p>'."\n";
$cols = abs((int)$cols); # make sure we have a positive integer
* @version 0.6
* @param integer $level optional: level of the heading to generate; default: 6
function makeMemberCols($array,$cols,$hd,$hdid,$txtnone,$level=6)
// validate/sanitize input
return '<p class="error">'.sprintf(ERR_CANNOTGEN,STRUC_COLS,STRUC_ARRAY).'</p>'."\n";
$cols = abs((int)$cols); # make sure we have a positive integer
$level = max(min((int)$level,6),3); # make sure level is in range 3-6
// initializations
// build structure
As can be seen from the @version numbers and @todo items in the docblocks, the code is far from "finished".
Deletions:
* - replace clear: both style at end with a class
* - support for internationalization (replace hard-coded strings)
return '<p class="error">Could not generate columns: array required</p>'."\n"; # @@@ i18n
$cols = abs((int)$cols); # cast to positive integer
* @version 0.5
function makeMemberCols($array,$cols,$hd,$hdid,$txtnone)
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 ##""makeMemberCols()""## (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.
Additions:
In general, you can use these methods anywhere you get (or build) an array and want to display the result in the form of columns - for instance to avoid over-long pages when there are a lot of items to show.
Several current actions and handlers could take advantage of these methods, in particular:
~-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.
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!
Several current actions and handlers could take advantage of these methods, in particular:
~-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.
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!
Additions:
Using a standard way to generate columns is more efficient, can ensure consistent and structural code and makes it easier to write methods (or actions or handlers) that need columns of items as output.
Deletions:
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 ##""makeMemberCols()""## (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.
Additions:
Add the following code in the ##""//MISC""## section right after the ##""makeMemberList()""## method (see ArrayToList for that):
Deletions:
Additions:
===##""makeCols()""##===
This method does the hard work of creating columnar output from an array, using floated ##div##s instead of a layout table. It requires the ##""makeId()""## method to be already present - see GenerateUniqueId.
Add the following code in the ##""//MISC""## section right after the ##""makeMemberList()""## method (see ArraytToList for that):
**##""makeCols()""##**
%%(php;1) /**
* Build vertically-arranged columns from an array.
*
* Given an array and number of columns, this method builds vertically-
* arranged columns (meaning they are read vertically, one by one)
* implemented as floated divs. Column width is derived from the
* specified number of columns, implemented as an embedded style because
* it's dynamically generated; left float is added to the style (hardcoded
* for now but alignment could become an option later).
*
* @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.3
*
* @todo - make alignment configurable
* - class as extra parameter (for each column)
* - replace clear: both style at end with a class
* - support for internationalization (replace hard-coded strings)
*
* @access public
*
* @param array $array required: flat array with content items; must be array but may be empty
* @param integer $cols optional: number of columns to generate; default: 1
* (will be cast to positive integer)
* @return string generated divs (or empty string if array was empty)
*/
function makeCols($array,$cols=1)
{
// validate/treat input
if (!is_array($array))
{
return '<p class="error">Could not generate columns: array required</p>'."\n"; # @@@ i18n
}
$cols = abs((int)$cols); # cast to positive integer
// build columns
$count = count($array);
$width = (int) (100 / $cols);
$lines = ($count % $cols == 0) ? (int)($count / $cols) : (int)(($count + $cols) / $cols);
$line = 0;
$out = '';
// data columns
foreach ($array as $val)
{
if (($line++ % $lines) == 0) $out .= "\n".' <div style="width: '.$width.'%; float: left;">'."\n";
$out .= ' '.$val.'<br />'."\n";
if (($line % $lines) == 0) $out .= " </div>";
}
if ($count > 0)
{
if (($line % $lines) != 0) $out .= " </div>";
$out .= '<br style="clear: both;">'."\n";
}
// return result
return $out;
}
%%
===##""makeMemberCols()""##===
This method is a wrapper around the ##""makeCols()""## 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.
As with the [[ArrayToList makeMemberList()]] method 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 ##""makeCols()""## method:
**##""makeMemberCols()""##**
%%(php;1) /**
* Display members of a collection in vertical columns; a heading precedes
* the columns; 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.
*
* @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 makeCols()
*
* @param array $array required: flat array with collection items
* @param string $hd required: heading for the whole
* @param string $hdid required: id for the heading
* @param string $txtnone required: text to display when the array is empty
* @return string div containing heading and list, or paragraph
*/
function makeMemberCols($array,$cols,$hd,$hdid,$txtnone)
{
$count = count($array);
$out = '';
if ($count > 0)
{
$out .= ' <h6 id="'.$this->makeId('hn',$hdid).'">'.$hd.'</h6>'."\n";
$out .= $this->makeCols($array,$cols);
}
else
{
$out = ' <p>'.$txtnone.'</p>'."\n";
}
return $out;
}
%%
This method does the hard work of creating columnar output from an array, using floated ##div##s instead of a layout table. It requires the ##""makeId()""## method to be already present - see GenerateUniqueId.
Add the following code in the ##""//MISC""## section right after the ##""makeMemberList()""## method (see ArraytToList for that):
**##""makeCols()""##**
%%(php;1) /**
* Build vertically-arranged columns from an array.
*
* Given an array and number of columns, this method builds vertically-
* arranged columns (meaning they are read vertically, one by one)
* implemented as floated divs. Column width is derived from the
* specified number of columns, implemented as an embedded style because
* it's dynamically generated; left float is added to the style (hardcoded
* for now but alignment could become an option later).
*
* @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.3
*
* @todo - make alignment configurable
* - class as extra parameter (for each column)
* - replace clear: both style at end with a class
* - support for internationalization (replace hard-coded strings)
*
* @access public
*
* @param array $array required: flat array with content items; must be array but may be empty
* @param integer $cols optional: number of columns to generate; default: 1
* (will be cast to positive integer)
* @return string generated divs (or empty string if array was empty)
*/
function makeCols($array,$cols=1)
{
// validate/treat input
if (!is_array($array))
{
return '<p class="error">Could not generate columns: array required</p>'."\n"; # @@@ i18n
}
$cols = abs((int)$cols); # cast to positive integer
// build columns
$count = count($array);
$width = (int) (100 / $cols);
$lines = ($count % $cols == 0) ? (int)($count / $cols) : (int)(($count + $cols) / $cols);
$line = 0;
$out = '';
// data columns
foreach ($array as $val)
{
if (($line++ % $lines) == 0) $out .= "\n".' <div style="width: '.$width.'%; float: left;">'."\n";
$out .= ' '.$val.'<br />'."\n";
if (($line % $lines) == 0) $out .= " </div>";
}
if ($count > 0)
{
if (($line % $lines) != 0) $out .= " </div>";
$out .= '<br style="clear: both;">'."\n";
}
// return result
return $out;
}
%%
===##""makeMemberCols()""##===
This method is a wrapper around the ##""makeCols()""## 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.
As with the [[ArrayToList makeMemberList()]] method 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 ##""makeCols()""## method:
**##""makeMemberCols()""##**
%%(php;1) /**
* Display members of a collection in vertical columns; a heading precedes
* the columns; 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.
*
* @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 makeCols()
*
* @param array $array required: flat array with collection items
* @param string $hd required: heading for the whole
* @param string $hdid required: id for the heading
* @param string $txtnone required: text to display when the array is empty
* @return string div containing heading and list, or paragraph
*/
function makeMemberCols($array,$cols,$hd,$hdid,$txtnone)
{
$count = count($array);
$out = '';
if ($count > 0)
{
$out .= ' <h6 id="'.$this->makeId('hn',$hdid).'">'.$hd.'</h6>'."\n";
$out .= $this->makeCols($array,$cols);
}
else
{
$out = ' <p>'.$txtnone.'</p>'."\n";
}
return $out;
}
%%
Additions:
=====Generating Columns from an Array=====
~-ArrayToList
>>This page presents new code for the [[WikkaCore Wikka Core]] to generate columns of items from an array of items to be presented - without using a table for layout.
In many cases we get an array back from some procedure and want to display the result in the form of a number of easy to read columns. The current Wikka code now does this "manually" and generates a table layout which is not only very structural code but also not very accessible. (Example: the [[CategoryActionInfo Category action]] can generate its output in "columns" but they need to be read horizontally rather than vertically - making it hard to "scan" so a particular name is hard to find - and the code generated is a layout table.)
Using a standard way to generate columns is more efficient, can ensure consistent and structural code and makes it easier to write methods that need columns of items as output.
Two separate methods were written to make it easy to generate well-structured columns 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.
====Status====
~-ArrayToList
>>This page presents new code for the [[WikkaCore Wikka Core]] to generate columns of items from an array of items to be presented - without using a table for layout.
In many cases we get an array back from some procedure and want to display the result in the form of a number of easy to read columns. The current Wikka code now does this "manually" and generates a table layout which is not only very structural code but also not very accessible. (Example: the [[CategoryActionInfo Category action]] can generate its output in "columns" but they need to be read horizontally rather than vertically - making it hard to "scan" so a particular name is hard to find - and the code generated is a layout table.)
Using a standard way to generate columns is more efficient, can ensure consistent and structural code and makes it easier to write methods that need columns of items as output.
Two separate methods were written to make it easy to generate well-structured columns 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.
====Status====
Deletions:
~-ArrayToColumns
>>This page presents new code for the [[WikkaCore Wikka Core]] to generate well-structured lists from an array of items to be presented.
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.
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.
