documentation-4.html

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

<HR>
</CODE></BLOCKQUOTE>
</LI>
</UL>
<P>Now you have a <CODE>$cart</CODE> object available by default on every
page that uses PHPLIB. That object is created automatically at
session startup, is carried from page to page by PHPLIBs session
management and is destroyed by the garbage collection that reaps
session records. You do not have to worry anymore about that
cart, but simply use it anytime between <CODE>page_open()</CODE>
and <CODE>page_close()</CODE>. PHPLIB does the rest for you.
<P>The <CODE>Cart</CODE> class is actually dead stupid. It maintains an array
<CODE>$cart-&gt;item[]</CODE> that holds records about what the user bought. Each
<CODE>$cart-&gt;item[$x]</CODE> consists of a
<CODE>$cart-&gt;item[$x]["art"]</CODE>, which is
the article number of an item the user wants to buy and of a
<CODE>$cart-&gt;item[$x]["num"]</CODE>, which is the # of items with that article
number that are wanted. <CODE>$cart-&gt;currentItem</CODE> is the next $x to use
for articles added to <CODE>$cart-&gt;item[]</CODE>.
<P>You add articles to the shopping cart with
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
$x = $cart->add_item($art, $num)
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>This will add <CODE>$num</CODE> items with the article number <CODE>$art</CODE>
to your cart contents. If you already have an item with that
article number in your cart, the count for that article is
increased by <CODE>$num</CODE>. Otherwise a new article entry is being
created and set to <CODE>$num</CODE>. The function does return the
<CODE>$x</CODE> index into the <CODE>$cart-&gt;item[]</CODE> array for that article.
<P>To remove an item from the shopping cart, code
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
$x = $cart->remove_item($art, $num)
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>This will remove <CODE>$num</CODE> items with the article number
<CODE>$art</CODE> from your cart, if there are that many items in your
shopping cart. If you do not have the <CODE>$art</CODE> in your cart or
there are not <CODE>$num</CODE> many <CODE>$art</CODE> in your cart, the
function will return false and not remove anything from the
cart. Otherwise, <CODE>$num</CODE> articles with article number
<CODE>$art</CODE> are taken out of the cart and if the count for that
article drops to zero while doing this, we even unset the array
element.
<P>You may check how many articles with a given article number are
in the cart:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
list($have, $num) = $cart->check($art)
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>The check function does return a two-element array. The first
element <CODE>$have</CODE> is true, if we have the wanted article in the cart.
If <CODE>$have</CODE> is true, <CODE>$num</CODE> holds the number of articles with that
number in the cart, otherwise <CODE>$num</CODE> is undefined (actually, it is
0, but you must not rely on that).
<P>Finally, we have a function
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
$cart->show_all()
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>which you may call to walk your shopping cart and have
Example_Cart to generate a list of articles in your cart. That
function will first call <CODE>$cart-&gt;show_cart_open()</CODE>, for which you
may provide code in your subclass. It will then call
<CODE>$cart-&gt;show_item($art, $num)</CODE> for each item in the cart. We have a
stupid default implementation for that function in Cart, but you
may provide more sophisticated code in <CODE>Example_Cart</CODE> for that, too.
Finally, at the end of your cart listing,
<CODE>$cart-&gt;show_cart_close()</CODE> is being called, which again may be code
of yours.
<P>The example in the previous section shows a more
sophisticated implementation of a Cart subclass. That
implementation uses show_cart_open() to create an opening 
table tag (formatted with a CSS class) and sets a counter
<CODE>$cart-&gt;sum</CODE> to
zero.
<P>In show_cart_close(), the table is being closed and the
<CODE>$cart-&gt;sum</CODE> counter is printed.
<P>As you might have guessed, <CODE>show_item($art, $num)</CODE> queries the
database for each article number, retrieves the article
description and prices and finally sums up all prices, taking the
number of articles per article into consideration. It also
generates table rows, printing a nice receipt for the customer.
<H2><A NAME="ss4.2">4.2 Template</A>
</H2>

<P><EM>Note:</EM> If you think that this is like FastTemplates, read
carefully. It isn't.
<P>
<P> 
The template class allows you to keep your HTML code in some
external files which are completely free of PHP code, but
contain replacement fields. The class provides you with
functions which can fill in the replacement fields with
arbitrary strings. These strings can become very large, e.g.
entire tables.
<P>
<P>
<H3>Instance variables</H3>

<P>
<P>
<CENTER><TABLE BORDER><TR><TD>
<BR>
classname</TD><TD>String. Serialization helper: The name of this class.</TD></TR><TR><TD>
debug</TD><TD>Boolean: if set to true, the class will emitdebugging output.</TD></TR><TR><TD>
unknowns</TD><TD>One of "keep", "comment", "remove" (Default).Determines how to handle unresolved variable names intemplates upon output. If set to "keep", those are leftuntouched. If set to "comment", unresolved variable names aretransformed into HTML comments reporting the error. If set to"remove", unresolved variable names are silently removed (thedefault).</TD></TR><TR><TD>
halt_on_error = "yes"</TD><TD>One of "yes"(Default), "report", "no". Determines how Template handleserror conditions. If set to "yes" (the Default), the error isreported, then execution is halted. If set to "report", theerror is reported, then execution continues by returning"false". If set to "no", errors are silently ignored, andexecution resumes reporting "false".</TD></TR><TR><TD>
last_error = ""</TD><TD>The last error message iskept in this variable.</TD></TR><TR><TD>

