FreeMED Module API Programming
Prev	Chapter 3. phpwebtools	Next

Classes

FileSerialize Class

The FileSerialize class allows data to be serialized and stored in a file, which can be read from in the same object-oriented manner. This makes creating caches very easy.

FileSerialize Constructor

object FileSerialize(string filename, [boolean base64]);

Creates a FileSerialize object using the specified filename. If base64 is true, the serialized data is base64 encoded.

FileSerialize->read

mixed FileSerialize->read

Reads serialized data from the file, and returns it.

FileSerialize->write

array $sql->write(mixed data);

Writes specified data to the file.

module Class

This is described in depth in the module section of this guide.

module_list Class

This class is used to access dynamic modules, and uses FileSerialize to keep an up-to-date cache of meta-information, so that all of the modules do not have to be loaded to load a single module.

module_list Constructor

object module_list(string package, [array options]);

Creates a module_list object for the software package specified in package. options can be: 'directory' (specifies the modules directory), 'display_hidden' (forces hidden modules to be shown in display functions), 'suffix' (specifies a particular suffix for modules).

module_list->cached

boolean module_list->cached(string directory);

Determines if the specified directory has an up-to-date cache.

module_list->categories

array module_list->categories

Returns an array of all of the categories of modules defined.

module_list->check_for

boolean module_list->check_for(string module_name);

Determines if module_name is a module which exists on the system. It determines this by checking to see if any of the class names in the cache match module_name.

module_list->empty_category

boolean module_list->empty_category(string category, [string minimum_version]);

Determines if a specified category has no modules in it. It can optionally only check for modules with a CATEGORY_VERSION above minimum_version.

module_list->execute

mixed module_list->execute(string module, [array parameters]);

Executes module module's "execute" method, optionally with parameters and returns the result.

module_list->generate_array

array module_list->generate_array(string category, string category_version, [string key_template], [string value_template], [string icon_template]);

Generates an array of module information from all the modules in the current module_list object, matching the category in the category option and having a minimum category version of category_version. It will also skip any modules with MODULE_HIDDEN set to true. The MODULE_HIDDEN behavior can be disabled by setting module_list->display_hidden to true.

The icon_template describes how the #icon# macro is expanded, and by default inserts an IMG HTML tag. The key_template and value_template are the templates used to form the keys and values of the associative array that is returned. They use the following macros, which expand:

Table 3-1. module_list macro expansion

Tag	Description
#author#	module author
#class#	class name
#description#	module description
#icon#	expanded icon tag
#name#	module name
#version#	module version

module_list->generate_list

string module_list->generate_list(string category, string category_version, [string template], [string icon_template]);

This function behaves like the module_list->generate_list() method, except that it produces a single string instead of an array.

module_list->get_module_name

array module_list->get_module_name(string module);

Returns the text name of a module (MODULE_NAME) from the module's class, which is passed as the module parameter.

notebook Class

notebook Constructor

object notebook(array common_variables, [integer options], [integer spill_at], [string form]);

Creates a notebook object. common_variables are variables that have to be passed with every page reload. options is a bit flag set, which can be composed of the options in the notebook class option flags table. These options are passed connected by bitwise or's (example: NOTEBOOK_COMMON_BAR | NOTEBOOK_STRETCH).

spill_at defines how many tabs should be displayed before a notebook "spills" to the next line of tabs. form optionally defines the name of the form that this notebook is using.

Table 3-2. Notebook class option flags

Flag	Description
NOTEBOOK_COMMON_BAR	display common bar at the bottom
NOTEBOOK_NOFORM	notebook is in already declared FORM
NOTEBOOK_STRETCH	stretch notebook to screen width
NOTEBOOK_TABS_LEFT	display tabs on the left
NOTEBOOK_TABS_RIGHT	display tabs on the right

notebook->been_here

boolean notebook->been_here

Returns true if this notebook has been previously loaded, or false if this was the first page load.

notebook->get_current_page

integer notebook->get_current_page

Returns the current notebook page.

notebook->get_vars

array notebook->get_vars

Returns an array of all variables used by the notebook. This is useful for embedding the notebook in other objects (like another notebook or a wizard).

notebook->is_cancelled

boolean notebook->is_cancelled

Returns true if the last action was to cancel the notebook.

notebook->is_done

boolean notebook->is_done

Returns true if the notebook has been completed.

notebook->add_page

void notebook->add_page(string name, array variables, string text, [array errors], [array warnings]);

Adds a notebook "page" with title as the tab name, variables as the list of all variables that are passed by this page exclusively, and text containing the body of the notebook page. errors and warnings are part of the phpwebtools verification system, and function the same way that the wizard class verification routines function.

notebook->display

string notebook->display

Returns the notebook widget to be displayed.

notebook->set_foreground_color

void notebook->set_foreground_color(string color);

Sets the foreground color for this widget in #RRGGBB format.

notebook->set_background_color

void notebook->set_background_color(string color);

Sets the background color for this widget in #RRGGBB format.

notebook->set_button_color

void notebook->set_button_color(string color);

Sets the button color for this widget in #RRGGBB format.

notebook->set_line_color

void notebook->set_line_color(string color);

Sets the line color for this widget in #RRGGBB format.

notebook->set_cancel_name

void notebook->set_cancel_name(string title);

Sets the text for the Cancel button.

notebook->set_submit_name

void notebook->set_submit_name(string title);

Sets the text for the Submit button.

notebook->set_refresh_name

void notebook->set_refresh_name(string title);

