TIP_Module

Introduction

Base class for modules

Source file

/Type/module.php

Extends

TIP_Type

abstract

yes

Properties

engine : TIP_Template_Engine

The template engine: required for TIP_Application instances

access

protected

Contains a reference to the template engine to use when parsing a file. See the TIP_Template class for details on what is a template engine. If not configured, it defaults to the one of the main module (that obviously MUST be configured).

locale_prefix : string

The locale prefix

access

protected

A string to be prepended while looking for locale strings. If not specified, it defaults to getType().

anonymous_privilege : TIP_PRIVILEGE_...

The anonymous privilege level for this module

access

protected

If not specified, it defaults to the anonymous privilege of the main application module, that must be configured.

default_privilege : TIP_PRIVILEGE_...

The default privilege level for this module

access

protected

If not specified, it defaults to the default privilege of the main application module, that must be configured.

privilege : TIP_PRIVILEGE_...

The current privilege descriptor

access

protected

keys : array

Custom keys

access

public

Every TIP_Module object can have a bounch of key => value pairs. These properties are mantained in this array and are used, for instance, by the getItem() method. Also, remember an object inherits the keys from its parents, in a hierarchy order.

Methods

checkOptions (&$options) : bool

Check the options

&$options

array
Properties values

lines

84 - 108

static

yes

access

protected

Overridable static method that checks $options for missing or invalid values and eventually corrects its content.

__construct ($options)

Constructor

$options

array
Properties values

lines

117 - 121

access

protected

Initializes a TIP_Module instance.

postConstructor ()

Overridable post construction method

lines

135 - 138

access

protected

Called after the construction happened. This can be overriden to do some other post costruction operation.

In TIP_Module, the postConstructor() method initializes the privilege stuff. This cannot be done in the constructor itsself, because the privilege level needs the TIP_User and TIP_Privilege modules to be instantiated, so it will lead to a mutual recursion if this operation is done directly in TIP_Module().

refreshPrivileges ([$privilege])

Refresh the privileges

$privilege

TIP_PRIVILEGE_... [ = null ]
The new privilege level

lines

151 - 174

access

protected

Refreshes the privileges of this module. If $privilege is not defined, gets the proper privilege using the default TIP_Privilege instance.

getLocale ($id, [$context], [$cached]) : string

Get a localized text

$id

string
The identifier

$context

array [ = null ]
A context associative array

$cached

bool [ = true ]
Whether to perform or not a cached read

lines

194 - 203

access

protected

Gets the localized text for a specified module. $id is prefixed by the 'locale_prefix' property.

This method always returns a valid string: if the localized text can't be retrieved, a string containing prefix.$id is returned and a warning message is logged.

See the TIP_Locale::get() method for technical details on how the text is localized.

localize (&$dst, $id, [$modifiers])

Localize an id

&$dst

string
Where to store the localized text

$id

string
The id to localize

$modifiers

array|null [ = null ]
A ('prefix','suffix') array

lines

219 - 225

access

protected

Similar to getLocale() but the result is stored in $dst instead of returned. Also, it provides a way to prepend a prefix and append a suffix on $id before calling getLocale() by specifing them in the $modifiers array.

Useful as callback in array_walk arguments.

getItem ($id) : mixed|null

Return the value of a generic item

$id

string
The item id

lines

241 - 249

access

protected

Gets the value of a generic item. The item is the basic form of dynamic data in TIP: it is a generic pair of key => value data with a dynamic value. Examples of items are keys fields.

This method can be overriden by the children to provide a more sophisticated interface, such as the fields management in the TIP_Content objects.

getRequest ($request) : mixed|null

Get the value of a pair throught a "request" interface

$request

string
The item id

lines

272 - 310

access

protected

This method is usually used by the template engine interface methods (the tag... functions) to access any pair information available in the TIP system.

A request can get the value of an item, a get, a post or a localized text: the type of the request is obtained parsing the $request token. Specify

item[...]

for items,

get[...]

for gets,

post[...]

for posts and

locale[...]

for localized text, specifying the id in place of the ellipsize.

If no type is specified (that is, $request is directly an identifier), the system will expand it in

