Docs For Class Module

Class Module

Description

The Module class - all modules are to extend this class

All modules are to extend this class so that they can have access to all the objects of the application.

See Module::set_references() to see how these objects can be accessed without needing to extending this class.

If a module does not extend this class, it does not have easy access to these objects. Hence, it is recommended to extend this class though it is not enforced.

Module output is also automatically rendered by the controller. This simplifies output management. See Module::$output and Module::render().

Any exception actions need to be registered in the Module's constructor. See Module::$exceptions.

Located in /phpfw.php (line 3954)

Direct descendents

Class	Description
Config	Load and save configuration files
Login	The Login Module
MailServer	The MailServer Module
PelWrap	Wrapper for the PEL library

Variable Summary

object Application $application

object Controller $controller

object Database $database

object Error $error

mixed $error_strings

array $exceptions

string $output

mixed $queries

object Sql $sql

string $template_file

mixed $use_render

mixed $use_template_library

mixed $use_view

Method Summary

void disable_render ()

void disable_template_library ()

void disable_view ()

void enable_render ()

void enable_template_library ()

void enable_view ()

mixed exec_module_action ()

void get_error_strings ()

void get_exceptions ()

void get_queries ()

void get_templating_library_paths ( &$path, &$template_dir, &$compiled_dir, string $path, string $template_dir, string $compiled_dir)

void initialize ()

string PHPTAL_render (string $template_file)

void register_error (string $error_name, string $error_text, string $error_severity)

void register_exception ( $action)

void register_query (string $query_name, string $query_text)

void render ()

void set_references ()

void set_template_file (string $template_file)

string Smarty_render (string $template_file)

Variables

object Application $application (line 4062)

var:
A reference to the Application object
This may not be used very often.
Sample usage:
- Add custom configuration variables to the config ini
- Use the values with $this->application->config

object Controller $controller (line 4117)

var:
A reference to the Controller object
All module:action links that are not in the exception list need to be encoded using the Controller::encode_url() function.
Sample usage:
- $view = new View("Link text");
- $view->a($this->controller->encode_url('module_name', 'action_name', 'param1=value1&param2=value2...'));
To get the parameters in the clicked URL above
- parse_str($this->controller->decode_url());
- echo $param1; echo $param2;

object Database $database (line 4086)

var:
A reference to the Database object
This object gives access to the entire database. Data from tables can be obtained or deleted using the methods in the Table class.
Sample usage:
- $table_object = $this->database->get_table_by_name($table_name);
- $table_object->get_table_rows();

object Error $error (line 4074)

var:
A reference to the Error object
Sample usage:
- Add an error string to the ini file
- Display it in the module using: $this->error->display_error('ERROR_NAME', $param1, $param2, ...);
where the string parameters replace %s in the error string.
See the default error ini file for examples.

mixed $error_strings (line 3997)

array $exceptions (line 3985)

var:
List of exception actions that can be directly called
Format: array('action1', 'action2', 'action3'); where actions are class methods.
This member needs to be populated in the Module's constructor using the Module::register_exception() function. E.g.
- $this->register_exception('action1');
Multiple exceptions can be registered by calling the function multiple times.
See Controller::$exceptions for how the exceptions are used.

string $output (line 3970)

var:
The HTML output for this module
The usage of this member depends on whether a template framework is in use in this application.
- If no templating framework is in use, Module::$output is treated
as a string. Each action in the module updates this string variable with the HTML to be outputted. Once the called action is done, the controller renders this HTML using the View class.
- If a templating framework is used, Module::$output is treated as
an associative array where each variable used in the template can be assigned as $output['variable_name'] = 'value'. Once the action is completed, the controller renders the HTML using the templating framework.

mixed $queries (line 4008)

object Sql $sql (line 4101)

var:
A reference to the Sql object
Execute SQL queries directly using this object.
Sample usage:
- Add a custom query in the sql ini file
- Execute the query using Sql::select_query() or Sql::update_query()
E.g.
- Select query: $this->sql->select_query('QUERY_NAME', $param1, $param2, ...);
- Update query: $this->sql->update_query('QUERY_NAME', $param1, $param2, ...);

string $template_file (line 4051)

var:
The name of the template file if using a template library
This is auto-detected as Module#action. The Module::set_template_file() function allows changing this to a custom file.

mixed $use_render (line 4043)

mixed $use_template_library (line 4022)

mixed $use_view (line 4034)

Methods

disable_render (line 4264)

Prevent the Module::render() function from running.

This method is useful if you'd like to control all the output directly from your module action instead of having Phpfw do it.

void disable_render ()

disable_template_library (line 4215)

Disable usage of the template library to render the output of the module.

On calling this function, the Module::render() function generates the output using the View class instead of the templating library when it is specified in the configuration file. This allows to make exceptions. See an example of how this is used in the Login module.

This method can be called in a module's action to make an exception for that action or in the module's constructor to make the exception across all the module's actions.

void disable_template_library ()

disable_view (line 4244)

Disable the View object usage in Module::render().

This method is useful if you are using AJAX functionality and do not require the Module to generate a complete HTML output.

void disable_view ()

enable_render (line 4274)

Enable the Module::render() function.

This method restores the Phpfw default of rendering the output in the Module::render() function.

void enable_render ()

enable_template_library (line 4234)

Enable usage of the template library to render the output of the module.

