Rabbit/Action

From Dionyziz

Actions, a core part of the Rabbit Structure, are structural modules which are responsible for receiving form content and calling the relevant library functions for updating server state. They are not presentational modules, and, as such, they must not be used to send any data to the client apart from the required redirection headers. Actions are one of the three user-accessible modules, the other two being Master Elements and Units, and, as such, are type-safe. They perform do-and-redirect tasks.

Contents 1 Action Names 2 Action Filenames 3 Do pointers 4 Using actions 5 Action file Syntax 6 TODO

[edit] Action Names

Each action must have a unique name, which can consist of any combination of lower-case letters and numbers. The slash characters can be used within a name to group similar actions together in a folder- and subfolder-like manner. For example, actions related to user functionalities can be grouped together under the "user/" name, and named, for instance "user/logon", "user/register" and so forth. The starting letter of each action as well as each letter following the slash character must always be lower-case Latin characters and cannot be numbers. Action names must also be unique when the slashes are removed from their names. Hence, it is not possible to have two actions named "user/register" and "userregister" respectively, as this introduces a naming conflict when the slashes are removed.

[edit] Action Filenames

Each action module is established as a PHP source file located under the /actions directory. The filename of an action is its action name followed by ".php". Action files are maskable.

[edit] Do pointers

All actions can be pointed-to by a do-pointer. A do-pointer is a string starting with "do/" and followed by the full action name. For instance, the do-pointer of the actionpage "user/logon" is "do/user/logon".

[edit] Using actions

Actions must be used whenever a regular (i.e. a form whose submission data is not completely handled by javascript onsubmit event) POST form is used. In the action attribute of an HTML form, specify the do-pointer of the actionpage you want the form to be submitted to; don't forget to use the POST HTTP method.

<form action="do/user/logon" method="post">
 Username: <input type="text" name="username" />
 Password: <input type="password" name="password" />
</form>

Keep in mind that actionpages are not used for XMLHTTP submissions; in this case you should be using the respective Coala method.

[edit] Action file Syntax

In the actual action files, there must be no direct output or bulk code. Only one function should be defined, named after your action file. To find the function name required for your action, follow these steps:

• Start by taking the action filename
• Capitalize the first letter and each letter after a slash character
• Remove all slash characters
• Add the word "Action" at the beginning

For example, if your action file resides at actions/user/logon.php, your function should be named ActionUserLogon(). You do not have direct access to $_POST variables. Instead, you should use the type-safety mechanism to make your action function accept parameters passed from the user through HTTP POST; as usual, the order of your parameters does not matter, but the names do. The function should not output anything. Each function, after validating the passed information and calling the needed library subroutines should redirect to an actual presentation page using the Redirect() method. All actions should return a value returned by a call to Redirect(). Care should be taken not to die() or exit() within an action, as it makes it impossible to perform the Rabbit cleanup operations afterwards.

<?php
function ActionSample( tInteger $variable ) {
    global $libs;
    
    $variable = $variable->Get();
    if ( $variable == 0 ) {
        return Redirect( '?p=form&missing=yes' );
    }
    $libs->Load( 'somelibrary' );
    SomeBackendFunction( $variable );
    
    return Redirect( '?p=success' );
}
?>

[edit] TODO

• Establish a standard controller for validation.
• Establish a standard controller for feedback and error reporting back to the submission form.

©2010 dionyziz