Docs For Class Plugins

Methods

Constructor Plugins [line 155]

Plugins Plugins(
)

Constructor. Sets $plugins_path and load events.

[ Top ]

are_events_available [line 1679]

boolean are_events_available(
array|string
$events, [boolean
$require_all_in_same_plugin = false] 
)

Check if the requested list of events is provided by any or one plugin.

Parameters:

array\|string	$events:	A single event or a list thereof
boolean	$require_all_in_same_plugin:	Make sure there's at least one plugin that provides them all? This is useful for event pairs like "CaptchaPayload" and "CaptchaValidated", which should be served by the same plugin.

[ Top ]

call_by_code [line 1256]

boolean call_by_code(
string
$code, [array
$params = array()] 
)

T-Tag: Call a specific plugin by its code.

This will call the Plugin::TemplateTag() event handler.

Parameters:

string	$code:	plugin code
array	$params:	Associative array of parameters (gets passed to the plugin)

API Tags:

Uses:

Plugins::get_by_code()

[ Top ]

call_method [line 1180]

NULL|mixed call_method(
integer
$plugin_ID, string
$method, array
&$params 
)

Call a method on a Plugin.

This makes sure that the Timer for the Plugin gets resumed.

Parameters:

integer	$plugin_ID:	Plugin ID
string	$method:	Method name.
array	&$params:	Params (by reference).

API Tags:

Return:

Return value of the plugin's method call or NULL if no such method.

[ Top ]

call_method_if_active [line 1235]

NULL|mixed call_method_if_active(
integer
$plugin_ID, string
$method, array
&$params 
)

Call a method on a Plugin if it is not deactivated.

This is a wrapper around call_method().

fp> why doesn't call_method always check if it's deactivated?

Parameters:

integer	$plugin_ID:	Plugin ID
string	$method:	Method name.
array	&$params:	Params (by reference).

API Tags:

Return:

Return value of the plugin's method call or NULL if no such method (or inactive).

[ Top ]

forget_events [line 639]

void forget_events(
integer
$plugin_ID 
)

Forget the events a Plugin has registered.

This gets used when unregistering a Plugin or if Plugin::PluginInit() returned false, which means "do not use it for subsequent events in the request".

Parameters:

integer

$plugin_ID:

Plugin ID

[ Top ]

get_by_classname [line 1485]

Plugin &get_by_classname(
string
$classname 
)

Get a plugin by its classname.

Parameters:

string

$classname:

API Tags:

Return:

(false in case of error)

[ Top ]

get_by_code [line 1508]

Plugin &get_by_code(
string
$plugin_code 
)

Get a specific Plugin by its code.

Parameters:

string

$plugin_code:

plugin code

API Tags:

Return:	(false in case of error)
Usedby:	Plugins::call_by_code()

[ Top ]

get_by_ID [line 1440]

Plugin &get_by_ID(
integer
$plugin_ID 
)

Get a specific plugin by its ID.

This is the workhorse when it comes to lazy-instantiating a Plugin.

Parameters:

integer

$plugin_ID:

plugin ID

API Tags:

Return:

(false in case of error)

[ Top ]

get_enabled_events [line 1638]

array get_enabled_events(
integer
$plugin_ID 
)

Get a list of (enabled) events for a given Plugin ID.

Parameters:

integer

$plugin_ID:

Plugin ID

[ Top ]

get_list_by_all_events [line 1592]

array get_list_by_all_events(

$events 
)

Get a list of plugins that provide all given events.

Parameters:

$events:

API Tags:

Return:

plugin_ID => & Plugin

[ Top ]

get_list_by_event [line 1541]

array get_list_by_event(
string
$event 
)

Get a list of Plugins for a given event.

Parameters:

string

$event:

Event name

API Tags:

Return:

plugin_ID => & Plugin

[ Top ]

get_list_by_events [line 1567]

array get_list_by_events(
array
$events 
)

Get a list of Plugins for a list of events. Every Plugin is only once in this list.

Parameters:

array

$events:

Array of events

API Tags:

Return:

plugin_ID => & Plugin

[ Top ]

get_next [line 786]

Plugin &get_next(
)

Get next plugin in the list.

NOTE: You'll have to call restart() or load_plugins_table() before using it.

API Tags:

Return:

(false if no more plugin).

[ Top ]

get_object_from_cacheplugin_or_create [line 1729]

boolean get_object_from_cacheplugin_or_create(
string
$objectName, [string
$eval_create_object = NULL] 
)

Load an object from a Cache plugin or create a new one if we have a cache miss or no caching plugins.

It registers a shutdown function, that refreshes the data to the cache plugin which is not optimal, but we have no hook to see if data retrieved from a DataObjectCache derived class has changed.

Parameters:

string	$objectName:	object name
string	$eval_create_object:	eval this to create the object. Default is to create an object of class $objectName.

API Tags:

Return:

True, if retrieved from cache; false if not

[ Top ]

get_Plugins_in_group [line 201]

array get_Plugins_in_group(

$group 
)

Will return an array that contents are references to plugins that have the same group, regardless of the sub_group.

Parameters:

$group:

[ Top ]