On calling this function, the Module::render() function generates the output using the templating library instead of the View class if a templating library is defined in the configuration. The default setting is to use the templating library if defined.

However, this method can be called by an action where the module disables the templating libraries across the board in its constructor using Module::disable_template_library(). As a result, the action can make an exception and still use the library if available.

This method should be called in a module's action to make an exception for that action assuming that the module constructor calls Module::disable_template_library().

void enable_template_library ()

enable_view (line 4254)

Enable the View object usage in Module::render().

This method restores the Phpfw default of rendering the final output in Module::render() using the View object.

void enable_view ()

exec_module_action (line 4358)

Execute another loaded module's action

First parameter is the name of the module - string
Second parameter is the name of the action to execute - string
Remaining parameters (if any) are any arguments to send the method

return: Returns the return value of the module action

mixed exec_module_action ()

get_error_strings (line 4308)

Get the error strings registered by the Module

The controller automatically calls this function to register the error strings.

void get_error_strings ()

get_exceptions (line 4295)

Get the exceptions registered by the Module

The controller automatically calls this function to register the exceptions.

void get_exceptions ()

get_queries (line 4317)

Get the queries registered by the Module

The controller automatically calls this function to register the queries.

void get_queries ()

get_templating_library_paths (line 4387)

Get templating library paths

This function sets up the templating library's paths. It is called by Module::*_render() functions.

void get_templating_library_paths ( &$path, &$template_dir, &$compiled_dir, string $path, string $template_dir, string $compiled_dir)

string $path: Path to the library
string $template_dir: Directory that contains the template files
string $compiled_dir: Directory that will contain the compiled templates
&$path
&$template_dir
&$compiled_dir

initialize (line 4326)

Reset the Module::$output

This function is called by the controller at load time. It is used to default initialize all members of the module.

void initialize ()

PHPTAL_render (line 4533)

Render the module output using PHPTAL

This function uses the associative array Module::$output populated by the called action and renders the template using PHPTAL.

The template file loaded depends on the current action being executed by the controller. Hence, if the User::show_details() action is being executed, the template file rendered by PHPTAL is User#show_details.html.

The output of the template is then returned.

This function is invoked by Module::render() when PHPTAL is used as the templating library. It can also be called directly to get the output from a template file in a module action.

return: Returns the output data

string PHPTAL_render (string $template_file)

string $template_file: The name of the template file to render

register_error (line 4168)

This function needs to be called in the Module's constructor. E.g.

$this->register_error('ERROR_NAME', 'error string', 'error severity');

Multiple errors can be registered by calling the function multiple times. Ensure that $error_name is unique for every call. It is also recommended to have your module's name as part of $error_name to ensure it does not conflict with other modules.

See Error::display_error() for how the error strings can be used.

void register_error (string $error_name, string $error_text, string $error_severity)

string $error_name: Name of the error - e.g. ERROR_MISSING_BLAH
string $error_text: The text message associated with the error. All instances of %s are replaced by the parameters provided to Error::display_error().
string $error_severity: The severity of the error message - valid values are ERROR, WARNING, STOP, MESSAGE

register_exception (line 4143)

This function needs to be called in the Module's constructor. E.g.

$this->register_exception('action1');

Multiple exceptions can be registered by calling the function multiple times.

See Controller::$exceptions for how the exceptions are used.

void register_exception ( $action)

$action

register_query (line 4194)

This function needs to be called in the Module's constructor. E.g.

$this->register_query('SQL_QUERY_NAME', 'SQL query syntax');

Multiple queries can be registered by calling the function multiple times. Ensure that $query_name is unique for every call. It is also recommended to have your module's name as part of $query_name to ensure it does not conflict with other modules.

See Sql::select_query() for how the queries can be used.

void register_query (string $query_name, string $query_text)

string $query_name: Name of the query - e.g. SQL_SPECIAL_QUERY
string $query_text: The actual SQL query. All instances of %s are replaced by the parameters provided to Sql::*_query() functions.

render (line 4419)

Render the module HTML output

The functionality of this method depends on whether a templating framework is in use or not:

This function creates a View and calls the View::render() function on Module::$output

if no framework is in use. i.e. template->framework is undefined in config.ini OR if Module::disable_template_library() is called in the module action or constructor when a framework is in use.

If a framework is in use, this function calls the appropriate *_render() function

for the specified framework. The output is then rendered using View::render() to add the HTML header.

The controller automatically calls this function. Do not call this function directly.

void render ()

set_references (line 4125)

Set the references to the application objects

This function makes the objects in the application accessible to all deriving module classes.

void set_references ()

set_template_file (line 4286)

Set a custom template file if using a templating library

The template file is auto-detected as Module#action. Using this function, it can be changed to a custom name. File extension is dependent on the templating library and does not need to be specified.

void set_template_file (string $template_file)

string $template_file: Name of the template file

Smarty_render (line 4478)

Render the module output using Smarty

This function uses the associative array Module::$output populated by the called action and renders the template using Smarty.

The output of the template is then returned.

This function is invoked by Module::render() when Smarty is used as the templating library. It can also be called directly to get the output from a template file in a module action.

return: Returns the output data

string Smarty_render (string $template_file)

string $template_file: The name of the template file to render

Documentation generated on Sat, 23 Jun 2007 21:28:26 -0500 by phpDocumentor 1.3.2