_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 relationship 68 The relationship fields.ini directive [[fields.ini file|Return to fields.ini file directives]] [[toc]] ===Synopsis=== Certain types of widgets (e.g. grid (v1.0) and checkbox (v1.2)) support the relationship directive which allows them to effectively add/remove records from a specified relationship. This directive only works with transient fields. ===Example 1: Checkboxes to add/remove categories=== (Note: This example requires Xataface 1.2 or higher to work) Suppose we have a database that keeps track of courses and the branch of research that they belong to. A course can be part of multiple branches. We want to be able to select the branches that a particular course belongs to on the edit form for that course using checkboxes. Table Structure: <code> courses: course_id : int (primary key) course_title : varchar branches: branch_id : int (primary key) branch_name : varchar branch_description: text course_branches: course_id : int branch_id : int </code> Relationship definition: (from the tables/courses/[[relationships.ini file]]): <code> [branches] course_branches.course_id="$course_id" course_branches.branch_id=branches.branch_id </code> Field definitions: (from tables/courses/[[fields.ini file]]): <code> [branches] transient=1 relationship=branches widget:type=checkbox </code> Things to notice: # This is a many-to-many relationship (hence the need for the course_branches join table. # The [branches] field is a transient field. # The relationship directive from the [[fields.ini file]] references our branches relationship that was defined in the [[relationships.ini file]]. # You can call the field anything that you like. There is no need for it to have the same name as the relationship. It just turned out that way in this example. ===Example 2: Using a grid widget=== Let's modify example 1 slightly to use a grid widget instead of checkboxes. The grid widget will allow us edit the records in a relationship using dynamic table. It automatically uses the correct widget for each column of the table according to the definition in the target table's [[fields.ini file]]. Most of the definition can remain the same. We only change the [[fields.ini file]] directive: <code> [branches] transient=1 relationship=branches widget:type=grid widget:columns="branch_name,branch_description" </code> In this case we are able to edit the branch name and description in each row of the grid. ===See Also=== * [[grid|The grid widget]] * [[checkbox|The checkbox widget]] * [[relationships.ini file|The relationships.ini file]] * [[fields.ini file|The fields.ini file]] grid widget, relationship, checkbox en 0 Application_Delegate_Class 12 Application Delegate Class [[toc]] ===Synopsis=== The application delegate class is similar to the [[Delegate_class_methods|table_delegate_class]] except that it is applicable to the application as a whole, not just one table. It allows the developer to implement hooks that will be executed by Xataface to modify behavior. Examples of customizations that can be made with the Application Delegate class include: * Permissions * User Preferences * Custom content to be inserted into templates. * Triggers * more. ===Location=== The delegate class is optional and should be located in the conf/ApplicationDelegate.php file in the application directory. ===Example=== <code> <?php class conf_ApplicationDelegate { function getPermissions(&$record){ return Dataface_PermissionsTool::NO_ACCESS(); } } </code> ===Available Methods=== ====Triggers==== {| class="listing listing2" ! Name ! Description ! Version |- | after_action_activate | Trigger called after activation is complete. Activation occurs after a user registers and responds to the registration confirmation email. | 1.2.5 |- | after_action_login | Trigger called after a user logs in | 1.0 |- | after_action_logout | Trigger called after a user logs out | 1.0 |- | after_action_edit | Trigger called after the edit action completes. | 1.0 |- | after_action_new | Trigger called after new action completes. | 1.0 |- | after_action_delete | Trigger called after the delete action completes. | 1.0 |- | [[after_action_activate]] | Trigger called after successfully email validation (after registering). | 1.2 |- | [[before_authenticate]] | Trigger called just before authentication is carried out. This allows you to change the authentication type based on such things as SESSION variables etc... | 1.2.5 |- | [[beforeHandleRequest]] | Trigger called on each page request immediately before the action handler is called. This is handy if you need to perform some action on each page request, such as changing the default action depending on the logged in user. | 1.0 |- | [[loginFailed]] | Trigger called after a failed login attempt. Allows you to provide your own logging. | 2.0.1 |- | [[startSession]] | If implemented, this overrides how Xataface starts its sessions. If you implement this method, your custom method should at least include a call to [http://php.net/session_start session_start]. | 1.2.5 |} ====Preferences==== {| class="listing listing2" ! Name ! Description ! Version |- | getPreferences | Returns the user preference settings. | 0.6 |} ====Permissions==== {| class="listing listing2" ! Name ! Description ! Version |- | getPermissions | Returns the permissions available for a given record. | 0.6 |- | getRoles | Returns the roles allowed for a given record. | 1.0 |- | __field__permissions | Returns the default permissions for a field of a given record. | 1.0 |- | __field__roles | Returns the default roles for a field of a given record. | 1.0 |- | fieldname__permissions | Returns the permissions that are allowed for the field "fieldname" on a given record. | 0.7 |- | fieldname__roles | Returns the roles that are allowed for the field "fieldname" on a given record. | 1.0 |- | rel_relationshipname__permissions | Returns the permissions pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |- | rel_relationshiopname__roles | Returns the role or roles pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |} See [[permissions]] for more information about Xataface's permissions architecture and how to implement custom application permissions. <nowiki><a name="registration"></a></nowiki> ====Registration==== {| class="listing listing2" ! Name ! Description ! Version |- | [[beforeRegister]] | Trigger called before the user registration form is saved. | 1.0 |- | [[afterRegister]] | Trigger called after registration form is saved. | 1.0 |- | [[validateRegistrationForm]] | Validates the input into the registration form. | 1.0 |- | [[sendRegistrationActivationEmail]] | Overrides the sending of the registration activation email. | 1.0 |- | [[getRegistrationActivationEmailInfo]] | Overrides the activation email info. Returns an associative array of the email details (e.g. subject, to, headers, etc... | 1.0 |- | [[getRegistrationActivationEmailSubject]] | Returns the subject of the activation email. | 1.0 |- | [[getRegistrationActivationEmailMessage]] | Returns the message body for the activation email. | 1.0 |- | [[getRegistrationActivationEmailParameters]] | Returns the parameters for the actication email. | 1.0 |- | [[getRegistrationActivationEmailHeaders]] | Returns the headers for the activation email. | 1.0 |- | [[after_action_activate]] | Trigger fired after activation is complete. | 1.2 |} See [[registration form]] for more information about Xataface's registration system and how to allow users to register for an account on your application. <nowiki><a name="password-reset"></a></nowiki> ====Forgot Password==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getPasswordChangedEmailInfo]] | 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. | 1.3 |- | [[getResetPasswordEmailInfo]] | Optional method to define the settings for the email that is sent when a user requests to reset their password. This step comes before the password changed email as first the user requests a password reset and receives this email. Then they click a link in this email to reset the password upon which time they receive a second email containing their temporary password. That email is generated by the [[getPasswordChangedEmailInfo]] method if defined. If this method is not defined then a generic email predefined in Xataface will be sent instead. | 1.3 |} ====RSS Feed Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getFeedItem]] | For RSS Feeds, overrides the defaults and returns an associative array with feed elements for a particular record | 1.0 |- | [[getFeed]] | For RSS feeds, overrides the default feed for a query, returning an array of feed items. | 1.0 |- | getFeedSource | Overrides the default feed source parameter for an RSS feed. | 1.0 |- | [[getRelatedFeed]] | For RSS feeds, overrides the default feed for a related feed. | 1.0 |- | getRSSDescription | Overrides the default generated RSS description for a record. | 1.0 |} ====Template Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[block__blockname]] | Outputs content that is meant to override a slot or a block named "blockname". | 0.6 |- | [[getNavItem]] | Overrides the navigation menu item for a particular table. | 1.3 |- | [[navItemIsSelected]] | Overrides the "selected" setting for nav menu items. This is used by the default implementation of [[getNavItem]]. | 1.3 |- | [[getTemplateContext]] | Returns an associative array of variables that should be made available to all templates. | 1.0 |} ====Output Cache Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getOutputCacheUserId]] | Returns a unique user id that is used by the output cache to ensure that different users don't use the same cached page (unless appropriate). This is generally not necessary as the output cache by default uses a different cache for each user... but in some cases you may want to use a different cache for the same user. | 2.0 |} ====Valuelist Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[valuelist__valuelistname]] | Defines a valuelist named ''valuelistname''. | 0.7 |} application delegate class en 0 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 Contribute_to_Xataface_Translation_Project 110 How to Contribute Translations [[toc]] ==Synopsis== Xataface stores its translations in INI files in its lang directory, one for each language. You can develop your own translation by first copying the en.ini file to xx.ini (where xx is the ISO language code for the language you are translating for), then modifying the translations into your target language. '''NOTE: THIS IS NOT THE PREFERRED WAY TO CONTRIBUTE TRANSLATIONS. PLEASE SEE "Adding Translations Using Google Spreadsheets" BELOW'''. ==Anatomy of a Language .INI file== The language .INI files (e.g. en.ini, es.ini, etc...) consist of key-value pairs, where the key is a unique identifier for a string in Xataface, and the value is the translation. All language files should contain the same keys, however if you omit a key from your translation, Xataface will just fall back to the default value that is defined in the PHP source code. ===Example Snippet from en.ini file=== <code> scripts.GLOBAL.FORMS.OPTION_PLEASE_SELECT = "Please Select ..." save_button_label = "Save" scripts.GLOBAL.MESSAGE.PERMISSION_DENIED = "Permission Denied" scripts.GLOBAL.NO_RECORDS_MATCHED_REQUEST = "No records matched your request." </code> In this small segment you can see 4 strings that are translated. The values on the left of the equals sign are the keys. Their corresponding values are on the right of the equals signs. A corresponding segment of the fr.ini (French) language file looks like: <code> scripts.GLOBAL.FORMS.OPTION_PLEASE_SELECT = "SVP sélectionnez ..." save_button_label = "Enregistrer" scripts.GLOBAL.MESSAGE.PERMISSION_DENIED = "Permission Refusée" scripts.GLOBAL.NO_RECORDS_MATCHED_REQUEST = "Aucun résultat ne correspond à votre requête." </code> You can see that the keys (the values on the left) are identical to those in the en.ini snippet. Only the values are changed (translated) into French. '''NOTE: IT IS BETTER TO USE GOOGLE SPREADSHEETS TO EDIT TRANSLATIONS, THAN TO WORK WITH INI FILES DIRECTLY. PLEASE SEE "Adding Translations Using Google Spreadsheets" BELOW''' ==Gotchas: Things to watch out for== When editing or adding translations in INI files, you need to be aware of a few gotchas related to how INI files work. If you mess up a line by forgetting to add a quote, you could cause a parse error which would cause Xataface to ignore the language file altogether. The following are a few common pitfalls: ===Use UTF-8 Encoding=== All ini files should use UTF-8 encoding, so make sure you are using a text editor that supports UTF-8 if you want to edit INI files. (But it is better to just use Google Spreadsheets for the editing if possible, in which case you don't have to worry about this). ===Wrap Translations in Double Quotes=== All translations should be wrapped in double quotes. E.g. <code> mykey="My Value" </code> If you forget to close a quote, it will likely cause a parse error and Xataface will fail to load the file. E.g. <code> mykey="My Value </code> would be a problem. ===Can't Use Double Quotes as Part of the Translation=== Since INI files use double quotes to wrap strings, you can't use a double quote inside your translation. E.g. you can't do this: <code> mylink="<a href="http://google.com">Google</a>" </code> because of the inline double quotes. One way around this is to try to use single quotes where possible. E.g. <code> mylink="<a href='http://google.com'>Google</a>" </code> Another way around this is to the ''"_Q"'' key sequence, which Xataface will automatically convert to a double quote for you at runtime. E.g. You could do: <code> mylink="<a href="_Q"http://google.com"_Q">Google</a>" </code> '''NOTE: If you use Google Spreadsheets to edit your translations, you won't have this problem. You can use double quotes inside your translations. The [[csv2ini]] tool will automatically convert these to an appropriate form when the spreadsheet is converted to the INI files.''' ===Leave Variables Alone=== Some translated strings include variables that are meant to be replaced by Xataface at runtime. These should be left intact across translations. You can identify a variable by their resemblance to PHP variables (prefixed with a $). E.g. In the en.ini file, the translation: <code> No action found = "No action found named '$name'" </code> has the variable ''$name''. So the French translation should maintain this variable. E.g. in the fr.ini file: <code> No action found = "Aucune action nommée '$name'" </code> ==Adding Translations Using Google Spreadsheets== In order to help keep translations more up to date, we have developed a set of tools to enable us to use Google Spreadsheets to edit and add translations, and convert these spreadsheets on demand into an appropriate set of language INI files. The spreadsheet containing the Xataface translations is public to view and is located [https://spreadsheets.google.com/ccc?key=0AqJNZUI7flxSdFVLWDlnVVpQZ3dMaGZhVjVHN2c3bEE&hl=en here]. If you would like to add your own translations or modify existing translations, please contact [mailto:steve@weblite.ca Steve Hannah] so that you can be given editor permission. You will first need a google docs account, then we can give you permission to edit the spreadsheet. This centralized spreadsheet is converted to INI files and merged into SVN before every release. You can also export this spreadsheet as a CSV and convert it to Xataface's language INI files yourself using the [[csv2ini]] tool that is located in the tools directory of the Xataface distribution. ===Gotchas with Google Spreadsheets=== Editing translations with Google Spreadsheets is much safer than editing the INI files directly. You don't have to worry about encoding issues, and you don't have to dance around double quotes like you do with INI files. There is only one known thing to watch out for: ====Starting a translation with a Single Quote==== If you start a translation with a single quote, Google Spreadsheets will interpret this as a directive to indicate that the contents of that cell should be considered a string (and not a number for example). E.g. If you enter the following into a Google Spreadsheets cell: <code> 'Help!', I exclaimed </code> If you unfocus from that cell it will only say: <code> Help!', I exclaimed </code> If you go back into edit mode of the cell again, you'll see your opening single quote again... and when you tab out, it will disappear again. You can work around this issue by just using two single-quotes for the first quote. E.g.: <code> ''Help!', I exclaimed </code> This way Google will interpret the first quote as a directive, and it will use the second one as an actual single quote. ====Converting the Google Translation Spreadsheet into INI Files==== So you've contributed a number of translations to the [https://spreadsheets.google.com/ccc?key=0AqJNZUI7flxSdFVLWDlnVVpQZ3dMaGZhVjVHN2c3bEE&hl=en Xataface Translations Google Spreadsheet], and you want to be able to use them in your installation of Xataface before the next release. Just follow the steps below: # Download the spreadsheet as a CSV file, using the ''File'' > ''Download as'' > ''CSV (Current Sheet)'' menu item in Google Spreadsheets. # Run the [[csv2ini]] PHP script located in the xataface/tools directory to convert the xataface-translations.csv file that you downloaded from Google Spreadsheets in the previous step into INI files. The conversion command looks like: <code> $ php /path/to/xataface/tools/csv2ini.php /path/to/xataface-translations.csv /path/to/destination/dir/ </code> This will convert the xataface-translations.csv file into a set of language INI files and place them the specified destination directory (don't forget the trailing slash) on /destination/dir so that the script knows its a directory. You can then copy these INI files into your xataface/lang directory to make them live. '''Note: the [[csv2ini]] script has only been used in a unix/os x type environment. Some small modifications would probably be necessary to make them work on Windows.''' Translations, Google Spreadsheets, en.ini, fr.ini en Module_Developers_Guide 112 Module Developers Guide [[toc]] ==Why Write a Xataface Module?== Xataface modules are components that can be used to extend Xataface's functionality in a generic way so that it can be used on multiple applications. If you find yourself trying to add the same functionality in multiple applications, you might consider writing a Xataface module so that you can share the functionality more easily. ==What can you do with a Xataface Module== * Create custom authentication handlers. * Provide custom actions and templates. * Implement blocks and slots for existing templates. * Respond to certain application triggers. ==Where do I place a Xataface Module?== Xataface modules can be placed in the xataface/modules directory (i.e. DATAFACE_PATH/modules). As of Xataface 1.3 they can also be placed directly in your application's modules directory (i.e. DATAFACE_SITE_PATH/modules). ==Your first module== For our first module, we're going to create a simple module that adds "hello world" at the beginning of every page. ===Step 1: Create the Module Class=== In your modules directory, create a directory called "Hello". And in this directory, create a file named "Hello.php", with the following contents: <code> <?php class modules_Hello { } </code> (So this file would be located at DATAFACE_PATH/modules/Hello/Hello.php) ===Step 2: Implement the block__before_body method=== We are going to add the phrase "hello world" before every page of our application. The easy way to do this is to fill the [[before_body]] slot of the [[Dataface_Main_Template.html]] template. We do this by implementing the ''block__before_body'' method in your module (just as we would if we were trying to fill this slot from the [[Application Delegate Class]]. <code> <?php class modules_Hello { function block__before_body(){ echo "hello world"; return true; } } </code> ===Step 3: Activate the Module=== Xataface only loads the modules that have been enabled in the conf.ini. We can enable our module by adding the following section to the [[conf.ini file]]: <code> [_modules] modules_Hello=modules/Hello.php </code> All this does is tell Xataface that the module class modules_Hello can be loaded from the location modules/Hello.php. Now if you start up your application, you should see the phrase "hello world" written at the top of each page. ==Example 2: Adding a Custom Action== Our first module shows an example of filling blocks and slots using a module. Let's now extends that to include a custom action that displays Hello World on its own page. Complete the following steps: # Add an ''actions'' directory inside our new module directory. i.e. modules/Hello/actions # Add a file named hello.php inside the ''actions'' directory with the following contents:<code> <?php class actions_hello { function handle($params){ echo "Hello World"; } } </code> # Go to index.php?-action=hello To see the results of your action. It should say "Hello World" on a blank page. From here on you can improve this action just as you would if you defined the action inside the application's actions directory. You can go on to restrict access to this action using permissions, or you could decide to use a template to display the action. ===Defining a Custom "hello" permission for our action=== Perhaps we want to create a special permission for our action so that regular users won't have access to this action unless they are specifically granted this permission. Let's create a "hello" permission with which to limit access to our action. # Create a file named "permissions.ini" inside your modules/Hello directory with the following contents:<code> hello = Permission to access the hello action </code> Now if you try to access your action (and you haven't been assigned ALL() permissions) you should receive either a login prompt or a permission denied message. If you want users to be able to access your action, you will need to explicitly add this permission to one of the user's assigned roles or return it as part of the list of authorized permissions in the getPermissions() method. ===Granting the "hello" permission to the "READ ONLY" role=== If we want the default READ ONLY role to have access to the "hello" permission we can actually modify the READ ONLY role inside the [[permissions.ini file]] that we created inside the Hello module: <code> hello = Permission to access hello action [READ ONLY extends READ ONLY] hello=1 </code> ==Example 3: Using Module Templates== Xataface, by default, stores its templates in the DATAFACE_SITE_PATH/templates and DATAFACE_PATH/templates directories. However if you are writing a module you probably want to keep templates that are used by the module inside the module directory so that you don't break dependencies when you use the module in different applications. You can use the [http://dataface.weblite.ca/df_register_skin df_register_skin] method to register additional directories for Xataface to look for templates in. This will allow you to add a ''templates'' directory inside your module directory for use by your module's templates. It is probably best to register this directory on demand (i.e. as part of individual actions) rather than register it globally. ===Using a Template from the hello action=== Let's modify our hello action to use a template that we are going to store and distribute with our module. # Create a directory named "templates" in the modules/Hello directory. # Create a file named "hello.html" inside the templates directory with the following contents:<code> {use_macro file="Dataface_Main_Template.html"} {fill_slot name="main_section"} Hello World {/fill_slot} {/use_macro} </code> Notice that we are extending the Dataface_Main_Template.html template (which is located in the main Xataface install) so that our hello action can now take on the look and feel of the rest of the application. # Modify the modules/Hello/actions/hello.php file to look like this:<code><?php class actions_hello { function handle($params){ df_register_skin('hello theme', dirname(__FILE__).'../templates'); df_display(array(), 'hello.html'); } } </code> Notice that we call the df_register_skin function to register the templates directory that we created in the previous step. Then we call df_display() to display the template. ==See Also=== * [[modules]] - A list of existing Xataface modules that you can download and install. * [[block__blockname]] - A list of some of the available blocks that can be filled in the default Xataface templates. * [http://xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Customizing Xataface's Look and Feel with Templates] - A tutorial on how to use Xataface's built-in smarty template engine. It has some sections on using delegate classes to override blocks and slots. * [http://xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing Xataface's Look and Feel] - Part of the Getting Started tutorial that shows how to use slots and blocks to customize the Xataface look and feel. modules en LDAP_or_Active_Directory 65 How to authenticate users with LDAP or Active Directory [[toc]] It is often easier to use the existing LDAP or Active Directory to authenticate users in Xataface than to create a new password for every user in the table users. ===In the conf.ini=== In the conf.ini file, in the [auth] part, you need to add your LDAP or AD configuration data : <code>[_auth] auth_type=ldap users_table = xata_users username_column = id ldap_host = "xxx.xxx.xxx.xxx" ldap_port = "389" ldap_base = "OU=blabla,DC=blablabla"</code> Here in the table users, you need the login but the password can be just ''PASS'', because the password will be fetched into the LDAP base. You need to add the [http://weblite.ca/svn/dataface/modules/Auth/ldap/trunk/ auth module] in the conf/modules directory. ===See Also=== * [[authentication]] - Overview of Authenthentication features in Xataface LDAP,Active Directory,Authentication en 0 field__pullValue 104 field__pullValue delegate class method [[toc]] The field__pullValue() delegate class method can be used to transform database from the database for use in an edit/new record form. Sometimes it is the case that we want users to be able to work with data differently than it is stored in the database. This method should always be accompanied by a corresponding [[field__pushValue]] method which performs the inverse operation and is used to transform the value in an edit form into a format that can be stored in the database. ===Example=== Given a field ''start_ip'' that stores an IP address in the database as an unsigned INT, we want to be able to work with the data on the edit form in a friendlier format - the standard IP address dot notation, so we define pullValue and pushValue methods for the field in the table's delegate class. <code> 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; } } </code> ==References== * [[Delegate class methods]] * [[Application Delegate Class]] * [[http://dataface.weblite.ca/Dataface_Record Dataface_Record API docs] * [http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields] - A how-to document. pushValue, pullValue en field__pushValue 105 [[toc]] The field__pushValue() delegate class method can be used to transform a field value as entered in the edit form into a format that can be stored in the database.. Sometimes it is the case that we want users to be able to work with data differently than it is stored in the database. This method should always be accompanied by a corresponding [[field__pullValue]] method which performs the inverse operation and is used to transform the value in the database into a format that can be edited in the edit form. ===Example=== Given a field ''start_ip'' that stores an IP address in the database as an unsigned INT, we want to be able to work with the data on the edit form in a friendlier format - the standard IP address dot notation, so we define pullValue and pushValue methods for the field in the table's delegate class. <code> 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; } } </code> ==References== * [[Delegate class methods]] * [[Application Delegate Class]] * [[http://dataface.weblite.ca/Dataface_Record Dataface_Record API docs] * [http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields] - A how-to document. pullValue, pushValue en loginFailed 184 loginFailed() Application Delegate Trigger [[toc]] The loginFailed() method of the Application Delegate class is executed after a failed login attempt. '''Available since 2.0.1''' ==Example== <code> function loginFailed($username, $userIp, $time){ error_log("Failed login for username: $username at IP $userIp at time $time"); } </code> login permissions failed password en XataJax 113 Introduction to XataJax [[toc]] Xataface 1.3 comes with a new module [[XataJax]] which comes installed standard. [[XataJax]] serves as a foundation for Javascript/AJAX powered Xataface applications and will hopefully usher in a new fresh generation of Xataface powered applications. ===Features=== Xataface provides pieces of infrastructure: # [[XataJax Compiler|A Javascript/CSS Compiler & Linker]] # A Javascript component library & API ====The Javascript/CSS Compiler & Linker==== Web 2.0 and HTML 5 is a great platform for application development, but it presents a challenge when it comes to developing large-scale, robust applications. It can be difficult to manage applications that consist of dozens or even hundrends of javascript libraries, some of which depend on each other. The XataJax compiler provides a solution to this problem by providing a just-in-time compilation of all of the javascripts that are necessary to service a particular request. It doesn't actually compile your Javascript into machine code, it just aggregates and minifies all of the javascript code together into a single file at runtime so that you don't have to worry about figuring out exactly which libraries you need to import in each template. This has 2 key benefits: 1. Load time. By having all of the scripts grouped into a single file, it is much quicker for the client to load the your scripts. 2. Code organization. Since the compiler will automatically resolve the script dependencies, you can keep your code nicely organized, which produces a far more maintainable source code base. ====The Javascript Component Library & API==== The 2nd part of the XataJax module is a new API that will help you develop rich Web 2.0 applications that interact with your database. The will allow you to build forms more dyanmically with Javascript, or load, update, and delete records directly using a javascript API. The goal is to eventually expose all important Xataface functionality via the XataJax API. Additional modules may build on top of this API to produce alternative dynamic interfaces for Xataface using existing web UI component libraries like JQueryUI or Sencha. XataJax, Ajax, Web 2.0 en modules 30 Xataface Modules [[toc]] Xataface provides a number of hooks that allow developers to create modules to extend its functionality. This page lists a handful of the currently available modules. * [[ShoppingCart|Shopping Cart]] - Converts your application into a shopping cart. * [[Filemaker]] - Export record sets as Filemaker XML. * [[DataGrid|Data Grid]] - Editable Datagrid. * [[Email]] - Convert your database into a email list. Send email to any found set. * [[reCAPTCHA module]] - A reCAPTCHA module to add CAPTCHA support to your Xataface forms. * [[XataJax]] - Platform for building Web 2.0 AJAX applications with Xataface. Will be a standard component for Xataface starting with version 1.3. ==Module Installation== You can add modules in either: # DATAFACE_PATH/modules directory (since 1.0) # DATAFACE_SITE_PATH/modules directory (since 1.3) Modules in the DATAFACE_SITE_PATH directory will supersede modules in the DATAFACE_PATH/modules directory (since 1.3). To activate a module for your application you also need to add an entry to the [[_modules]] section of your [[conf.ini file]]. Each module will come with its own installation instructions. ==Authentication Modules== Modules to add alternative authentication methods are added to the modules/Auth directory. ==Developing Your Own Modules== See [[Module Developers Guide]]. modules, captcha en 0