get_Plugins_in_sub_group [line 223]

array get_Plugins_in_sub_group(

$group, [
$sub_group = ''] 
)

Will return an array that contents are references to plugins that have the same group and sub_group.

Parameters:

	$group:
	$sub_group:

[ Top ]

get_plugin_groups [line 176]

array get_plugin_groups(
)

Get a list of available Plugin groups.

[ Top ]

get_trigger_event [line 998]

mixed get_trigger_event(
string
$event, [array
$params = NULL], [string
$get = 'data'] 
)

Trigger an event and return an index of params.

This is handy to collect return values from all plugins hooking an event.

Parameters:

string	$event:	Event name, see Plugins_admin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin
string	$get:	Index of $params that should get returned

API Tags:

Return:

The requested index of $params

[ Top ]

get_trigger_event_first_return [line 1033]

mixed get_trigger_event_first_return(
string
$event, [array
$params = NULL] 
)

Trigger an event and return the first return value of a plugin.

Parameters:

string	$event:	Event name, see Plugins_admin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin

API Tags:

Return:

NULL if no Plugin returned something or the return value of the first Plugin

[ Top ]

get_trigger_event_first_true [line 1016]

mixed get_trigger_event_first_true(
string
$event, [array
$params = NULL], [string
$get = 'data'] 
)

The same as get_trigger_event(), but stop when the first Plugin returns true.

Parameters:

string	$event:	Event name, see Plugins_admin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin
string	$get:	Index of $params that should get returned

API Tags:

Return:

The requested index of $params

[ Top ]

has_event [line 1663]

boolean has_event(
integer
$plugin_ID, string
$event 
)

Has a plugin a specific event registered and enabled?

Parameters:

integer	$plugin_ID:
string	$event:

Information Tags:

Todo:

fp> The plugin should discover its events itself / This question should be asked to the Plugin itself. dh> Well, "discover" means to look up if it has a given method; this does not appear to belong into the Plugin class. A plugin won't also really know if some event is enabled or disabled.

[ Top ]

init_settings [line 661]

void init_settings(
Plugin
&$Plugin 
)

Init Plugin::$Settings and Plugin::$UserSettings, either by unsetting them for PHP5's overloading or instantiating them for PHP4.

This only gets used for installed plugins, but we're initing it for PHP 5.1, to trigger a helpful error, when e.g. Plugin::Settings gets accessed in PluginInit().

Parameters:

Plugin

&$Plugin:

[ Top ]

instantiate [line 1778]

Plugin &instantiate(

$row 
)

Callback, which gets used for Results.

Parameters:

$row:

API Tags:

Return:

(false in case of error)

[ Top ]

instantiate_Settings [line 693]

boolean instantiate_Settings(
Plugin
&$Plugin, string
$set_type 
)

Instantiate Settings object (class PluginSettings) for the given plugin.

The plugin must provide setting definitions (through Plugin::GetDefaultSettings() OR Plugin::GetDefaultUserSettings()).

Parameters:

Plugin	&$Plugin:
string	$set_type:	settings type: "Settings" or "UserSettings"

API Tags:

Return:

NULL, if no Settings

[ Top ]

load_events [line 1698]

void load_events(
)

(Re)load Plugin Events for enabled (normal use) or all (admin use) plugins.

Redefined in descendants as:

Plugins_admin::load_events() : (Re)load Plugin Events for enabled (normal use) or all (admin use) plugins.
Plugins_admin_no_DB::load_events() : No-operation.

[ Top ]

load_plugins_table [line 1401]

void load_plugins_table(
)

Load Plugins data from T_plugins (only once), ordered by priority.

This fills the needed indexes to lazy-instantiate a Plugin when requested.

Redefined in descendants as:

Plugins_admin_no_DB::load_plugins_table() : No-operation.

[ Top ]

quick [line 1344]

string quick(
string
$plugin_code, array
$params 
)

Quick-render a string with a single plugin and format it for output.

Parameters:

string	$plugin_code:	Plugin code (must have render() method)
array	$params:	'data': Data to render 'format: format to output, see format_to_output()

API Tags:

Return:

Rendered string

Information Tags:

Todo:

rename

[ Top ]

Plugin &register(
string
$classname, [int
$ID = 0], [int
$priority = -1], [array
$apply_rendering = NULL], [string
$classfile_path = NULL], [boolean
$must_exists = true], [NULL|string
&$orig_code = NULL] 
)

Register a plugin.

This handles the indexes, dynamically unregisters a Plugin that does not exist (anymore) and instantiates the Plugin's (User)Settings.

Attention: The code of the plugin is set to NULL if it is found to be not unique! To get the original code, use the $orig_code parameter.

Parameters:

string	$classname:	name of plugin class to instantiate and register
int	$ID:	ID in database (0 if not installed)
int	$priority:	Priority in database (-1 to keep default)
array	$apply_rendering:	When should rendering apply? (NULL to keep default)
string	$classfile_path:	Path of the .php class file of the plugin.
boolean	$must_exists:	Must the plugin exist (classfile_path and classname)? This is used internally to be able to unregister a non-existing plugin.
NULL\|string	&$orig_code:	If a reference to a variable is given here, it will receive the code of the plugin we are registering, even if the code is found to be not unique.