item[...]

. This means

getRequest('name')

is logically equivalent to

getRequest('item[name]')

.

getValidRequest ($requests) : mixed|null

Get the first valid request

$requests

array
An array of request

lines

322 - 336

access

protected

usedby

The method used to resolve the requests

Given an array of requests, gets the first request in this array that has a not-null value.

tryRun ($path) : bool

Try to execute a template file

$path

array|string
The file path to run

lines

347 - 356

access

public

Parses and executes the specified file. Similar to run(), but it does not raise any warning/error if $path is not found.

run ($path) : bool

Execute a template file

$path

array|string
The file path to run

lines

367 - 376

access

public

Parses and executes the specified file. If $path is a string, the module id is prepended to the real path.

insertInPage ($path) : bool

Prepend a template file to the page

$path

array|string
The file path to run

lines

387 - 392

access

protected

Runs the $path template using the current template engine and puts the result at the beginning of the page.

appendToPage ($path) : bool

Append a template file to the page

$path

array|string
The file path to run

lines

403 - 408

access

protected

Runs the $path template using the current template engine and puts the result at the end of the page.

getTag ($name, $params) : bool|null

Execute a tag

$name

string
The tag name

$params

string
Parameters to pass to the tag

lines

430 - 450

access

public

Executes the specified tag, using $params as arguments. This function prepend 'tag' to $name and try to call the so formed method. If you, for instance, runs getTag('Test', ''), a tagTest('') call will be performed.

A tag is a request from the template engine to echoes something. It can be tought as the dinamic primitive of the TIP system: every dinamic tag parsed by the template engine runs a tag.

The tags - as everything else - are inherited from the module parents, so every TIP_Module tags are available to the TIP_Module children.

callAction ($action) : bool|null

Execute an action

$action

string
The action name

lines

481 - 521

access

public

Executes the Action action. This function tries to run Action by calling the following protected methods in this order:

• runManagerAction()
• runAdminAction()
• runTrustedAction()
• runUntrustedAction()
• runAction()

The first method called depends on the current privilege, get throught a TIP::getPrivilege() call. The first method that returns true (meaning the requested action is executed) stops the chain.

Usually the actions are called adding variables to the URI. An example of an action call is the following: http://www.example.org/?module=news&action=view&id=23

This URI will call the "view" action on the "news" module, setting "id" to 23 (it is request to view a news and its comments). You must check the documentation of every module to see which actions are available and what variables they require.

tagIsValue ($params) : string|null

Check if a string is not empty

$params

string
Parameters of the tag

lines

534 - 537

access

protected

tagIsSet ($params) : string|null

Check if a request is set

$params

string
Parameters of the tag

lines

546 - 551

uses

getValidRequest()

access

protected

$params is a string in the form "request,request,...".

tagIsAhah ($params) : string|null

Expand to 'true' if the current request is an AHAH request

$params

string
Parameters of the tag

lines

556 - 559

access

protected

tagRaw ($params) : string|null

Output the first defined request

$params

string
Parameters of the tag

lines

571 - 580

uses

getValidRequest()

access

protected

$params is a string in the form "request,request,...".

This tag will perform a serie of request and will echo the first value found.

tagTryRaw ($params) : string|null

Try to output the first defined request

$params

string
Parameters of the tag

lines

592 - 598

uses

getValidRequest()

access

protected

$params is a string in the form "request,request,...".

Equal to tagRaw(), but do not log any warning if the request is not found.

tagHtml ($params, [$raise_error]) : string|null

Htmlize the first defined request

$params

string
Parameters of the tag

$raise_error

boolean [ = true ]
Whether to generate an error

lines

610 - 620

access

protected

$params is a string in the form "request,request,...".

Equals to tagRaw(), but the result is converted throught TIP::toHtml() before the output.

tagTryHtml ($params) : string|null

Try to htmlize the first defined request

$params

string
Parameters of the tag

lines

630 - 633

access

protected

$params is a string in the form "request,request,...".

Equals to tagTryRaw(), but the result is converted throught TIP::toHtml() before the output.

