documentation-5.html

PHPLOB注释详细版 使用模板技术的好帮手 PHP最有用的东东了

<P>
<P>
<H3>High-level instance methods</H3>

<P>
<P>
<DL>
<P>
<DT><B>show($ary, $class = "")</B><DD><P> 
Will format and print the two dimensional array (or hash)
<CODE>$ary</CODE> as a table according to the filtering rules explained
above. If <CODE>$class</CODE> is set, each HTML element will be tagged
as belonging to the named class; this is useful with cascading
style sheets.
<P>
<DT><B>show_page($ary, $start, $num, $class = "")</B><DD><P>Just as <CODE>show()</CODE>, but will show only <CODE>num</CODE> elements
starting at <CODE>start</CODE>.
<P>
<DT><B>show_result($db, $class = "")</B><DD><P>Will format and print the result set of <CODE>$db</CODE>. <CODE>$db</CODE> is
exspected to be a subclass of <CODE>DB_Sql</CODE> that has just
been sent a query. <CODE>Table</CODE> will grab all available results
from the result set of that query by calling
<CODE>$db-&gt;next_record()</CODE> repeatedly and format them
into a table.
<P>
<DT><B>show_result_page($db, $start, $num, $class = "")</B><DD><P>
<P>Just as <CODE>show_result()</CODE>, but will show only <CODE>num</CODE>
elements starting at <CODE>start</CODE>.
<P>
</DL>
<P>
<H3>Mid-level instance methods</H3>

<P>
<P>
<DL>
<DT><B>show_table_rows($ary, $class="")</B><DD><P>Walks the passed array displaying each row of data as an HTML
table row.
<P>
<DT><B>show_table_rows_result($db, $class="")</B><DD><P>Walks the passed database object displaying each record as an 
HTML table row.
<P>
<DT><B>show_table_page_rows($ary, $start, $num, $class="")</B><DD><P>Walks the passed array displaying each row of data as an HTML
table row. However, data does not start displaying until
<CODE>$start</CODE> element and end after <CODE>$num</CODE> rows.
<P>
<DT><B>show_table_page_rows_result($db, $start, $num, $class="")</B><DD><P>Walks the passed database object displaying each record as an 
HTML table row. However, data does not start displaying until
<CODE>$start</CODE> record and ends after <CODE>$num</CODE> records have been displayed.
<P>
<DT><B>show_table_heading_row($ary, $class="")</B><DD><P>Uses the passed array to create an HTML header row.
<P>
<DT><B>show_table_heading_row_result($db, $class="")</B><DD><P>Uses the passed database object to create an HTML header row.
<P>
<DT><B>show_table_heading_cells($data, $class="")</B><DD><P>Walks the passed array and displays each item in an HTML table
header cell.
<P>
<DT><B>show_table_cells($row, $row_key, $data, $class="")</B><DD><P>Walks the passed array and displays each item in an HTML table cell.
<P>
</DL>
<P>
<H3>Low-level instance methods</H3>

<P>
<P>
<DL>
<DT><B>table_open($class = "")</B><DD><P>This function can be overridden by a subclass of Table. It
is called as the very first step in table creation and
should output HTML that opens a table (for example
<CODE>printf("&lt;table%s&gt;\n", $class?" class=$class":"");</CODE>).
<P>
<DT><B>table_close()</B><DD><P>This function can be overridden by a subclass of Table. It
is called as the very last step in table creation and
should output HTML that closes a table (for example
<CODE>printf("&lt;</CODE>table&gt;\n");/).
<P>
<DT><B>select_colnames($data)</B><DD><P>Internal function to generate a list of column names.
<P>
<DT><B>table_heading_row($data, $class = "")</B><DD><P>Internal driver function to generate a table heading row.
<P>
<DT><B>table_heading_cell($col, $val, $class)</B><DD><P>This function can be overridden by a subclass of Table. It
is called each time a table heading cell is to be generated.
<P><CODE>$col</CODE> is the current column number, <CODE>$val</CODE> is the name
of the column. <CODE>$class</CODE> is the HTML CSS class of the
element that is to be generated.
<P>
<DT><B>table_heading_cell_open($class="")</B><DD><P>Starts a header cell.
<P>
<DT><B>table_heading_cell_close($class="")</B><DD><P>Ends a header cell.
<P>
<DT><B>table_heading_row_add_extra($data, $class="")</B><DD><P>Virtual function for derived classes. This function is called 
after all header cells have been created. It allows the 
programmer to add additional HTML code to the header row 
before it is closed.
<P>
<DT><B>table_row($data, $class = "")</B><DD><P>Internal driver function to generate a table row.
<P>
<DT><B>table_row_open($row, $data, $class = "")</B><DD><P>This function can be overridden by a subclass of Table. It
is called as the very first step in row creation and
should output HTML that opens a table row.
<P><CODE>$row</CODE> is the current row number. <CODE>$data</CODE> is a hash of
column name/value pairs for that row and <CODE>$class</CODE> is an
optional HTML CSS class name for all generated elements.
<P>
<DT><B>table_row_close()</B><DD><P>This function can be overridden by a subclass of Table. It
is called as the very last step in row creation and
should output HTML that closes a table row.
<P>
<DT><B>table_cell($row, $cell, $key, $val, $class)</B><DD><P>This function can be overridden by a subclass of Table. It
is called each time a table cell is to be generated.
<P><CODE>$row</CODE> is the current row number, <CODE>$cell</CODE> is the
current cell number. <CODE>$key</CODE> is the current column name,
<CODE>$val</CODE> is the value of the cell. <CODE>$class</CODE> is the
HTML CSS class of the element that is to be generated.
<P>
<DT><B>table_cell_open($class="")</B><DD><P>Starts a cell.
<P>
<DT><B>table_cell_close($class="")</B><DD><P>Ends a cell.
<P>
<DT><B>set_checkbox_heading($class="")</B><DD><P>This function creates an empty header cell to coincide with
the checkbox option for that column.
<P>
<DT><B>table_checkbox_cell($row, $row_key, $data, $class="")</B><DD><P>Outputs HTML code to display a checkbox. This function runs
if the member variable <CODE>$check</CODE> has been set. <CODE>$check</CODE> should be
set to some key within the <CODE>$data</CODE> array (ex: if <CODE>$data["myKey"]</CODE>,
then set <CODE>$check="myKey"</CODE>).
<P>
<DT><B>set_checkbox($row, $row_key, $data, $class="")</B><DD><P>Creates an HTML checkbox based on the passed data, only if
the instance variable <CODE>$check</CODE> is set.
<P>
</DL>
<P>
<H3>Example</H3>