<CAPTION>Accessible instance variables.</CAPTION>
</TD></TR></TABLE></CENTER>
<P>
<CENTER><TABLE BORDER><TR><TD>
<BR>
file</TD><TD>Hash of strings. A translation table whichtranslates variable names into filenames.</TD></TR><TR><TD>
root</TD><TD>String (Pathname). The base directory from whichtemplate files are being loaded.</TD></TR><TR><TD>
varkeys</TD><TD>Hash of strings. A translation table whichtranslates variable names into regular expressions forthemselves.</TD></TR><TR><TD>
varvals</TD><TD>Hash of strings. A translation table whichtranslates variable names into replacement values for theirrespective varkeys.</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>Template($root = ".", $unknowns = "remove")</B><DD><P>Constructor. May be called with two optional parameters. The
first parameter sets the template directory (see
<CODE>set_root()</CODE>, the second parameter sets the policy
regarding handling of unknown variables.
<P>
<DT><B>set_root($root)</B><DD><P>The function checks that $root is a valid directory and sets
this directory as the base directory where templates are being
stored.
<P>
<DT><B>set_unknowns($unknowns = "keep")</B><DD><P>The function sets the policy for dealing with unresolved
variable names. Must be either "remove", "comment" or "keep". If
set to "keep", those are left untouched. If set to "comment",
unresolved variable names are transformed into HTML comments
reporting the error. If set to "remove", unresolved variable
names are silently removed (the default).
<P>
<DT><B>set_file($handle, $filename = "")</B><DD><P>The function defines a filename for the initial value of a
variable. It may be called with either a $handle/$filename pair
or with a hash of $handle/$filename pairs. The files are not
referenced yet, but only when needed.
<P>
<DT><B>set_block($parent, $handle, $name = "")</B><DD><P>A variable $parent may contain a variable block named by
$handle. The function removes that block from $parent and
replaces it with a variable reference named $name. If $name is
omitted, it is assumed to be the same as $handle.
<P>
<DT><B>set_var($varname, $value = "")</B><DD><P>The functions sets the inital value of a variable. It may be
called with either a $varname/$value pair or with a hash of
$varname/$value pairs.
<P>
<DT><B>subst($handle)</B><DD><P>The function returns the value of the variable named $handle,
with all defined variable values filled in. The resulting string
is not "finished", that is, the unresolved variable name policy
has not been applied yet.
<P>
<DT><B>psubst($handle)</B><DD><P>This is a shorthand for <CODE>print $this->subst($handle)</CODE>.
<P>
<DT><B>parse($target, $handle, $append = false)</B><DD><P>The function substitutes the values of all defined variables in
the variable named $handle and stores or appends the result in
the variable named $target.
<P>If $handle is an array of variable names, $append is ignored.
The variables named by $handle are being sequentially
substituted and the result of each substitution step is stored
in $target. The resulting substitution is available in the
variable named by $target, as is each intermediate step for the
next $handle in sequence.
<P>
<DT><B>pparse($target, $handle, $append = false)</B><DD><P>A shorthand for <CODE>print $this->parse(...)</CODE>.
<P>
<DT><B>get_vars()</B><DD><P>Returns a hash of all defined values, keyed by their names.
<P>
<DT><B>get_var($varname)</B><DD><P>Returns the value of the variable named by $varname. If $varname
references a file and that file has not been loaded, yet, the
variable will be reported as empty.
<P>When called with an array of variable names, an hash of values,
keyed by their names, will be returned.
<P>
<DT><B>get_undefined($handle)</B><DD><P>The function will return a hash of unresolved variable names in
$handle, keyed by their names (that is, the hash has the form
$a[$name] = $name).
<P>
<DT><B>finish($str)</B><DD><P>The function will returned the finished version of $str, that
is, the policy regarding unresolved variable names will be
applied to $str.
<P>
<DT><B>p($varname)</B><DD><P>The function will print the finished version of the value of the
variable named by $varname.
<P>
<DT><B>get($varname)</B><DD><P>The function will return the finished version of the value of
the variable named by $varname.
<P>
<DT><B>haltmsg($msg)</B><DD><P>This function can be overridden by your subclass of Template. It
will be called with an error message to print.
</DL>
<P>
<H3>Internal instance methods</H3>

<P>
<DL>
<DT><B>filename($filename)</B><DD><P>When called with a relative pathname, this function will return
the pathname with $this->root prepended. Absolute pathnames are
taken unchanged.
<P>The resulting filename must exist, or an error is generated.
<P>
<DT><B>varname($varname)</B><DD><P>The function will construct a variable name regexp for a given
variable name.
<P>
<DT><B>loadfile($handle)</B><DD><P>If a variable is undefined or empty and is backed by a filename,
the backing file will be loaded and the files contents will be
assigned as the variables value.
<P>
<DT><B>halt($msg)</B><DD><P>This function is called whenever an error occurs and will handle
the error according to the policy defined in
$this->halt_on_error.
</DL>
<P>
<H3>Example</H3>

<P>The class manages a set of variables which are text strings.
These strings may contain references to other variables in the
form of "{variable}". When parsed or substituted, a variable
reference is being replaced by the value of that variable.
<P>A variable value may be defined manually by calling
<CODE>set_var("name", "value");</CODE> or it may be defined from
a file by calling <CODE>set_file("name",
"filename.ihtml");</CODE>. In the latter case, the contents of the
file are being loaded when needed (as late as possible) and set
as the value of that variable.
<P>A third way to define a variable value is to call
<CODE>set_block("parent", "block", "name");</CODE>. In this case,
the variable named <CODE>parent</CODE> is being searched for a block
that starts with <CODE>&lt;!-- BEGIN block --&gt;</CODE> and ends
with <CODE>&lt;!-- END block --&gt;</CODE>. This string is removed
from the variable <CODE>parent</CODE> and assigned to the variable named
<CODE>block</CODE>. In <CODE>parent</CODE>, a variable reference to <CODE>name</CODE> is
placed instead. If the optional parameter <CODE>"name"</CODE> is left
out, <CODE>"block"</CODE> is being used instead.
<P>Use <CODE>Template</CODE> direcly or define a subclass of <CODE>Template</CODE>
as needed.
<P>Define a template file named page.ihtml as follows:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
&lt;html&gt;
 &lt;head&gt;&lt;title&gt;{PAGETITLE}&lt;/title&gt;&lt;/head&gt;
 &lt;body bgcolor="#ffffff"&gt;
 &lt;table border=1 cellpadding=4 cellspacing=0 bgcolor="#eeeeee"&gt;
  &lt;tr&gt;
   &lt;td colspan=2&gt;&lt;h1&gt;{PAGETITLE}&lt;/h1&gt;&lt;/td&gt;
  &lt;/tr&gt;
  &lt;tr&gt;
   &lt;td&gt;{OUT}&lt;/td&gt;
   &lt;td&gt;Content&lt;/td&gt;
  &lt;/tr&gt;
 &lt;/table&gt;
 &lt;/body&gt;
&lt;/html&gt;
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>This file contains a reference to the variable <CODE>pagetitle</CODE>
and a reference to the variable named <CODE>out</CODE>. Another template 
file, named box.ihtml, contains a block named row with three
variable references {TITLE}, {NUM} and {BIGNUM}:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
&lt;!-- start box.ihtml --&gt;
&lt;table border=1 bgcolor="#cccccc" cellpadding=4 cellspacing=0&gt;
 &lt;tr&gt;
  &lt;td colspan=2&gt;&lt;b&gt;{TITLE}&lt;/b&gt;&lt;/td&gt;
 &lt;/tr&gt;
  &lt;!-- BEGIN row --&gt;
  &lt;tr&gt;
   &lt;td&gt;{NUM}&lt;/td&gt;
   &lt;td&gt;{BIGNUM}
  &lt;/tr&gt;
  &lt;!-- END row --&gt;
&lt;/table&gt;
&lt;!-- end box.ihtml --&gt;
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>The following php3 file demonstrates how to use these templates:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
&lt;?php
  include("./template.inc");

  # create Template instance called $t  
  $t = new Template("/page/to/webserver/template", "keep");

  # define variables named page and box, referencing files
  $t-&gt;set_file(array(
     "page" =&gt; "page.ihtml",
     "box"  =&gt; "box.ihtml"));

  # extract the block named "row" from "box", creating a
  # reference to {rows} in "box".
  $t-&gt;set_block("box", "row", "rows");

  # define the variables TITLE and PAGETITLE
  $t-&gt;set_var(array("TITLE"     =&gt; "Testpage",
                    "PAGETITLE" =&gt; "hugo"));

  # define NUM and BIGNUM, then append "row" to "rows"...
  for ($i=1; $i&lt;=3; $i++) {
    $n  = $i;
    $nn = $i*10;
    $t-&gt;set_var(array("NUM" =&gt; $n, "BIGNUM" =&gt; $nn));
    $t-&gt;parse("rows", "row", true);
  }

  # build out from box, then build out from page...
  $t-&gt;parse("out", array("box", "page"));

  # finish out and print it.
  $t-&gt;p("out");
?&gt;
&lt;hr&gt;
&lt;?php
  # report leftover variables, if any.
  print implode(", ", $t-&gt;get_undefined("rows"));
 ?&gt;
</PRE>
<HR>
</CODE></BLOCKQUOTE>

<P>
<P>
<HR>
<A HREF="documentation-5.html">Next</A>
<A HREF="documentation-3.html">Previous</A>
<A HREF="documentation.html#toc4">Contents</A>
</BODY>
</HTML>