Class: Hooks
Source Location: /CORE/system/classes/core/Hooks.php
Class Hooks
Class Overview
|
The plugin API is located in this file, which allows for creating actions and filters and hooking functions, and methods. The functions or methods will then be run when the action or filter is called.
The API callback examples reference functions, but can be methods of classes. To hook methods, you'll need to pass an array one of two ways. Any of the syntaxes explained in the PHP documentation for the 'callback' type are valid. Also see the Plugin API for more information and examples on how to use a lot of these functions. A list of existing hooks can be found here: apply_filter('admin_menu', $menu); The Admin Menu structure is given in $menu, so you can customize the menu to your needs (most often you will add items). apply_filters('edit_item_meta', array(), $item) Called before the Item Attribute screen is rendered (currently only for pages). If you want to add further input fields from your plugin, add an key/value pair entry to the first argument array. Each pair is one collapsable admin box, with "key" = box title and "value" = box content. do_action('update_item', $itemtype, $id, $langid, $val, $timestamp) Called when updating any Item. $val is the array with all submitted item properties. If you use project fields, fetch the required values from $_POST. do_action('admin_header') do_action('admin_footer') apply_filters('metatags', $values, $item); Send from the {metatags} Smarty TAGs apply_filters('create_item_meta', array(), _BIGACE_ITEM_MENU) Send in the "Create Page" Dialog. See "edit_item_meta" for further information. apply_filters('dialog_setting_images', $vars, $id) Returns an array with the values for the image inserting/linking dialog. apply_filters('dialog_setting_links', $vars, $id) Returns an array with the values for the cms link/url inserting dialog.
Located in /CORE/system/classes/core/Hooks.php [line 79]
Author(s):
Information Tags:
| Version: | $Id: Hooks.php,v 1.5 2009/03/04 23:05:56 kpapst Exp $ |
| Copyright: | Copyright (C) Kevin Papst |
| License: | GNU Public License |
|
Methods
|
Method Summary
| static
void
|
add_action() |
add_action() - Hooks a function on to a specific action. |
| static
boolean
|
add_filter() |
add_filter() - Hooks a function or method to a specific filter action. |
| static
mixed
|
apply_filters() |
apply_filters() - Call the functions added to a filter hook. |
| static
string
|
current_filter() |
current_filter() - Return the name of the current filter or action. |
| static
int
|
did_action() |
did_action() - Return the number times an action is fired. |
| static
int|boolean
|
has_action() |
has_action() - Check if any action has been registered for a hook. |
| static
int|boolean
|
has_filter() |
has_filter() - Check if any filter has been registered for a hook. |
| static
boolean
|
remove_action() |
remove_action() - Removes a function from a specified action hook. |
| static
boolean
|
remove_filter() |
remove_filter() - Removes a function from a specified filter hook. |
| null |
do_action() |
do_action() - Execute functions hooked on a specific action hook. |
Methods
static void add_action(
string
$tag, callback
$function_to_add, [int
$priority = 10], [int
$accepted_args = 1]
)
|
|
add_action() - Hooks a function on to a specific action.
Actions are the hooks that the BIGACE core launches at specific points during execution, or when specific events occur. Plugins can specify that one or more of its PHP functions are executed at these points, using the Action API.
Parameters:
|
string |
$tag: |
The name of the action to which the <tt>$function_to-add</tt> is hooked. |
|
callback |
$function_to_add: |
The name of the function you wish to be called. |
|
int |
$priority: |
optional. Used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action. |
|
int |
$accepted_args: |
optional. The number of arguments the function accept (default 1). |
API Tags:
static boolean add_filter(
string
$tag, callback
$function_to_add, [int
$priority = 10], [int
$accepted_args = 1]
)
|
|
add_filter() - Hooks a function or method to a specific filter action.
Filters are the hooks that BIGACE launches to modify text of various types before adding it to the database or sending it to the browser screen. Plugins can specify that one or more of its PHP functions is executed to modify specific types of text at these times, using the Filter API. To use the API, the following code should be used to bind a callback to the filter function example_hook($example) { echo $example; }
Hooked functions can take extra arguments that are set when the matching do_action() or apply_filters() call is run. The <tt>$accepted_args allow for calling functions only when the number of args match. Hooked functions can take extra arguments that are set when the matching <tt>do_action()</tt> or <tt>apply_filters()</tt> call is run. For example, the action <tt>comment_id_not_found</tt> will pass any functions that hook onto it the ID of the requested comment. <strong>Note:</strong> the function will return true no matter if the function was hooked fails or not. There are no checks for whether the function exists beforehand and no checks to whether the <tt>$function_to_add is even a string. It is up to you to take care and this is done for optimization purposes, so everything is as quick as possible.
Parameters:
|
string |
$tag: |
The name of the filter to hook the <tt>$function_to_add</tt> to. |
|
callback |
$function_to_add: |
The name of the function to be called when the filter is applied. |
|
int |
$priority: |
optional. Used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action. |
|
int |
$accepted_args: |
optional. The number of arguments the function accept (default 1). |
API Tags:
| Return: | true |
| Usedby: | Hooks::add_action() - Adds an action. Parameter list and functionality are the same. |
static mixed apply_filters(
string
$tag, mixed
$value, mixed
$var,...
)
|
|
apply_filters() - Call the functions added to a filter hook.
The callback functions attached to filter hook <tt>$tag</tt> are invoked by calling this function. This function can be used to create a new filter hook by simply calling this function with the name of the new hook specified using the <tt>$tag</a> parameter. The function allows for additional arguments to be added and passed to hooks. function example_hook($string, $arg1, $arg2) { //Do stuff return $string; } $value = apply_filters('example_filter', 'filter me', 'arg1', 'arg2');
Parameters:
|
string |
$tag: |
The name of the filter hook. |
|
mixed |
$value: |
The value on which the filters hooked to <tt>$tag</tt> are applied on. |
|
mixed |
$var,...: |
Additional variables passed to the functions hooked to <tt>$tag</tt>. |
API Tags:
| Return: | The filtered value after all hooked functions are applied to it. |
static string current_filter(
)
|
|
current_filter() - Return the name of the current filter or action.
API Tags:
| Return: | Hook name of the current filter or action. |
static int did_action(
string
$tag
)
|
|
did_action() - Return the number times an action is fired.
Parameters:
|
string |
$tag: |
The name of the action hook. |
API Tags:
| Return: | The number of times action hook <tt>$tag</tt> is fired |
static int|boolean has_action(
string
$tag, [callback
$function_to_check = false]
)
|
|
has_action() - Check if any action has been registered for a hook.
Parameters:
|
string |
$tag: |
The name of the action hook. |
|
callback |
$function_to_check: |
optional. If specified, return the priority of that function on this hook or false if not attached. |
API Tags:
| Return: | Optionally returns the priority on that hook for the specified function. |
static int|boolean has_filter(
string
$tag, [callback
$function_to_check = false]
)
|
|
has_filter() - Check if any filter has been registered for a hook.
Parameters:
|
string |
$tag: |
The name of the filter hook. |
|
callback |
$function_to_check: |
optional. If specified, return the priority of that function on this hook or false if not attached. |
API Tags:
| Return: | Optionally returns the priority on that hook for the specified function. |
static boolean remove_action(
string
$tag, callback
$function_to_remove, [int
$priority = 10], [int
$accepted_args = 1]
)
|
|
remove_action() - Removes a function from a specified action hook.
This function removes a function attached to a specified action hook. This method can be used to remove default functions attached to a specific filter hook and possibly replace them with a substitute.
Parameters:
|
string |
$tag: |
The action hook to which the function to be removed is hooked. |
|
callback |
$function_to_remove: |
The name of the function which should be removed. |
|
int |
$priority: |
optional The priority of the function (default: 10). |
|
int |
$accepted_args: |
optional. The number of arguments the function accpets (default: 1). |
API Tags:
| Return: | Whether the function is removed. |
static boolean remove_filter(
string
$tag, callback
$function_to_remove, [int
$priority = 10], [int
$accepted_args = 1]
)
|
|
remove_filter() - Removes a function from a specified filter hook.
This function removes a function attached to a specified filter hook. This method can be used to remove default functions attached to a specific filter hook and possibly replace them with a substitute. To remove a hook, the <tt>$function_to_remove</tt> and <tt>$priority</tt> arguments must match when the hook was added. This goes for both filters and actions. No warning will be given on removal failure.
Parameters:
|
string |
$tag: |
The filter hook to which the function to be removed is hooked. |
|
callback |
$function_to_remove: |
The name of the function which should be removed. |
|
int |
$priority: |
optional. The priority of the function (default: 10). |
|
int |
$accepted_args: |
optional. The number of arguments the function accpets (default: 1). |
API Tags:
| Return: | Whether the function existed before it was removed. |
null do_action(
string
$tag, [
$arg = ''], mixed
$arg,...
)
|
|
do_action() - Execute functions hooked on a specific action hook.
This function invokes all functions attached to action hook <tt>$tag</tt>. It is possible to create new action hooks by simply calling this function, specifying the name of the new hook using the <tt>$tag</tt> parameter. You can pass extra arguments to the hooks, much like you can with apply_filters().
Parameters:
|
string |
$tag: |
The name of the action to be executed. |
|
mixed |
$arg,...: |
Optional additional arguments which are passed on to the functions hooked to the action. |
|
|
$arg: |
|
API Tags:
| Return: | Will return null if $tag does not exist in Hooks::$filter array |
| See: | apply_filters() This function works similar with the exception that nothing is
returned and only the functions or methods are called. |
|
|