<P>Table is not automatically included or prepended into each page.
Include the table class into the pages that are to use Table.
Then create an instance of Table:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
&lt;?php
  // Include Table
  require("table.inc");
  
  // make a Table instance
  $t = new Table;
  
  // We want table headings to be printed.
  $t-&gt;heading = "on";
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>Now create a two dimensional array or prepare a database query
and have table print it.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
  // Create a database object
  $db = new DB_Session;
  
  // create a twodim array called $tab
  $tab = $db->metadata("active_sessions");
  
  // print that array
  $t-&gt;show($tab, "metadata");
  
  // prepare a database query
  $db-&gt;query("select * from active_sessions");
  
  // print that result
  $t-&gt;show_result($db, "data");
</PRE>
<HR>
</CODE></BLOCKQUOTE>

<H2><A NAME="ss5.3">5.3 Menu</A>
</H2>

<P>Menu will generate a hierarchical menu of clickable items
suitable as a navigation bar. Menu takes a tree definition of
items as the basis for this navigation bar and knows which
subtrees to fold, depending on the current position in the menu
tree. Menu uses the current URL as presented in
<CODE>PHP_SELF</CODE> to determine the current position in the
menu tree automatically.
<P>Menu does not depend on a hierarchical organisation of files in
URL-space to generate a menu hierarchy. The organisation of menu
items and the organisation of files in URL-space are in fact
completely independent and Menu uses a mapping hash to derive a
menu position from an URL. In the following class documentation
we'll say URL when we mean files the latter and menustring when
we mean the former. In the context of the Menu class, URLs are
always relative URLs starting at the root of the local servers
URL space, as we'll see them in PHP_SELF. They may look
like <CODE>/menu/index.php3</CODE>. A menustring is usually numeric
and all components have the same length, if necessary with
leading zeroes. It may look like <CODE>/001/007</CODE>, denoting an
item in main menu 1, submenu 7.
<P>
<H3>Instance variables</H3>

<P>
<P>
<CENTER><TABLE BORDER><TR><TD>
<BR>
$urlmap</TD><TD>Hash. Maps a relative URL as seenin PHP_SELF to a menustring.</TD></TR><TR><TD>
$map</TD><TD>Menustring. Current position in menu.</TD></TR><TR><TD>
$item</TD><TD>Hash of Hashes. The <CODE>item</CODE> hash is indexed bymenustring. For each menustring, an arbitrary number of itemattributes is stored. Menu does not use the <CODE>item</CODE> array,only <CODE>Menu::get_cell()</CODE> does, which you implement. Eachmenu item will automatically get an attribute <CODE>url</CODE> through<CODE>urlmap</CODE> inversion from the class constructor and the name ofthe menu item should be stored as the <CODE>title</CODE> attribute. Youmay add other attributes such as <CODE>textcolor</CODE> and <CODE>bgcolor</CODE>and use them in your <CODE>Menu::get_cell()</CODE>implementation.</TD></TR><TR><TD>
$nomain</TD><TD>Boolean. If set, the first menu item will neverbe shown. This menu item is always the menu root, adding anextra level of indentation.</TD></TR><TR><TD>
$title</TD><TD>String. After calling <CODE>get_title()</CODE>, this variable contains the title of the page based on it's location in the menu hierarchy.</TD></TR><TR><TD>
$title_delim</TD><TD>String. Used to delimit (i.e., separate) components in the page title built by <CODE>get_title()</CODE>. Default is <CODE>" : "</CODE></TD></TR><TR><TD>

