Actions are Elgg's way of providing interactivity: every active participation by the user is performed via an action. Logging in, creating, updating or deleting content are all generic categories of actions.
The traditional development method would be to create PHP scripts that handle each action individually. While plugin authors must still write code to handle each action, Elgg diverts everything through a single, unified action handler. It also prevents authors from accidentally making their actions available to logged-out users (if they don't want them to be).
Contents |
Actions in Elgg are all accessed via a URL like your-elgg-site/action/name/here. Real-world examples include action/login and action/plugins/enable; like views, subdirectories may be used to provide structure and context to the URL.
Actions are handled by the following PHP script :
elgg/engine/handlers/action_handler.php
Actions URLs start with the keyword "action", followed by the registered action's name. For example :
http://www.monsite.fr/elgg/action/systemsettings/install
In the previous example, the registred name is : systemsettings/install
In the ELGG's ".htaccess" file, you notice a rewrite rule :
RewriteRule ^action\/([A-Za-z0-9\_\-\/]+)$ engine/handlers/action_handler.php?action=$1
Therefore, the following URL:
http://www.monsite.fr/elgg/action/systemsettings/install
is rewritten to:
http://www.monsite.fr/elgg/engine/handlers/action_handler.php?action=systemsettings/install
In the Apache access log file, action can be detected by searching for the HTTP code 302. For example :
127.0.0.1 - - [10/Feb/2010:10:25:55 +0100] "GET /elgg1.6.1/ HTTP/1.1" 200 4488
127.0.0.1 - - [10/Feb/2010:10:26:42 +0100] "POST /elgg1.6.1/ HTTP/1.1" 302 -
127.0.0.1 - - [10/Feb/2010:10:26:42 +0100] "GET /elgg1.6.1/install.php HTTP/1.1" 200 6070
127.0.0.1 - - [10/Feb/2010:10:28:26 +0100] "POST /elgg1.6.1/action/systemsettings/install HTTP/1.1" 302 -
Actions must be registered before use. You do this by calling the following function:
function register_action($action, $public = false, $filename = "", $admin_only = false)
The first parameter is the URL you want to claim. These all start with your-elgg-site/action, so for example to claim your-elgg-site/action/yourplugin/youraction for logged-in users only, you'd call:
register_action('yourplugin/youraction', false, $CONFIG->pluginspath . 'yourplugin/actions/youractionfile.php');
Once that has been registered, the action is available for use.
See also: Extending Actions
There is no need to reference the Elgg engine from your action file; this is done for you. All you need to do is grab any input fields using:
$field = get_input('input_field_name', 'default_value');
And load entities and perform actions on them accordingly.
To forward the page once you've completed your actions, use the function:
forward('url/to/forward/to');
For example, to forward to the user's profile:
forward(get_loggedin_user()->getURL());
URLs can also be relative to the Elgg root:
forward('pg/yourplugin/' . get_loggedin_user()->username);
Remember to use calls to system_message (for positive feedback) or register_error (for warnings and errors) in your file, to let the user know what's happened. These are called using:
system_message('Your message');
And:
register_error('This is an error!');
Note that it's a good idea to use the internationalisation functions.
For enhanced security, all actions require a security token. A few views and functions automatically generate security tokens:
elgg_view('output/url', array('is_action' => TRUE));
elgg_view('output/confirmlink');
elgg_view('input/securitytoken');
elgg_view('input/form', array('body' => '...form body...'));
$url = elgg_add_action_tokens_to_url("http://myelgg.org/action/myaction");
Calls to action URLs that do not include security tokens will be ignored and a warning will be generated. Security tokens are validated by the function action_gatekeeper()
Note: Sometimes, you need to send use the security tokens "outside" PHP code. For example, you may need to inject security tokens into rich interfaces (Flash, JavaScript,...). In this case, you can use the following code:
$__elgg_ts = time();
$__elgg_token = generate_action_token($__elgg_ts);
Please note that if using Flash, it does not use the session cookie of the browser so a work around needs to be used. There are two approaches for this. You can pass the session identifier as a POST parameter. This will only work if the server has session.use_only_cookies turned off. You may not be able to or may not want to do this as it is a server level configuration. If so, there is another method that involves passing additional data in the POST request. See more information on it here.
See also: Main forms article