tagLocalized ($params) : string|null

Localized label

$params

string
Parameters of the tag

lines

643 - 653

access

protected

$params is the id of the string to localize. If there are no dots, the current module id and '.label.' are prepended to $params.

Output a properly localized string.

tagGetProperty ($params) : string|null

Get the property value specified in $params

$params

string
Parameters of the tag

lines

658 - 661

access

protected

tagGetPropertyRaw ($params) : string|null

Get the raw property value specified in $params

$params

string
Parameters of the tag

lines

666 - 669

access

protected

tagSetProperty ($params) : string|null

Change a property value

$params

string
Parameters of the tag

lines

676 - 681

access

protected

$params must be a string in the format 'property,value'.

tagAddToProperty ($params) : string|null

Append a string to a property

$params

string
Parameters of the tag

lines

688 - 697

access

protected

$params must be a string in the format 'property,string'.

tagUri () : string|null

Build a relative URI: $params must be referred to the site root

lines

702 - 705

access

protected

tagTemplateUri () : string|null

Build a relative URI: $params must be referred to the template root

lines

712 - 717

access

protected

If the URI does not point to a readable file, the fallback URI is used.

tagDataUri () : string|null

Build a relative URI: $params must be referred to the module data root

lines

722 - 726

access

protected

tagCacheUri () : string|null

Build a relative URI: $params must be referred to the module data root

lines

731 - 739

access

protected

tagModuleUri () : string|null

Build a relative URI: $params must be referred to the module template root

lines

744 - 748

access

protected

tagIconUri () : string|null

Build an icon URI

lines

753 - 757

access

protected

tagActionUri ($params) : string|null

Build a relative action URI

$params

string
Parameters of the tag

lines

765 - 768

access

protected

$params is a string in the form "action[,id[,param1=value1,param2=value2,...]]" The module name can be overriden specifying it as module=...

tagIs ($params) : string|null

Check if $params is the current user id

$params

string
Parameters of the tag

lines

776 - 779

access

protected

Expands to true if the current logged-in user id equals to $params or false otherwise.

tagRun ($params) : string|null

Execute a template

$params

string
Parameters of the tag

lines

787 - 795

access

protected

Executes the template file $params found in the current module template path, using the current template engine.

tagInList ($params) : string|null

Check if a value is in a list

$params

string
Parameters of the tag

lines

806 - 817

access

protected

$params is a string in the form "needle,value1,value2,...".

Outputs true if needle is present in the comma separated list of values. Useful to check if a value is contained (that is, if it is selected) in a "set" or "enum" field.

tagDate ($params) : string|null

Format a datetime

$params

string
Parameters of the tag

lines

831 - 836

uses

TIP::formatDate()

access

protected

Converts a datetime (in SQL format) to a specified format.

$params must be a string in the format '[date][,format]', where format is any format allowed by the TIP::formatDate() method. If the date is not specified, the current date is assumed. If the format is not specified, it defaults to 'date'.

tagModuleExists ($params) : string|null

Check if a module exists

$params

string
Parameters of the tag

lines

848 - 852

access

protected

Expands to true if the module module exists or to false otherwise. This tag only checks if the logic file for the $params module exists, does not load the module itsself nor change the default module.

Useful to provide conditional links between different modules.

runManagerAction ($action) : bool|null

Executes a management action

$action

string
The action name

lines

869 - 872

access

protected

Executes an action that requires the 'manager' privilege.

runAdminAction ($action) : bool|null

Executes an administrator action

$action

string
The action name

lines

884 - 887

access

protected

Executes an action that requires at least the 'admin' privilege.

runTrustedAction ($action) : bool|null

Executes a trusted action

$action

string
The action name

lines

899 - 902

access

protected

Executes an action that requires at least the 'trusted' privilege.

runUntrustedAction ($action) : bool|null

Executes an untrusted action

$action

string
The action name

lines

914 - 917

access

protected

Executes an action that requires at least the 'untrusted' privilege.

runAction ($action) : bool|null

Executes an unprivileged action

$action

string
The action name

lines

929 - 932

access

protected

Executes an action that does not require any privileges.