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 prefers to divert everything through a single, unified action handler, that provides security and minimises 404 errors. It also prevents authors from accidentally making their actions available to logged-out users (if they don't want them to be).

The action handler

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.

Registering actions

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

Structure of your action handling file

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($_SESSION['user']->getURL());

URLs can also be relative to the Elgg root:

forward('pg/yourplugin/' . $_SESSION['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.

Security

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.

See also: Main forms article