GettingStarted:Why_Use_Xataface 72 Why Use Xataface ==Why Use Xataface?== Some simple examples similar to those that are frequently encountered by web developers, and how dataface can be used to acheive a solution. As a web services developer in the Faculty of Applied Sciences at Simon Fraser University, I am frequently getting requests to build websites that are manageable by the site owner. Most of these requests also specify certain types of content that must be stored on the website, and much of this content needs to be n-ary (i.e., there will be multiple instances of each type of content). Let me give you an example. ===Example 1: Website for Faculty of Widgetry=== The Faculty of Widgetry needs a website to publish information about its undergraduate programs. It is important for them to be able to publish admission requirements, and program overviews for each program. It is also important to have course outlines and timetables for each course. The Faculty of Widgetry has 12 undergraduate programs and over 100 courses offered. ====Solution 1: Static HTML==== To build this web site using only static HTML pages using Dreamweaver or some other HTML editor would require at least 112 pages to be created (one for each course and program). However, once we recognize that there are only 2 types of pages required (one for courses and one for programs), we can reduce the task down to creating 2 templates and filling in the main content for each program and course individually. Most HTML editors have some templating ability so you can make changes to the template and have the changes propogated to all pages that use that template with the click of a button. This works great, but courses are added frequently, and outlines are changed. Do you really want to receive requests to update all of these pages every time there are changes to make? (If your answer is 'yes', then you probably won't be interested in reading the rest of this tutorial). Whether the Dean of the faculty knows it or not, it is very important for the program assistants to be able to update these web pages on their own. To acheive these goals you can: * Install Dreamweaver on the Program Assistants' computers, teach them how to use it, and allow them to perform updates. * Install Contribute, which is a scaled down version of Dreamweaver to make it easier for the Program Assistants to edit the content. * Use another solution that is equivalent to one of the above 2 solutions. Installing Dreamweaver for each Program Assistant is a little overkill, and since it has the ability to do much more than just update content. In addition, Dreamweaver is really a developer's tool - not a secretary's tool, so it can be difficult to learn at first. The best reason NOT to install Dreamweaver on the Program Assistant's computer, however, is that it enables him/her to muck things up by accident (believe me, I has happened to me more times than I care to count). Admittedly, Contribute is a viable option as it controls access to only certain portions of web pages to be edited, and it is targetted at secretaries (not developers) so it is easier to use. In fact, given the requirements for this web site (as stated above), this is a perfectly good solution. However you better hope that none of the following requirements are added: * Each program web page should contain an up-to-date list of all of the courses required for the program, along with a link to the course outline for that course. * Course outlines should be available in PDF format as well as HTML format. * An index page showing all of the courses available should be added. This page must allow courses to be organized by program, course subject, or course number. * Any other requirement that would have information formatted in more than one way. If any of these requirements are likely to be added (EVER) then you would be well-advised to look into solutions that use a database back-end. ====Solution 2: Use a Content Management System (CMS)==== There are hundreds of content management systems available that will allow you to store and update content through the web (TTW). Some of them even have an assortment of add-ons that will allow you to store more specific types of information. Some good CMS's include Plone, Drupal, and Xoops. Suppose we want to develop the Faculty of Widgetry website using one of these CMS's. Any good CMS will allow you to create and edit HTML documents easily (without having to write any custom products). However, it is often the case that our documents require the content to be structured. For example, each program has some common data associated with it: Program Name, Admission Deadline, Program Description, Outline, Courses, etc... If we want to properly separate data from presentation, we would need to build a special content-type to store our programs. Most CMS's allow you to develop custom content-types using the underlying programming language and an API (Application Programming Interface). Some API's are easier to use than others and some are documented better than others. The common element is that each has its own proprietary interface for writing these add-ons. If you are using a CMS and you are proficient in the creation of add-on content-types, then you will be able to build the Faculty of Widgetry website without great difficulty. However there are a number of reasons why you may choose NOT to use a CMS: * Steep learning curve: Depending on the CMS it can be very time consuming and difficult to learn how to use and modify the CMS to suit you purposes. * It is over-kill: Most CMS's are filled with features and modules that you will never need. In fact it can even be a pain to turn them off if you don't want them. * You can get tied into the CMS: When you are using a CMS, you will start developing for the CMS. With all of your content in the CMS it may be difficult to migrate to a different solution later on. (The truth of this statement will vary for different CMS's). Choose your CMS carefully. ====Solution 3: Use an existing Application==== OK, OK, let's not get too carried away with trying to develop the website until we have checked the market to see if someone else has already done it better. Maybe there is already a PHP application that makes websites for Faculties easy. I mean, I can't be the first person that needed to build a website for a Faculty. In fact if you do a search or go to Hotscripts.com, you will probably find a handful of applications or scripts that almost do what you need. If you're lucky, maybe you can find an application that does exactly what you need (but frankly, I've never been that lucky). If you find one, maybe it's worth taking it for a test drive. But beware. Using a system that almost does what you need but is difficult to modify to your needs can be worse than building it by scratch. Make sure that you are able to modify the application to suit your needs exactly. ====Solution 4: Use PHP and MySQL==== If all we want to do is separate the data from the presentation and allow the Program Assistants to update data on the website, why not just design a MySQL database with the appropriate tables and fields to store the required data. In our case we will need 2 tables: '''Programs''': * Fields: ** ProgramID : int ** ProgramName : varchar ** ProgramDescription: text ** AdmissionDeadline: date ** Outline_HTML : text ** Outline_PDF : blob '''Courses''': * Fields: ** CourseID : int ** CourseSubject : varchar ** CourseTitle : varchar ** CourseNumber : int ** ProgramID : int ** CourseDescription : text ** Outline_HTML : text ** Outline_PDF : blob Now it's easy to create a few web pages that extract data from the database and displays it as HTML. In fact if there is an existing page template that you can use for the header and footer, you can develop the entire Faculty website in under an hour (you just have to create 3 pages). '''Question''': How will the Program Assistants update the information in the database? '''Answer''': OK, let's assume that you're not going to teach them SQL and that a DB Admin tool will also be too difficult to learn. Then you have to create HTML forms to update records in the database. Ouch! What was easy just became hard. Making HTML forms is a real pain, because you have to validate the input, deal with file uploads, and also make sure that everything is stored to the database OK without losing any information. Such a basic task, but it can be very difficult. This is when it is time to use Xataface. ====Solution 5: Use Xataface==== OK, this isn't really its own solution. It is more like "Solution 4 Part II", because Xataface is intended to complement your custom application you built with solution 4, by providing an easy-to-use, configurable user interface that is targeted at secretaries and normal users (as opposed to database administrators). A Xataface application takes only seconds to set up and it will provide you with a full user interface for your users to edit information in the database. introduction motivation why en GettingStarted:Introduction 71 Introduction Web Lite is a simple framework for building data-driven web applications in PHP and MySQL. This section introduces some of the concepts and applications of Dataface. To fully understand what Xataface is, we must first define a few key terms: '''Framework''' - A set of software routines that provide a foundation structure for an application. Frameworks take the tedium out of writing an application from scratch. (From Answers.com) '''Data-driven design'''- Designing an application around the data that it will store. Xataface is a ''Framework'' in the sense that it is a set of classes and libraries that take the tedium out of writing web applications. It provides a simple web interface to a MySQL database enabling users to update, delete, and find data in the underlying database. The interface is targeted at secretaries and end-users as opposed to database administrators. Xataface enables ''data-driven design'' because it allows developers to develop web sites by first designing the database that will be used to store the data on the website, and then design the pages used to display the data. The developer can focus on the data because he or she does not have to worry about having to build forms to update the data. If the requirements of the application change, the developer can simply add a field to the database table and all associated web forms will be updated automatically (because they are all dynamically generated using the database schema). ===Requirements=== * [http://php.net PHP] >= 4.3 * [http://mysql.com MySQL] >= 3.2.3 ===Key Technologies=== * [http://pear.php.net PEAR class libraries] (HTML_QuickForm, etc...) * [http://smarty.net Smarty Templating Engine] * [http://plone.org Plone] Javascript and CSS style sheets ===Development Procedures=== # Identify the data that will need to be stored for a web site. ##[[Image:http://xataface.com/documentation/tutorial/getting_started/er-diagram.png]] # Design the database using your favorite database administration program (e.g., PHPMyAdmin) ##[[Image:http://xataface.com/documentation/tutorial/getting_started/phpMyAdmin-1-small.gif]] # Tell Xataface some DB connection info, and voila! You have an application: ##[[Image:http://xataface.com/documentation/tutorial/getting_started/new-record-form-1-small.gif]] ===Where to go from here=== This tutorial will teach you the basics of Xataface and how to construct a simple application using the Xataface. After reading this tutorial you will be ready to tackle some medium to large web sites with the help of the Xataface reference documentation. You are also encouraged to mail the [http://xataface.com/forum Xataface forum] if you have questions. introduction requirements getting started en 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 Authenticating_Against_the_Joomla!_Users_Table 93 Xataface is able to use the joomla users table to authenticate against so that, you can allow your users to log into your Xataface application using the same credentials as they use to access your joomla website. Achieving this level of integration requires 2 simple steps : 1 - Set up the [_auth] section of your conf.ini file to reference the joomla users table and the correct username and password columns. 2 - Create a delegate class for the joomla users table to be able to decrypt the password set in the table. ==Configure the conf.ini file== Joomla users table is named jos_users. So you have to declare this table in the conf.ini file. <code>[_auth] users_table = jos_users username_column = username password_column = password</code> Note that username_column and password_column are very simple... ==Create a delegate class for your users table== Now we have to create a delegate class for the users table to decrypt the passwords set in joomla. Joomla uses a custom md5 encryption. ===Joomla encryption=== When a user is setting a password in joomla, the system does several things : 1 - generate a random key containing alphanumeric characters example : <code>8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> 2 - concate the clear entered password with the random key example : <code>password8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> 3 - doing a md5 encryption on the result string example : <code>md5(password8NdiRqLRKLHaNwudJ3InJknsew9sc7pL = f2b1fb3996442db549c1ed1a1eebbfe1</code> 4 - concate the md5 string with the random key separated by ":" example : <code>f2b1fb3996442db549c1ed1a1eebbfe1:8NdiRqLRKLHaNwudJ3InJknsew9sc7pL</code> So it's a great encryption but xataface doesn't know how to do that. Here is the utility of the delegate class. We will define a function inside which could compare the entered password in xataface with the joomla stored password. ===Creating the delegate class=== 1 - Add a jos_users directory in your directory table 2 - Create a jos_users.php file inside this new directory ===Creating the decrypt password function=== Before posting this code, I would like to thank fantomasdm who created this function. So here is the code of the function to paste directly in the jos_users delegate class : <code><? class tables_jos_users { function password__serialize($password){ $app =& Dataface_Application::getInstance(); $query = "SELECT id, gid, block, password, usertype FROM jos_users where username='".$_POST['UserName']."'"; $result = mysql_query($query,$app->db()) or die("Query failed" . mysql_error() ); $line = mysql_fetch_array($result, MYSQL_ASSOC); mysql_free_result($result); $arraypass=explode(":", $linea['password']); $key=$arraypass[1]; $ret = md5(trim($password).$key).":".$key; return $ret; } } ?></code> Save your file and test the result. Enjoy ! ;-) joomla authentication md5 en Key 83 fields.ini Directive: Key The '''Key''' directive is used only when the table is a view and you need to explicitly define which columns are part of the primary key. For example, if we created a view on the books table to only show books in a given year as follows: <code> create view books_2000 as select * from books where year='2000' </code> And we wanted to use this view as a table in our Xataface application we would need to tell it that the primary key of this view is the book_id field. So in the fields.ini file we would add: <code> [book_id] Key=PRI </code> Note that this is case sensitive. key=PRI will not work. ===Compound Primary Keys=== For primary keys comprising multiple columns we would add this directive for each field in the key. E.g. if our books_2000 view had 2 fields in the primary key, say author_id and book_index, we would have in the books_2000 fields.ini file: <code> [author_id] Key=PRI [book_index] Key=PRI </code> Links: * [http://xataface.com/forum/viewtopic.php?f=4&t=6723 Lookup widget on view with compound primary key] Return to [[fields.ini file]] Key, Views, MySQL Views, Create View, PRI, Primary Keys en 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 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 lookup 61 The Lookup Widget Return to [[widget:type]] page to see list of all widget types. Back to [[fields.ini file]] to see other fields.ini directives. [[toc]] ===Synopsis=== The lookup widget allows users to look a record from another table to insert into the field. It is like a select widget except that it doesn't use a vocabulary. Instead you just specify a table on which it should search using the widget:table directive. In order to use the lookup widget to edit a field, you should set the [[widget:type]] directive of the [[fields.ini file]] for the field to '''lookup''. I.e. <code> [fieldname] widget:type=lookup widget:table=mytable </code> '''Note that the lookup widget requires the [[widget:table]] directive to be set to the target table of the lookup or it will not work properly.''' ===Required Directives=== The following [[fields.ini file]] directives are required to accompany the field definition if a lookup widget is used: {| class="listing listing2" |- ! Name ! Description ! Version |- | widget:table | The name of the table in which the lookup widget should look up related records. | 1.0 |} ===Optional Directives=== The following additional optional directives may be used to customize the behaviour of the lookup widget: {| class="listing listing2" |- ! Name ! Description ! Version |- | widget:filters:-limit | Sets the number of records that are shown by default in the lookup widget. Default is 30 if this is omitted. E.g.<code>widget:filters:-limit=100</code> to show 100 records at a time. | 1.0 |- | widget:filters:-sort | Specifies the columns to sort the results on. E.g. <code>widget:filters:-sort=category_name asc, year desc</code> | 1.0 |- | widget:filters:* | Any valid Xataface directive can be used to filter the results by specifying widget:filters:param (where "param" is a valid Xataface GET parameter, which could include a column name to filter results on, or other filter directives). <code>widget:filters:country=Canada</code> To only show results with Country=Canada. | 1.0 |- | widget:filters:*=$* | Dynamic filters. Causes the options in the record browser to be filtered on the value of another field in the form. e.g. <code>widget:filters:country_id="$country_id"</code> would show only results with records having country_id matching the value of the 'country_id' field in the current form. | 1.3.1 |} See [[URL Conventions]] for an overview of the types of GET parameters Xataface can take. Any GET parameters that manipulate a query can be used with the widget:filters:* directive to modify the query results that are shown in the lookup widget. ===Example=== In this example we have a field named appointee that is supposed to reference the contacts table. So in the [[fields.ini file]] we would have: <pre> [appointee] widget:type=lookup widget:table=contacts </pre> Initially we just have a little find icon next to the field. If the user clicks it, a dialog pops up enabling them to search for the contact that they want: [[Image:http://media.weblite.ca/files/photos/Picture%2023.png?max_width=640]] ===Additional Tips=== Although the lookup widget does not use a vocabulary as indicated in the Synopsis above, it is still useful to define a vocabulary in the fields.ini file for this field. The reason is because the lookup widget is only used with the edit action, where you are inserting or editing data into the field. However, it is not used to the display the data in the view or list actions. Therefore, you must still have a vocabulary defined to properly display these values. In order to customize the display of the lookup widget's select list, you must edit the delegate class for the table which is referenced by the widget:table directive. There are two important points to note: # The items in the selection list are formatted based on the getTitle(&$record) delegate class function if it is defined. However, ... # The Search box will search on text in VARCHAR and TEXT fields. If you need to search for data in numeric fields, you can create a grafted field using a function such as CONCAT() to display numbers as text. Links: * [http://xataface.com/forum/viewtopic.php?f=4&t=6723 Lookup widget on view with compound primary key] lookup widget, widget:filters, widget:-filters:limit, widget:table en 0 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 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 _output_cache 45 The Xataface Output Cache <nowiki><div class="portalMessage">Note: There was a bug in the output cache affecting Xataface version 1.0 to 1.3rc1. If you are using a version of Xataface older than 1.3rc2 then you should either disable the output cache, or replace the Dataface/OutputCache.php file with one from a newer version.</div></nowiki> [[toc]] Xataface does quite a bit of heavy lifting on each page request. If your application is getting a lot of traffic that is slowing your server down, you may want to look at enabling the Xataface output cache. ===Features=== * Improve speed of application dramatically - especially for seldom updated sites. * Supports multiple languages. * Supports multiple users (each user has own cache). * Provides GZIP compression for improved performance. ===How it works?=== When you receive a request, Xataface will return a cached version of the page if the page has been accessed before. If the page doesn't yet exist in the cache it generates the page, saves it to the cache and outputs it to the user transparently. The cache is completely transparent to your users. ===Where is the cache stored?=== Xataface creates a table called ''__output_cache'' that stores all of the cached content for your application. This table stores both a GZIPed and regular version of each page. If the user's browser supports GZIP compression, Xataface will automatically return the GZIP version. This results in further performance improvements. ===What if I make changes to the database?=== Xataface records which tables were in use when a page is cached. If any of those tables are modified after the page is cached, Xataface will mark that cached page as ''out of date'' and regenerate it the next time that it is requested. ===What if I make changes to my configuration files and templates?=== The output cache will have to be manually cleared if you make any changes to your source files (e.g. PHP, templates, and INI files). Clearing the cache is as easy as deleting or emptying the ''__output_cache'' table. ===How do I enable the Cache?=== Add the following to your [[conf.ini file]]: <code> [_output_cache] enabled=1 </code> ===How do I disable the Cache?=== Simply comment out or remove the ''[_output_cache]'' section of your [[conf.ini file]]. E.g. <code> ;[_output_cache] ; enabled=1 </code> ===Configuration Options=== The following directives can be added to the ''[_output_cache]'' section of your [[conf.ini file]] to customize how your output cache works. {| class="listing listing2" |- ! Name ! Description ! Version |- | lifeTime | Number of seconds before cached page is considered ''out of date''. | 0.7 |- | tableName | The name of the table to store the cached pages. Default '__output_cache'. | 0.7 |- | ignoredTables | A comma-delimited list of tables that don't affect the output cache (i.e. these tables can be changed without causing the output cache to be refreshed. | 0.7 |- | observedTables | A comma-delimited list of tables that should affect the status of the output cache for every page (whether the table is explicitly used by the page or not). This is a useful way to tell Xataface to refresh your cache. | 0.7 |- | exemptActions | A comma-delimited list of actions that are exempt from the output cache (and thus should not be cached). | 0.7 |} output cache en 0 Cached_permissions 179 Cached Permissions ==Cached Permissions== ===Introduction=== When you insert a SQL query in your getPermissions function, this will slow down the app dramatically because this function is called by each query. To resolve this problem, it is better to use cached permissions in your /conf/ApplicationDelegate.php or table/table.php. ===Procedure=== Here is an example : <code> class tables_mytable { private $cachedPerms = null; private function _getCachedPerms($param1, $param2, ..., $paramN){ if ( !isset($this->cachedPerms) ) { $this->cachedPerms = array(); // do some stuff $res = mysql_query("select * from foo where bar=1 and param2='".addslashes($param2)."'"); while ( $row = mysql_fetch_assoc($res) ) $this->cachedPerms[$row['fooid']] = $row; } return $this->cachedPerms; } function getPermissions($record){ // do some stuff $perms = $this->getCachedPerms($param1, $param2, ..., $paramN); return $perms; } }</code> Here, getPermissions() will run a db query on its first request, but subsequent requests will just load the cached value. permissions, cache, quick, query en permissions.ini_file 26 permissions.ini_file ==The permissions.ini File== [[toc]] The permissions.ini file stores custom permissions and roles that can be used by an application. It is an optional file that should be placed in the application root directory (i.e. the same directory where your conf.ini, and index.php files are located). The permissions.ini file allows you to define two things: # Permissions # Roles (i.e. sets of permissions). Permissions and roles are used throughout Xataface to limit access to actions, records, fields, and relationships. For example, each action in your application can specify a permission that is necessary to perform the action. Your delegate classes may include getPermissions() methods to define what permissions a user gets when interacting with different records. This file (permissions.ini) simply defines the permissions that can be used by your application. It doesn't actually assign those permissions. Assigning permissions is the job of the getPermissions() (or getRoles()) method. ===Defining Permissions=== Permissions are defined by standalone properties in the beginning of the permissions.ini file. For example, if you were desiging a proof-reading application, you might need permissions for "submit_for_proof", or "approve_text" to correspond with the submitting a document to be proof-read, and approving a document's proof. In this case we would have the following at the beginning of our permissions.ini file: <code> submit_for_proof = Submit a document to be proofread approve_text = "Approve this document's proof" </code> The left side of the equals sign is the name of the permission. The right side contains a human readable description of the permission and what it is for. ===Limiting Access to Actions based on Permissions=== At this point these permissions don't do anything. In order to be useful we need reference these permissions from an action or a section. For example, let's create an action called "submit_for_proof" which displays a form for a user to submit a document record to be proofread. Our actions.ini file entry might look something like: <code> [submit_for_proof] url="{$this->url('-action=submit_for_proof')}" label="Submit document for proof" category=record_actions permission=submit_for_proof template=submit_for_proof.html </code> And for completeness, since this make-believe action specifies th "submit_for_proof.html" template, we'll create the "submit_for_proof.html" template in the templates directory: <code> <html><body>You have permission to perform this action.</body></html> </code> ===Defining Who Get's Which Permissions=== Finally, in order to benefit from permissions, your application has to decide that it is going to use permissions (unless you define a getPermissions() method, users are granted ALL permissions by default. Hence if you try to access our submit_for_proof action, we'll see it without any problem. Regardless of who we are. So let's create a simple, but restrictive getPermissions() method in our application delegate class: <code> <?php class conf_ApplicationDelegate { function getPermissions(&$record){ return Dataface_PermissionsTool::READ_ONLY(); } } </code> Now if we try to access our submit_for_proof action it will give us a "Permission Denied" message, because we are only granted READ ONLY permissions (which is a role that includes the view permission and some others - but not our custom "submit_for_proof" permission. Now we'll make a small modification to our getPermissions() method to provide us with our submit_for_proof permission: <code> <?php class conf_ApplicationDelegate { function getPermissions(&$record){ $perms = Dataface_PermissionsTool::READ_ONLY(); $perms['submit_for_proof'] = 1; return $perms; } } </code> Now if we try to access our submit_for_proof action, it will show us our template with no error messages (hopefully). ===Roles=== Roles are sets of permissions. They are defined in the permissions.ini file as sections with lists of included permissions. It might be handy to create roles such as EDITOR or MANAGER which contain sets of permissions that are meant to be assigned to users of those types. For example an EDITOR may have the view and edit permissions, but not the delete permission. A MANAGER might have the view, edit, and delete permissions. You can define these two roles in the permissions.ini file as follows: <code> [EDITOR] view=1 edit=1 [MANAGER] view=1 edit=1 delete=1 </code> Then we could assign these roles to users using the Dataface_PermissionsTool::getRolePermissions() method: <code> function getPermissions(&$record){ $user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user and $user->val('role') == 'EDITOR' ){ return Dataface_PermissionsTool::getRolePermissions('EDITOR'); } else if ( $user and $user->val('role') == 'MANAGER' ){ return Dataface_PermissionsTool::getRolePermissions('MANAGER'); } return Dataface_PermissionsTool::READ_ONLY(); } </code> Or equivalently we could use the getRoles() method of our delegate class instead of getPermissions(): <code> function getRoles(&$record){ $user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if ( $user and $user->val('role') == 'EDITOR' ){ return 'EDITOR'; } else if ( $user and $user->val('role') == 'MANAGER' ){ return 'MANAGER' } return 'READ ONLY'; } </code> ===Xataface Core Permissions & Roles=== Xataface is distributed with its own permissions.ini file that defines some core permissions and roles. You can look at this permissions.ini file (located in the Xataface directory) to see what the format should look like. Any settings you place in your application's permissions.ini file will augment or override settings in Xataface's file. Some core permissions include: {| class="listing listing2" |- ! Name ! Description ! Version |- | view | Permission to view a record or field. This permission is required to access the view tab, and several other details tabs. | 0.6 |- | list | Permission to access the list tab. | 0.6 |- | calendar | Permission to access the calendar tab. | 0.6 |- | edit | Permission to edit a record or field. This also gives access to the edit tab. | 0.6 |- | new | Permission to edit a record or field for the purpose of creating a new record. This permission is required to access the new record form. | 0.6 |- | select_rows | Permission to select rows in list view to perform actions on them. | 0.6 |- | post | Permission to post a record using HTTP POST | 0.6 |- | copy | Permission to copy a record. | 0.6 |- | update_set | Permission to perform an update on a result set (i.e. access the update set action). | 0.8 |- | add new related record | Permission to add a new record to a relationship. See [[Relationship Permissions]] | 0.6 |- | add existing related record | Permission to add an existing record to a relationship. See [[Relationship Permissions]] | 0.6 |- | view related records | Permission to view the records in a relationship. See [[Relationship Permissions]] | 1.0 |- | delete | Permission to delete a record. | 0.6 |- | delete found | Permission to access the delete found set action (to delete multiple records at a time). | 0.6 |- | show all | Permission to access show all records action. | 0.6 |- | remove related record | Permission to remove a record from a relationship. See [[Relationship Permissions]] | 0.6 |- | delete related record | Permission to delete a record in a relationship. This is stronger than the remove related record permission in that it allows the user to delete the record from the database. See [[Relationship permissions]] | 0.6 |- | find | Permission to perform the find action. | 0.6 |- | import | Permission to perform the import action (to import records into the database). | 0.6 |- | export_csv | Permission to perform the Export CSV action (to export the result set in comma-separated-value format). | 0.6 |- | export_xml | Permission to perform the Export XML action (to export the result set as XML). | 0.8 |- | translate | Permission to translate a record into another language. This permission provides access to the "translate" tab. | 0.8 |- | history | Permission to view history information for a record (e.g. the history tab). This requires that history be enabled. | 0.8 |- | edit_history | Permission to edit history information such as undo/redo support for a record. | 0.8 |- | navigate | Permission to navigate through records of a table. | 0.6 |- | reorder_related_records | Permission to reorder the records of a relationship (this is different than just sorting). It sets a default order for the records. Requires the metafields:order directive to be set for the relationship. | 0.6 |- | ajax_save | Permission to save a record through AJAX. | 0.8 |- | ajax_load | Permission to load a record through AJAX. | 0.8 |- | ajax_form | Permission to access the inline editing ajax form for a record. | 0.8 |- | find_list | Permission to search current table. | 0.6 |- | find_multi_table | Permission to perform a site-wide search. | 0.8 |- | register | Permission to register for an account. | 0.8 |- | xml_view | Permission to view a result set as xml. | 0.8 |- | view_xml | View the XML for an individual record. | 0.8 |- | manage_output_cache | Management permission to clear the output cache. | 0.8 |- | manage_migrate | Permission to access the migration tool to migrate between versions. | 0.8 |- | manage | Permission to access the management control panel. | 0.8 |- | manage_build_index | Permission to rebuild the search index. | 0.8 |- | expandable | Whether the record can be expanded in the left nav menu | N/A |} Some core roles include: {| class="listing listing2" |- ! Name ! Permissions Included ! Version |- | READ ONLY | view, list, calendar, view xml, show all, find, navigate, ajax_load, find_list, find_multi_table, rss, export_csv, export_xml, and export_json | 0.6 |- | EDIT | All permissions in READ ONLY, and edit, add new related record, add existing related record, add new record, remove related record, reorder_related_records, import, translate, new, ajax_save, ajax_form, history, edit_history, copy, update_set, and select_rows | 0.6 |- | DELETE | All permissions in EDIT, and delete and delete found. | 0.6 |- | OWNER | All permissions in DELETE except navigate, new, and delete found. | 0.6 |- | REVIEWER | All permissions in READ ONLY, and edit and translate. | 0.6 |- | USER | All permissions in READ ONLY, and add new related record. | 0.6 |- | ADMIN | All permissions in DELETE and xml_view | 0.6 |- | MANAGER | All permissions in ADMIN and manage, manage_output_cache, manage_migrate, manage_build_index, and install. | 0.6 |} ===Extending and Overriding Roles=== The cleanest and easiest way to define a new role is to extend an existing role. Xataface allows you to extend roles via the '''extends''' keyword. For example, if you wanted to create a role '''TEST ROLE''' that contained all of the same permissions as the READ ONLY role, you could define it as follows in your application's permissions.ini file: <code> [TEST ROLE extends READ ONLY] </code> If we wanted it to contain the same permissions as READ ONLY but to also allow the edit permission we would define it as: <code> [TEST ROLE extends READ ONLY] edit=1 </code> If we wanted to disallow the list permission, we would do something like: <code> [TEST ROLE extends READ ONLY] edit=1 list=0 </code> ===Overriding Existing Roles=== You can also redefine existing roles: <code> [READ ONLY extends READ ONLY] my_permission=1 </code> This is handy if you have added your own custom permissions that you feel should be included in a core role. Note that there are some caveats regarding the order of how these roles are defined. Please refer to this forum post for more details: [http://www.xataface.com/forum/viewtopic.php?t=6187 Overriding Roles / Permissions] ==See Also== * [[Relationship Permissions]] * [[getPermissions]] - The getPermissionsMethod * [[Delegate class methods]] - Delegate class methods. * [http://xataface.com/documentation/tutorial/getting_started/permissions Getting started with Xataface permissions] permissions.ini, getPermissions, permissions en 0 Authenticating_Against_the_PHPBB_Users_table 92 Authenticating Against the PHPBB Users Table Return to [[authentication]] [[toc]] Xataface is able to use the PHPBB users table to authenticate against so that, you can allow your users to log into your Xataface application using the same credentials as they use to access your PHPBB message forum. Achieving this level of integration requires 2 simple steps: # Set up the [[_auth]] section of your [[conf.ini file]] to reference the PHPBB users table and the correct username and password columns. # Specify the correct encryption on the password column. This step will be different for different versions of PHPBB. ==PHPBB 2== PHPBB version 2 and lower simply use MD5 encryption on the password column, which Xataface supports natively via the [[encryption]] directive of the [[fields.ini file]]. Therefore we can set up our Xataface application to authenticate against our PHPBB2 database ('''assuming that our PHPBB is set up in the same database as our Xataface app''') by doing the following: # Set up the [_auth] section of the [[conf.ini file]] as follows:<code> [_auth] users_table = phpbb_users username_column = username password_column = user_password </code> # Set up the user_password field to use md5 encryption in the ''tables/phpbb_users/fields.ini'' file <code> [user_password] encryption=md5 </code> That's it! Now you should be able to log into your Xataface application using the username/password from PHPBB. ==PHPBB 3== PHPBB version 3 and higher uses a custom encryption function for the password column so it is a little more complicated (but not that much). Step one (the [[conf.ini file]]) is the same as for PHPBB version 2 listed above. The 2nd part, however, requires us to implement a custom serialization for the user_password field. So the steps are below: # Set up the [_auth] section of the [[conf.ini file]] as follows:<code> [_auth] users_table = phpbb_users username_column = username password_column = user_password </code> # Implement the user_password__serialize() method in your phpbb_users delegate class (i.e. the ''tables/phpbb_users/phpbb_users.php'' file):<code> <?php class tables_phpbb_users { function user_password__serialize($password){ $itoa64 = './0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; $sql = "select user_password from phpbb_users where username='".addslashes($_POST['UserName'])."'"; $res = mysql_query($sql, df_db()); if ( !$res ) throw new Exception(mysql_error(df_db())); $row = mysql_fetch_assoc($res); mysql_free_result($res); $hash = $this->_hash_crypt_private($password, $row['user_password'], $itoa64); return $hash; } /** * The crypt function/replacement */ function _hash_crypt_private($password, $setting, &$itoa64) { $output = '*'; // Check for correct hash if (substr($setting, 0, 3) != '$H$') { return $output; } $count_log2 = strpos($itoa64, $setting[3]); if ($count_log2 < 7 || $count_log2 > 30) { return $output; } $count = 1 << $count_log2; $salt = substr($setting, 4, 8); if (strlen($salt) != 8) { return $output; } /** * We're kind of forced to use MD5 here since it's the only * cryptographic primitive available in all versions of PHP * currently in use. To implement our own low-level crypto * in PHP would result in much worse performance and * consequently in lower iteration counts and hashes that are * quicker to crack (by non-PHP code). */ if (PHP_VERSION >= 5) { $hash = md5($salt . $password, true); do { $hash = md5($hash . $password, true); } while (--$count); } else { $hash = pack('H*', md5($salt . $password)); do { $hash = pack('H*', md5($hash . $password)); } while (--$count); } $output = substr($setting, 0, 12); $output .= $this->_hash_encode64($hash, 16, $itoa64); return $output; } /** * Encode hash */ function _hash_encode64($input, $count, &$itoa64) { $output = ''; $i = 0; do { $value = ord($input[$i++]); $output .= $itoa64[$value & 0x3f]; if ($i < $count) { $value |= ord($input[$i]) << 8; } $output .= $itoa64[($value >> 6) & 0x3f]; if ($i++ >= $count) { break; } if ($i < $count) { $value |= ord($input[$i]) << 16; } $output .= $itoa64[($value >> 12) & 0x3f]; if ($i++ >= $count) { break; } $output .= $itoa64[($value >> 18) & 0x3f]; } while ($i < $count); return $output; } } </code> PHPBB, authentication, security, authentication modules en preferences 10 preferences ==Xataface Preferences== [[toc]] Xataface preferences can be defined in 3 ways: # In the ''[_prefs]'' section of rhe [[conf.ini file]] for global static preferences. # Implementing the [[getPreferences]] method in the [[Application Delegate Class]] # In the [[__prefs__]] section of the fields.ini file for a table for static preferences on that table. (Limited to only certain preferences). ===Example [_prefs] section=== In the conf.ini <code> [_prefs] hide_updated=1 hide_posted_by=1 </code> ===Example [[getPreferences]] method=== In the [[Application Delegate Class]]: <code> function getPreferences(){ return array('hide_update'=>1, 'hide_posted_by'=>1); } </code> ===Available Preferences=== {| class="listing listing2" ! Name ! Description ! Default ! Version |- | show_result_stats | Show the result statistics (e.g. found x of y records in table z) | 1 | 0.6 |- | show_jump_menu | Show he drop-down menu that allows you to "jump" to any record in the found set. | 1 | 0.6 |- | show_result_controller | Show Next, previous, page number .. links... | 1 | 0.6 |- | show_table_tabs | Show Details, List, Find, etc... tabs. | 1 | 0.6 |- | show_actions_menu | Show New record, Show all, delete, etc.. | 1 | 0.6 |- | show_logo | Show logo at top of app | 1 | 0.6 |- | show_tables_menu | Show the tabs to select a table. | 1 | 0.6 |- | show_search | Show search field in upper right. | 1 | 0.6 |- | show_record_actions | Show actions related to particular record | 1 | 0.6 |- | show_bread_crumbs | Show bread crumbs at top of page to show where you are. | 1 | 0.6 |- | show_record_tabs | View, Edit, Translate, History, etc... | 1 | 0.6 |- | show_record_tree | Show tree to navigate the relationships of this record. | 1 | 0.6 |- | list_view_scroll_horizontal | Whether to scroll list horizontal if it exceeds page width | 1 | 0.6 |- | list_view_scroll_vertical | Whether to scroll list vertical if it exceeds page height. | 1 | 0.6 |- | hide_posted_by | Whether to hide the ''posted by'' text in glance lists (e.g. in the view tab, the related records are shown in the left column. This hides the ''posted by'' text next to each related record. | 0 | 1.0b4 |- | hide_updated | Whether to hide the ''updated'' text in the glance lists (e.g. in the view tab, the related records are shown in the left column. This hides the ''updated'' text next to each related record. | 0 | 1.0b4 |- | SummaryList_logo_width | The width of the logo to be used as the preview image in summary lists. | null | 0.7 |- | SummaryList_hideSort | Hides the sort control for a summary list (the box that allows users to sort by column). | 0 | 0.7 |- | hide_user_status | Hides the user's status (e.g. "You are logged in as ..." | 0 | 0.7 |- | hide_personal_tools | Hides the personal tool links in upper right. This includes likes such as "Control Panel" and "My Profile" | 0 | 0.7 |- | hide_resultlist_controller | Hides the controller for a result list (E.g. next/back/results per page etc...). | 0 | 0.7 |- | hide_related_sections | Hides the sections of the view tab that show the related records. These are the sortable section boxes. Not the related tabs. | 0 | 1.3 |- | hide_record_search | Hides the record search form that appears in the view tab. Not to be confused with the find tab. | 0 | 1.3 |- | show_resultlist_controller_only_when_needed | Sets the resultlist controller (e.g. back/next/results per page/etc...) to only show up if paging is required (i.e. if there are more records than can be shown on one page (according to the '-limit' parameter). | 0 | 1.0 |- | hide_record_view_logo | Hides the logo for a record that appears in the upper left of the view tab for each record. | 0 | 0.7 |- | horizontal_tables_menu | Whether to force the tables menu to appear as tabs along the top of the page (alternative is as a menu on the left). If there are 10 or fewer allowed tables, then the default is 1, otherwise the default is set to 0. | 1 | 0.6 |- | hide_result_filters | In list view, setting this value to 1 will cause the column filters to be hidden (the select lists to filter the results). | 0 | 0.7 |- | disable_select_rows | A value of 1 causes the checkboxes in each row of the list view to be hidden. | 0 | 0.7 |- | result_list_use_geturl | Use the getURL() method to link to records in the list view rather than the default (which uses the -cursor parameter). | 0 | 0.7 |- | disable_ajax_record_details | Whether to disable the ajax record details (the '+' sign beside each record in list view that expands to show the record details. | 1 | 0.7 |- | use_old_resultlist_controller | As of Xataface 1.1, a new style result list controller is used that resembles facebook. It is more slimmed down and is easier to manage. If you prefer the old controller, set this preference to 1. | 0 | 1.1 |} ===Inverse Preferences=== The following preferences perform the inverse of some of the options above. When these options are set to 1, their respective option is set to 0. {| class="listing listing2" ! Name ! Inverse |- | hide_nav_menu | show_tables_menu |- | hide_view_tabs | show_table_tabs |- | hide_result_controller | show_result_controller |- | hide_table_result_stats | show_result_stats |- | hide_search | show_search |} preferences, prefs, getPreferences en 0 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 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 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 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 after_action_activate 181 after_action_activate Delegate Class Method Return to [[Application Delegate Class]] [[toc]] The '''after_action_activate''' hook is a method that can be defined in the [[Application Delegate Class]] which is called after an account has been activated via the registration process. The full registration process goes as follows: # User fills in registration form. # An email is sent to the user with a link to activate their account. # User clicks on activation link. # User is taken back to the application and activation occurs, which consists of creating a new record in the '''users''' table. # The ''after_action_activate'' trigger is called. ===Since=== This hook has been available since Xataface Version 1.2 ===Example=== <code> /** * A trigger to send the user a confirmation email after their account has been activated. * @params array $params Associative array of passed parameters. Contains a single key 'record' * with the Dataface_Record object of the users table with the user that was activated. */ function after_action_activate(array $params){ $user = $params['record']; mail($user->val('email'), 'Your account is activated', 'Your account has been activated... etc..'); } </code> ===See Also=== * [[Application Delegate Class]] * [[registration_form]] - More information user registration forms. * [[beforeRegister]] - Trigger called before the user registration form is saved. * [[afterRegister]] - Trigger called after registration form is saved. * [[validateRegistrationForm]] - Validates the input into the registration form. * [[sendRegistrationActivationEmail]] - Overrides the sending of the registration activation email. * [[getRegistrationActivationEmailInfo]] - Overrides the activation email info. Returns an associative array of the email details (e.g. subject, to, headers, etc... * [[getRegistrationActivationEmailSubject]] - Returns the subject of the activation email. * [[getRegistrationActivationEmailMessage]] - Returns the message body for the activation email. * [[getRegistrationActivationEmailParameters]] - Returns the parameters for the actication email. * [[getRegistrationActivationEmailHeaders]] - Returns the headers for the activation email. Registration, activation, register, activate, users en GettingStarted:relationships 78 Relationships ==Relationships== Xataface allows you to define relationships between tables using the relationships.ini file. Xataface applications without relationships between tables can be quite boring. In our FacultyOfWidgetry application, we have implicitly defined a relationship between the Program table and the Course table by adding a ProgramID field to the Course table. In the previous section we saw how to configure this relationship from the context of a 'Course' by adding a select list to the Course table form to select the Program that the Course belongs to. From the 'Program' side it is a little bit more complicated. There are no fields in the 'Program' table that can be edited to add a 'Course' to the list of courses in a 'Program', and it would be highly inconvenient to have to edit a 'Course' record in order to add the course to a 'Program'. What we want is a sort of 'Add Course' button to add a course to a 'Program'. ===Concepts, Definitions, and Terminology=== Before we can delve into examples, it will help to go over some of the concepts and terminology involved in relationships using Xataface. Xataface relationships are always defined in a one-way fashion from the point of view of one table. For example, if you define a one-to-many relationship from the 'Program' table to the 'Course' table, the mirror (many-to-one) relationship from 'Course' to 'Program' is not automatically created. This method of defining relationships allows us to unambiguously refer to the source and destination tables of a relationship. '''Definition 1:''' The ''source table'' of a relationship is the table on which a relationship is defined. For example if we define a relationship named 'Courses' on the 'Program' table to associate courses in a given program, then the 'Program' table would be considered the source table of the relationship, and the 'Course' table would be a destination table of the relationship. '''Definition 2:''' The ''destination table'' of a relationship a table from which related records are selected. There may be multiple destination tables in a given relationship but only one source table. If there are multiple destination tables, then one of these tables is designated as the domain table and the remaining destination tables are called join tables. '''Definition 3:''' A ''domain table'' is a destination table which stores the object of the relationship. For example if we define a many-to-many relationship between the 'Program' table and the 'Course' table, (i.e., each program can contain multiple courses and each course can be part of multiple programs), then we would need to add a join table to map 'Course' records to 'Program' records. Let's call this table 'ProgramCourses'. Each record of the 'ProgramCourses' table would contain a 2 fields: a 'ProgramID' field (to reference the program) and a 'CourseID' field to reference the course. If we define the relationship from the point of view of a 'Program' then the 'Program' table would be the source table, the 'ProgramCourses' table would be the join table, and the 'Course' table would be the domain table. Don't worry if these definitions and terms aren't clear at this point. Use this section as a reference for when you run across the terms later in the tutorial. ===Defining a relationship=== To define a relationship in Xataface, all you need to do is tell Xataface how to select the related records using SQL. Xataface will be able to figure out how to add/remove records to the relationship from this information. This information is defined inside a the 'relationships.ini' file inside the configuration folder for the table. ====Example 1: Adding a 'Courses' relationship to the 'Program' table==== We want to be able to associate multiple courses with each program. We do this by defining a relationship on the 'Program' table as follows: # Add a file named 'relationships.ini' to the 'Program' table's configuration folder (i.e., tables/Program/relationships.ini). Your application's directory structure should now look like:<nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-relationships.gif]]<nowiki><br/></nowiki>Notice, in particular the addition of the 'relationships.ini' file in the 'Program' directory. # Add the following to the 'relationships.ini' file:<code> [Courses] Course.ProgramID = "$ProgramID" </code> This little snippet defines a relationship named 'Courses' on the 'Program' table. 'Program' is the source table. 'Course' is the destination table. There are no join tables because this is only a one-to-many relationship. You may be wondering what the $ProgramID means. This is a variable that represents the value of the 'ProgramID' field in the source record. This relationship specifies that courses whose 'ProgramID' field matches the value of the 'ProgramID' field in the source record, are related to the source record. The english language makes this seem more difficult and complex than it really is. Let's check out our changes. Since we have defined the relationship on the 'Program' table, we will click on the 'Program' link in the navigation menu: [[Image:http://xataface.com/documentation/tutorial/getting_started/course-relationship-defined-1.gif]] Notice that there is now a 'course' tab at the top of the page. Click on this tab to see the courses that are related to this Program (as defined by our 'Courses' relationship). If it says that "No records matched the request" or something to that effect, then you don't have any Course records in the relationship yet. Just click the "Add New Courses Record" button in the upper left to add a course. If there are courses in the relationship, then the Courses tab will look something like: [[Image:http://xataface.com/documentation/tutorial/getting_started/courses-related-records.gif]] Currently there is only one course in the program, but we can add more. If you click on the "Add New Courses" button in the upper left, you will be presented with a new course form that will allow you to add a new course in this Program. ===Example 2: Making the 'Courses' relationship a Many-to-Many relationship=== Example 1 shows how Xataface can handle a one-to-many relationship. Now we will alter the database a little bit and turn this into a many-to-many relationship. # Add a table named 'ProgramCourses' to the database. The SQL table definition for this table should be something like:<code> CREATE TABLE `ProgramCourses` ( `ProgramID` INT( 11 ) NOT NULL , `CourseID` INT( 11 ) NOT NULL , PRIMARY KEY ( `ProgramID` , `CourseID` ) ) </code><nowiki><p>Note that it is important for ALL of your tables to have Primary keys. If a table is missing its primary keys, some strange behavior may occur with relationships involving that table.</p> <p> The above defined table will serve as a join table between 'Program' and 'Course' </p></nowiki> # Since this is now going to be a many-to-many relationship, we no longer need the 'ProgramID' field in the 'Course' table. (Do not confuse this with the ProgramID field in the 'Program' table. That field is important and needed.). Before removing this field, we will transfer the information across so that the existing relationships are maintained. The following SQL query will effectively all of the old one-to-many relationships into equivalent many-to-many relationships:<code> INSERT INTO ProgramCourses( ProgramID, CourseID ) SELECT ProgramID, CourseID FROM Course </code><nowiki><p> And now we can remove the 'ProgramID' field from the 'Course' table. ALTER TABLE Course DROP ProgramID</p></nowiki> # Finally, we will need to modify the relationship definition in the relationships.ini file of the 'Program' table:<code> [Courses] Course.CourseID = ProgramCourses.CourseID ProgramCourses.ProgramID = "$ProgramID" </code><nowiki><p> This means that all courses for which a (ProgramID, CourseID) pair matches the CourseID of the course and the ProgramID of the source Program record are included in the relationship.</p></nowiki> # Now we can check our application for changes. Go to the 'Program' table in your application (using your web browser) and click on the 'courses' tab once again:<nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/multi-relationship.gif]]<nowiki> <p> This looks almost the same as before. Notice, however that now there is an "Add Existing Courses Record" button at the top. This is because with a many-to-many relationship, you are able to add related records in 2 ways:</p></nowiki> ## Adding a completely new record that did not exist before. ## Selecting a record that already exists and adding it to the relationship. ===Example 3: Defining Relationships using SQL=== The previous examples used a simple INI file syntax to define relationships. However, some people may be more comfortable defining their relationships using SQL. This is also possible. Let's look at the relationships.ini file from example 1:<code> [Courses] Course.ProgramID = "$ProgramID" </code> This also could have been defined as follows:<code> [Courses] __sql__ = "SELECT * FROM Course WHERE ProgramID='$ProgramID'" </code> '''Note: Make sure you use two underscores on either side of 'sql' in the above example. It should be '__sql__' not '_sql_'.''' The two syntaxes are equivalent. In fact, the former will be converted into the later by Xataface behind the scenes. Now let's look at example 2's relationships.ini file:<code> [Courses] Course.CourseID = ProgramCourses.CourseID ProgramCourses.ProgramID = "$ProgramID" </code> This could have been written as:<code> [Courses] __sql__ = "SELECT * FROM ProgramCourses, Course WHERE Course.CourseID = ProgramCourses.CourseID AND ProgramCourses.ProgramID = '$ProgramID'" </code> The two are equivalent. This example, however, shows how defining a relationship using SQL can be beneficial. The above SQL query will work but it can be done better using Joins as follows:<code> [Courses] __sql__ = "SELECT * FROM ProgramCourses pc INNER JOIN Course c ON pc.CourseID = c.CourseID WHERE pc.ProgramID = '$ProgramID'" </code> All of these 3 methods will produce the same results, but the last one will probably give a little bit better performance. ===Relationship Restrictions=== Xataface has built-in logic to figure out how to add new and existing records to relationships that you define, as long as your relationships obey a few guidelines. # All tables must have a Primary key # The WHERE clause of your SQL definition for the relationship must contain only '=' comparisons, and 'AND' conjunctions. i.e., it cannot receive an 'OR' conjunction, nor can comparisons be done using '>', or '<'. This is because given 'AND' and '=' conjunctions it is easy for Xataface to be able to add records that will satisfy the relationship. If an 'OR' conjunction is used, it makes it ambiguous (though this will probably be corrected in future Xataface releases. ===Download Source Files=== [http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-8-tar.gz Download the source files for this application as a tar.gz archive] relationships 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 relationships.ini_file 20 relationships.ini_file ==relationships.ini File Reference== [[toc]] ===Overview=== The relationship.ini file is a configuration file which is associated with a single table of a database application. It provides metadata about the table's relationships to other tables to help Xataface dictate how they should be included in the application. ===Field Directives=== The following directives may be added to a field's section of the relationship.ini file to customize the field's behavior. Some directives are not applicable to all fields. {| class="listing listing2" |- ! Name ! Description ! Version |- | __sql__ | The SQL query that defines this relationship. | all |- | [[action:visible]] | A boolean value (0 or 1) that indicates whether this relationship should be visible in the record tabs. | all |- | [[action:condition]] | An expression that evaluates to a boolean that determines at runtime whether the relationship's tab should appear in the record tabs. | all |- | [[action:delegate]] | The name of an alternative action that can be used instead of the standard related records list. One possible value for this would be "related_records_checkboxes" which would provide the user with a checkbox group to select the records that should be part of the relationship rather than the usual related record list. | 1.0 |- | [[section:limit]] | Integer. The number of records to show in the related record sections (in the view tab). Default is 5. | 1.0 |- | [[section:visible]] | Boolean value (0 or 1) indicating whether the relationship information should appear as a section on the left side of the table. | all |- | [[actions:addexisting]] | Boolean value (0 or 1) indicating whether the action to add existing records should exist in this relationship. | all |- | [[actions:addnew]] | Boolean value (0 or 1) indicating whether the action to add news records should exist in this relationship. | all |- | [[action:label]] | The label that appears in the relationship tab for this relationship. | all |- | [[list:type]] | Optional type of list to use for the related record list. Possible value: "treetable" | 0.8 |- | [[meta:class]] | An optional special class to assign to the relationship. E.g. "parent" or "children". | 0.8 |- | [[metafields:order]] | If the relationship should have a default order this specifies the field that should be used for this sort. | all |- | [[visibility:fieldName]] | If given the value hidden will make that particular fieldName disappear in the relationship. This will only be applied for that particular relationship. | all |- | [[visibility:find]] | If given the value hidden this will cause the related fields to not appear on the find form. Normally each relationship is provided a section of the find form to enable users to find records that contain at least one match in the related records. | 1.3rc4 |- | [[vocabulary:existing]] | Specifies a valuelist that can be used to provide the set of records that can be added to this relationship. If target table has a single column primary key then the valuelist should use the primary key for the value. If it has a multi-column primary key, then the value should be in the form key1=value1&key2=value2 etc... See also [[relationshipname__getAddableValues]] delegate class method for a programatic solution. | 1.0 |} ==Relationship Permissions== See [[Relationship Permissions]] ==See Also== * [http://xataface.com/documentation/tutorial/getting_started/relationships Getting started with relationships] relationships.ini file, relationships en 0 Introduction_to_RSS_Feeds_in_Xataface 40 Introduction_to_RSS_Feeds_in_Xataface ==Introduction to RSS Feeds in Xataface== [[toc]] A default Xataface application provides RSS feeds to any found set in your application. This article explains a little bit about RSS and how you can configure Xataface to give you the desired results for your RSS feed. ===What is RSS?=== From [http://en.wikipedia.org/wiki/RSS_(file_format) Wikipedia's RSS article]: "RSS is a family of Web feed formats used to publish frequently updated works such as blog entries, news headlines, audio, and videoin a standardized format.[2] An RSS document (which is called a "feed", "web feed",[3] or "channel") includes full or summarized text, plus metadata such as publishing dates and authorship. Web feeds benefit publishers by letting them syndicate content automatically. They benefit readers who want to subscribe to timely updates from favored websites or to aggregate feeds from many sites into one place. RSS feeds can be read using software called an "RSS reader", "feed reader", or "aggregator", which can be web-based or desktop-based. A standardized XML file format allows the information to be published once and viewed by many different programs. The user subscribes to a feed by entering the feed's URI (often referred to informally as a "URL", although technically, those two terms are not exactly synonymous) into the reader or by clicking an RSS icon in a browser that initiates the subscription process. The RSS reader checks the user's subscribed feeds regularly for new work, downloads any updates that it finds, and provides a user interface to monitor and read the feeds." In a way RSS replaces email subscriptions so that you can subscribe to receive updates when content is added or changed on websites that you monitory. This way you can monitory these changes in your RSS reader so that your email box doesn't get clogged up. ===Using RSS in Xataface=== Xataface allows you to subscribe to: # Entire tables # Any found set # Changes to a particular record # Related record lists ====Example 1: Subscribing to receive news updates==== A user wants to be alerted whenever a new item is inserted into the ''news'' table, so he navigates to the ''list'' tab of the ''news'' table, and clicks the RSS Feed icon in the upper right. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for the ''news'' table. When new records are inserted, he'll receive alerts in his RSS reader. ====Example 2: Subscribing to receive found set updates==== A user wants to be alerted whenever a new item is inserted into the ''news'' table that contains the phrase "Buffalo Bills", because he is a Buffalo Bills fan. So he navigates to the ''news'' table, and does a search for the phrase "Buffalo Bills". Then he clicks on the "RSS Feed" icon in the upper right of the result set list. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for ''news'' items containing the phrase "Buffalo Bills". Whenever a new item is posted with this phrase, he will be notified via RSS of the new record. ====Example 3: Subscribing to a related list==== Suppose you want to receive updates whenever a particular author adds a book to his list of published works. Further suppose this is represented by a relationship between the ''authors'' table and the ''books'' table named ''publications''. You can subscribe to the RSS feed for his publications by navigating to the ''publications'' tab for that author, then clicking on the "RSS Feed" icon in the upper right. Now whenever this author adds a new book to his publications list, you'll be notified via RSS. ===Example usage in Xataface=== # A user wants to be alerted whenever a new item is inserted into the ''news'' table, so he navigates to the ''list'' tab of the ''news'' table, and clicks the RSS Feed icon in the upper right. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for the ''news'' table. When new records are inserted, he'll receive alerts in his RSS reader. # A user wants to be alerted whenever a new record about "Wayne Gretzky" is inserted in to the ''news'' table. He navigates to the ''news'' table, then performs a search for "Wayne Gretzky" using the top right search box. Then, he clicks on the "RSS Feed" icon in the upper right of the result list. Now, whenever a new item is inserted with the phrase "Wayne Gretzky", the user will be notified via RSS. ===Configuring RSS Feeds=== As with everything else in Xataface, you can configure your RSS feeds to appear just as you want them to. The following delegate class methods are available to be defined in the table delegate class for your feed: {| 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 |- | getRSSDescription | Overrides the default generated RSS description for a record. | 1.0 |- | [[getSingleRecordSearchFeed]] | Overrides the default feed for a subsearch within a record. This works identically to the [[getFeed]] method except that it takes 2 parameters: one for the current record, and a second parameter for the query. | 1.2.3 |} ==Example Configuration== There are 2 parts to configuring your RSS feeds. # Configuring the feed as a whole # Configuring the feed items (that is each record that will appear in your RSS feed). ===Configuring the Feed as a whole=== For configuring the feed as a whole, we have 2 options. We can specify the title, description, and link for the feed in the ''[_feed]'' section of your [[conf.ini file]]. This is sort of a "one size fits all" approach where all feeds generated from your application will share the same title. E.g. <code> [_feed] title="My Site News" description="News updates from my site" link="http://www.example.com" </code> However, if we want our feed's information to depend on the user's query (e.g. what the user was searching for, or which table the feed is generated on, we have more flexibility if we define the [[getFeed]] method in either the [[Application Delegate Class|application delegate class]] or the [[Delegate class methods|table delegate class]]. E.g. <code> function getFeed($query=array()){ $params = array(); if ( @$query['-search'] ) $params['title'] = '"'.$query['-search'].'" results'; else $params['title'] = 'All records from my table'; return $params; } </code> Notice that I don't need to define all possible parameters. Any parameters that I don't define will be provided automatically by Xataface, or it will simply use the values specified in your ''[_feed]'' section of the [[conf.ini file]]. ===Configuring Feed Items=== Configuring the feed items is quite important for ensuring that subscribers are seeing what you want them to see in the RSS feed. Xataface tries to guess appropriate content for your feed items if you don't specify it explicitly, but you'll likely want to tweak it a little bit to make the feed look more polished for your purposes. Use the [[getFeedItem]] [[Delegate class methods|delegate class method]] to specify how a feed item behaves (e.g. the title, content, date, author, link). E.g. <code> function getFeedItem(&$record)){ return array( 'description' => $record->val('body') ); } </code> Once again, notice that we don't need to specify all available options. Only those options that we want to override. In this case we want the description of the feed item to simply display the body of our news item. The description of an RSS feed item is effectively the body text that the user sees why they click on an item in their news reader, so this is quite important. RSS Feeds en 0 Delegate_class_methods 7 Delegate_class_methods ==Delegate Class Reference== [[toc]] A delegate class is a PHP class that complements a particular table with custom bahaviors. Basic table metadata can be supplied using the [[fields.ini file]], however some things are better customized using PHP. ===Delegate Class Location=== The delegate class should be located in a file named TABLENAME.php (where TABLENAME is the name of the table with which the delegate class is associated) inside the table's [[table configuration directory|configuration directory]]. E.g. given a table named "people", you would place the delegate class in the file "tables/people/people.php" ===Basic Delegate Class=== <code> <?php class tables_people {} ?> </code> ===Available Methods=== ====Table Settings==== {| class="listing listing2" ! Name ! Description ! Version |- | [[sql delegate method|__sql__]] | Defines the SQL query that can be used to fetch records of this table. This is identical to the [[fields.ini file]] [[__sql__]] directive, except that by defining it in the delegate class you have more flexibility. | 1.0 |} ====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_relationshipname__roles | Returns the role or roles pertaining to the relationship ''relationshipname'' on a given record. | 1.0 |} ====Triggers==== {| class="listing listing2" ! Name ! Description ! Version |- | [[after_action_edit]] | Trigger called after the edit action is succesfully completed. | 0.7 |- | [[after_action_new]] | Trigger called after the new action is successfully completed. | 0.7 |- | [[after_action_delete]] | Trigger called after the delete action is successfully completed. | 0.7 |- | [[afterAddExistingRelatedRecord]] | Trigger called after an existing related record is added. | 0.5 |- | [[aftereAddNewRelatedRecord]] | Trigger called after a new related record is added. | 0.5 |- | [[afterCopy]] | Trigger called after a record is copied. | 1.3 |- | [[afterDelete]] | Trigger called after a record is deleted. |0.5 |- | [[afterAddRelatedRecord]] | Trigger called after a related record of this table is added (either an existing record or a new record). | 0.5 |- | [[afterRemoveRelatedRecord]] | Trigger called after a related record is removed from a relationship. | 1.1.6 |- | [[afterInsert]] | Trigger called after a given record is inserted. | 0.5 |- | [[afterSave]] | Trigger called after a given record is saved (insert or update). | 0.5 |- | [[afterUpdate]] | Trigger called after a given record is updated. | 0.5 |- | [[beforeAddExistingRelatedRecord]] | Trigger called before an existing related record is added. | 0.5 |- | [[beforeAddNewRelatedRecord]] | Trigger called before a new related record is added. | 0.5 |- | [[beforeAddRelatedRecord]] | Trigger called before a related record of this table is added (either an existing record or a new record). | 0.5 |- | [[beforeCopy]] | Trigger called before a record is copied. | 1.3 |- | [[beforeDelete]] | Trigger called before a record is deleted. | 0.5 |- | [[beforeRemoveRelatedRecord]] | Trigger called before a related record is removed. | 1.1.6 |- | [[beforeSave]] | Trigger called before a given record is saved (insert or update). | 0.5 |- | [[beforeInsert]] | Trigger called before a given record is inserted. | 0.5 |- | [[beforeUpdate]] | Trigger called before a given record is updated. | 0.5 |- | [[init]] | This method is called the first time the table is loaded. It allows you to specify initialization details. | 0.8 |} ====Field Filters==== {| class="listing listing2" ! Name ! Description ! Version |- | fieldname__htmlValue | Returns the value of the field "fieldname" for a given record as HTML. | 0.5 |- | fieldname__display | Returns the value of the field "fieldname" appropriate for displaying. | 0.5 |- | [[fieldname__default]] | Returns the default value for the field ''fieldname''. New record forms will be prepopulated with this value. | 0.7 |- | [[fieldname__validate]] | Validates the input for the field ''fieldname''. | 0.6 |- | fieldname__parse | Parses the input value for the field ''fieldname''. This is called by Xataface inside the setValue() method or each record to normalize input values before they are stored in the object (not the database). | 0.5 |- | fieldname__toString | Converts the value of the field ''fieldname'' to a string. This string representation is used as the basis for most higher level data retrieval methods (such as serialize and display). This could be treated as an inverse to the [[fieldname__parse]] method. | 0.5 |- | fieldname__serialize | Converts a value of the field ''fieldname'' to be saved in the database. This should return a string representation of the value that is suitable for database storage. | 0.5 |- | fieldname__link | A link that appears beside the field ''fieldname'' on the edit form. | 0.6 |- | [[field__pushValue]] | Converts form input for field ''fieldname'' to be ready to store in a Dataface_Record. | 0.6 |- | [[field__pullValue]] | Converts a value for field ''fieldname'' in a Dataface_Record object to be ready to be inserted as a value on an HTML form. | 0.6 |- | [[field__fieldname]] | Effectively creates a calculated field named "fieldname" available on the given record. | 0.6 |- | [[no_access_text]] | Replace the default NO ACCESS permission text with another text. | 1.1.6 |- | [[no_access_link]] | Replace the default link of the NO ACCESS permission link with another link. | 1.1.6 |} ====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 |} ====List Tab Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | css__tableHeaderCellClass | Returns a custom CSS class for a table header cell (th tag) in the list view. Takes the name of a table column as a parameter. | 2.0alpha2 |- | css__tableRowClass | Returns a custom CSS class for a table row (tr tag) in list view. Takes a Dataface record as a parameter. | 1.2 |- | fieldname__renderCell | Overrides the table cell content for the "fieldname" field in list view with custom HTML. | 1.0 |- | renderRow | Overrides the the html used for a row in list view for the given record. | 0.7 |- | renderRowHeader | Overrides the header for the table in list view. | 0.7 |- | renderRelatedRow | Overrides the html used for a row in a related record list for a given related record. | 1.0 beta 4 |- | renderRelatedRowHeader | Overrides the html used for the header in a related list. | 1.0 beta 4 |} ====Record Metadata==== {| class="listing listing2" ! Name ! Description ! Version |- | [[getBreadCrumbs]] | Returns the bread crumbs (i.e. you are here) for a given record as an associative array of path parts. | 0.6 |- | [[getChildren]] | Returns a list of Dataface_Record objects that are to be considered children of the given record. | 0.8 |- | [[getCreated]] | Returns a unix timestamp marking the date that a record was created. | 0.9 |- | getDescription | Returns a string description summary of this record. This is used for indexing, RSS feeds, and anywhere that a brief summary of a record is appropriate. | 0.7 |- | getPublicLink | Returns the public URL of this record (in case it is different than the standard URL). | 0.8 |- | getTitle | Returns the title for a given record. The title is used in various parts of the application to represent the record. | 0.5 |- | [[getURL]] | Overrides the getURL() method for a record. Returns the URL that should be used to display the given record. | 0.6 |- | titleColumn | Returns a string SQL select expression that is used to describe the title of records. | 0.5 |} ====View Tab Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[How_to_Add_Custom_Sections_to_View_Tab|section__sectionname]] | Defines a section to be displayed in the view tab for the given record. | 0.7 |} ====Search Setup==== {| class="listing listing2" ! Name ! Description ! Version |- | getSearchableText | If [[_index|Indexing]] is turned on, then this returns the text that should be stored in the index for this record for searchability. | 1.0 |} ====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 |} ===XML Output Customization=== {| class="listing listing2" ! Name ! Description ! Version |- | [[toXML]] | Overrides the default XML produced for a record in the [[export xml]] action. Returns an XML string. | 1.2.7 |- | [[getXMLHead]] | Returns a string to be included at the beginning of XML output for a particular record. (just inside the opening tag). | 1.2.7 |- | [[xmlTail]] | Returns a string to be included at the end of XML output for a particular record. (just inside the closing tag). | 1.2.7 |} ====Valuelist Customization==== {| class="listing listing2" ! Name ! Description ! Version |- | [[valuelist__valuelistname]] | Defines a valuelist named ''valuelistname''. | 0.7 |} ====Importing Records==== {| class="listing listing2" ! Name ! Description ! Version |- | [[__import__filtername]] | Defines an import filter to named ''filtername'' which is used to import records into the table. | 0.7 |} RSS,Feeds,delegate classes, triggers en 0 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 xataface_templates 23 xataface_templates ==Xataface Templates== [[toc]] Xataface uses the [http://smarty.php.net Smarty Template Engine] to power all of its templates. Templates are stored in the one of the following locations: * %XATAFACE_ROOT%/Dataface/templates * %SITE_ROOT%/templates Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application. You may also have subdirectories within these templates directories. ===Cascading Templates=== Xataface uses a simple cascading technique for deciding which template to use. If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory. In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory. The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...). Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired. ===Useful Smarty Tags introduced by Xataface=== In addition to the standard set of Smarty tags, Xataface templates provide some of its own. ==Xataface Templates== Xataface uses the [http://smarty.php.net Smarty Template Engine] to power all of its templates. Templates are stored in the one of the following locations: * %XATAFACE_ROOT%/Dataface/templates * %SITE_ROOT%/templates Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application. You may also have subdirectories within these templates directories. ===Cascading Templates=== Xataface uses a simple cascading technique for deciding which template to use. If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory. In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory. The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...). Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired. ===Useful Smarty Tags introduced by Xataface=== In addition to the standard set of Smarty tags, Xataface templates provide some of its own. {| class="listing listing2" |- ! Name ! Description ! Version |- | [[templates:tags:use_macro|use_macro]] | Include another template with the option to override certain sections. | 0.6 |- | define_slot | Marks a section that can be overridden by other templates that include this one via the use_macro tag. | 0.6 |- | fill_slot | Overrides content in a template that has been included via the use_macro tag. | 0.6 |- | block | Marks an insertion point where content can be inserted by delegate classes and modules. | 0.6 |- | load_record | Loads a [http://dataface.weblite.ca Dataface_Record] object from the database to be used in the template. | 0.6 |- | group | Groups an array of records together based on a field value. | 0.6 |- | img | Displays a thumbnail of an image. | 0.6 |- | actions | Loads an associative array of actions defined in the actions.ini file, based on certain criteria. | 0.6 |- | actions_menu | Displays a menu of actions based on certain criteria. | 0.6 |- | record_actions | A specialization of the actions_menu tag. This displays a menu of actions only in the record_actions category. | 0.6 |- | record_tabs | A specialization of the actions_menu tag. This displays a menu of actions only in the record_tabs category. | 0.6 |- | result_controller | Displays the paging controls for the current table's records. Use this for any listing of records. | 0.6 |- | result_list | Displays the result list (from the list tab) for the current request. | 0.6 |- | related_list | Displays the related records list for the current request. | 0.6 |- | bread_crumbs | Displays the bread crumbs for the current request. | 0.6 |- | search_form | Displays the find form for the current table. | 0.6 |- | language_selector | Displays a menu to select the user's preferred language. | 0.6 |- | next_link | Displays a link to the next XXX records. | 0.6 |- | prev_link | Displays a link to the previous XXX records. | 0.6 |- | jump_menu | Displays the select list of the records found in this found-set so that the user can jump directly to any record. | 0.6 |- | limit_field | Displays a text field for the user to select the number of records to display per page. | 0.6 |- | result_index | Displays the index of pages (1 to XXX) for this query. | 0.6 |- | summary_list | Displays a list of records in the current found set using a summary format rather than the regular table format. | 0.6 |- | sort_controller | Displays a control to sort the results on any column. | 0.6 |- | glance_list | Displays a simple, brief list of records matching certain criteria. | 0.6 |- | record_view | Loads structured data for a record as required for the view tab. | 0.6 |- | feed | Generates a link to an RSS feed based on certain criteria. | 0.6 |- | translate | Display a section of text in the user's selected language. (i18n). | 0.6 |- | if_allowed | The contents of this block are shown only if the user has certain permissions. | 0.6 |- | editable | Make a section of the page editable using AJAX. | 0.6 |- | abs | Convert a URL into an absolute URL. | 0.6 |} ===Useful Template Variables=== Xataface makes certain variables available to every template: {| class="listing listing2" |- ! Name ! Description ! Version |- | $ENV.REQUEST | Reference to the $_REQUEST array (HTTP Request parameters, both GET and POST) | 0.6 |- | $ENV.SESSION | Reference to the $_SESSION array (the session variables) | 0.6 |- | $ENV.DATAFACE_PATH | The file system path to the Xataface directory (i.e. the directory containing all of the Xataface files such as dataface-public-api.php). | 0.6 |- | $ENV.DATAFACE_URL | The URL to the Xataface directory. | 0.6 |- | $ENV.DATAFACE_SITE_PATH | The file system path to your application directory. (i.e. the directory containing your conf.ini and index.php files). | 0.6 |- | $ENV.DATAFACE_SITE_URL | The URL to your application directory. | 0.6 |- | $ENV.DATAFACE_SITE_HREF | The URL to your application's script. This differs from the $ENV.DATAFACE_SITE_URL variable in that this also includes the script name. | 0.6 |- | $ENV.SCRIPT_NAME | Same as $ENV.DATAFACE_SITE_HREF | 0.6 |- | $ENV.APPLICATION | A reference to the application's conf array (i.e. the parsed contents of the conf.ini file). | 0.6 |- | $ENV.APPLICATION_OBJECT | A reference to the Dataface_Application object for the application. | 0.6 |- | $ENV.SERVER | A reference to the $_SERVER array. | 0.6 |- | $ENV.QUERY | A reference to the current query (i.e. Dataface_Application::getInstance()->getQuery()) | 0.6 |- | $ENV.action | The name of the current action as specified by the -action REQUEST parameter. | 0.6 |- | $ENV.table | The name of the current table as specified by the -table REQUEST parameter. | 0.6 |- | $ENV.table_object | A reference to the current table. | 0.6 |- | $ENV.relationship | The name of the current relationship as specified by the -relationship REQUEST parameter. | 0.6 |- | $ENV.limit | The value of the -limit REQUEST parameter. This is the number of records to show per page. | 0.6 |- | $ENV.start | The value of the -start REQUEST parmeter. This is the starting point in the result set which is currently being displayed. | 0.6 |- | $ENV.resultSet | A reference to the [http://dataface.weblite.ca/Dataface_QueryTool Dataface_QueryTool] object for this result set. | 0.6 |- | $ENV.record | A reference to the [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object that is matched by the current query. | 0.6 |- | $ENV.mode | The name of the current mode. e.g. find, list, browse | 0.6 |- | $ENV.language | The 2-digit ISO language code that is currently selected as the user's preferred language. | 0.6 |- | $ENV.prefs | A reference to the preferences array ($conf['_prefs']) | 0.6 |- | $ENV.search | The value of the current full-text search (i.e. the search that was entered into the upper right search field. | 0.6 |} ==Smarty Plugins== One of the most powerful features of [http://www.smarty.net Smarty] is its pluggable architecture. You can easily add your own custom plugins to a registered "plugins" directory to add functions, modifiers, blocks, and other features to your templates. Prior to Xataface 2.0, you Smarty plugins could only be placed in the ''lib/Smarty/plugins'' directory of the Xataface distribution folder. This is not very conducive to Xataface updates, though. In general it is best practice to not change anything inside the xataface directory. Most other configuration and extensions can be handled by making changes to your application's directory which override corresponding functionality in Xataface. As of Xataface 2.0, you can create a directory named ''plugins'' to your application directory, Smarty knows to look in this directory for plugins. For versions of Xataface prior to 2.0, you can make a small modification to the SkinTool to also add support as desribed in [http://xataface.com/forum/viewtopic.php?f=4&t=6722 this post]. ===Example Plugin=== The following is an example Smarty plugin adapted from [http://www.smarty.net/docs/en/plugins.functions.tpl this page] but modified slightly to work in Xataface. It is a simple "eightball" plugin that adds a tag {eightball} to Xataface that you can use in any of your templates. Whenever this tag is rendered it outputs one of a set of predefined strings randomly. # Add a ''plugins'' directory to your application directory. i.e. ''path/to/app/plugins'' # Add a file inside this ''plugins'' directory called ''<nowiki>function.eightball.php</nowiki>'' with the following content:<code> <?php /* * Smarty plugin * ------------------------------------------------------------- * File: function.eightball.php * Type: function * Name: eightball * Purpose: outputs a random magic answer * ------------------------------------------------------------- */ function smarty_function_eightball($params, Dataface_SkinTool $template) { $answers = array('Yes', 'No', 'No way', 'Outlook not so good', 'Ask again soon', 'Maybe in your reality'); $result = array_rand($answers); return $answers[$result]; } </code> # If you compare this function to the original example in [http://www.smarty.net/docs/en/plugins.functions.tpl the smarty tutorial] you'll notice that the 2nd parameter has been changed to type ''Dataface_SkinTool'' from ''Smarty_Internal_Template''. If you don't make this change, you will get a fatal error when you try to use the tag. This function defines an ''{eightball}'' tag that can be added to any Smarty template in Xataface. # Next we'll create a template that uses this tag. If your application doesn't have a ''templates'' directory, create one now (i.e. path/to/app/templates). # Add a file inside your templates directory called ''testing.html'' with the following content:<code> The eight ball says {eightball} </code> # Now we need to display this template somewhere in our interface. In this case, we'll choose the ''before_record_content'' block. (This will render the template before the main section of the view tab). Add the following method to your [[Application_Delegate_Class]]:<code> function block__before_record_content(){ df_display(array(), 'testing.html'); } </code> # Now if you load your application in a web browser and navigate to the details view for a record, you should see something like the following: <nowiki><img src="http://media.weblite.ca/files/photos/Screen_Shot_2012-04-16_at_12.33.01_PM.png?max_width=640"/></nowiki> ===See also:=== * [http://www.xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing the Look & Feel of Xataface] (From the Getting Started Tutorial) * [http://www.xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Cusomizing the Xataface Look & Feel] Tutorial templates, plugins, smarty en 0 timestamp 44 timestamp Return to [[fields.ini file]] A very simple sample of this could be your table contains the table date_created as a type of date. In your fields.ini, you would include this: <code> [date_created] timestamp=insert widget:type=hidden </code> The widget:type=hidden will make the field not visible during entry and editing. And the timestamp=insert causes the field to be filled upon insertion of a new record. ===Possible Values=== * '''update''' - Causes timestamp to be updated whenever the record is modified. * '''insert''' - Causes the timestamp to be updated only when the record is first inserted. timestamp, date, datetime en 0 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 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