![]() |
Xataface
2.0alpha2
Xataface Application Framework
|
An interface to document the methods that can be implemented in the Application delegate class. This is not a real interface. It is merely used for documentation purposes. More...
Public Member Functions | |
Permissions | |
| getPermissions (Dataface_Record $record) | |
| Returns associative array of permissions that should be granted to the current user on the specified record. | |
| getRoles (Dataface_Record $record) | |
| Returns one or more roles that are to be granted to the current user for the specified record. | |
Triggers | |
| after_action_activate () | |
| Trigger executed after a user account is activated. | |
| after_action_login () | |
| Trigger executed after a user logs in. | |
| after_action_logout () | |
| Trigger executed after a user logs out. | |
| after_action_edit () | |
Trigger executed after succesfully editing a record. This is called after the edit action is complete in constrast to the afterSave() method that is called after a record is saved. The key difference is that afterSave() may be called many times per request (as many records may be changed and saved in a request). after_action_edit(), on the other hand is only called once after the edit form has been successfully saved. | |
| after_action_new () | |
Trigger executed after successfully inserting a new record through the new action. This is called after the new action is complete in contrast to the afterInsert() method that is called after a record is inserted. The key difference is that afterInsert() may be called multiple times per request, since many records may be inserted in a single request. The after_action_new() trigger, on the other hand, is only called once after the new form has been successfully saved. | |
| after_action_delete () | |
| Trigger executed after successfully deleting a record through the UI. | |
| before_authenticate () | |
| Trigger executed before the authentication step occurs in each request. This method may be handy for changing the authentication type at the last minute depending on various factors. | |
| beforeHandleRequest () | |
| Trigger executed before each request (but after the autehntication step). It is often useful to implement this method to provide desirable default behavior for a request. | |
| startSession () | |
| Overrides the code to start sessions. If this is implemented it will override how xataface starts sessions. This may be useful if you have your own custom session handler. | |
Preferences | |
| getPreferences () | |
| Returns the preferences to assign the current user. This is run after the authentication step on each request (but before the beforeHandleRequest() method). | |
Registration | |
| beforeRegister (Dataface_Record $user) | |
| A trigger executed before the registration form is saved. This can be used to perform some custom actions like emailing the administrator. | |
| afterRegister (Dataface_Record $user) | |
| A trigger that is executed after the registration form is saved. This can be used to perform some custom actions like emailing the administrator. | |
| validateRegistrationForm (array $values) | |
| A hook that validates the input into the user registration form to make sure that the input is valid. | |
| sendRegistrationActivationEmail (Dataface_Record $user, $activationURL) | |
| A hook that can be implemented to override the sending of an activation email to the user. | |
| getRegistrationActivationEmailInfo (Dataface_Record $user, $activationURL) | |
| A hook that can be implemented to override the default information that is used to send the registration activation email (the email that the user receives when they register). | |
| getRegistrationActivationEmailSubject (Dataface_Record $user, $activationURL) | |
| A hook that can be implemented to override the default registration activation email subject line (the email that the user receives when they register). | |
| getRegistrationActivationEmailMessage (Dataface_Record $user, $activationURL) | |
| A hook that can be implemented to override the default registration activation email message body (the email that the user receives when they register). | |
| getRegistrationActivationEmailParameters (Dataface_Record $user, $activationURL) | |
| a hooke that can be implemented to override the default registration activation email parameters (the email the user receives when they register). | |
| getRegistrationActivationEmailHeaders (Dataface_Record $user, $activationURL) | |
| A hook that can be implemented to override the default registration activation email headers. | |
Forgot Password | |
| getPasswordChangedEmailInfo (Dataface_Record $user, $password) | |
| Optional method to define the settings for the email that is sent to the user upon successful resetting of their password using the password reset function. | |
| getResetPasswordEmailInfo (Dataface_Record $user, $reset_url) | |
| Optional method to define the settings for the email that is sent to the user when they request to reset their password. | |
RSS Feed Customization | |
| getFeed (array $query) | |
| Returns an associative array of parameters to configure the RSS feed for a particular table . | |
| getRelatedFeed (Dataface_Record $record, $relationship) | |
| Returns an associative array of parameters to configure the RSS feed for the related records of a particular parent record. | |
Template Customization | |
| block__blockname () | |
| Inserts content into a particular block or slot of a template in Xataface. | |
| getNavItem ($key, $label) | |
| The getNavItem() method of the application delegate class can be used to override the items that appear in the navigation menu (i.e. the menu that allows users to select the table via either tabs along the top or items along the side). It should return an associative array with characteristics of the navigation item including the href (i.e. link), label, and selected status. | |
| navItemIsSelected ($key) | |
| getTemplateContext () | |
| getSearchTarget (array $action) | |
| Returns the name of an action that should be used as the target action of a search performed from the current context. In past releases searches would always go to the list action. This gives you the ability to override this behavior with your own custom action depending on the circumstances. | |
Valuelist Customization | |
| valuelist__valuelistname () | |
An interface to document the methods that can be implemented in the Application delegate class. This is not a real interface. It is merely used for documentation purposes.
Every Xataface project may define an Application Delegate class that helps to customize the behavior of the app. It may be used to define permissions that are granted to users (e.g. getPermissions()), or to customize parts of the interface (e.g. block__blockname()), or to affect the flow of control (e.g. beforeHandleRequest()). Although it is not required to implement an Application Delegate Class for your application, it is hard to imagine a very powerful application not having one.
Definition at line 66 of file ApplicationDelegateClass.php.
| after_action_activate | ( | ) |
Trigger executed after a user account is activated.
| after_action_delete | ( | ) |
Trigger executed after successfully deleting a record through the UI.
| after_action_edit | ( | ) |
Trigger executed after succesfully editing a record. This is called after the edit action is complete in constrast to the afterSave() method that is called after a record is saved. The key difference is that afterSave() may be called many times per request (as many records may be changed and saved in a request). after_action_edit(), on the other hand is only called once after the edit form has been successfully saved.
| after_action_login | ( | ) |
Trigger executed after a user logs in.
| after_action_logout | ( | ) |
Trigger executed after a user logs out.
| after_action_new | ( | ) |
Trigger executed after successfully inserting a new record through the new action. This is called after the new action is complete in contrast to the afterInsert() method that is called after a record is inserted. The key difference is that afterInsert() may be called multiple times per request, since many records may be inserted in a single request. The after_action_new() trigger, on the other hand, is only called once after the new form has been successfully saved.
| afterRegister | ( | Dataface_Record | $user | ) |
A trigger that is executed after the registration form is saved. This can be used to perform some custom actions like emailing the administrator.
@param Dataface_Record $user A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. @returns mixed If this method returns a PEAR_Error object, then registration will fail with an error. @par Example: @code <?php
class conf_ApplicationDelegate { function afterRegister(&$record){ // mail the admin to let him know that the registration is occurring. mail('admin@example.com', 'New registration', 'A new user '.$record->val('username').' has registered); } }
| before_authenticate | ( | ) |
Trigger executed before the authentication step occurs in each request. This method may be handy for changing the authentication type at the last minute depending on various factors.
| beforeHandleRequest | ( | ) |
Trigger executed before each request (but after the autehntication step). It is often useful to implement this method to provide desirable default behavior for a request.
This may be used for such things as:
| beforeRegister | ( | Dataface_Record | $user | ) |
A trigger executed before the registration form is saved. This can be used to perform some custom actions like emailing the administrator.
@param Dataface_Record $user A Dataface_Record object encapsulating the record
that is being inserted in the users table for this registration.
@returns mixed If this method returns a PEAR_Error object, then registration
will fail with an error.
@par Example:
@code
<?php
class conf_ApplicationDelegate { function beforeRegister(&$record){ // mail the admin to let him know that the registration is occurring. mail('admin@example.com', 'New registration', 'A new user '.$record->val('username').' has registered); } }
| block__blockname | ( | ) |
Inserts content into a particular block or slot of a template in Xataface.
@see <a href="http://xataface.com/documentation/tutorial/getting_started/changing-look-and-feel">Changing Xataface Look and Feel</a>
@par Example
@code
function block__before_header(){
echo "<h1>Hello World</h1>"; } This would print "Hello World" at the top of each page as follows:
block__blockname() method in either your application delegate class or your table delegate class.| getFeed | ( | array | $query | ) |
Returns an associative array of parameters to configure the RSS feed for a particular table .
@param array $query The HTTP query. Contains information like the current table, current action, and search parameters. This allows you to customize your RSS feed depending on the user's query parameters. @returns array Returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys: - @p title - The title for the RSS feed. If this omitted, it will try to use the title directive of the [_feed] section of the conf.ini file. Failing that, it will try to generate an appropriate title for the feed depending on the current query. (since 1.0) - @p description - A Description for this RSS feed. If this is omitted, it will try to use the description directive of the [_feed] section of the conf.ini file. Since 1.0 - @p link - A link to the source page of the RSS feed. If this is omitted, it will try to use the link directive of the [_feed] section of the conf.ini file. Since 1.0 - @p syndicationURL- A link to the source page of the RSS feed. If this is omitted, it will try to use the syndicationURL directive of the [_feed] section of the conf.ini file. Since 1.0
@see DelegateClass::getFeed() @see DelegateClass:getFeedItem() @see <a href="http://xataface.com/wiki/getFeed">getFeed Wiki Page</a> @see <a href="http://xataface.com/wiki/Introduction_to_RSS_Feeds_in_Xataface">Introduction to RSS Feeds in Xataface</a>
| getNavItem | ( | $key, | |
| $label | |||
| ) |
The getNavItem() method of the application delegate class can be used to override the items that appear in the navigation menu (i.e. the menu that allows users to select the table via either tabs along the top or items along the side). It should return an associative array with characteristics of the navigation item including the href (i.e. link), label, and selected status.
Using this method it is now possible to have non-table navigation items as well. You would just add these items to the \[_tables\] section of the conf.ini file then override the item using this method. @since 1.3 @section how_the_nav_menu_is_built How the Nav Menu Is Built Xataface builds the navigation menu by looping through each item in the [_tables] section of the conf.ini file, passing it to the getNavItem() method, and adding the resulting navigation item to the menu. If getNavItem() returns null, then that item will be skipped. If getNavItem throws an exception, then the default rendering for the menu item will take place. @param string $key The key of the nav item. In the case of a table, this would be the table name. @param string $label The label of the nav item (may be overridden). @returns mixed This method should return either: - An associative array with the properties of the nav item. - @p null to indicate that this nav item should be omitted altogether. (e.g. if the user shouldn't have permission for it). If returning an associative array, it should contain the following keys: - @p href - (String) The URL where this nav item should point. - @p label - (String) The label of this nav item. - @p selected - (Boolean) True if the nav item is currently selected. False otherwise. @throws Exception If you want to signal Xataface to just use default rendering for the current navigation item you can just throw an exception. The default rendering will link to the table named @p $key, and the item's label will be the same as @p $label. @section getNavItem_examples Examples Given the following conf.ini file: @code ...
[_tables] people=People books=Books accounts=Accounts reports=Reports
...
Suppose we want the navigation menu to only show the people and books options for regular users. Admin users can see all options.
*In addition, the 'reports' option doesn't correspond with a table of the database. Instead we are just going to link it to a custom action named 'reports'.
*Our getNavItem() method will look something like this:
| getPasswordChangedEmailInfo | ( | Dataface_Record | $user, |
| $password | |||
| ) |
Optional method to define the settings for the email that is sent to the user upon successful resetting of their password using the password reset function.
| Dataface_Record | $user | The Dataface_Record of the user whose password has been changed. |
| string | $password | The new temporary password that has been assigned to the user. |
subject - The subject line of the email.message - The message content of the email.headers - The Email headers (as a string).parameters - Extra parameters for the mail function.| getPermissions | ( | Dataface_Record | $record | ) |
Returns associative array of permissions that should be granted to the current user on the specified record.
| Dataface_Record | $record | The record on which we are granting permissions. |
The following flowchart shows the flow of control Xataface uses to determine the record-level permissions for a record. (click here to enlarge):
| getPreferences | ( | ) |
Returns the preferences to assign the current user. This is run after the authentication step on each request (but before the beforeHandleRequest() method).
@see <a href="http://xataface.com/wiki/preferences">Preferences</a> - for information about
Xataface preferences.
@returns array(string=>boolean)
@par Example:
@code
function getPreferences(){
return array('hide_update'=>1, 'hide_posted_by'=>1);
}
| getRegistrationActivationEmailHeaders | ( | Dataface_Record | $user, |
| $activationURL | |||
| ) |
A hook that can be implemented to override the default registration activation email headers.
| Dataface_Record | $user | The record that is being inserted into the users table. |
| string | $activationURL | The url where the user can go to activate their account. |
| getRegistrationActivationEmailInfo | ( | Dataface_Record | $user, |
| $activationURL | |||
| ) |
A hook that can be implemented to override the default information that is used to send the registration activation email (the email that the user receives when they register).
@param Dataface_Record $user A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. @param string $activationURL The URL where the user can go to activate their account. @returns mixed If this method returns a PEAR_Error object, then registration will fail with an error. @par Example @code <?php
class conf_ApplicationDelegate {
function getRegistrationActivationEmailInfo(&$record, $activationURL){ return array( 'subject' => 'Welcome to the site.. Activation required', 'message' => 'Thanks for registering. Visit '.$activationURL.' to activate your account', 'headers' => 'From: webmaster@example.com' . "\r\n" . 'Reply-To: webmaster@example.com' . "\r\n" . 'X-Mailer: PHP/' . phpversion() );
} }
| getRegistrationActivationEmailMessage | ( | Dataface_Record | $user, |
| $activationURL | |||
| ) |
A hook that can be implemented to override the default registration activation email message body (the email that the user receives when they register).
@param Dataface_Record $user A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. @param string $activationURL The URL where the user can go to activate their account. @returns mixed If this method returns a PEAR_Error object, then registration will fail with an error. @par Example @code <?php
class conf_ApplicationDelegate {
function getRegistrationActivationEmailInfo(&$record, $activationURL){ return 'Thanks for registering. Please visit '.$activationURL.' to activate.'; } }
| getRegistrationActivationEmailParameters | ( | Dataface_Record | $user, |
| $activationURL | |||
| ) |
a hooke that can be implemented to override the default registration activation email parameters (the email the user receives when they register).
| Dataface_Record | $user | The record that is being inserted into the users table. |
| string | $activationURL | The URL where the user can go to activate their account. |
| getRegistrationActivationEmailSubject | ( | Dataface_Record | $user, |
| $activationURL | |||
| ) |
A hook that can be implemented to override the default registration activation email subject line (the email that the user receives when they register).
@param Dataface_Record $user A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. @param string $activationURL The URL where the user can go to activate their account. @returns mixed If this method returns a PEAR_Error object, then registration will fail with an error. @par Example @code <?php
*class conf_ApplicationDelegate {
function getRegistrationActivationEmailInfo(&$record, $activationURL){
reeturn 'Welcome to the site.. Activation required';
}
*}
| getRelatedFeed | ( | Dataface_Record | $record, |
| $relationship | |||
| ) |
Returns an associative array of parameters to configure the RSS feed for the related records of a particular parent record.
| Dataface_Record | $record | The parent record whose relationship is being published as an RSS feed. |
| string | $relationship | The name of the relationship whose records are being published. |
title - The title for the RSS feed. If this omitted, it will try to use the title directive of the [_feed] section of the conf.ini file. Failing that, it will try to generate an appropriate title for the feed depending on the current query. (since 1.0)description - A Description for this RSS feed. If this is omitted, it will try to use the description directive of the [_feed] section of the conf.ini file. Since 1.0link - A link to the source page of the RSS feed. If this is omitted, it will try to use the link directive of the [_feed] section of the conf.ini file. Since 1.0syndicationURL- A link to the source page of the RSS feed. If this is omitted, it will try to use the syndicationURL directive of the [_feed] section of the conf.ini file. Since 1.0| getResetPasswordEmailInfo | ( | Dataface_Record | $user, |
| $reset_url | |||
| ) |
Optional method to define the settings for the email that is sent to the user when they request to reset their password.
@since 1.3 @param Dataface_Record $user The Dataface_Record of the user whose password has been changed. @param string $reset_url The URL where the user should go to reset their password. When they visit this URL they will receive a message saying that their password has been changed and the new password has been emailed to them. That subsequent email can be customized using the getPasswordChangedEmailInfo() method. @returns array This method should return an associative array with 0 or more of the following keys:
subject - The subject line of the email.message - The message content of the email.headers - The Email headers (as a string).parameters - Extra parameters for the mail function.| getRoles | ( | Dataface_Record | $record | ) |
Returns one or more roles that are to be granted to the current user for the specified record.
| Dataface_Record | $record | The record on which the roles are to be granted. |
The following flowchart shows the flow of control Xataface uses to determine the record-level permissions for a record. (click here to enlarge):
| getSearchTarget | ( | array | $action | ) |
Returns the name of an action that should be used as the target action of a search performed from the current context. In past releases searches would always go to the list action. This gives you the ability to override this behavior with your own custom action depending on the circumstances.
| array | $action | The action definition to check (this would be the source action). |
| getTemplateContext | ( | ) |
| navItemIsSelected | ( | $key | ) |
| sendRegistrationActivationEmail | ( | Dataface_Record | $user, |
| $activationURL | |||
| ) |
A hook that can be implemented to override the sending of an activation email to the user.
@param Dataface_Record $user A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. @param string $activationURL The URL where the user can go to activate their account. @returns If this method returns a PEAR_Error object, then registration will fail with an error. @par Example @code <?php
class conf_ApplicationDelegate {
function sendRegistrationActivationEmail(&$record, $activationURL){ // mail the admin to let him know that the registration is occurring. $username = $record->val('username'); $email = $record->val('email');
mail($email, 'Welcome to the team', 'Welcome '.$record->val('username'). '. You have been successfully registered. Please visit '.$activationURL.' to activate your account' ); } }
| startSession | ( | ) |
Overrides the code to start sessions. If this is implemented it will override how xataface starts sessions. This may be useful if you have your own custom session handler.
| validateRegistrationForm | ( | array | $values | ) |
A hook that validates the input into the user registration form to make sure that the input is valid.
@param array $values An associative array of the input values of the registration form. @returns mixed If this method returns a PEAR_Error object then the validation will fail - and the user will be asked to correct his input. @par Example: @code <?php
class conf_ApplicationDelegate { function validateRegistrationForm($values){ if ( $values['age'] < 18 ){ return PEAR::raiseError("Sorry you must be at least 18 years old to join this site."); } return true; } }
| valuelist__valuelistname | ( | ) |
1.8.1.2