Sets the text for the Refresh button.

notebook->set_revise_name

void notebook->set_revise_name(string title);

Sets the text for the Revise button.

notebook->set_spill_at

void notebook->set_spill_at(integer spill);

Sets the number of tabs to display before the notebook widget "spills" them onto the next row.

notebook->set_stretch_on

void notebook->set_stretch_on

Sets the notebook to stretch to the screen size.

notebook->set_stretch_on

void notebook->set_stretch_off

Sets the notebook to not stretch to the screen size.

sql Class

$sql Constructor

object sql(enum database_type, array options);

This is called to create the sql object. Under normal circumstances, this would not have to be called, since lib/freemed.php (which is included by almost every part of FreeMED) creates the main sql object. database_type can be SQL_MYSQL, SQL_POSTGRES, SQL_ORACLE, or any of the types supported by phpwebtools.

options is an associative array, with the possible options listed in the sql class option table.

Table 3-3. sql class option table

Option	Description
'database'	database name
'host'	server host name
'path'	used by SQL_SQLITE only
'password'	SQL server password
'serialize'	when true, uses serialize method to compact arrays
'user'	SQL server user name
'verbose'	set verbosity

$sql->fetch_array

array $sql->fetch_array(sql_result result);

Returns an associative array of values from an SQL query. Uses same conventions as mysql_fetch_array().

$sql->last_record

integer $sql->last_record([sql_result result], [string table]);

Returns the id of the last record to be added to a table. It can optionally take the result of the last query and the name of the table, if the id to be retrieved was not the absolute last query performed.

$sql->num_rows

integer $sql->num_rows(sql_result result);

Returns the number of rows in an sql result, or returns 0 if the result is invalid. Uses the same syntax as mysql_num_rows().

$sql->query

sql_result $sql->query(string query);

Executes an SQL query. Uses the same syntax as mysql_query().

$sql->results

boolean $sql->results(sql_result result);

Determines from an sql result whether any data was retrieved or not.

$sql->create_table_query

string $sql->create_table_query(string table, array values, [array keys]);

Generates an SQL table definition CREATE TABLE query from the table definition specified in values, which is an associative array with the keys being the column names and the values being their definitions which are specified by SQL__(something) macros.

Optionally, an array of keys can be provided, with the first value becoming the primary key. If keys are not specified, the table is created with the SQL_SERIAL column being the primary key.

Table 3-4. sql->create_table_query macros

Macro	Description
SQL__BLOB
SQL__CHAR(size)
SQL__DATE
SQL__DOUBLE(size)
SQL__ENUM(array of values)
SQL__INT(size)
SQL__INT_UNSIGNED(size)
SQL__REAL
SQL__SERIAL
SQL__TEXT
SQL__TIMESTAMP(size)
SQL__VARCHAR(size)

$sql->drop_table_query

object $sql->drop_table_query(string table);

Generates a DROP TABLE query for the specified table.

$sql->insert_query

string $sql->insert_query(string table, array values);

Generates an INSERT query for the specified table. values is an array which can have both associative values (where the key is the sql column name and the value is what is to be inserted), or simply normal array values (where the value is pulled from the global variable with the same name as the column specified). This method automatically sanitizes variables, so no addslashes() commands are needed.

$sql->update_query

string $sql->update_query(string table, array values, array where);

Generates an UPDATE query for the specified table. Has the same syntax as $sql->insert_query(), except that where is used to determine which table is updated. An example of a where value could be array('id' => $id) or array('ptlname' => $last, 'ptfname' => $first).

$sql->select_record_query

string $sql->select_record_query(string table, string criteria, [array fields]);

Generates a SELECT query on the specified table. criteria is passed as a WHERE clause, and fields, if specified, is an array of the column names or column clauses that should be returned. If fields is not specified, all columns will be returned. This does not currently handle multiple table queries, joins, etc.

$sql->distinct_values

array $sql->distinct_values(string table, string field);

Returns an array of all distinct values of the specified field in the specified table.

$sql->generate_hash

array $sql->generate_hash(string table, string key, string value, [string clause]);

Returns an associative array of values from the specified table, with the key being defined by key and the value being defined by value. These can be specified as either column names or as format strings, where the column names are encased by ##'s (for example: "##ptlname##, ##ptfname##"). Optionally, clause can be specified to further qualify or order the query (for example: "WHERE ptlname LIKE 'B%'' ORDER BY ptlname,ptfname").

wizard Class

wizard Constructor

object wizard(array common_variables, [integer options]);

Creates a wiard object. common_variables are variables that have to be passed with every page reload.

wizard->been_here

boolean wizard->been_here

Returns true if this wizard has been previously loaded, or false if this was the first page load.

wizard->get_current_page

integer wizard->get_current_page

Returns the current wizard page.

wizard->get_vars

array wizard->get_vars

Returns an array of all variables used by the wizard. This is useful for embedding the wizard in other objects (like another wizard or a notebook).

wizard->is_cancelled

boolean wizard->is_cancelled

Returns true if the last action was to cancel the wizard.

wizard->is_done

boolean wizard->is_done

Returns true if the wizard has been completed.

wizard->add_page

void wizard->add_page(string name, array variables, string text, [array errors]);

Adds a wizard "page" with title as the tab name, variables as the list of all variables that are passed by this page exclusively, and text containing the body of the wizard page. errors are part of the phpwebtools verification system, and function the same way that the notebook class verification routines function.

Prev	Home	Next
Functions	Up	Module Programming