calendar 100 Calendar Widget Back to [[widget:type]] [[toc]] ===Synopsis=== The calendar widget is the default widget for editing date and datetime fields. It is javascript pop-up calendar that allows users to select date and time visually. It can be configured to allow different date and time formats, themes, starting days of the week, and more. [[image:http://media.weblite.ca/files/photos/calendar_widget.png?max_width=400]] ===Usage=== For DATE and DATETIME fields, the calendar widget is the default widget used, so you need not specify it explicitly in the fields.ini file. For other types of fields you may designate them to use the calendar widget in the [[fields.ini file]] as follows: <code> [my_field] widget:type=calendar </code> ===Configuration Options=== The calendar widget supports some configuration options that can be set in the [[fields.ini file]]. These options are as follows: {| class="listing listing2" |- ! Name ! Description ! Default ! Version |- | [[widget:lang]] | The language to use for the calendar. This is a 2-digit ISO language code. | en | 0.5.3 |- | [[widget:theme]] | The theme to use for the calendar. It only ships with one theme at present. | calendar-win2k-2 | 0.5.3 |- | [[widget:firstDay]] | The first day of the week (e.g. Monday=1) | 1 | 0.5.3 |- | [[widget:showsTime]] | Boolean value indicating whether the calendar should show the time as well. | 0 for DATE fields, 1 for DATETIME fields. | 0.5.3 |- | [[widget:ifFormat]] | The input format of the date. This takes a formatting string as supported by [http://ca2.php.net/strftime the strftime function]. | %Y-%m-%d %I:%M %P | 0.5.3 |- | [[widget:timeFormat]] | Whether to use 12 hour or 24 hour time format. | 12 | 0.5.3 |} ===Examples=== ====Setting the time to use 24 hour format==== In your [[fields.ini file]]: <code> [my_field] wiget:type=calendar widget:timeFormat = 24 </code> ===See Also=== * [[date]] Widget - A widget for editing date and time using select drop-down lists. * [[time]] Widget - A widget for selecting time from a set of possibilities in a single select list. calendar widget, fields.ini file, widget:type en Introduction_to_the_Xataface_API 101 Introduction to the Xataface API Back to [http://xataface.com/wiki the wiki] [[toc]] ===Synopsis=== Xataface is provides an API to help in developing your own custom actions. This API includes objects and functions to more easily interact with the database (i.e. search, edit, delete, and save records), build forms, use templates, and more. This section of the wiki endeavors to highlight some of the more useful and commonly used aspects of the API. ===The dataface-public-api.php Facade=== Much of the functionality provided by the Xataface API is wrapped up easy-to-use functions which are made available in the dataface-public-api.php script, which is always present in a Xataface application (it is loaded at the beginning of your index.php file). ===Some Common Tasks=== ====Loading a Single Record from the Database==== <code> // Load record from 'people' table matching person_id=10 $record = df_get_record('people', array('person_id'=>10)); // Load record from people table with first_name 'John' and last_name 'Smith' $record2 = df_get_record('people', array('first_name'=>'=John', 'last_name'=>'=Smith')); // $record and $record2 are Dataface_Record objects. echo "Loaded Person: ".$record->val('person_id'). " named ".$record->val('first_name').' '.$record->val('last_name'); </code> In the above examples we load a [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object and use the val() method to display particular field values. The 2nd arguments of df_get_record() is an array which serves as a query. See [[URL Conventions]] for more examples of the types of queries that you can provide here. ====Loading a set of records from the Database==== <code> // Load the first 30 canadians from the people table $people = df_get_records_array('people', array('nationality'=>'=canadian')); foreach ( $people as $person){ // $person is a Dataface_Record object echo "<br>Person ".$person->val('person_id')." is named ".$person->val('first_name'); } </code> '''Caveat: Note that when loading records using df_get_records_array() it only loads a preview of each record for memory's sake.''' A preview of the record is the same as a full record except that all fields are truncated to be less than 255 characters. If you have long text fields that you need to load, then these will be truncated. There are a few different solutions if you need to load the entire contents of a long field, including: * Use df_get_record instead. (This is only preferable if you are only loading a single record). * Use the [[struct]] [[fields.ini file]] directive on the field to designative the field contents as a 'stucture' that should never be truncated. * Use the extended form of ''df_get_records_array()'' with the 5th parameter (preview) set to false. E.g. <code> $people = df_get_records_array('people',array(), null, null, false); </code> ====Editing and Saving a Record==== <code> $person = df_get_record('people', array('person_id'=>10)); // Using setValue() to set a single field value. $person->setValue('first_name', 'Peggy'); // Using setValues() to set multiple field values at once $person->setValues(array('first_name'=>'Peggy', 'last_name'=>'Sue')); // Commit the changes to the database $person->save(); </code> xataface api, df_get_record, df_get_records_array, Dataface_Record, Editing, Saving, Loading, Searching en before_authenticate 102 before_authenticate hook Return to [[Application Delegate Class]] The '''before_authenticate''' hook is a method that can be defined in the [[Application Delegate Class]] which is called before the authentication step occurs on '''every''' request (not just on login). It is meant to be used to perform custom code that may affect the authentication settings. ===Since=== This hook has been available since Xataface Version 1.2.5. ===Example=== <code> /** * Implemented trigger to be called before authentication to set the authentication * type to basic. */ function before_authenticate(){ $auth = Dataface_AuthenticationTool::getInstance(); if ( @$_SESSION['-login-type'] == 'basic' ) $auth->setAuthType('basic'); } </code> In the above example we used a separate action to store the user's preferred login type in a session variable. This preference is then applied in the before_authenticate method to override the authentication type. ===Chain Authentication Support=== The most common use of this hook is likely to implement some sort of chain authentication, where authentication methods are attempted until one succeeds. ===See Also=== * [[Application Delegate Class]] * [[authentication]] - Overview of Xataface authentication * [[Writing Custom Authentication Plugins]] * [[Authenticating Against the PHPBB Users Table]] * [[LDAP or Active Directory]] - Using LDAP or Active Directory for authentication. * [http://xataface.com/documentation/tutorial/getting_started/permissions Permissions Section of the Getting Started tutorial] * [[_auth]] - Directives available in the [[_auth]] section of the [[conf.ini file]]. authentication 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 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 __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 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 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 beforeSave 109 beforeSave Trigger Back to [[Delegate class methods]] [[toc]] ===Synopsis=== The beforeSave trigger can be implemented in any table's [[delegate class|Delegate Class Methods]] to perform functionality that should be run *before* a record of that table is saved. This is a useful place to insert additional field values depending on the input of the save record form. This method is called both when records are inserted and when existing records are updated. Some other triggers include [[beforeInsert]], [[beforeUpdate]], [[afterSave]], [[afterInsert]], and [[afterUpdate]], which do what you might expect. ===Method Signature=== <code>function beforeSave( Dataface_Record $record);</code> ====Parameters==== # '''$record''' - The record that is about to be saved. This is a [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object. ====Returns==== # [http://dataface.weblite.ca/Dataface_Error Dataface_Error] on failure (if you want to cancel the save). ===Examples=== Given a table named "people", suppose we wanted to automatically populate a field named "full_name" with the concatenation of the "first_name" and "last_name" fields. (Note you could also achieve a similar thing by making a calculated field for "full_name", but for this example, we assume that we actually want to store this in the database. We create a beforeSave() trigger that automatically updates the "full_name" field every time the record is saved. In the "people" table delegate class (i.e. tables/people/people.php) <code> class tables_people { function beforeSave($record){ $record->setValue('full_name', $record->val('first_name').' '.$record->val('last_name') ); } } </code> ==See Also== * [http://www.xataface.com/documentation/tutorial/getting_started/triggers Triggers section of the Xataface Getting Started Tutorial] triggers, beforeSave, 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 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 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 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 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 Using_RecordGrid 115 Using RecordGrid ==Xataface RecordGrid Class and Template== Also see [http://lamp.weblite.ca/dataface-0.6/docs/index.php?-table=Classes&-action=browse&ClassID=30| RecordGrid in the API Doc]. [[toc collapse=0]] ===Introduction=== As we learned in '''[http://xataface.com/documentation/tutorial/getting_started/dataface_actions Actions I: The Basics]''', we can retrieve custom data from the DB in action via queries. This site deals with showing data in tabular form, like it could be received from even such a query. It is done by using Dataface_RecordGrid. ===First Example=== <code> class actions_testTableAction { // Will be called from Xataface, if this action is called function handle(&$params){ $this->app =& Dataface_Application::getInstance(); // reference to Dataface_Application object // Custom query $result = mysql_query("select * from testTable", $this->app->db()); $body = "<br /><br />"; if(!$result) { // Error handling $body .= "MySQL Error ..."; }else { while($row = mysql_fetch_assoc($result)) // Fetch all rows { // Maybe do something with the single rows $data[] = $row; // Add singe row to the data } mysql_free_result($result); // Frees the result after finnished using it $grid = new Dataface_RecordGrid($data); // Create new RecordGrid with the data $body .= $grid->toHTML(); // Get the HTML of the RecordGrid } // Shows the content (RecordGrid or error message) in the Main Template df_display(array('body' => $body), 'Dataface_Main_Template.html'); } } </code> You get your data from the query, fetch it into an associative array, create with it an RecordGrid and use the toHTML function. This is sure better than manually create the html tags around the data. =====Screenshot: Blank RecordGrid===== <nowiki> <img src="http://i89.photobucket.com/albums/k234/horchr/xataface/RecordGrid_blank.png?max_width=610"/> </nowiki> =====Screenshot: ResultList===== <nowiki> <img src="http://i89.photobucket.com/albums/k234/horchr/xataface/RecordList.png?max_width=713"/> </nowiki> ===Colored Example=== As you see above, the resultlist has colored rows, our First Example not. But you can easily change this, when you override the Dataface_RecordGrid.html template: <code> <table id="{$id}" class="listing {$class}"> <thead> <tr> {foreach from=$labels item=label} <th>{$label}</th> {/foreach} </tr> </thead> <tbody> {section name=row loop=$data} <tr class="listing {cycle values="odd,even"}"> {foreach from=$columns item=col} <td>{$data[row][$col]}</td> {/foreach} </tr> {/section} </tbody> </table> </code> The magic happens in <tr class="listing {cycle values="odd,even"}"> The {cycle values="odd,even"} value cycles these two values and creates so the alternating row classes, like they are in the RecordList. By the way, {cycle ...} is a Smarty Function, see [http://www.smarty.net/docsv2/en/language.custom.functions.tpl| Smarty Doc]. (Find fruther information to template overriding in the tutorial and its links: [http://xataface.com/documentation/tutorial/getting_started/changing-look-and-feel| Changing the Look and Feel]) =====Screenshot: colored RecordGrid===== <nowiki> <img src="http://i89.photobucket.com/albums/k234/horchr/xataface/RecordGrid_colored.png?max_width=610"/> </nowiki> ===Example completly imitating ResultList=== The Colored Example doesn't look like the ResulList? Its rows aren't as high as theres? That's a styling matter or rather in this case a cause of the checkboxes. Here an example with checkboxes and added (empty) links, so it looks completly like the ResultList: Change the part in action.php <code> while($row = mysql_fetch_assoc($result)) // Fetch all rows { // Maybe do something with the single rows $row['<input type="checkbox">'] = '<input type="checkbox">'; $data[] = $row; // Add singe row to the data } mysql_free_result($result); // Frees the result after finnished using it $grid = new Dataface_RecordGrid($data, // Create new RecordGrid with the data array('<input type="checkbox">', 'testID', 'name', 'description', 'number'), //Order and selection of the colums null); // No other labels defined -> it uses keys of the associative array $body .= $grid->toHTML(); // Get the HTML of the RecordGrid </code> Dataface_RecordGrid.html template <code> <table id="{$id}" class="listing {$class}"> <thead> <tr> {foreach from=$labels item=label} <th><a class="unmarked_link">{$label}</a></th> {/foreach} </tr> </thead> <tbody> {section name=row loop=$data} <tr class="listing {cycle values="odd,even"}"> {foreach from=$columns item=col} <td><a class="unmarked_link">{$data[row][$col]}</a></td> {/foreach} </tr> {/section} </tbody> </table> </code> =====Screenshot: RecordGrid completly imitating ResultList===== <nowiki> <img src="http://i89.photobucket.com/albums/k234/horchr/xataface/RecordGrid_colored_checkboxes_links.png?max_width=610"/> </nowiki> =====Screenshot: ResultList===== <nowiki> <img src="http://i89.photobucket.com/albums/k234/horchr/xataface/RecordList.png?max_width=713"/> </nowiki> ===Try it out=== Use the following code with static test data and any template in this article (or even without overriding it) to try it out. <code> class actions_testTableAction { // Will be called from Xataface, if this action is called function handle(&$params){ $this->app =& Dataface_Application::getInstance(); // reference to Dataface_Application object $result_dummy = array( array('testID' => '1', 'name' => 'testname', 'description' => 'a short description', 'number' => '258'), array('testID' => '2', 'name' => 'another name', 'description' => 'a bit longer description to this data set', 'number' => '946'), array('testID' => '3', 'name' => 'dummy name', 'description' => 'yea, a dummy data set!', 'number' => '1342'), array('testID' => '4', 'name' => 'not empty', 'description' => 'this data set isn\'t empty ...', 'number' => '282'), array('testID' => '5', 'name' => 'your entry', 'description' => 'this entry is only for you', 'number' => '79'), array('testID' => '6', 'name' => 'no idea', 'description' => 'running out of ideas ...', 'number' => '203'), array('testID' => '7', 'name' => 'the last one', 'description' => 'the end', 'number' => '26841') ); $body = "<br /><br />"; foreach($result_dummy as $row) // Fetch all rows { // Maybe do something with the singe rows $row['<input type="checkbox">'] = '<input type="checkbox">'; $data[] = $row; // Add singe row to the data } $grid = new Dataface_RecordGrid($data, // Create new RecordGrid with the data array('<input type="checkbox">', 'testID', 'name', 'description', 'number'), //Order and selection of the colums null); // No other labels defined -> it uses keys of the associative array $body .= $grid->toHTML(); // Get the HTML of the RecordGrid // Shows the content (RecordGrid or error message) in the Main Template df_display(array('body' => $body), 'Dataface_Main_Template.html'); } } </code> RecordGrid, Dataface_RecordGrid, data in tabular form 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 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 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 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 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 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 init 140 init() Delegate Class Method == Synopsis == This method is called once, just after the table is loaded for the first time. It allows you to specify initialization details, such as [[setSecurityFilters|security filters]]. Note that it takes a single parameter: a Dataface_Table object of the table that is being initialized. == Example == <code> function init(&$table){ .... } </code> 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 Grafted_fields 158 Grafted fields ==Grafted Fields== ===Introduction=== When there are numerous tables, it is difficult for the user to see get an information that will help one to enter the right data in the right field. So instead of navigating in the relative tables and lose some time, it is more convenient to add a grafted field from that relative table in the table. To be able to sort a column by the content displayed when this content is extracted form a relative table, a grafted field is necessary because the real content is just an id, not the most convenient to sort in human-readable way. ===Procedure=== Two ways to add a grafted filed * The first one is to add a __sql__ statement at the beginning of fields.ini, including the grafted field through a join. <code>__sql__ = "select p.*, d.total from programmation p left join dev d on p.id_programmation=d.id_programmation" </code> * The second one is to create the function __sql__ in the delegate class <code>function __sql__(){ return "select p.*, d.total from programmation p left join dev d on p.id_programmation=d.id_programmation"; } </code> ===Sorting order based on relationship=== The solution is to hide the field with the id and to add the grafted field with the name in the fields.ini <code>[name_programmation] order=10 [id_programmation] visibility:list=hidden </code> ===Debugging=== A couple of things to check for: *1. If you have set blanket default permissions for your fields using the __field__permissions() method you could be disallowing access to the field. *2. If you have set default field visibility in the fields.ini file via the [__global__] section.... *3. Check to make sure that your __sql__ directive is at the beginning of the file and that it is __sql__ and not _sql_ *4. Try to enter an obviously invalid SQL query for the __sql__ directive to see if you get an error (to confirm that it is picking up the __sql__ directive at all). grafted fields, grafted, sorting columns, sort, relative records, relative tables en test_page_34 177 Hello World Hello world en Clean_the_html_for_the_export 178 Clean the HTML to export data ==Clean HTML tags and entities to export your data== #Override the display() of the field to strip the tags... but this would affect all parts of the application where the HTML fields are displayed. #Create a grafted field, then override its display to show the stripped contents of the HTML area field. e.g. in the fields.ini: <code> __sql__ = "select t.*, null as stripped_field from mytable t" [original_field] widget:type=htmlarea visibility:csv=hidden [stripped_field] visibility:csv = visible visibility:list=hidden visibility:browse=hidden visibility:find=hidden </code> Then in the delegate class: <code> function stripped_field__display($record){ return html_entity_decode(strip_tags($record->val('original_field')), ENT_QUOTES, 'UTF-8'); } </code> en