/**
* Elgg Actions
*
- * Actions are the primary controllers (The C in MVC) in Elgg. They are
- * registered by {@link register_elgg_action()} and are called either by URL
- * http://elggsite.org/action/action_name or {@link action($action_name}. For
- * URLs, a rewrite rule in .htaccess passes the action name to
- * engine/handlers/action_handler.php, which dispatches the action.
+ * Actions are one of the primary controllers (The C in MVC) in Elgg. They are
+ * registered by {@link register_elgg_action()} and are called by URL
+ * http://elggsite.org/action/action_name. For URLs, a rewrite rule in
+ * .htaccess passes the action name to engine/handlers/action_handler.php,
+ * which dispatches the request for the action.
*
- * An action name should be registered to exactly one file in the system, usually under
- * the actions/ directory.
+ * An action name must be registered to a file in the system. Core actions are
+ * found in /actions/ and plugin actions are usually under /mod/<plugin>/actions/.
+ * It is recommended that actions be namespaced to avoid collisions.
*
* All actions require security tokens. Using the {@elgg_view input/form} view
- * will automatically add tokens as hidden inputs. To manually add hidden inputs,
- * use the {@elgg_view input/securitytoken} view.
+ * will automatically add tokens as hidden inputs as will the elgg_view_form()
+ * function. To manually add hidden inputs, use the {@elgg_view input/securitytoken} view.
*
* To include security tokens for actions called via GET, use
- * {@link elgg_add_security_tokens_to_url()}.
+ * {@link elgg_add_security_tokens_to_url()} or specify is_action as true when
+ * using {@lgg_view output/url}.
*
* Action tokens can be manually generated by using {@link generate_action_token()}.
*
*/
/**
-* Perform an action.
-*
-* This function executes the action with name $action as
-* registered by {@link elgg_register_action()}.
-*
-* The plugin hook action, $action_name will be emitted before
-* the action is executed. If a handler returns false, it will
-* prevent the action from being called.
-*
-* @note If an action isn't registered in the system or is registered
-* to an unavailable file the user will be forwarded to the site front
-* page and an error will be emitted via {@link register_error()}.
-*
-* @warning All actions require {@link http://docs.elgg.org/Actions/Tokens Action Tokens}.
-* @warning Most plugin shouldn't call this manually.
-*
-* @param string $action The requested action
-* @param string $forwarder Optionally, the location to forward to
-*
-* @link http://docs.elgg.org/Actions
-* @see elgg_register_action()
-*
-* @return void
-*/
+ * Perform an action.
+ *
+ * This function executes the action with name $action as registered
+ * by {@link elgg_register_action()}.
+ *
+ * The plugin hook 'action', $action_name will be triggered before the action
+ * is executed. If a handler returns false, it will prevent the action script
+ * from being called.
+ *
+ * @note If an action isn't registered in the system or is registered
+ * to an unavailable file the user will be forwarded to the site front
+ * page and an error will be emitted via {@link register_error()}.
+ *
+ * @warning All actions require {@link http://docs.elgg.org/Actions/Tokens Action Tokens}.
+ *
+ * @param string $action The requested action
+ * @param string $forwarder Optionally, the location to forward to
+ *
+ * @link http://docs.elgg.org/Actions
+ * @see elgg_register_action()
+ *
+ * @return void
+ * @access private
+ */
function action($action, $forwarder = "") {
global $CONFIG;
/**
* Registers an action.
*
- * Actions are registered to a single file in the system and are executed
- * either by the URL http://elggsite.org/action/action_name or by calling
- * {@link action()}.
+ * Actions are registered to a script in the system and are executed
+ * either by the URL http://elggsite.org/action/action_name/.
*
* $filename must be the full path of the file to register, or a path relative
* to the core actions/ dir.
*
* @tip Put action files under the actions/<plugin_name> directory of your plugin.
*
- * @tip You don't need to include engine/start.php, call {@link gatekeeper()},
- * or call {@link admin_gatekeeper()}.
+ * @tip You don't need to include engine/start.php in your action files.
*
* @internal Actions are saved in $CONFIG->actions as an array in the form:
* <code>
* @param string $action The name of the action (eg "register", "account/settings/save")
* @param string $filename Optionally, the filename where this action is located. If not specified,
* will assume the action is in elgg/actions/<action>.php
- * @param string $access Who is allowed to execute this action: admin, public, or logged_in.
+ * @param string $access Who is allowed to execute this action: public, logged_in, admin.
* (default: logged_in)
*
* @see action()
* @see http://docs.elgg.org/Actions
*
- * @return true
+ * @return bool
*/
function elgg_register_action($action, $filename = "", $access = 'logged_in') {
global $CONFIG;
return true;
}
+/**
+ * Unregisters an action
+ *
+ * @param string $action Action name
+ * @return bool
+ * @since 1.8.1
+ */
+function elgg_unregister_action($action) {
+ global $CONFIG;
+
+ if (isset($CONFIG->actions[$action])) {
+ unset($CONFIG->actions[$action]);
+ return true;
+ } else {
+ return false;
+ }
+}
+
/**
* Validate an action token.
*
- * Calls to actions will automatically validate tokens.
- * If tokens are not present or invalid, the action will be
- * denied and the user will be redirected to the front page.
+ * Calls to actions will automatically validate tokens. If tokens are not
+ * present or invalid, the action will be denied and the user will be redirected.
*
* Plugin authors should never have to manually validate action tokens.
*
- * @access private
- *
* @param bool $visibleerrors Emit {@link register_error()} errors on failure?
* @param mixed $token The token to test against. Default: $_REQUEST['__elgg_token']
* @param mixed $ts The time stamp to test against. Default: $_REQUEST['__elgg_ts']
* @return bool
* @see generate_action_token()
* @link http://docs.elgg.org/Actions/Tokens
+ * @access private
*/
function validate_action_token($visibleerrors = TRUE, $token = NULL, $ts = NULL) {
global $CONFIG;
}
/**
-* Validates the presence of action tokens.
-*
-* This function is called for all actions. If action tokens are missing,
-* the user will be forwarded to the site front page and an error emitted.
-*
-* This function verifies form input for security features (like a generated token), and forwards
-* the page if they are invalid.
-*
-* @access private
-* @return mixed True if valid, or redirects to front page and exists.
-*/
+ * Validates the presence of action tokens.
+ *
+ * This function is called for all actions. If action tokens are missing,
+ * the user will be forwarded to the site front page and an error emitted.
+ *
+ * This function verifies form input for security features (like a generated token),
+ * and forwards if they are invalid.
+ *
+ * @return mixed True if valid or redirects.
+ * @access private
+ */
function action_gatekeeper() {
if (validate_action_token()) {
return TRUE;
* @example actions/manual_tokens.php
*
* @return string|false
+ * @access private
*/
function generate_action_token($timestamp) {
$site_secret = get_site_secret();
}
/**
- * Check if an action is registered and its file exists.
+ * Check if an action is registered and its script exists.
*
* @param string $action Action name
*
return (isset($CONFIG->actions[$action]) && file_exists($CONFIG->actions[$action]['file']));
}
-/**
- * Initialize some ajaxy actions features
- */
-function actions_init() {
- elgg_register_action('security/refreshtoken', '', 'public');
-
- elgg_register_simplecache_view('js/languages/en');
-
- elgg_register_plugin_hook_handler('action', 'all', 'ajax_action_hook');
- elgg_register_plugin_hook_handler('forward', 'all', 'ajax_forward_hook');
-}
-
/**
* Checks whether the request was requested via ajax
*
* @return bool whether page was requested via ajax
+ * @since 1.8.0
*/
function elgg_is_xhr() {
return isset($_SERVER['HTTP_X_REQUESTED_WITH'])
* @param string $type
* @param string $reason
* @param array $params
- *
+ * @return void
+ * @access private
*/
function ajax_forward_hook($hook, $type, $reason, $params) {
if (elgg_is_xhr()) {
/**
* Buffer all output echo'd directly in the action for inclusion in the returned JSON.
+ * @return void
+ * @access private
*/
function ajax_action_hook() {
if (elgg_is_xhr()) {
}
}
+/**
+ * Initialize some ajaxy actions features
+ */
+function actions_init() {
+ elgg_register_action('security/refreshtoken', '', 'public');
+
+ elgg_register_simplecache_view('js/languages/en');
+
+ elgg_register_plugin_hook_handler('action', 'all', 'ajax_action_hook');
+ elgg_register_plugin_hook_handler('forward', 'all', 'ajax_forward_hook');
+}
+
elgg_register_event_handler('init', 'system', 'actions_init');
projects / lorea / elgg.git / commitdiff