Sql_Query will generate a query form for simple table queries: A list of field names, comparision operators and input fields is presented. The user may search for any values in any of the presented columns using SQL standard operators. Multiple query conditions are possible and these conditions can be joined using AND and OR operations.
The number of query conditions can be made variable. If so, the user may shrink and grow the query widget using the appropriate buttons.
All button labels and other messages of the interface are variable and held in language dictionaries. Currently, de and en dictionaries are provided.
|
classname | Serialization helper: The name of this class. |
| persistent_slots | Serialization helper: Names of all persistent slots |
| conditions | Number of query conditions |
| input_size | Visible width of input fields |
| input_max | Useable width of input fields |
| method | Form method to GET or POST the form |
| lang | Language dictionary to use |
| translate | Flag: translate column names |
| container | Flag: create a master container |
| variable | Flag: create resize buttons |
|
|
|
dict | The GUI language dictionary. |
| compare | SQL comparison function dictionary.
|
Initialization function. Currently empty.
The function will generate and return HTML for the SQL Query selection form. All
variables in the form will start with the prefix $base and
have numeric indices appended after an underline character. It
is possible to have multiple Sql_Query instances on a single
page, if they use different base characters.
The function must know the field names of the SQL table that is
to be queried. $option can be either a simple array of
these field names ($translate set empty) or a hash field
name to long name ($translate set to on).
All tags in the generated form are tagged with a CSS stylesheet
class, if $class is set to a CSS classname. $class is
optional and if it is left empty, no class attributes are
generated. $target is the URL of the SQL Query form target.
It is optional and if it is left empty, a self referencing form
is generated (recommended).
The function returns a string containing the HTML to render the SQL Query selection form.
When the form() generated page is submitted, a lot of
parameters have to be evaluated and transformed into a SQL
where condition matching the user selections. The
where() function takes care of all this; it just needs to
be told which $base prefix has been used in the form()
call.
The $incr parameter is optional and determines how many
query condition rows are added or subtracted when the "More"
and "Fewer" buttons are used. The default value is 1.
The function returns a string which can be successfully used behind a "where" keyword in a SQL query.
This function does all the work for where(), but does not
resize the query condition window.
The Sql_Query class can be used directly. It is more useful
when made persistent, so it is recommended that you add the line
require("sqlquery.inc") to your prepend.php3 file
where indicated in that file.
See the Table class in this section for a nice method to display and format query results. See the DB_Sql class (a core class) for a nice method to connect to databases.
The following code fragment is quite large, but contains a complete and working example using the Sql_Query, DB_Sql and Table classes to query a database table.
<?php
// We require() sqlquery.inc and table.inc in prepend.inc
// to make this example work!
page_open(array("sess" => "Example_Session"));
$db = new DB_Example; // That's a DB_Sql subclass.
$t = new Table; // For formatting results
$t->heading = "on"; // We want table headings..
?>
<html>
<head><title>Testseite</title>
<style type="text/css"><!--
h1 { font-family: arial, helvetica, sans-serif; color: #d33e30 }
table.test { background-color: #eeeeee }
th.test { font-family: arial, helvetica, sans-serif }
td.test { font-family: arial, helvetica, sans-serif }
table.query { background-color: #cccccc }
td.query { font-face: arial, helvetica, sans-serif }
--></style>
</head>
<body bgcolor="#ffffff">
<h1>Testpage</h1>
<?php
// the following fields are selectable
$field = array(
"username" => "Login Name",
"password" => "Password",
"perms" => "Permissions"
);
// When we hit this page the first time,
// there is no $q.
if (!isset($q)) {
$q = new Sql_Query; // We make one
$q->conditions = 1; // ... with a single condition (at first)
$q->translate = "on"; // ... column names are to be translated
$q->container = "on"; // ... with a nice container table
$q->variable = "on"; // ... # of conditions is variable
$q->lang = "en"; // ... in English, please
$sess->register("q"); // and don't forget this!
}
// When we hit that page a second time, the array named
// by $base will be set and we must generate the $query.
// Ah, and don't set $base to "q" when $q is your Sql_Query
// object... :-)
if (isset($x)) {
$query = $q->where("x", 1);
}
// In any case we must display that form now. Note that the
// "x" here and in the call to $q->where must match.
// Tag everything as a CSS "query" class.
printf($q->form("x", $field, "query));
printf("<hr>");
// Do we have a valid query string?
if ($query) {
// Show that condition
printf("Query Condition = %s<br>\n", $query);
// Do that query
$db->query("select * from auth_user where ". $query);
// Dump the results (tagged as CSS class test)
printf("Query Results = %s<br>\n", $db->num_rows());
$t->show_result($db, "test");
}
page_close();
?>
</body>
</html>
The Table class is a neat way to format two-dimensional associative arrays of data or the results of a database query into a table. Table and its subclasses allow you to simply pass them either an array or a query result and they spit out the proper HTML for a table containing all the values. Table has some primitive filtering capabilities making it useful even without subclassing, but for the full power of Table you have to write your own subclass.
When used with the check option, it is assumed that the table
is part of a HTML FORM element. Code is generated to create
an INPUT TYPE=CHECKBOX element before each table row. The
checkboxes will form an array indexed by row number. The name of
the array will whatever you set the check instance variable
to.
Exactly one of two types of possible column filtering take place
when each table row is generated. If the fields instance
variable is set, only the columns keyed by the named fields in
that array are shown in that order. That is, if you fill in the
fields instance variable with array("a", "c", "e"),
only the columns a, c and e become part of the
generated table.
If fields has not been set, all data columns are traversed
with each() and all columns whose names match the regexp in
filter are shown in the table. By default, this regular
expression lets through all column names that start with an
alphabetic character and continue with either alphanumeric
characters or "_" (underscore). This default has been
chosen, because the DB_Sql database class uses
mysql_fetch_array() internally to get data
from the database and this function returns all columns twice
with both a numeric index and proper column names. The default
filter will make all data show up only once and with proper
column names.
Additionally, the map_cols instance variable provides column
name remapping. If map_cols is set, it will remap the name
of the found column with a new name.
For instance, a table with the following columns, fname,
lname, and mydate can be remapped to First Name,
Last Name, and Date using the following code (where
$t is your instantiated Table class object):
$t->map_cols = array("fname" => "First Name",
"lname" => "Last Name",
"mydate" => "Date");
The map_cols instance variable also allows you to map column
names to different languages using this same technique.
For derived classes, the instance variable add_extra has been added.
If this variable is set, then the functions table_heading_row_add_extra()
and table_row_add_extra() are called. In the Table class, these
functions do nothing, but in derived classes override these functions to
provide additional functionality that may be needed. For instance, hyperlinks
to provide edit, delete, or view capabilities for that row
could be easily added into these functions (in your derived Table class)
allowing greater customization.
A subclass of Table, CSV_Table, is being provided to allow to
create CSV representations of your data with minimal effort. CSV
(comma separated values) can be imported by MySQL's LOAD DATA
INFILE statement and many spreadsheet import functions.
The Table class now provides both high-level, mid-level and low-level
functions through modularization. This allows programmers to use either
the simplified high-level functionality or, depending on the degree of
complexity needed, the power of the mid- or low-level functions. Every
effort to maintain backwards compatibility has been applied. However, it
would be a good idea to become familiar with the new functions if you
use the Table class extensively. Typically, the high- and mid-level
support functions begin with show_ while the low-level functions
do not.
|
classname | Serialization helper: The name of this class. |
| check | If set, the check option is active. |
| filter | A regular expression selecting the columns that are shown. |
| fields | A list of colum names that are shown. |
| heading | A flag; if set, a heading is being created. |
| map_cols | A list of colum names that remap (replace) the static column names. |
| add_extra | A flag; if set, the the extra functions for heading and rows are called. |
|
|
Will format and print the two dimensional array (or hash)
$ary as a table according to the filtering rules explained
above. If $class is set, each HTML element will be tagged
as belonging to the named class; this is useful with cascading
style sheets.
Just as show(), but will show only num elements
starting at start.
Will format and print the result set of $db. $db is
exspected to be a subclass of DB_Sql that has just
been sent a query. Table will grab all available results
from the result set of that query by calling
$db->next_record() repeatedly and format them
into a table.
Just as show_result(), but will show only num
elements starting at start.
Walks the passed array displaying each row of data as an HTML table row.
Walks the passed database object displaying each record as an HTML table row.
Walks the passed array displaying each row of data as an HTML
table row. However, data does not start displaying until
$start element and end after $num rows.
Walks the passed database object displaying each record as an
HTML table row. However, data does not start displaying until
$start record and ends after $num records have been displayed.
Uses the passed array to create an HTML header row.
Uses the passed database object to create an HTML header row.
Walks the passed array and displays each item in an HTML table header cell.
Walks the passed array and displays each item in an HTML table cell.
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
printf("<table%s>\n", $class?" class=$class":"");).
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
printf("<table>\n");/).
Internal function to generate a list of column names.
Internal driver function to generate a table heading row.
This function can be overridden by a subclass of Table. It is called each time a table heading cell is to be generated.
$col is the current column number, $val is the name
of the column. $class is the HTML CSS class of the
element that is to be generated.
Starts a header cell.
Ends a header cell.
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.
Internal driver function to generate a table row.
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.
$row is the current row number. $data is a hash of
column name/value pairs for that row and $class is an
optional HTML CSS class name for all generated elements.
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.
This function can be overridden by a subclass of Table. It is called each time a table cell is to be generated.
$row is the current row number, $cell is the
current cell number. $key is the current column name,
$val is the value of the cell. $class is the
HTML CSS class of the element that is to be generated.
Starts a cell.
Ends a cell.
This function creates an empty header cell to coincide with the checkbox option for that column.
Outputs HTML code to display a checkbox. This function runs
if the member variable $check has been set. $check should be
set to some key within the $data array (ex: if $data["myKey"],
then set $check="myKey").
Creates an HTML checkbox based on the passed data, only if
the instance variable $check is set.
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:
<?php
// Include Table
require("table.inc");
// make a Table instance
$t = new Table;
// We want table headings to be printed.
$t->heading = "on";
Now create a two dimensional array or prepare a database query and have table print it.
// Create a database object
$db = new DB_Session;
// create a twodim array called $tab
$tab = $db->metadata("active_sessions");
// print that array
$t->show($tab, "metadata");
// prepare a database query
$db->query("select * from active_sessions");
// print that result
$t->show_result($db, "data");
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
PHP_SELF to determine the current position in the
menu tree automatically.
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 /menu/index.php3. A menustring is usually numeric
and all components have the same length, if necessary with
leading zeroes. It may look like /001/007, denoting an
item in main menu 1, submenu 7.
|
$urlmap | Hash. Maps a relative URL as seenin PHP_SELF to a menustring. |
| $map | Menustring. Current position in menu. |
| $item | Hash of Hashes. The item hash is indexed bymenustring. For each menustring, an arbitrary number of itemattributes is stored. Menu does not use the item array,only Menu::get_cell() does, which you implement. Eachmenu item will automatically get an attribute url throughurlmap inversion from the class constructor and the name ofthe menu item should be stored as the title attribute. Youmay add other attributes such as textcolor and bgcolorand use them in your Menu::get_cell()implementation. |
| $nomain | Boolean. If set, the first menu item will neverbe shown. This menu item is always the menu root, adding anextra level of indentation. |
| $title | String. After calling get_title(), this variable contains the title of the page based on it's location in the menu hierarchy. |
| $title_delim | String. Used to delimit (i.e., separate) components in the page title built by get_title(). Default is " : " |
|
|
|
$children | Hash of arrays. The children is indexed bymenustring. For each menustring, an array of childrenmenustrings is stored. This array is generated from urlmapin the class constructor and is used to determine which submenusare visible from the current map position. |
| $visible | Array of menustrings. The visible arraycontains the menustrings visible from the current mapposition. It is calculated by the Menu::get() andMenu::show() functions. |
|
|
Constructor. Calls Menu::setup() internally.
A shorthand notation for print $this->get().
This function will calculate the menu items visible from the
current map position. The menu will be constructed by
calling Menu::start_menu() 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, Menu::shift_in($oldlevel, $level)
is called once, if it decreases,
Menu:shift_out($oldlevel, $level) is called once.
After that, Menu::get_cell($number, $level) is
called once. The number is an index into the visible array.
After all menu cells have been drawn,
Menu::end_menu() will be called once.
You are expected to implement this function yourself. It should
render a single menu item. You may use the visible and
item arrays for that purpose: $m = $this->visible[$n]
will return a menu string and $attr = $this->item[$m] is a
hash of attributes for that menu string. $hilite =
($this->visible[$n] == $this->map) is true for the current
menu item, which should be rendered in way to stand out from the
rest of the menu items.
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 $this->title_delim to separate the components
of the title. This function sets $this>title to the calculated
title and returns the title as a string.
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.
This function looks at the current URL in $PHP_SELF
and tried to translate this into a menustring. If the URL
matches a menustring directly, this is easy.
If not, the current URL will be sequentially shortened by
applying the dirname PHP function to it until it matches.
This allows you to create a single menu item for all files in a
directory.
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 /3/2,
this function will return an array with the elements ""
(the empty string), /3 and /3/2.
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.
To use Menu, you must enable the require statement for
menu.inc in prepend.php3. To use
Menu_Button, you must enable the require statement
for menu.inc and menu_button.inc in prepend.php3.
Use a subclass of either Menu or Menu_Button to
create a menu. Define a class Example_Menu in your
local.inc file with a number of menu items in it. Do not
forget to build a constructor.
class Example_Menu extends Menu {
# Map of PHP_SELF URL strings to menu positions
var $urlmap = array(
"/menu/index.php3" => "",
"/menu/item1.php3" => "/1",
"/menu/item11.php3" => "/1/1",
"/menu/item12.php3" => "/1/2",
"/menu/item13.php3" => "/1/3",
"/menu/item2.php3" => "/2",
"/menu/item21.php3" => "/2/1",
"/menu/item22.php3" => "/2/2",
"/menu/item221.php3" => "/2/2/1",
"/menu/item222.php3" => "/2/2/2",
"/menu/item23.php3" => "/2/3",
"/menu/item24.php3" => "/2/4"
);
# Information about each menu item
var $item = array(
"" => array("title" => "Main"),
"/1" => array("title" => "Text 1"),
"/1/1" => array("title" => "Text 1.1"),
"/1/2" => array("title" => "Text 1.2"),
"/1/3" => array("title" => "Text 1.3"),
"/2" => array("title" => "Text 2"),
"/2/1" => array("title" => "Text 2.1"),
"/2/2" => array("title" => "Text 2.2"),
"/2/2/1"=> array("title" => "Text 2.2.1"),
"/2/2/2"=> array("title" => "Text 2.2.2"),
"/2/3" => array("title" => "Text 2.3"),
"/2/4" => array("title" => "Text 2.4")
);
function Example_Menu() {
$this->setup();
}
}
In each of your files mentioned in the above urlmap, create
an instance of Example_Menu and call the show()
method of that instance.
<?php
$m = new Example_Menu;
?><html>
<head>
<title><?php $m->get_menu() ?></title>
</head>
<body bgcolor="#ffffff">
<table border=1 bgcolor="#eeeeee" cellspacing=0 cellpadding=4>
<tr>
<td colspan=2 valign=top align=center>
<h1><?php print $m->title ?></h1>
</td>
</tr>
<tr>
<td align=left valign=top><?php $m->show() ?></td>
<td align=left valign=top>Content</td>
</tr>
</table>
</body>
</html>
The form class (sometimes called OOH Forms) is a convenience library for dealing with html forms. It provides Javascript and server-side form validation, and is customizable and extensible.
The OOH Forms library consists of five files: oohforms.inc
of_checkbox.inc of_radio.inc of_select.inc
of_text.inc of_textarea.inc. oohforms.inc
automatically includes the others. You may wish to modify this so you
can manually include the files for just the form elements you use. Or
you may wish to cut and paste the contents of the element files into
oohforms.inc to save the overhead of multiple includes.
Determining the appropriate configuration of the files for your site
is left an exercise for the reader; for most purposes
require("oohforms.inc") will suffice.
In general, the structure of a page that uses oohforms is as follows:
require("oohforms.inc"); // include the library
$f = new form; // create a form object
$f->add_element(...); // set up form elements
$f->add_element(...);
$f->add_element(...);
if ($submitname) // Is there data to process?
if ($err = $f->validate()) { // Is the data valid?
echo $err; // No; Display error
$f->load_defaults(); // Load form with submitted data
else {
/* Process data */ // Data ok; Do something with it
}
$f->start(...); // Start displaying form
$f->show_element(...); // Show elements
$f->show_element(...);
$f->show_element(...);
$->finish(); // Finish form
There are obviously many variations on this theme, but that covers the basics. Specific methods are documented below.
Outputs the initial <form> tag and sets up some initial
state needed by the class. All of the arguments are optional, though
you'll usually want to use at least one in order to get Javascript
validation. $jvsname is an arbitrary string used to link the
Javascript to the form; if it is empty (the default), no Javascript
validation is provided. $method is the HTTP method used to submit the
form; default is "POST". $action is the URL that receives
the form submission; default is $PHP_SELF. $target is the
frame target for the form results; default is _self.
Outputs the any hidden fields that were added to the form, the
final </form> tag, then the Javascript validation
function (if necessary). $after and $before are both
optional; if either is a nonempty string it is output as additional
Javascript to be run on submission of the form, either before or after
the validation code. Though the order of the arguments may seem
counterintuitive, it makes the common case easier to type; in general
you'll want to wait until after the validation has taken place to do
anything fancy with Javascript. Note that unlike with validation, OOH
Forms has no way of giving you server side functionality equivalent to
the Javascript you use here.
add_element is used to define the attributes of a
particular form element so that the other class methods can use and
manipulate it properly. add_element takes exactly one
argument: an associate array whose key value pairs are used to
define the form element type and it's various attributes. Some of
these attributes correspond to html attributes, while others are
needed for the value added features of oohforms. The attributes and
the syntax and semantics of the values they take are documented below;
note that not all element types use all of the attributes
The type of element this is; can be "submit", "hidden",
"text", "textarea", "select", "radio",
"checkbox", or "file".
A string naming this element. This name will be used as an
argument to other methods and will be the name="" value in the
generated html (and hence the variable name in PHP). Do not
append [] to the name if you want an array valued element; set
the multiple attribute instead.
The default value of this form element. If the form element has
the multiple attribute set, value can be an array. If the
this is a select element, value can refer to either the
textual name (label in the options array) or the submission
value (value in options).
A flag to tell oohforms to assume this element is array valued.
The use of this flag is most straightforward with select elements,
but it can be use with text and checkbox elements as well.
See the show_element documentation for more information
about how oohforms deals with such elements.
Extra html code that is inserted verbatim into the opening form
tag. For select elements, the extra html goes into the
select tag, not the option tags.
For text elements, used to set the html size attribute that
gives the width in characters of the text entry box. For select
elements, the size (number of options visible at once) of the
selection box. Validation is only performed on select elements
if size is set to 1, since select validation doesn't make
much sense if you can see multiple options at once. For file
elements, the maximum size file upload to accept.
If set for a text element, renders the html as a password
element, i.e. entry displays as asterisks.
If set for a submit element, convert to an image element and
use the value of src as the source URL for the image.
Used verbatim as the maxlength html attribute in text
elements.
If length_e is set, this is the minimum length
text element entry accepted by the validator.
If set, validate the text element to assure it has at least
minlength characters. The value of length_e is the
error string to be used in the event of failed validation.
If set, perform validation on a text, radio, or
select element. For a text element, validation assures a
match with valid_ regex. radio element validation
assures that one of the options in the group has been chosen.
select validation only works for select elements with
multiple unset and size equal to 1; the validator will not
accept the first option of accept menu, assuming that it is some sort
of prompt (e.g. "Please select an item"). In all cases, the value of
valid_e is the error string used for failed validations.
Regular expression used to validate entry into a test field if
valid_e is set. Note that if you must use ^...$ if you
want the regex to match the whole entry.
If set, regex matching is case insensitive.
Only used for a checkbox element that does not have
multiple set. If checked is set, the element will display
as checked.
Used verbatim as the rows= element in a textarea element.
Used verbatim as the cols= element in a textarea element.
Used verbatim as the wrap= element in a textarea element.
Array of options to be displayed in a select element. If the
elements of the array are simple values (strings or numbers), they are
simply displayed verbatim and used as the value for that particular
option. The elements may themselves be associate arrays with keys
"label" and "value". In that case, the value of
"label" is displayed and the value of "value" is used on
submission.
Examples:
$f->add_element(array("type"=>"text",
"name"=>"foo",
"valid_regex"=>"^[a-z]*$",
"valid_e"=>"Letters only",
"icase"=>1,
"value"=>"bar"));
$f->add_element(array("type"=>"checkbox",
"name"=>"compress",
"multiple"=>1));
$f->add_element(array("type"=>"textarea",
"name"=>"comment",
"rows"=>6,
"cols"=>40,
"value"=>""));
$o = array(array("label"=>"Please Select","value"=>0),
array("label"=>"Apple","value"=>1),
array("label"=>"Orange","value"=>2),
array("label"=>"Pear","value"=>3),
array("label"=>"Grape","value"=>4));
$f->add_element(array("type"=>"select",
"name"=>"menu",
"options"=>$o,
"size"=>1,
"valid_e"=>"Please select a fruit",
"value"=>"apple"));
Outputs the form element named $name. Usually, the second
argument is not used. It is always necessary for radio elements
and checkbox elements with the multiple attribute set, since
many of these may have the same name. It also must be used for
submit elements to label the submission button; the value
attribute is not used for submit elements. For other elements
that may be array valued (notably text elements) multiple calls
to show_element will show successive values.
Sets the default value of form elements to the value of the PHP variables with the same name. This is generally used to redisplay a form with the same values which were submitted. The argument is optional; if given it is an array of element names; only these elements ares affected.
Validates a form submission. If all of the elements are valid,
return $result, otherwise return the relevant error message (the
valid_e or length_e attribute of some form
element). $result defaults to false. The second argument
is also optional; it is an array of names of elements to validate.
Freezes the form elements whose names are given in the array passed as the argument. If no argument is given, freeze all of the elements. Frozen elements are rendered as plain, static html rather than form widgets. This static rendering is accompanied by appropriate hidden elements to simulate the affect of using the unfrozen version of the element.
Since OOH Forms is object oriented, it can be easily customized by
extending the classes that define the element types. In general, you
must make sure your derived class has a constructor and you may
override any of the self_* functions of
of_element. The source for the existing elements is the
best documentation for how to do this properly, but a few general
notes follow.
Display an instance of this element unfrozen. $val is the
$value argument of show_element if there was one;
$which can be used as an index for array valued elements; it is
equal to the number of times show_element has been called
for this element previously. This function must return the number of
hidden tags output.
Display an instance of this element frozen. In addition to the html to show the frozen element, you must output tags for hidden fields to duplicate the effect of submitting an unfrozen element of this type. The function must return the number of hidden tags output;
Validate $val for this element. If it is valid, return false,
otherwise return the relevant error string.
Print out Javascript code to validate this element.
$ndx_array is an array of the indices of the elements to
be validated as used in the Javascript form.element[] array. This is
needed since the extra [] in array valued element names confuses
Javascript.
Set the default value for this element to $val. Usually the
default definition of this function, which just copies $val to
$this->value is all that is needed, but there may be special
cases that need to do something else. See the implementation of the
checkbox element for an example.
The tpl_form class is intended to provide a general framework for
HTML form deployment. It heavily depends on OOH Forms library, so it
is required that you read and understand the relative documentation.
The main idea is that you create a black box by sub-classing
tpl_form, provide some HTML code mixed with OOH Forms calls
to actually render the form itself. Your application will then use
that black box to obtain some input from the user. Your application
doesn't have to know how to handle user input, nor how to validate
input data, since internal methods will take care of that.
This approach is very similar (I think) to OOH Forms one, only
at a higher level. OOH Forms elements have no way to communicate
with each other, and are only able to perform "simple" checks
on data integrity, while tpl_form adds a consistent interface for
complex data evaluation and processing.
Furthermore, the get_default_values and set_default_values
methods can be used to maintain user input between sessions, without
worrying about serialization of form variables (a BAD THING(tm)), using
an hash array containing field names and values.
You'll note that an array is used to share data with the application.
You may object this is kinda futile, since all user input data may be
found in global vars and HTTP_POST or HTTP_GET global hashes.
This is true, and in the general case you'll pass back and forth an
empty array. The values variable is intended for use in very
complex data-entry setup, where a form behaviour may depend on previous
data entered by the user. In this case, if all forms cooperate reading
and writing to values hash array, final result may be constructed
step by step across multiple HTML pages.
|
classname | Name of the class. Used for serialization AND in display to determine the filename of template containing HTML/php code needed to actually render the form. | |
| error | Contains error messages generated by validate and validate_input methods.values | This is a sort of "shared memory area" between the form and the application. Is read in init method and passed back in get_values method. |
| form data | Holds form info (Form object). | |
| has defaults | Flag, form default values were passed via set_default_values method. Should not be tampered with by the user.
|
This is a sort of a constructor for the class. $values is an hash array
intended to store form values to be passed back to the application via
get_values method.
Returns an array containing all data submitted by the user for the
form. This array is intended to be passed to set_defaults_values
some time later.
Restore form defaults from an array as returned by get_default_values.
Actually display form fields. This method should not be overridden in descendants. User should instead provide a file named as the derived class and with ".ihtml" extension which will be automatically included.
This method should not be overridden. It is intended as the main
interface between the application and the form. Once the form has
been properly derived to suit designer's needs, application calls
get_values and receives back the array passed to init,
eventually modified by process_input method, or false
if user input is invalid. In that latter case, the application should
call display to (re)present the form to the user, eventually
filled with proper default values.
Sort of a "destructor". There should no real need to call it,
except maybe freeing some memory. May be called from the application,
otherwise is not executed. Returns true.
Init the Form object, which will contain all fields info. The hidden
field form_name, automatically added by this routine, is used by other
methods to determine if form has already been submitted by the
user. You shouldn't override this in descendants, use setup_fields
instead. Returns true.
Override this method in order to provide form fields definition that suit your needs.
Validates user input. This method should not be overridden in
descendants. See validate_input instead. Returns false on error
and sets error variable accordingly.
This method should be overridden in descendants, in order to provided
complex validation methods (i.e. field2 should not be empty IF
field1 == "other"). Should return false on error and set
error variable with a sensible error message.
Process user data. This method should not be overridden by descendants.
See process_input and process_default instead. Returns true
on success, false otherwise.
This method should be overridden in descendants. It is executed after
validation has taken place. The data passed to the form could be
used to fill values array.
This method should be overridden in descendants. It is executed when form validation fails or before presenting the form for the first time. Should be used to bypass form displaying if data can be extracted from previous actions, divination, penguin fly watching or whatever.
Suppose you have a form that the user should fill with her (eheh) name and e-mail. You want to check wether this e-mail is valid, or your blind date setup is lost. A... er... simple regular expression for validating syntactically the e-mail is presented in the example code below.
$this->form_data->add_element(array(
"type"=>"text",
"name"=>"email",
"valid_e"=>"Syntax error in E-Mail address.",
"valid_regex"=>"^([-a-zA-Z0-9.]+@[-a-zA-Z0-9]+(\.[-a-zA-Z0-9]+)+)*$"
));
Now, this piece of code should do the job, but since you're feeling
very paranoid today, you'd also like to validate the host name part of the
address with DNS. So, you put together some code which takes an hostname
in input and reports true on valid hostname, false otherwise
(HINT: on
PHP Code Exchange
you should find a procedure for "active" email validation).
Now that you have your shining new code, you can check the address.
The user fills out the form, you parse user input, no syntax errors,
time to call your mycheckhost from the application. If the function
is ok update your database, else load defaults into the form, display
again, close the page, goodbye.
I've done something similar for MANY forms, some of them with very complex validation procedures, and I found that was too easy producing very bad and unreadable code (well, I actually realized that the first time I had to change some logic in data validation...).
tpl_form should provide a solid framework to build your forms
with, and all the code will be self-contained and separated from main
application logic. Hope you'll like it.
Time to see some code. First of all, class declaration, sub-classing
tpl_form:
class myform extends tpl_form {
var $classname = "myform";
function setup_fields() {
$this->form_data->add_element(array(
"name"=>"email",
..., // See previous code snippet
));
$this->form_data->add_element(array(
"name"=>"submit",
"type"=>"submit",
"value"=>"submit"
));
}
function validate_input() {
global $email;
list($uname, $hostname) = split("@", $email);
if (! mycheckhost($hostname)) {
$this->error = sprintf("Sorry, unknown host %s, try again.", $hostname);
return false;
}
// Additional checks here...
return true;
}
}
You shuld provide a file myform.ihtml with HTML and php code to
render the form. Minimalistic example:
<html>
<body>
<?php
$this->form_data->start_form($this->classname, "POST", $sess->self_url(), "");
printf("%s<br>\n", $this->error);
$this->form_data->show_element("email");
printf("<br>\n");
$this->form_data->show_element("submit");
$this->form_data->finish();
?>
</body>
</html>
Your tpl_form class is complete, and will only need a little
work on the artistic side... 8-) To use your brand new class, include
class definition code into your application, then...
$mf = new myform;
$mf->init(array()); // This is not strictly required, AT PRESENT,
// but I recommend it
if ($rv = $mf->getdata()) {
$mf->clear(); // This is not strictly required, anyway it should free
// some memory...
global $email;
// process your data at will
} else {
$mf->display();
}
Hope this very little example does help in understanding the
real power of tpl_form class, at least in terms of
rapid designing and code partitioning.
The Tree class can render tree structures such as directory hierarchies and menu structures as HTML. The structure must be given to Tree as an nested array of arrays of arbitrary depth.
The idea of Tree is, that there are several mathematical models a tree could be viewed: One model is a data structure like nested arrays or a pointer structure from where you can print multidimensional graphics and can do other neat things like deleting one part of the tree or inserting a whole subtree. But you can also imagine a tree as a one dimensional string or as a sequence of function calls (which is nearly the same in the mathematical sense).
To generate HTML-code from a tree-structure it is like this: You need at the end a one-dimensional string, which tells the browser what to do. The Tree class assists you in generating this string in this way, that it will go through the whole tree and call several functions on every stage trough the way. It will be your task to change the functions, so that a nice layout will be generated.
|
classname | Serialization helper: The name of this class. |
| delimiter | a char for truncating the "path" |
| tree | an array of an array of an array |
| outp | the "output" |
| prfx, sufx, flag | internal - some helpers to create outp
|
This function is completely user driven! You have to create an array with the structure described below. See the example for details.
Don't be shy to create some own functions which are called by
build_tree() - e.g. for recursive calls.
This is the most important function of this class. It will call the output functions in the right order with the correct parameters.
All variables are optional. The parameters are perhaps useful, if you want to display only partial trees, but this is not supported now.
This function is mostly used internally, but could be useful
for you to generate $this->tree. This function generates
a PHP3 associate array-index string from a path, which is also
a string but truncated by $this->delimiter. If $key
is given, it will be added to $path (minds empty path and
so on).
Example:
$t->delimiter="/";
$path= "usr/local/lib";
## $path must be given as a var, because it is called by reference!
$bla = $t->path_to_index($path,"etc");
## $path is now "usr/local/lib/etc"
## $bla is now ["usr"]["local"]["lib"]["etc"]
This function isn't used internally, but could be useful for you during generating the output tree. It will remove one from the depth of the path.
Example:
$t->delimiter="/";
$path= "usr/local/lib";
$bla = $t->path_to_parent($path);
## $path is now "usr/local"
## $bla is now ["usr"]["local"]
This function is the 'non-call-by-reference-version' of
path_to_index. It will add the $key to
the path and return it.
This function is the 'non-call-by-reference-version' of
path_to_parent. It will find the
parent of path and return it.
This function is the 'non-call-by-reference-version' of
path_to_index(). It will return the
associate key to the tree described by path.
This function is called by go_trough_tree()
at the beginning of the output of a tree.
All *tree-functions are called by go_trough_tree(),
but it's your turn, to give them a nice layout. I think it is possible
to generate nearly every kind of tree-layout with this. Have a look at
the variables: E.g. $depth makes it possible to handle every
"level" in another manner.
This function is called by go_trough_tree()
at the beginning of the output of a tree.
It is called every time, when go_trough_tree()
will call itself recursively. You could also say it is called, when
the current item has a successor.
This function is called, when the current item has no successor.
This function is the "opposite" of growtree(). It is
called every time, when the current item was the last item in this
sub-list.
Called when leaving tree.
As said above, before you call go_trough_tree(),
first $tree must be generated.
$tree consists of nested arrays of arbitrary depth. An example:
$t= new Tree;
$t->tree = array(
"usr" => array(
0 => "allowed",
"lib" => "forbidden",
"local" => "allowed",
"bin" => "forbidden",
"etc" => array(
0 => "allowed",
"hosts" => "forbidden",
"mailcap"=> "allowed"
),
"var" => "allowed",
"tmp" => "allowed"
),
"root" =>"forbidden"
);
$t->go_through_tree();
print $t->outp;
This is a completely recursive structure and I think, it is clear, how to create it with a recursive call of a function. If not, see the example below.
One little quirk has to be explained, because it is a little bit confusing: the array name 0 (zero) is used for the value of the parent element. As shown in the example, an element with children (for example "etc") cannot have attributes (such as "allowed"). Instead the value of this element is stored in a pseudo-child named 0. If this element is not present, it will have the value "Array" (perhaps something that should be changed).
The output of this example if you don't change the output-functions will look like this:
/
^---- usr->'allowed' : 'usr' (1) [1/2]
| ^---- lib->'forbidden' : 'usr^lib' (2) [2/7]
| O---- local->'allowed' : 'usr^local' (2) [3/7]
| O---- bin->'forbidden' : 'usr^bin' (2) [4/7]
| O---- etc->'allowed' : 'usr^etc' (2) [5/7]
| | ^---- hosts->'forbidden' : 'usr^etc^hosts' (3) [2/3]
| | \--- mailcap->'allowed' : 'usr^etc^mailcap' (3) [3/3]
| O---- var->'allowed' : 'usr^var' (2) [6/7]
| \--- tmp->'allowed' : 'usr^tmp' (2) [7/7]
\--- root->'forbidden' : 'root' (1) [2/2]
Looks a bit confusing. From left to right the fields are
path_to_*-functions)
My example is just going trough the directory structure of your hard disk.
The following code could read it:
class dir_Tree extends Tree {
var $classname = "dir_Tree";
var $delimiter="/";
var $tdat;
function build_tree ($path=".") {
$this->tree=$this->recurs_dir($path,0);
}
## This example code can read and output 1000 directory entries with
## many subdirs in about 20 seconds on my system (P200, 64 MB);
## 220 dir entries with a maximum depth of 4 are read in 2 seconds.
## This is ok. :)
function recurs_dir ($path,$depth) {
GLOBAL $flap_out;
$d=opendir($path);
while ( $name=readdir($d) ) {
$pathname=$path . $this->delimiter . $name;
if (is_dir($pathname) && !ereg("\.\.?",$pathname)) {
if (isset($flap_out[$pathname])) {
$array[$name]=$this->recurs_dir($pathname,$depth+1);
}
# ATTENTION: It is IMPORTANT fill the [0] array
# *after* filling the rest of the array!
$array[$name][0]=$pathname;
} else {
$array[$name]=$pathname;
}
}
closedir($d);
return($array);
}
#################################################
## FLAPPING IN and OUT
## This is used to create an array which includes
## all sub-paths which should be showed
##
function flapping ($path) {
GLOBAL $flap_out;
if ($path) {
if (is_dir($path)) {
if (isset($flap_out[$path])) {
unset($flap_out[$path]);
} else {
$flap_out[$path]=$name;
}
}
}
}
}
$t= new dir_Tree;
$t->flapping($val); ## $val is given by GET-method, see *tree()-functions
$t->build_tree();
$t->go_through_tree();
print $t->outp;
With this code it is very easy to flap in and out whole
parts of the tree. Send the path via GET-method and put
this path in flapping(). The whole $flap_out-array must be
persistent (e.g. via session). Perhaps you can program a garbage
collection, which will look into $flap_out and check for paths that
already exist?
There is one known bug: If a name of a subpath contains the
$delimiter-string. This cannot be solved correctly and you have
to look for it when you create the tree.
The same thing is with the value [0] (zero) of a sub-array. This element is always used as the attribute of the parent element.
A good tip: when you build your tree recursively then the [0]-index must be filled after the subtree is returned from recursive call. See in the example above what I mean. I think it's a PHP3 specialty.
Also it is possible that not every name could be inserted into the associate index-field (Control-chars etc.), but this is untested.
This is a set of functions, which are used very often by me.
They are so easy, that I now stop describing and simply insert the code. Perhaps the next revision of this set I will replace it with a better description:
<?php
##
## Strings2-Functions
##
## Copyright (c) 1998-2000 Alex 'SSilk' Aulbach
##
## These Functions are very practical and if I could program
## C a little bit better it will be placed directly in PHP3.
## But I can't... :-}
##
##
## Have you ever worried about such constructs like
## echo ($faxnumber) ? sprintf("Fax: %s",$faxnumber) : "";
##
## This functionset could help you to replace those constructs by
## p_iftrue($faxnumber,"Fax: %s");
## which is nearly the half of typing and looks more clear and solves
## an error if $faxnumber is unset.
##
function o_iftrue ($val,$str) {
if (isset($val) && $val) {
return(sprintf($str,$val));
}
}
function p_iftrue ($val,$str) {
print o_iftrue($val,$str);
}
##
## Output "One or More"
##
## This function is good if you want to differ a output by number:
## e.g. o_1or2($q->num_rows(),
## "Found only one matching record",
## "Found %s records");
## Will output if num_rows() is 1: "Found only one matching record"
## 200: "Found 200 records"
##
## if $val is empty() or "" a blank string will be returned!
##
function o_1or2 ($val,$str1,$str2) {
if (isset($val) && $val) {
if (1==$val) {
return(sprintf($str1,$val));
} else {
return(sprintf($str2,$val));
}
} else {
return(false);
}
}
function p_1or2 ($val,$str1,$str2) {
print o_1or2 ($val,$str1,$str2);
}
##
## This is for the case, that you want to output something
## if $val is false e.g.
##
## p_0or1($faxnumber,"THERE IS NO FAXNUMBER","Faxnumber: %s");
##
function o_0or1 ($val,$str1,$str2) {
if (empty($val) || !$val) {
if (isset($val)) {
return(sprintf($str1,$val));
} else {
return($str1);
}
} else {
return(sprintf($str2,$val));
}
}
function p_0or1 ($val,$str1,$str2) {
print o_0or1 ($val,$str1,$str2);
}
##
## Replaces all blank-chars with
## This function is used, when you are not willing to let the browser
## break your lines an can be used instead of <NOBR>-Tag
## as very compatible replacement
##
## can also be replaced by a true whitespace which has in
## ISO-latin-1 the code 160
##
function o_nonbsp ($val) {
return(ereg_replace("[[:blank:]\n\r]"," ",$val));
}
function p_nonbsp ($val) {
print o_nonbsp($val);
}
?>