API Tags:

Return:	Plugin ref to newly created plugin; string in case of error
Access:	protected

[ Top ]

render [line 1284]

string render(
string
&$content, array
$renderers, string
$format, array
$params, [
$event_prefix = 'Render'] 
)

Render the content of an item by calling the relevant renderer plugins.

Parameters:

string	&$content:	content to render (by reference)
array	$renderers:	renderer codes to use for opt-out, opt-in and lazy
string	$format:	Output format, see format_to_output(). Only 'htmlbody', 'entityencoded', 'xml' and 'text' are supported.
array	$params:	Additional params to the Render* methods (e.g. "Item" for items). Do not use "data" or "format" here, because it gets used internally.
	$event_prefix:

API Tags:

Return:

rendered content

[ Top ]

restart [line 770]

void restart(
)

Load plugins table and rewind iterator used by get_next().

[ Top ]

set_Plugin_status [line 254]

boolean set_Plugin_status(
Plugin
&$Plugin, string
$status 
)

Sets the status of a Plugin in DB and registers it into the internal indices when "enabled".

Otherwise it gets unregistered, but only when we're not in Plugins_admin, because we want to keep it in then in our indices.

{@ object, not $admin_Plugins. }}

Parameters:

Plugin	&$Plugin:
string	$status:	New status ("enabled", "disabled", "needs_config", "broken")

API Tags:

Return:

True on success, false on failure.

[ Top ]

stop_propagation [line 819]

void stop_propagation(
)

Stop propagation of events to next plugins in trigger_event().

[ Top ]

trigger_collect [line 1055]

array trigger_collect(
string
$event, [array
$params = NULL], [boolean
$ignore_empty = true] 
)

Trigger an event and return an array of all return values of the relevant plugins.

Parameters:

string	$event:	Event name, see Plugins_admin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin
boolean	$ignore_empty:	Ignore empty() return values?

API Tags:

Return:

List of return values, indexed by Plugin ID

[ Top ]

trigger_event [line 832]

boolean trigger_event(
string
$event, [array
$params = array()] 
)

Call all plugins for a given event.

Parameters:

string	$event:	event name, see Plugins_admin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin

API Tags:

Return:

True, if at least one plugin has been called.

[ Top ]

trigger_event_first_false [line 903]

array trigger_event_first_false(
string
$event, [array
$params = NULL] 
)

Call all plugins for a given event, until the first one returns false.

Parameters:

string	$event:	event name, see Plugins_admin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin

API Tags:

Return:

The (modified) params array with key "plugin_ID" set to the last called plugin; Empty array if no Plugin returned true or no Plugin has this event registered.

[ Top ]

trigger_event_first_return [line 943]

array trigger_event_first_return(
string
$event, [array|NULL
$params = NULL], [array|NULL
$search = NULL] 
)

Call all plugins for a given event, until the first one returns a value (not NULL) (and $search is fulfilled, if given).

Parameters:

string	$event:	event name, see Plugins_admin::get_supported_events()
array\|NULL	$params:	Associative array of parameters for the Plugin
array\|NULL	$search:	If provided, the return value gets checks against this criteria. Can be: ( 'in_array' => 'needle' )

API Tags:

Return:

The (modified) params array with key "plugin_ID" set to the last called plugin and 'plugin_return' set to the return value; Empty array if no Plugin returned true or no Plugin has this event registered.

[ Top ]

trigger_event_first_true [line 868]

array trigger_event_first_true(
string
$event, [array
$params = NULL] 
)

Call all plugins for a given event, until the first one returns true.

Parameters:

string	$event:	event name, see Plugins_admin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin

API Tags:

Return:

The (modified) params array with key "plugin_ID" set to the last called plugin; Empty array if no Plugin returned true or no Plugin has this event registered.

[ Top ]

trigger_karma_collect [line 1086]

integer|NULL trigger_karma_collect(
string
$event, array
$params 
)

Trigger a karma collecting event in order to get Karma percentage.

Parameters:

string	$event:	Event
array	$params:	Params to the event

API Tags:

Return:

Spam Karma (-100 - 100); "100" means "absolutely spam"; NULL if no plugin gave us a karma value

[ Top ]

unregister [line 589]

boolean unregister(
Plugin
&$Plugin, [boolean
$force = false] 
)

Un-register a plugin.

This does not un-install it from DB, just from the internal indexes.

Parameters:

Plugin	&$Plugin:
boolean	$force:	Force unregistering (ignored here, but used in Plugins_admin)

API Tags:

Return:

True, if unregistered

Redefined in descendants as:

Plugins_admin::unregister() : Un-register a plugin, only if forced.

[ Top ]

validate_renderer_list [line 1790]

array validate_renderer_list(
[array
$renderers = array('default')] 
)

Validate renderer list.

Parameters:

array

$renderers:

renderer codes ('default' will include all "opt-out"-ones)

API Tags:

Return:

validated array of renderer codes

[ Top ]

	plugins

[ class tree: plugins ] [ index: plugins ] [ all elements ]

Class: Plugins

Class Plugins