<CAPTION>Accessible instance variables.</CAPTION>
</TD></TR></TABLE></CENTER>
<P>
<CENTER><TABLE BORDER><TR><TD>
<BR>
$children</TD><TD>Hash of arrays. The <CODE>children</CODE> is indexed bymenustring. For each menustring, an array of childrenmenustrings is stored. This array is generated from <CODE>urlmap</CODE>in the class constructor and is used to determine which submenusare visible from the current <CODE>map</CODE> position.</TD></TR><TR><TD>
$visible</TD><TD>Array of menustrings. The <CODE>visible</CODE> arraycontains the menustrings visible from the current <CODE>map</CODE>position. It is calculated by the <CODE>Menu::get()</CODE> and<CODE>Menu::show()</CODE> functions.</TD></TR><TR><TD>

<CAPTION>Internal instance variables.</CAPTION>
</TD></TR></TABLE></CENTER>
<P>
<H3>Instance methods</H3>

<P>
<P>
<H3>Accessible instance methods</H3>

<P>
<P>
<DL>
<DT><B>Menu()</B><DD><P>Constructor. Calls <CODE>Menu::setup()</CODE> internally.
<P>
<DT><B>show()</B><DD><P>A shorthand notation for <CODE>print $this->get()</CODE>.
<P>
<DT><B>get()</B><DD><P>This function will calculate the menu items visible from the
current <CODE>map</CODE> position. The menu will be constructed by
calling <CODE>Menu::start_menu()</CODE> first. For each visible
menu item, Menu will check the current indentation level and the
indentation level of the current menu cell. If the indentation
level increases, <CODE>Menu::shift_in($oldlevel, $level)</CODE> 
is called once, if it decreases,
<CODE>Menu:shift_out($oldlevel, $level)</CODE> is called once.
<P>After that, <CODE>Menu::get_cell($number, $level)</CODE> is
called once. The number is an index into the <CODE>visible</CODE> array.
<P>After all menu cells have been drawn,
<CODE>Menu::end_menu()</CODE> will be called once.
<P>
<DT><B>get_cell($n, $level)</B><DD><P>
<P>You are expected to implement this function yourself. It should
render a single menu item. You may use the <CODE>visible</CODE> and
<CODE>item</CODE> arrays for that purpose: <CODE>$m = $this->visible[$n]</CODE>
will return a menu string and <CODE>$attr = $this->item[$m]</CODE> is a
hash of attributes for that menu string. <CODE>$hilite =
($this->visible[$n] == $this->map)</CODE> is true for the current
menu item, which should be rendered in way to stand out from the
rest of the menu items.
<P>
<DT><B>get_title()</B><DD><P>
<P>This function will calculate the title of the current page based
on the position of the current page in the menu hierarchy. This
function uses <CODE>$this->title_delim</CODE> to separate the components
of the title. This function sets <CODE>$this>title</CODE> to the calculated
title and returns the title as a string.
<P>
<DT><B>setup()</B><DD><P> 
This function initializes the internal arrays of Menu and should
be called once from the constructor. It actually is the
constructor, but language stupidity has it that PHP3 constructor
names vary with class names, which means that you have to write
a new constructor for each subclass and call this function
manually.
<P>
</DL>
<P>
<H3>Internal instance methods</H3>

<P>
<DL>
<DT><B>normalize_pos($pos)</B><DD><P>This function looks at the current URL in <CODE>$PHP_SELF</CODE>
and tried to translate this into a menustring. If the URL
matches a menustring directly, this is easy.
<P>If not, the current URL will be sequentially shortened by
applying the <CODE>dirname</CODE> PHP function to it until it matches.
This allows you to create a single menu item for all files in a
directory.
<P>
<DT><B>split_path($p)</B><DD><P>This function is used in the construction of the set of visible
menu items. Given a menustring or a pathname, it constructs
a series of pathnames which converge elementwise against the
given pathname. That is, given the menustring <CODE>/3/2</CODE>,
this function will return an array with the elements <CODE>""</CODE>
(the empty string), <CODE>/3</CODE> and <CODE>/3/2</CODE>.
<P>
<DT><B>find_visible($r)</B><DD><P>This function calculates the actual set of visible URLs given a
series of converging pathnames. It will include the set of
children of each of these pathnames in the visible set, then
sort this set numerically.
<P>
</DL>
<P>
<H3>Example</H3>

<P>
<P>To use <CODE>Menu</CODE>, you must enable the require statement for
<CODE>menu.inc</CODE> in <CODE>prepend.php3</CODE>. To use
<CODE>Menu_Button</CODE>, you must enable the require statement
for <CODE>menu.inc</CODE> and <CODE>menu_button.inc</CODE> in <CODE>prepend.php3</CODE>.
<P>Use a subclass of either <CODE>Menu</CODE> or <CODE>Menu_Button</CODE> to
create a menu. Define a class <CODE>Example_Menu</CODE> in your
<CODE>local.inc</CODE> file with a number of menu items in it. Do not
forget to build a constructor.