after_action_activate 181 after_action_activate Delegate Class Method Return to [[Application Delegate Class]] [[toc]] The '''after_action_activate''' hook is a method that can be defined in the [[Application Delegate Class]] which is called after an account has been activated via the registration process. The full registration process goes as follows: # User fills in registration form. # An email is sent to the user with a link to activate their account. # User clicks on activation link. # User is taken back to the application and activation occurs, which consists of creating a new record in the '''users''' table. # The ''after_action_activate'' trigger is called. ===Since=== This hook has been available since Xataface Version 1.2 ===Example=== <code> /** * A trigger to send the user a confirmation email after their account has been activated. * @params array $params Associative array of passed parameters. Contains a single key 'record' * with the Dataface_Record object of the users table with the user that was activated. */ function after_action_activate(array $params){ $user = $params['record']; mail($user->val('email'), 'Your account is activated', 'Your account has been activated... etc..'); } </code> ===See Also=== * [[Application Delegate Class]] * [[registration_form]] - More information user registration forms. * [[beforeRegister]] - Trigger called before the user registration form is saved. * [[afterRegister]] - Trigger called after registration form is saved. * [[validateRegistrationForm]] - Validates the input into the registration form. * [[sendRegistrationActivationEmail]] - Overrides the sending of the registration activation email. * [[getRegistrationActivationEmailInfo]] - Overrides the activation email info. Returns an associative array of the email details (e.g. subject, to, headers, etc... * [[getRegistrationActivationEmailSubject]] - Returns the subject of the activation email. * [[getRegistrationActivationEmailMessage]] - Returns the message body for the activation email. * [[getRegistrationActivationEmailParameters]] - Returns the parameters for the actication email. * [[getRegistrationActivationEmailHeaders]] - Returns the headers for the activation email. Registration, activation, register, activate, users en getPasswordChangedEmailInfo 121 getPasswordChangedEmailInfo Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== 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. Introduced in Xataface 1.3. Exists in 1.3 or higher. ===Signature=== <code> function getPasswordChangedEmailInfo(Dataface_Record $user, string $password){} </code> ===Parameters=== * '''$user''' - The Dataface_Record of the user whose password has been changed. * '''$password''' - The new temporary password that has been assigned to the user. ===Returns=== 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. ==See Also== * [[getResetPasswordEmailInfo]] - A delegate class method to define the email that is sent to the user when they request a password reset. This is the step that immediately precedes the Password Changed email step. forgot password, reset password en getResetPasswordEmailInfo 122 getResetPasswordEmailInfo Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== Optional method to define the settings for the email that is sent to the user when they request to reset their password. Introduced in Xataface 1.3. Exists in 1.3 or higher. ===Signature=== <code> function getResetPasswordEmailInfo(Dataface_Record $user, string $reset_url){} </code> ===Parameters=== * '''$user''' - The Dataface_Record of the user whose password has been changed. * '''$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=== 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. ==See Also== * [[getPasswordChangedEmailInfo]] - A delegate class method to define the email that is sent to the user once their password has been reset to a temporary password. It informs the user of their new temporary password and should include instructions on how to change their password to their own choice. This step immediately follows the reset password step. forgot password, reset password en beforeHandleRequest 107 beforeHandleRequest Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== The beforeHandleRequest method is a very useful hook that can be implemented in an [[Application Delegate Class]] to perform some processing before every request. This hook is called after user authentication is taken care of, but before control has been passed to the specific action. This means that it is possible to do things such as change the current action or adjust query parameters depending on various factors. ===Example Uses=== * To require users to fill agree to license terms before they can visit particular parts of the application. * To implement custom logging functionality to record user actions * To change the default action for some or all tables. * To automatically create user accounts in some cases. * To change query parameters (e.g. default sorting etc...). ==Examples== ===Example 1: Changing the default action for a particular table=== <code> class conf_ApplicationDelegate { function beforeHandleRequest(){ $app = Dataface_Application::getInstance(); $query =& $app->getQuery(); // Make sure you assign by reference (i.e. =& ) // for this if you want to make changes to the query if ( $query['-table'] == 'dashboard' and $app->_conf['using_default_action'] ){ $query['-action'] = 'my_default_action'; } } } </code> In the above example, we make use of the Application configuration variable [[using_default_action]] to find out if the request is using the default action. This flag is set by Xataface if the user hasn't explicitly declared the action in the URL (i.e. -action has not explicitly been set). ==See Also== * [[Application Delegate Class]] * [http://dataface.weblite.ca/Dataface_Application Dataface_Application API Docs] * [[Xataface URL Conventions]] * '''[[Customizing Theme Based on IP Address]]''' - Article containing an example of using beforeHandleRequest hook. beforeHandleRequest, Application Delegate en getNavItem 125 getNavItem Application Delegate Class Method Return to [[Application Delegate Class]] [[toc]] ===Synopsis=== 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''' ====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. ===Signature=== <code> function mixed getNavItem( string $key, string $label ) throws Exception </code> ===Parameters=== * '''$key''' - The key of the nav item. In the case of a table, this would be the table name. * '''$label''' - The label of the nav item (may be overridden). ===Returns=== This method should return either: # An associative array with the properties of the nav item. # 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: * '''href''' - (String) The URL where this nav item should point. * '''label''' - (String) The label of this nav item. * '''selected''' - (Boolean) True if the nav item is currently selected. False otherwise. ===Throws=== 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 ''$key'', and the item's label will be the same as ''$label''. ==Examples== Given the following conf.ini file: <code> ... [_tables] people=People books=Books accounts=Accounts reports=Reports ... </code> 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: <code> function getNavItem($key, $label){ if (!isAdmin() ){ switch ($key){ case 'people': case 'books': // non-admin users can see these throw new Exception("Use default rendering"); } // Non-admin users can't see any other table. return null; } else { //Admin users can see everything.. $query =& Dataface_Application::getInstance()->getQuery(); switch ($key){ case 'reports': // reports is not a table so we need to return custom properties. return array( 'href' => DATAFACE_SITE_HREF.'?-action=reports', 'label' => $label, 'selected' => ($query['-action'] == 'reports') ); } // For other actions we need to make sure that they aren't selected // if the current action is reports because we want the 'reports' // tab to be selected only in that case. return array( 'selected' => ($query['-table'] == $key and $query['-action'] != 'reports') ); } } </code> ===See Also=== * [[isNavItemSelected]] - Overrides default behavior of whether a navigation item is currently selected. getNavItem, navigation menu en Authenticating_Against_the_PHPBB_Users_table 92 Authenticating Against the PHPBB Users Table Return to [[authentication]] [[toc]] Xataface is able to use the PHPBB users table to authenticate against so that, you can allow your users to log into your Xataface application using the same credentials as they use to access your PHPBB message forum. Achieving this level of integration requires 2 simple steps: # Set up the [[_auth]] section of your [[conf.ini file]] to reference the PHPBB users table and the correct username and password columns. # Specify the correct encryption on the password column. This step will be different for different versions of PHPBB. ==PHPBB 2== PHPBB version 2 and lower simply use MD5 encryption on the password column, which Xataface supports natively via the [[encryption]] directive of the [[fields.ini file]]. Therefore we can set up our Xataface application to authenticate against our PHPBB2 database ('''assuming that our PHPBB is set up in the same database as our Xataface app''') by doing the following: # Set up the [_auth] section of the [[conf.ini file]] as follows:<code> [_auth] users_table = phpbb_users username_column = username password_column = user_password </code> # Set up the user_password field to use md5 encryption in the ''tables/phpbb_users/fields.ini'' file <code> [user_password] encryption=md5 </code> That's it! Now you should be able to log into your Xataface application using the username/password from PHPBB. ==PHPBB 3== PHPBB version 3 and higher uses a custom encryption function for the password column so it is a little more complicated (but not that much). Step one (the [[conf.ini file]]) is the same as for PHPBB version 2 listed above. The 2nd part, however, requires us to implement a custom serialization for the user_password field. So the steps are below: # Set up the [_auth] section of the [[conf.ini file]] as follows:<code> [_auth] users_table = phpbb_users username_column = username password_column = user_password </code> # Implement the user_password__serialize() method in your phpbb_users delegate class (i.e. the ''tables/phpbb_users/phpbb_users.php'' file):<code> <?php class tables_phpbb_users { function user_password__serialize($password){ $itoa64 = './0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; $sql = "select user_password from phpbb_users where username='".addslashes($_POST['UserName'])."'"; $res = mysql_query($sql, df_db()); if ( !$res ) throw new Exception(mysql_error(df_db())); $row = mysql_fetch_assoc($res); mysql_free_result($res); $hash = $this->_hash_crypt_private($password, $row['user_password'], $itoa64); return $hash; } /** * The crypt function/replacement */ function _hash_crypt_private($password, $setting, &$itoa64) { $output = '*'; // Check for correct hash if (substr($setting, 0, 3) != '$H$') { return $output; } $count_log2 = strpos($itoa64, $setting[3]); if ($count_log2 < 7 || $count_log2 > 30) { return $output; } $count = 1 << $count_log2; $salt = substr($setting, 4, 8); if (strlen($salt) != 8) { return $output; } /** * We're kind of forced to use MD5 here since it's the only * cryptographic primitive available in all versions of PHP * currently in use. To implement our own low-level crypto * in PHP would result in much worse performance and * consequently in lower iteration counts and hashes that are * quicker to crack (by non-PHP code). */ if (PHP_VERSION >= 5) { $hash = md5($salt . $password, true); do { $hash = md5($hash . $password, true); } while (--$count); } else { $hash = pack('H*', md5($salt . $password)); do { $hash = pack('H*', md5($hash . $password)); } while (--$count); } $output = substr($setting, 0, 12); $output .= $this->_hash_encode64($hash, 16, $itoa64); return $output; } /** * Encode hash */ function _hash_encode64($input, $count, &$itoa64) { $output = ''; $i = 0; do { $value = ord($input[$i++]); $output .= $itoa64[$value & 0x3f]; if ($i < $count) { $value |= ord($input[$i]) << 8; } $output .= $itoa64[($value >> 6) & 0x3f]; if ($i++ >= $count) { break; } if ($i < $count) { $value |= ord($input[$i]) << 16; } $output .= $itoa64[($value >> 12) & 0x3f]; if ($i++ >= $count) { break; } $output .= $itoa64[($value >> 18) & 0x3f]; } while ($i < $count); return $output; } } </code> PHPBB, authentication, security, authentication modules en sql_delegate_method 87 __sql__ Delegate Method return to [[Delegate class methods]] ===Synopsis=== The __sql__ delegate class method can be defined in any delegate class to specify the SQL query that should be used to fetch records for a given table. This method overrides the [[__sql__]] directive of the fields.ini file. This strategy is primarily used to graft columns from another table onto the base table. =====Use Caution===== This is an advanced feature and, if used incorrectly, can muck up your application. Make sure that your SQL query includes a superset of the columns in the base table, and is a row-for-row match for the rows in the base table. I.e. you should never use an internal join. Always use a left join so that all of the rows of the base table are returned even if the join table doesn't have a corresponding row. If you want to simply filter a table's records, and don't need to graft any additional columns onto the table, you should use the [[setSecurityFilters]] method. ===Example=== Given the table foo, its delegate class: <code> class tables_foo { function __sql__(){ return "select f.*, c.category_name from foo f left join categories c on f.category_id=c.category_id"; } } </code> This effectively grafts a column "category_name" onto the foo table based on a join with the categories table. __sql__, SQL queries, delegate class en field__fieldname 141 Defining Calculated Fields Return to [[Delegate class methods]] Xataface allows you to define calculated fields using the delegate class. These fields won't be visible in the UI by default, but they will be accessible to some modules (e.g. the HTML Reports Module) and they are always accessible to you via the API. E.g. If you define a calculated field named ''year'', you would be able to access this value using the regular Dataface_Record syntax: <code> $record->val('year'); </code> You could also define any number of filter methods and permissions on this field just as you can on regular fields. e.g. <code> function year__permissions($record){ // Return special permissions on the year field. } </code> or <code> function year__display($record){ // Override how the year is displayed in the UI. return $record->val('year').' A.D.'; } </code> ==How to Define a Calculated Field== In the delegate class you simply create a method with the following naming convention: <code> function field__fieldname(Dataface_Record $record); </code> where the return value is the value that the given record should have for the field ''filedname''. E.g. <code> function field__year($record){ $time = trtotime($record->strval('date')); if ( $time ){ return date('Y', $time)); } else { return ''; } } </code> calculated fields, field__fieldname en afterCopy 123 afterCopy Delegate class Method Return to [[Delegate class methods]] [[toc]] ===Synopsis=== A delegate class method that will be executed after a record is copied using the copy set or copy selected function. All xataface copies are shallow which means that related records are not copied by default. If you want a more complex copy function for a table you can implement functionality in this hook. Available since version 1.3 ===Signature=== <code> function afterCopy( Dataface_Record $original, Dataface_Record $copy); </code> ===Parameters=== * '''$original''' - The original record that was copied. * '''$copy''' - The resulting copied record. ===Returns=== * Either return nothing or you may return a PEAR_Error object to indicate that an error occurred with the copy. ==See Also== * [[beforeCopy]] - The beforeCopy hook that can be implemented in the delegate class to run just before a record is copied. afterCopy, copy record hook en beforeCopy 124 beforeCopy Delegate Class Method Return to [[Delegate class methods]] [[toc]] ===Synopsis=== A delegate class method that will be executed before a record is copied using the copy set or copy selected function. All xataface copies are shallow which means that related records are not copied by default. If you want a more complex copy function for a table you can implement functionality in this hook. Available since version 1.3 ===Signature=== <code> function beforeCopy( Dataface_Record $original, array $values); </code> ===Parameters=== * '''$original''' - The original record that is to be copied. * '''$values''' - Associative array of values that are meant to be changed in the copy. Keys correspond with column names. ===Returns=== * Either return nothing or you may return a PEAR_Error object to indicate that an error occurred with the copy. ==See Also== * [[afterCopy]] - The afterCopy hook that can be implemented in the delegate class to run just after a record is copied. beforeCopy, copy records en fieldname__validate 94 fieldname__validate Delegate Class Method Return to [[Delegate class methods]] [[toc]] ===Synopsis=== Xataface allows you to add validation on any particular field in table by adding a fieldname__validate method to the table's delegate class of the form: <code> function myfield__validate(&$record, $value, &$params){ if ( $value != 'Steve' ){ $params['message'] = 'Sorry you must enter "Steve"'; return false; } return true; } </code> ===Parameters=== * &$record : A [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object encapsulating the record we are validating. Note that the values of this object correspond with the submitted values from the form, and not necessarily the actual values of the record in the database. * $value : The value that is being inserted. * &$params : An output array that can be used to pass back a message if validation fails. You would set this array's 'message' parameter to be a message. ===Returns=== Returns a boolean value. True if the value is ok and false if validation failed. ===See Also=== * [[validators]] - For simple validation rules you can use the [[validators|validator:VALIDATOR_NAME]] directive of the [[fields.ini file]]. * [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section on form validation in the Getting Started tutorial. validate, validation, delegate class validation, custom validator en fieldname__default 133 fieldname__default Delegate Class Method Return to [[Delegate class methods]] [[toc]] ===Synopsis=== Xataface allows you to pre-populate any particular field in a table by adding a fieldname__default method to the table's delegate class of the form: <code> function fieldname__default(){ return value; }</code> Returns the default value for the field fieldname. New record forms will be prepopulated with this value. ===Examples=== <code> function minimum_bid__default(){ return 100; }</code> <code> function mydatecol__default(){ return date('Y-m-d'); }</code> <code> function owner_id__default(){ $auth =& Dataface_AuthenticationTool::getInstance(); $user =& $auth->getLoggedInUser(); if ( isset($user) ) return $user->val('userid'); return null; }</code> ===See Also=== * [http://xataface.com/forum/viewtopic.php?t=5028 Pre-entered Data] (forum thread) - setting defaults field values on general fields using the fieldname__default delegate class function * [http://xataface.com/forum/viewtopic.php?t=4004 How to initialize a Date field to today's date?] (forum thread) - alternate methods to use specifically with a date/time field * [http://xataface.com/forum/viewtopic.php?t=3988 Setting default select setting from users table] (forum thread) - solution to populate the current user default, initialize, populate, pre-populate, delegate class default en beforeAddRelatedRecord 108 beforeAddRelatedRecord Delegate Class Method Return to [[Delegate class methods]] [[toc]] ==Synopsis== The ''beforeAddRelatedRecord'' delegate class method can be implemented in any table's delegate class. It will be executed before any related record is added to that table's relationships. Since it will be fired for all relationships on the table, you will have to include logic to only execute if the relationship that you are targeting is being added to. ==Method Signature== <code> function beforeAddRelatedRecord( Dataface_RelatedRecord $record ); </code> ==Parameters== * '''$record''' - The [http://dataface.weblite.ca/Dataface_RelatedRecord Dataface_RelatedRecord] object encapsulating the record that is being added to the relationship. ===Returns=== * void - If all is well * [http://dataface.weblite.ca/Dataface_Error Dataface_Error] object if something went wrong. It is quite common to return a permission denied error from this method after doing some checks. e.g. <code> function beforeAddRelatedRecord($record){ if ( /* some checks here */ ){ return Dataface_Error::permissionDenied('Sorry you don\'t have permission to do this.'); } } </code> ==Examples== ===Example 1: Permission Check=== <code> function beforeAddRelatedRecord($record){ if ( $record->_relationshipName == 'program_roles' ){ // check to make sure that we are allowed to add roles to this program $program = df_get_record('programs', array('program_id'=>'='.$record->val('program_id'))); if ( !$program ){ return Dataface_Error::permissionDenied("Program could not be found"); } if ( !$program->checkPermission('add new related record', array( 'relationship' => 'program_roles' ) ) ){ return Dataface_Error::permissionDenied("You don't have permission to add roles to this program"); } } } </code> The above example requires a little bit of context to understand. This method is defined in the 'users' table. There is a relationship between the ''users'' table and the ''programs'' table called 'program_roles'. It keeps track of the roles that users have with respect to programs. There is a mirror relationshp in the ''programs'' table that goes to the ''users'' table, also named ''program_roles''. Both the ''users'' table and the ''programs'' table contain rel_program_roles__roles() methods to define who can and cannot add to this relationship. However these don't discern on the content that is being added to the relationship, so it is still possible that an ineligible program could be added to the relationship via the users table (or vice versa). So, in the ''users'' table we defined the ''beforeAddRelatedRecord'' above which checks the permissions of the programs table to see if that particular program can be added to this relationship by this user. ==See Also== * [http://dataface.weblite.ca/Dataface_RelatedRecord Dataface_RelatedRecord API Docs] * [[Delegate class methods]] * [http://xataface.com/documentation/tutorial/getting_started/relationships Introduction to Relationships] - from the Getting Started Tutorial * [[relationships.ini file]] reference beforeAddRelatedRecord, Delegate class methods, relationship triggers en getChildren 126 getChildren Delegate Class Method Return to [[Delegate class methods]] [[toc]] The getChildren() method can be implemented in a table's delegate class to specify the logical "child" records of a given record which can be used when creating hierarchical applications. This method will effectively override the output of the Dataface_Record::getChildren() method for records of this table. ===Signature=== <code> function getChildren( Dataface_Record $record) : Dataface_Record[] </code> ===Parameters=== # '''$record''' - The Dataface_Record that is the subject of the query ===Returns=== This method should return an array of Dataface_Record objects that are considered to be children of the subject record. ===Examples=== <code> function getChildren($record){ return df_get_records('webpages', array( 'parent_id'=>'='.$record->val('webpage_id') ) ); } </code> ==See Also== * '''[[getParent]]''' - A Delegate class method to return the logical parent of a given record. getChildren Delegate class method en validators:VALIDATOR_NAME:message 96 validators:VALIDATOR_NAME:message directive for the fields.ini file Return to [[fields.ini file]] [[toc]] ===Synopsis=== If you want to customize the error message associated with a particular [[validator|validation rule]] you can use the validators:VALIDATOR_NAME:message directive in the fields.ini file. ===Format=== <code> [myfield] validators:VALIDATOR_NAME:message = MESSAGE </code> ===Examples=== If you don't like the default error message that is displayed when you make the first_name field required, you can customize it with your own message. E.g. <code> [first_name] validators:required=1 validators:required:message = "Please enter your first name" </code> ===See Also=== * [[validators]] - The [[fields.ini file]] directive for adding a validation rule to a field. This directive must be used in conjunction with [[validators]]. * [[fieldname__validate]] - For more complex validation rules you can define them in the table delegate class. * [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section in the Getting Started tutorial on form validation. validation messages,error messages,form validation rules en validators 95 validators:NAME fields.ini directive Return to [[fields.ini file]] [[toc]] ===Synopsis=== In the fields.ini file you can specify validation rules to be applied to any field by adding the validators:NAME directive in that field's section of the [[fields.ini file]]. ===Available Validators=== {| class="listing listing2" |- ! Name ! Description ! Value ! Version |- | required | Field is required | 1 | All |- | maxlength | Maximum number of characters allowed. | $length | All |- | minlength | Minimum number of characters allowed. | $length | All |- | rangelength | Range (min and max) characters allows | $min,$max | All |- | email | Input must be syntactically correct email address. | 1 | All |- | emailorblank | Accepts an email address or a blank field. | 1 | All |- | regex | Input must match the provided regular expression. | A regular expression | All |- | lettersonly | Input must contain only letters (i.e. [a-zA-Z] | 1 | All |- | numeric | The input must contain a valid positive or negative integer or decimal number. | 1 | All |- | nopunctuation | The input must not contain any of these characters: <nowiki>( ) . / * ^ ? # ! @ $ % + = , " ' &gt; &lt; ~ [ ] { }.</nowiki> | 1 | All |- | nonzero | The input must not begin with zero. | 1 | All |- | uploadedfile | The element must contain a successfully uploaded file. | 1 | All |- | maxfilesize | The uploaded file must be no more than $size bytes. | $size | All |- |filename | The uploaded file must have a filename that matches the regular expression $file_rx. | $file_rx | All |} ===Examples=== To make a the first_name field required we add the following to the [[fields.ini file]]: <code> [first_name] validators:required=1 </code> '''Note that fields that are declared NOT NULL in the database are required by default.'''. If you wanted to remove the ''required'' validator from a field that is NOT NULL in the database you would add the following to the [[fields.ini file]]: <code> [first_name] validators:required=0 </code> ===See Also=== * [[fieldname__validate]] - For more complex validation you can define the [[fieldname__validate]] method in the [[Delegate class methods|Table Delegate Class]]. * [http://www.devarticles.com/c/a/Web-Graphic-Design/Using-HTML-Quickform-for-Form-Processing/12/ HTML_QuickForm article] going over HTML_Quickform validation. Dataface's forms are built on HTML_QuickForm. * [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section from getting started tutorial introducing form validation in a tutorial format. validation, form validation, validators,validator:name en __global__ 106 __global__ section for the fields.ini file Return to [[fields.ini file]] [[toc]] ===Synopsis=== The fields.ini file supports a __global__ section that applies to all fields in the current table. This is particularly useful for setting up default functionality that you wish to see on all fields except a few. For example you may wish to have all fields hidden from list view by default, and only explicitly enable a few. Same for CSV export or the details form. ===Example 1: Hiding All Fields from List View=== In the fields.ini file: <code> [__global__] ;; hide all of the fields from list view visibility:list=hidden [first_name] ;; show the first name in list view visibility:list=visible [last_name] visibility:list=visible ;;.... etc.... </code> In the above example we used the __global__ section to declare that we want all fields to be hidden from list view by default. Then we explicitly showed first_name and last_name in list view. In this case only first_name and last_name will appear in the list view. ==See Also== *[[fields.ini file]] *[[visibility:list]] __global__, fields.ini, visibility:list en meta:class 127 meta:class relationships.ini file directive Return to [[relationships.ini file]] [[toc]] The ''meta:class'' directive allows you to ascribe special meaning to a relationship which Xataface can use in various parts of your application to provide enhanced capabilities. For example you can specify a relationship as a "parent" relationship, thereby using the relationship to obtain the "parent" of records of this table. This can be used to help build breadcrumbs. You can also specify a relationship as a "children" relationship which would treat records in the relationship as children of the current record. This can be used in conjunction with the [[list:type]]=treetable directive of the [[relationships.ini file]] to build a tree table that navigates all child records and subtrees. The Dataface_Record class contains some methods for retrieving the parent and children of records and these methods will take into account any settings you make here. ===Allowed Values=== {| class="listing listing2" |- ! Name ! Description ! Version |- | parent | Designates the relationship as a 'parent' relationship, meaning that the first record in this relationship will be treated as the parent of the current record. This setting can be overridden by the [[getParent]] method of the table delegate class if implemented. | 0.8 |- | children | Designates the relationship as a 'children' relationship meaning that records of the the relationship will be treated as a children. This setting can be overridden by the [[getChildren]] method of the table delegate class if implemented. | 0.8 |} ==See Also== # '''[[list:type]]''' - [[relationships.ini file]] directive to use a treetable for the related record list of a relationship. # '''[[getChildren]]''' - Delegate class method to explicitly define the Dataface_Record objects that are to be considered as child records of the current record. # '''[[getParent]]''' - Delegate class method to explicitly define the Dataface_Record object that is to be considered as the parent record of the current record. en list:type 128 list:type relationships.ini file directive Return to [[relationships.ini file]] [[toc]] The list:type directive allows you to override the default list that is used to display related records. As of Xataface 1.3 there is only one possible value that will have any effect on this directive: "treetable". Setting <code> list:type=treetable </code> will cause the related records to be displayed as an expandable/collapsible tree table as shown here: <nowiki><img src="http://media.weblite.ca/files/photos/Screen%20shot%202011-04-29%20at%2011.49.33%20AM.png?max_width=640"/></nowiki> ===Prerequisites=== The TreeTable component needs to be able to figure out the logical children of each record in order to know what to show when a row is expanded. You can use either the [[meta:class]] directive of the [[relationships.ini]] file to specify a relationship as a "children" relationship, or you can implement the [[getChildren]] method of the table delegate class to manually define a record's child elements. ==See Also== * [[getChildren]] * [[meta:class]] * [[getParent]] en XataJax_Compiler 114 Introduction to the XataJax Compiler Return to [[XataJax]] '''DISCLAIMER''': This page introduces features that require Xataface 1.3 or higher. At present (Jan. 2011) only Xataface 1.2.6 has been released to the public. [[toc]] ===Synopsis=== The XataJax compiler is a Javascript CSS compiler and linker that comes with the [[XataJax]] module and will be a standard part of Xataface starting in version 1.3. It provides a mechanism to process and compile (or so to speak) all of the javascripts required for a page request at the time that the page is requested. This results in a more scalable, manageable javascript and CSS source base - and in improved performance for your applications. ===Compiler Directives=== {| class="listing listing2" |- ! Name ! Description ! Version |- | [[xatajax include directive|include]] | Includes another javascript file inside the current one in place of this directive. Sample code:<code>//include <myscript.js></code> | XataJax 0.1 Xataface 1.3 |- | [[xatajax require directive|require]] | Includes another javscript file inside the current one only if that file hasn't already been included. Sample code: <code>//require <myscript.js></code> | XataJax 0.1 Xataface 1.3 |- | [[xatajax require-css directive|require-css]] | Includes a CSS script in the CSS file. This will will search in the [[Dataface_CSSTool]] include path for the script. Sample code: <code>//require-css <mystyles.css></code> | XataJax 0.1 Xataface 1.3 |- | [[xatajax load directive|load]] | Loads the specified Javascript file in a separate script tag. This enables you to reference other scripts without including them in the same bundle, allowing for more effective caching. Sample code: <code>//load <myscript.js></code> | XataJax 0.1 Xataface 1.3 |} ===How it Works=== The XataJax compiler works similar to a regular code compiler. It provides 4 server-side directives to allow you to express dependencies between scripts and stylesheets: # '''include''' : Includes another javascript file inside the current script in place of the '''include'' directive. # '''require''' : Includes another javascript file inside the current script (if it hasn't already been included) - i.e. if a script is included twice with a require directive, it will only actually be included once. # '''load''' : Registers a dependency to another script, but doesn't include it in the same bundle. This may be used if your script requires code from another javascript, but you don't want it all to be bundled into the same javascript file. This may help with caching in certain cases. # '''require-css''' : Registers a dependency to a CSS file. If your script depends on a CSS file, then it can be registered in this way. ===Brief Example=== ''scriptA.js'': <code> //require <scriptB.js> alert('You are in script A'); </code> ''scriptB.js'': <code> alert('You are in script B'); </code> If you loaded ''scriptA.js'', it would actually result in the following javascript being executed: <code> alert('You are in script B'); alert('You are in script A'); </code> Notice that it included ''scriptB.js'' inside script A before the alert of script A. That is why script B's alert comes first. Note that this example won't work if you simply try to load scriptA.js directly in Apache. These directives are only evaluated if the scripts are served by Xataface. Here is a simple Xataface action that demonstrates how to use this in your Xataface script. ====Creating a custom action==== In your application directory, create an ''actions'' directory if you don't already have one. Then create a single file named ''hello.php'' with the following content: <code> class actions_hello { function handle($params){ $jsTool = Dataface_JavascriptTool::getInstance(); $jsTool->addPath('js', DATAFACE_SITE_URL.'/js'); $jsTool->import('scriptA.js'); echo '<html><head></head><body>'.$jsTool->getHtml().'</body></html>'; exit; } } </code> '''About this code:''' <code>$jsTool = Dataface_JavascriptTool::getInstance();</code> We start by obtaining an instance of the JavascriptTool. This is the object that does all of the magic of compiling your scripts and managing dependencies. <code>$jsTool->addPath('js', DATAFACE_SITE_URL.'/js');</code> This line adds the ''js'' directory to the tool's include path, and specifies (with the 2nd parameter) the URL to reach this directory also. The JavascriptTool works like most source code compilers. You need to give it the path where it can expect to find its libraries and scripts. Only paths that you add here will be searched for javascripts. You can add as many paths as you like. By default it will have the DATAFACE_PATH/js and the XATAJAX_PATH/js directories in the include path so you can directly reference any scripts in those directories always. <code> $jsTool->import('scriptA.js');</code> This is where we declare that we want to use ''scriptA.js'' in the current request. This line then assumes that the scriptA.js file is located in one of the directories of the current include path. In our case we make sure that it resides in the DATAFACE_SITE_PATH/js directory. <code>echo '<html><head></head><body>'.$jsTool->getHtml().'</body></html>';</code> On this line we simply output the HTML script tags that the javascript tool generates linking to our resulting script. Now we can test our our action by going to the page index.php?-action=hello. If everything worked correctly you should see the appropriate alert dialogs appear - first telling you you're in Script B, then telling you you're in Script A. If it doesn't work, you should check your javascript error logs to see what went wrong. '''NOTE:''' - This simple example actually shows you the step of writing out the HTML tags explicitly with the getHtml() method. If you are using a standard Xataface template that is based on the Dataface_Main_Template.html template, then this step is unnecessary because the XataJax module will automatically include this HTML just before the closing </body> tag in your pages. XataJax, compiler, javascript, css, compiler en Key 83 fields.ini Directive: Key The '''Key''' directive is used only when the table is a view and you need to explicitly define which columns are part of the primary key. For example, if we created a view on the books table to only show books in a given year as follows: <code> create view books_2000 as select * from books where year='2000' </code> And we wanted to use this view as a table in our Xataface application we would need to tell it that the primary key of this view is the book_id field. So in the fields.ini file we would add: <code> [book_id] Key=PRI </code> Note that this is case sensitive. key=PRI will not work. ===Compound Primary Keys=== For primary keys comprising multiple columns we would add this directive for each field in the key. E.g. if our books_2000 view had 2 fields in the primary key, say author_id and book_index, we would have in the books_2000 fields.ini file: <code> [author_id] Key=PRI [book_index] Key=PRI </code> Links: * [http://xataface.com/forum/viewtopic.php?f=4&t=6723 Lookup widget on view with compound primary key] Return to [[fields.ini file]] Key, Views, MySQL Views, Create View, PRI, Primary Keys en Customizing_Theme_Based_on_IP_Address 103 Customizing Theme Based on IP Address This article deals with the following topics: # Using [[field__pullValue]]/[[field__pushValue]] methods to customize how a field is edited and stored in the database. # Using [[beforeHandleRequest]] to modify the application settings based on the user's IP address # Storing ranges of IP addresses in the database. Last week I set up a site that needed to have slightly different behavior depending on the IP address of the remote user. E.g. If a user is connecting from an IP address between 192.168.0.0 to 192.168.0.255 we would use a different theme than if they were connecting from a different block. In addition to different themes, we also to use different types of authentication depending on which IP block the user is visiting from. This requirement is actually common for systems that are syndicated by different organizations and should behave slightly differently depending on which organization the user belongs to (assuming they are connecting from that organization's network). To implement this behavior we need to solve one issue. '''How do we store a range of IP addresses in the database so that they can be queried easily to match if the user's IP address falls in that range.''' It turns out that this is quite easy to do, since IP addresses are actually just a 4 digit number (base 256). So we can easily convert this number to base 10 and store it as a regular unsigned integer in the database. In addition, both PHP and MySQL provide functions to convert from an IP address to an integer and back. The PHP functions are called [http://ca3.php.net/long2ip long2ip] and [http://ca3.php.net/ip2long ip2long] respectively. So we have stored a start IP address and an end IP address as integers, we could simply query the database to see if a given IP address falls in that range as follows: <code> $intIP = ip2long($_SERVER['REMOTE_ADDR']); $sql = sprintf('select * from ip_blocks where start_ip<=%u and end_ip>=%u', $intIP, $intIP); ... etc.... </code> '''It is important to note that you need to use the sprintf() function for converting $intIP into a string because PHP will convert it to an integer which could overflow if you leave it to do a default conversion.''' For the above query, we assuming a table with a definition like: <code> create table ip_blocks ( ip_block_id int(11) not null primary key, start_ip unsigned int(11) not null end_ip unsigned int(11), key (start_ip), key (end_ip) ) </code> Now if we attach some information to the IP block, like the theme that should be used, we can check the user IP address against the available IP blocks at the beginning of each request to set the theme for that request. We will use the [[beforeHandleRequest]] method of the [[Application Delegate Class]] to house this because it allows us to set things like the theme or change the user's action. e.g. <code> class conf_ApplicationDelegate { function beforeHandleRequest(){ $app = Dataface_Application::getInstance(); // Get a reference to the current query so we can // alter it if necessary. $query =& $app->getQuery(); // Get the user's IP address and covert it to a long int. $intIP = ip2long($_SERVER['REMOTE_ADDR']); $sql = sprintf('select `theme` from ip_blocks where start_ip<=%u and end_ip>=%u', $intIP, $intIP); $res = mysql_query($sql, df_db()); if ( !$res ) throw new Exception(mysql_error(df_db())); $row = mysql_fetch_row($res); // If we didn't find any valid IP ranges, let's redirect the // user to a different action to let them know that // they're not welcome here. if ( !$row ){ $query['-action'] = 'not_welcome'; // This assumes that we have defined an action // called "not_welcome" return; } $theme = $row[0]; $themePath = 'themes/'.basename($theme); // Check that the theme exists. if ( $theme and file_exists($themePath) ){ df_register_skin($theme, $themePath); } } } </code> The above snippet makes use of the [[df_register_skin]] method that registers a theme to be used dynamically. The first parameter is the theme name, and the second parameter is the path to the theme. This code works great if we already have IP addresses stored properly as integers in our database, but how do we make it so users can work with the IP addresses as IP addresses and not integers? We need to be able to transform from integer to IP address to display in the edit record form, and then convert the resulting IP address back to an integer for storage in the database. Xataface provides two delegate class methods precisely for this purpose: # [[field__pullValue]] - Transforms a value as stored in the database to a format that is preferred in the edit form. # [[field__pushValue]] - Transforms a value entered into the edit form into a format that is preferred by the database. So, in our delegate class we would have: <code> <?php class tables_ip_blocks { /** * @param Dataface_Record $record The record we are pushing the value * into * @param HTML_QuickForm_element $el The QuickForm widget that we are * retrieving the value from. */ function start_ip__pushValue($record, $el){ $val = ip2long($el->getValue()); if ( $val !== false ){ return sprintf('%u', $val ); } return null; } function start_ip__pullValue($record, $el){ $val = $record->val('start_ip'); if ( $val ) return long2ip($val); return $val; } function end_ip__pushValue($record, $el){ $val = ip2long($el->getValue()); if ( $val !== false ){ return sprintf('%u', $val ); } return null; } function end_ip__pullValue($record, $el){ $val = $record->val('end_ip'); if ($val){ return long2ip($val); } return $val; } } </code> The [[field__pullValue]] and [[field__pushValue]] method should be inverses of each other. '''Note that support for [[field__pullValue]] and [[field__pushValue]] are supported by Xataface since version 0.6, however support for them with the grid widget was not added until Xataface version 1.3.''' Now, on the edit form, users can enter and edit IP addresses in the normal format, but they will be converted to unsigned integers for storage in the database. There is only one thing remaining, though. In the list view still shows the integer version of the IP addresses. We want them to show them as regular IP addresses. So we add [[field__display]] methods to our delegate class: <code> function start_ip__display($record){ $val = $record->val('start_ip'); if ( $val ) return long2ip($val); return $val; } function end_ip__display($record){ $val = $record->val('end_ip'); if ($val){ return long2ip($val); } return $val; } </code> ==References== * [http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields] ip address, pullValue, pushValue, beforeHandleRequest en GettingStarted:Introduction 71 Introduction Web Lite is a simple framework for building data-driven web applications in PHP and MySQL. This section introduces some of the concepts and applications of Dataface. To fully understand what Xataface is, we must first define a few key terms: '''Framework''' - A set of software routines that provide a foundation structure for an application. Frameworks take the tedium out of writing an application from scratch. (From Answers.com) '''Data-driven design'''- Designing an application around the data that it will store. Xataface is a ''Framework'' in the sense that it is a set of classes and libraries that take the tedium out of writing web applications. It provides a simple web interface to a MySQL database enabling users to update, delete, and find data in the underlying database. The interface is targeted at secretaries and end-users as opposed to database administrators. Xataface enables ''data-driven design'' because it allows developers to develop web sites by first designing the database that will be used to store the data on the website, and then design the pages used to display the data. The developer can focus on the data because he or she does not have to worry about having to build forms to update the data. If the requirements of the application change, the developer can simply add a field to the database table and all associated web forms will be updated automatically (because they are all dynamically generated using the database schema). ===Requirements=== * [http://php.net PHP] >= 4.3 * [http://mysql.com MySQL] >= 3.2.3 ===Key Technologies=== * [http://pear.php.net PEAR class libraries] (HTML_QuickForm, etc...) * [http://smarty.net Smarty Templating Engine] * [http://plone.org Plone] Javascript and CSS style sheets ===Development Procedures=== # Identify the data that will need to be stored for a web site. ##[[Image:http://xataface.com/documentation/tutorial/getting_started/er-diagram.png]] # Design the database using your favorite database administration program (e.g., PHPMyAdmin) ##[[Image:http://xataface.com/documentation/tutorial/getting_started/phpMyAdmin-1-small.gif]] # Tell Xataface some DB connection info, and voila! You have an application: ##[[Image:http://xataface.com/documentation/tutorial/getting_started/new-record-form-1-small.gif]] ===Where to go from here=== This tutorial will teach you the basics of Xataface and how to construct a simple application using the Xataface. After reading this tutorial you will be ready to tackle some medium to large web sites with the help of the Xataface reference documentation. You are also encouraged to mail the [http://xataface.com/forum Xataface forum] if you have questions. introduction requirements getting started en Authenticating_Against_the_Joomla!_Users_Table 93 Xataface is able to use the joomla users table to authenticate against so that, you can allow your users to log into your Xataface application using the same credentials as they use to access your joomla website. Achieving this level of integration requires 2 simple steps : 1 - Set up the [_auth] section of your conf.ini file to reference the joomla users table and the correct username and password columns. 2 - Create a delegate class for the joomla users table to be able to decrypt the password set in the table. ==Configure the conf.ini file== Joomla users table is named jos_users. So you have to declare this table in the conf.ini file. <code>[_auth] users_table = jos_users username_column = username password_column = password</code> Note that username_column and password_column are very simple... ==Create a delegate class for your users table== Now we have to create a delegate class for the users table to decrypt the passwords set in joomla. Joomla uses a custom md5 encryption. ===Joomla encryption=== When a user is setting a password in joomla, the system does several things : 1 - generate a random key containing alphanumeric characters example : <code>8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> 2 - concate the clear entered password with the random key example : <code>password8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> 3 - doing a md5 encryption on the result string example : <code>md5(password8NdiRqLRKLHaNwudJ3InJknsew9sc7pL = f2b1fb3996442db549c1ed1a1eebbfe1</code> 4 - concate the md5 string with the random key separated by ":" example : <code>f2b1fb3996442db549c1ed1a1eebbfe1:8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> So it's a great encryption but xataface doesn't know how to do that. Here is the utility of the delegate class. We will define a function inside which could compare the entered password in xataface with the joomla stored password. ===Creating the delegate class=== 1 - Add a jos_users directory in your directory table 2 - Create a jos_users.php file inside this new directory ===Creating the decrypt password function=== Before posting this code, I would like to thank fantomasdm who created this function. So here is the code of the function to paste directly in the jos_users delegate class : <code><? class tables_jos_users { function password__serialize($password){ $app =& Dataface_Application::getInstance(); $query = "SELECT id, gid, block, password, usertype FROM jos_users where username='".$_POST['UserName']."'"; $result = mysql_query($query,$app->db()) or die("Query failed" . mysql_error() ); $line = mysql_fetch_array($result, MYSQL_ASSOC); mysql_free_result($result); $arraypass=explode(":", $linea['password']); $key=$arraypass[1]; $ret = md5(trim($password).$key).":".$key; return $ret; } } ?></code> Save your file and test the result. Enjoy ! ;-) joomla authentication md5 en documentation_guide 70 Documentation Guide Xataface uses a wiki to manage its online documentation which can be edited by anyone. All you have to do is [http://xataface.com/wiki/index.php?-action=login login with your forum username and password] ([http://xataface.com/forum/profile.php?mode=register register for the forum here]). Then when you are browsing a page of the wiki, you'll see an 'Edit' tab along the top. Click on this tab to start editing the page in your browser. Wiki markup is a little simpler than HTML and a little more complex than plain text. It is easy to get a handle on once you get started. If you aren't sure how to format it exactly how you want, don't worry. Someone may come by after you and improve on your formatting. That's what the community approach is all about. ==The Documentation Team== Join the Xataface documentation team to help participate in the planning of the documentation. If you want to help out, contact [mailto:steve@weblite.ca Steve Hannah] and he'll add you to the documentation group where you can access the private documentation forums and meet the rest of the team. ==Using the Wiki== The following is a brief guide in using the Xataface Wiki. All following instructions assume that you are already [http://xataface.com/wiki/index.php?-action=login logged in] to the wiki. You can use your forum username and password to login. ===Editing an Existing Page=== # Navigate to the page that you want to edit # Click on the "Edit" tab along the top. # Make changes to your page. # Save the changes. ===Adding a New Page=== ====Method 1: Add a link from an existing page=== # Navigate to an existing page that you want to link to your new page. # Click on the "Edit" tab along the top. # Somewhere in the content of the page, add a link to your new page (which doesn't exist yet), by adding the following markup<code> [[The name of your new page]] </code> # Save your changes. # Click on the "view" tab along the top and find the place where you added your link. It should be displayed with a '?' right after it. Click on the '?' and it will bring you to the "new page form". # fill in the form with your page contents and click save. ====Method 2: Accessing new page form directly==== # Access the [http://xataface.com/wiki/index.php?-action=new&-table=wiki new page form] directly. ===Uploading Images=== Image can be uploaded at [http://media.weblite.ca The Web Lite Media Manager]. You'll need an account to access this site. If you are a member of the documentation team you can request an account from [mailto:steve@weblite.ca Steve Hannah] so that you can upload images here. Steps: # Log into [http://media.weblite.ca the Web Lite Media Manager]. # Click on "Add New File" in the menu on the left. # Select a name for the file, and browse to the image you want to upload in the file upload field. You don't need to check any category boxes. Press save. # Click on the "View" tab for your newly uploaded image. # Copy the embed code for the image from the "Embed Code" field. # In the wiki page add the embed code where you want your image to appear as follows:<code> [[Image:EMBED_CODE]] </code> Where EMBED_CODE is the URL for the image as you copied and pasted out of the media manager. # Save your changes. ===Uploading Video=== ===Adding Source Code Snippets=== documentation wiki en _auth 97 _auth section of the conf.ini file [[conf.ini file|Return to conf.ini file]] [[toc]] ===Synopsis=== The ''_auth'' section of the conf.ini file includes configuration directives to enable authentication in a Xataface application. For more information about authentication and registration see [[authentication]]. This section may include the following directives: ===Directives=== {| class="listing listing2" |- ! Directive ! Description ! Required ! Default ! Version |- | users_table | The name of the table that contains your user accounts. | Yes | None | 0.6 |- | username_column | The name of the column that stores the username. | Yes | None | 0.6 |- | password_column | The name of the column that stores the password. | Required if using basic authentication. | None | 0.6 |- | auth_type | Specifies the authentication module that is being used. E.g. basic, cas, ldap, http, facebook, etc... | No | basic | 0.6 |- | allow_register | Flag to enable user registration. If this is set to 1, then a ''register'' link will appear below the login form. | No | 0 | 0.8 |- | session_timeout | Number of seconds of inactivity after which the user will be logged out. Note: Arithmetic don't work in the conf.ini, use seconds. | No | 86400 (=> 24*60*60 (24 hours)) | 1.3rc4 |} ===See Also=== * [[authentication]] - Overview of Xataface Authentication * [[conf.ini file]] - Directives available in the conf.ini file. _auth,authentication,conf.ini file,allow_register en secure 88 secure fields.ini directive [[fields.ini file]] directive used only with [[container fields]]. If this flag is set, then the field contents will be treated in a secure manner and will obey the application permissions. If this directive is not set, then uploaded files in [[container fields]] are served directly by the web server without considering application permissions. Setting this directive will cause the application use a special get_blob action to serve the uploaded file, and this obeys application permissions. ==Example== Given a field to upload a PDF report, your [[fields.ini file]] section for this field might be something like: <code> [pdf_report] Type=container allowed_extensions="pdf" savepath="uploads" url="uploads" </code> Now if we upload a file named "foo.pdf" in this field, it will be uploaded to: http://www.example.com/path/to/myapp/uploads/foo.pdf Now we change the field definition to use the secure directive: <code> [pdf_report] Type=container allowed_extensions="pdf" savepath="uploads" url="uploads" secure=1 </code> In this case it will still upload files to the ''uploads'' directory, but all of the links generated in the Xataface interface (and via the ''display()'' and ''htmlValue()'' methods) will be for a URL like: http://www.example.com/path/to/myapp/index.php?-action=getBlob&-table=mytable&-field=pdf_report&record_id=10 Which will serve up the PDF file as an attachment. ===Restricting Direct Access to uploads directory=== Note: You still need to restrict access to the uploads directory or it may be possible for users to still guess the absolute URL to files in it. You can restrict access by placing an .htaccess file in the uploads directory (if you are using Apache) with the following contents: <code> deny from all </code> If you are using IIS or another web server you should look into the methods available for you to restrict access to directories. ===HTTP Response Codes=== The [[getBlob action]] will return the following HTTP Response Codes: * '''404''' - If either the record does not exist, or the record's specified container field is empty. * '''403''' - If the current user doesn't have permission to access this record. * '''500''' - If there is another error. The actual error will be written to the error log. secure,fields.ini file en reCAPTCHA_module 99 The reCAPTCHA module [[toc]] ===Synopsis=== The Xataface reCAPTCHA module CAPTCHA support to any Xataface form that is rendered to the public (i.e. when users are not logged in). This is particularly useful for the [[registration form]] as a means of spam prevention. Below is a screenshot of a registration form with the reCAPTCHA module installed: [[Image:http://media.weblite.ca/files/photos/Picture%2038.png?max_width=640]] For more information about reCAPTCHA see [http://recaptcha.net/]. ===Installation=== # Download/extract the module directory into your xataface/modules directory. Currently this module is only available in SVN (http://weblite.ca/svn/dataface/modules/reCAPTCHA/trunk/) # Add the following to the <nowiki>[_modules]</nowiki> section of your [[conf.ini file]].<code> [_modules] modules_reCAPTCHA=modules/reCAPTCHA/reCAPTCHA.php </code> # Add the following section to your conf.ini file.<code> [reCAPTCHA] public_key="xxxxxxx" private_key="xxxxxxx" </code> Where public_key, private_key are your keys from your reCAPTCHA account. '''(Note that you need to register for a free reCAPTCHA account at [http://recaptcha.net/] in order for this to work.''' ===Usage=== If you are NOT logged in, you will now see a reCAPTCHA validation image before the submit button for all webforms in your Xataface application. If you fail to enter the captcha text correctly the form will not validate. If you are logged in this module has no effect. ===See Also=== * [[registration_form|Enabling User Registration in Xataface]] * [[modules|Xataface Modules]] captcha, registration, validation en registration_form 98 Setting up User Registration [[toc]] ===Synopsis=== Xataface optionally enables you to allow users to register for an account in your application. If your ''users'' table includes a column for email, it will also perform email validation before the account is activated. Before tackling user registration, it is good to have an understanding of Xataface's [[authentication]] and [http://xataface.com/documentation/tutorial/getting_started/permissions permissions] faculties. ===Enabling Registration=== To enable registration, simply add the following to the ''[[_auth]]'' section of the [[conf.ini file]]: <code> allow_register=1 </code> e.g. after adding this, your ''[[_auth]]'' section might look like: <code> [_auth] users_table=users username_column=username password_column=password allow_register=1 </code> After doing this, you'll notice a little ''Register'' link below the login form. [[Image:http://media.weblite.ca/files/photos/Picture%2036.png?max_width=640]] Clicking on this link will produce a registration form for the user which is essentially a "New Record" form on your ''users'' table. [[Image:http://media.weblite.ca/files/photos/Picture%2037.png?max_width=640]] Some features of this registration form include: * Checks to ensure that the username is unique * If the users table contains an ''email'' field, it will use the user-entered address for email validation before activation is complete. ===Setting up Permissions to Support Registration=== '''Xataface <= 1.2.4''': You must ensure that unlogged-in users have permission to add new records to the ''users'' table. This means that your getPermissions() method on the users table should, at least, provide the ''new'' permission. In addition these users must be granted the ''register'' permission in order to be able to register to begin with. '''Xataface >= 1.2.5''': You no longer need to provide the ''new'' permission to allow users to register. You simply need to provide the ''register'' permission. ====Sample Permissions on Users Table==== In the tables/users/users.php file (assuming my ''users'' table is actually named "users") <code> class tables_users { function getPermissions($record){ if ( isAdmin() ) return null; $perms['register'] = 1; return $perms; } } </code> '''Note that this example is only applicable for Xataface 1.2.5 or higher. In Xataface 1.2.4 you needed to provide users with the ''new'' permission rather than the ''register'' permission, which opens up a small security hole since users could potentially just use the "new" action if they new the URL and by-pass the registration and activation email altogether'''. Some notes on this example: * The isAdmin() function is not part of Xataface. It is used as a bit of *magic* here to reduce code. It is supposed to simply return true if the currently logged in user is an admin. Hence if the user is an admin, this method defers to the Application Delegate class's permissions (i.e. this method should not affect administrators). * We are giving all users (logged in or not) the register permission which enables them to register for an account on the system. * Generally you will want to restrict permissions on some of the fields in the users table. E.g. users should not be able to set their role or access level when they register. You can define more fine-grained permissions on these fields using the [[fieldname__permissions]] method of the users table delegate class (per the following example). ====Restricting Permissions on Particular Fields==== You probably don't want users to be able to set their access level when the register for an account, and your "users" table will quite often contain some field like "role" which stores this information. So the previous example is not quite realistic. You will also need to restrict permissions on the "role" field (and any other fields that you want to prevent users from setting themselves. <code> function role__permissions(&$record){ if ( isAdmin() ) return null; return Dataface_PermissionsTool::NO_ACCESS(); } </code> This will cut off the user's ability to set their own role when they register. You will likely want to set the default role value either in the mysql table definition or in the [[beforeInsert]] trigger. ===Email Validation=== As mentioned above, registration works by sending an activation email to the address specified in the user's registration. This email contains a link back to the ''activate'' action of your Xataface application, which will create the user account and log the user in. This implies that your ''users'' table must store an email address for your users. If you add a field named ''email'' to the ''users'' table, Xataface will assume that you mean to use this field as the user's email address, and thus, for email validation. However you can override this functionality and use *any* field as an email field by setting the ''email'' directive of the appropriate field in the [[fields.ini file]] for the ''users'' table. '''Example: Assigning the my_addr field of the users table to be used for email validation''': In the tables/users/fields.ini file: <code> [my_addr] email=1 </code> ====Disabling Email Validation==== 99% of the time, email validation is the preferred way of ensuring that people who register are who they say they are. You may, however, prefer to let users register directly without requiring the email activation step. You can disable email validation by overriding the ''register'' action in the [[actions.ini file]] as follows: In your application's [[actions.ini file]]: <code> [register > register] email_validation=0 </code> After setting this, the user account will automatically be created, and the user logged in upon saving the registration form. ===Triggers: Overriding Registration Workflow=== Xataface provides a number of triggers in the [[Application Delegate Class]] to override and extend the behavior of the user registration and activation process. For a list of available triggers see [[Application Delegate Class#registration]]. ===Preventing Spam with CAPTCHA=== One problem with enabling automatic registration is that it invites SPAM in the form of bots that can learn how to automatically register for user accounts and then leave unwanted input into your application. The Xataface [[reCAPTCHA module]] allows you to avoid these problems to some extent by forcing users who aren't logged in to fill a CAPTCHA field in order to successfully submit the form. This is especially helpful for registration forms. After installing the [[reCAPTCHA module]] the registration form will include a CAPTCHA field like the one depicted below: [[Image:http://media.weblite.ca/files/photos/Picture%2038.png?max_width=640]] For more information about the reCAPTCHA module [[reCAPTCHA module|click here]]. registration form, _auth, authentication en Relationship_Permissions 111 Relationship Permissions [[toc]] ==Synopsis== As relationships are a core feature of Xataface, it is helpful to understand how to handle permissions on related records. Even if you apply permissions to every table individually, you need to take into account the relationships that you have defined between tables, because they may open access to actions that you did not intend. For example, suppose we have two tables: ''people'' and ''publications'', and we have a relationship from ''publications'' table to the ''people'' table called ''publication_authors''. Suppose you give a user write access to a record of the publications table, but no access to the people table. If you are allowing the ''add new related record'' permission on the ''publications'' table record, then the user will still be able to add new people, via the "Add related people record" function of the database. This may or may not be desirable. This article discusses the issues that arise due to relationships and permissions, and how to deal with them. ==Relationship Permissions== The Xataface [[permissions.ini file]] defines a handful of permissions that are related to the management of related records. These include: {| class="listing listing2" |- ! Name ! Description ! Included in Roles |- | [[add new related record]] | Permission to add a new related record to a relationship. | EDIT, DELETE, OWNER, ADMIN, MANAGER |- | [[add existing related record]] | Permission to add an existing record to a relationship. | EDIT, DELETE, OWNER, ADMIN, MANAGER |- | [[remove related record]] | Permission to remove a record from a relationship. (This only allows removing a record from the relationship - not deleting the record from the database, so this is only really relevant in a many-to-many relationship). | EDIT, DELETE, OWNER, ADMIN, MANAGER |- | [[delete related record]] | Permission to delete a related record. This allows both removing the related record from the relationship, and deleting the record from the database. This permission is not included in any default roles. A combination of permission for [[remove related record]] in the source table and [[delete]] in the target table, are equivalent to access to this permission. Use this permission only when you need to override the ability to delete records from the database based on membership in a relationship. | - |- | [[view related records]] | Permission to view the records of a relationship. | READ ONLY, EDIT, DELETE, OWNER, ADMIN, MANAGER |- | [[related records feed]] | Permission to access the RSS feed of a relationship. | READ ONLY, EDIT, DELETE, OWNER, ADMIN, MANAGER |} ==Fine-grained, Per-relationship Permissions== You may often find that defining a flat set of permissions to all relationships on a record is insufficient for your purposes, because some relationships may demand different access levels than others. You can override the permissions for any particular relationship by implementing the [[rel_relationshipname__permissions]] method in the table's delegate class, where ''relationshipname'' is the name of the relationship. e.g. Consider the relationship ''manufacturers'': <code> function rel_manufacturers__permissions($record){ // $record is a Dataface_Record object return array( 'view related records' => 0 ); } </code> This will tell xataface that users should not be able to view related records on the ''manufacturers'' relationship. This will override any permissions that were defined in the [[getPermissions]] method. ==More Complete Example== In the following example, we design a products database. We use 2 relationships on our products table: One to keep track of the parts that are used in our product. The other to keep track of the users that are allowed to edit our products. We want to make it so that only the product owner can manage the editors for a product, but anyone in the product_editors relationship is allowed to edit the product or add/remove parts from the product. We don't want to give any users access directly to the parts, product_parts, or product_editors tables. We want all access to go through the relationships on the products table. ===Database/Relationship Design=== Consider a database with 4 tables: # products (product_id, product_name, owner_username) # parts (part_id, part_name) # product_parts (part_id, product_id) # product_editors (product_id, editor_username) # users (username, password, role) And we have the following relationships on the ''products'' table: <code> [parts] parts.part_id=product_parts.part_id product_parts.product_id="$product_id" [editors] product_editors.product_id="$product_id" </code> ===Application Permissions : Very Restrictive=== Like a good boyscout, we define our default permissions in the [[Application Delegate Class]] to be very restrictive: Don't let anyone do anything. <code> class conf_ApplicationDelegate { function getPermissions($record){ return Dataface_PermissionsTool::NO_ACCESS(); } } </code> ===Products Table Permissions: Less restrictive=== Now we open it up for our products table in the getPermissions() method of the products delegate class. In tables/products/products.php: <code> class tables_products { function getPermissions($record){ $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user and $record and $record->val('owner_username') == $user->val('username')){ // Give the record owner Edit permissions on the product return Dataface_PermissionsTool::getRolePermissions('EDIT'); } // Everybody else gets read only access to the products table. return Dataface_PermissionsTool::READ_ONLY(); } } </code> ===Checking if the current User is an Editor=== So far we have given the product owner edit permissions and everyone else read only permissions. We still need to allow editors to edit the product. In order to do this we need to be able to *efficiently* find out if the current user is an editor of a particular product. There are a few different ways to do this, but some are better than others. Some strategies include: # Perform an SQL query inside the [[getPermissions]] method to see if the user is an editor for the product. '''THIS IS VERY BAD!!!''' The [[getPermissions]] method should not include any IO or database queries because it is called a large number of times per request... making expensive calls in this method will slow down your app dramatically. # Create a function to load and cache all of the current user's products so that this can be easily checked at will. This is fine if the user is expected be able to edit only a few products. If he could be an editor for thousands of products, this may not be practical as it will cause you to have to load thousands of records into memory on every page request. # Use the [[__sql__]] method of the delegate class to create a grafted field on the ''products'' table indicating whether the current user is an editor for the product. This results in a very quick and accessible indicator variable that can be used in the [[getPermissions]] method to check to see if the current user is an editor for the current product. E.g. In the tables/products/products.php file (delegate class):<code> function __sql__(){ return sprintf("select p.*, pe.editor_username from products p left join product_editors pe on p.product_id=pe.product_id where pe.editor_username='%s'", addslashes( Dataface_AuthenticationTool::getInstance()->getLoggedInUsername() ) ); }</code> This will result in a situation where product records will have an additional field ''editor_username'' which will either be blank if the current user is not an editor for the product; or will contain the current user's username if they are an editor for the product. ===Table Permissions for Product Editors=== Now that we have a reliable way to tell, for any given product, whether the current user is, in fact, an editor, we can ammend the [[getPermissions]] method of the products table to include our editor permissions. <code> class tables_products { function getPermissions($record){ $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user and $record and $record->val('owner_username') == $user->val('username')){ // Give the record owner Edit permissions on the product return Dataface_PermissionsTool::getRolePermissions('EDIT'); } if ( $user and $record and $record->val('editor_username') == $user->val('username') ){ // If the user is an editor, we give them edit permissions // also return Dataface_PermissionsTool::getRolePermissions('EDIT'); } if ( $user ){ // Other logged in users have read only access $perms = Dataface_PermissionsTool::READ_ONLY(); $perms['new'] = 1; // We'll also let them add new products return $perms; } // Regular users just get the default permissions as // defined in the Application Delegate class return null; } } </code> ===Removing Editor Access to the Editor Relationship=== You'll notice that at this point, the product editor has exactly the same permission as the product owner. They both have permission to add and remove records from all relationships on the product. However, we don't want them to be able to access the editors relationship at all. We will use the [[rel_relationshipname__permissions]] method to override the permissions for the ''editors'' relationship. In the tables/products/products.php delegate class: <code> function rel_editors__permissions($record){ $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user and $record and $record->val('owner_username') == $user->val('username')){ // Owners should just get their normal permissions return null; } if ( $user and $record and $record->val('editor_username') == $user->val('username') ){ // If the user is an editor, we give them edit permissions // also return array( 'view related records' => 0, 'add new related record' => 0, 'add existing related record' => 0, 'remove related record' => 0, 'delete related record' => 0 ); } // Other users just get their normal permissions return null; } </code> ===Assigning product owner by default=== With the current permissions, something funny would happen. Users have permission to add new records, but once the record is added they won't be able to edit it because they are neither an editor nor the owner of the product. We'll fix this by assigning the current user as the product's owner using the [[beforeSave]] trigger in the products delegate class: <code> function beforeSave($record){ $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user ){ $record->setValue('owner_username', $user->val('username')); } } </code> ===Testing Out Our Solution=== In your testing of the solution, you should find the following: # Trying to access any table other than the ''products'' table should result in a ''permission denied'' error. # If you access the ''products'' table, you should be able to see a list of existing products, and the "Add New Record" action. # After you add a new product you should see that you are the product owner. # As a product owner you should see both the ''parts'' and ''editors'' tabs in your product record. You should be able to view and add new records to both of these relationships. # Add another user as an editor to your product, then log in as that user. You should be able to edit the product, but you shouldn't be able to see the ''editors'' tab for the product. ==See Also== * [[permissions.ini file]] - Overview of the Xataface permissions.ini file * [http://xataface.com/documentation/tutorial/getting_started/permissions Getting Started with Xataface Permissions] * [[How to granulate permissions on each field]] - Brief tutorial on how to set permissions on a field by field basis. * [[Delegate class methods]] - A list of all of the available delegate class methods that you can implement. Many of them pertain to permissions and triggers. * [[Application Delegate Class]] - Overview of the application delegate class. * [[relationships.ini file]] - The relationships.ini file directives. relationships, permissions, rel_relationshipname__permissions, getPermissions, permissions.ini en