tab 48 tab ==tab directive of the fields.ini file== [[toc]] The ''tab'' directive of the [[fields.ini file]] specifies which tab of the record edit form a field should be displayed on. Xataface supports multiple tabs on the edit form by way of this ''tab'' directive. If no fields contain the ''tab'' directive then all fields are displayed in a single tab (named ''__main__''). ==Example 1: Placing address info on separate tab== Consider the following ''people'' table: <code> CREATE TABLE `people` ( person_id int(11) not null auto_increment primary key, first_name varchar(32) not null, last_name varchar(32) not null, address varchar(100), city varchar(100), province varchar(100), country varchar(100), postal_code varchar(20) ) </code> We want to split the fields into two tabs: * Personal Info * Address Info ===Splitting form into tabs=== We'll do this in two steps. We use the ''tab'' directive to assign all address-related fields to the ''address_info'' tab. In the tables/people/fields.ini file: <code> [address] tab=address_info [city] tab=address_info [province] tab=address_info [country] tab=address_info [postal_code] tab=address_info </code> Now, when we load the edit form of the ''people'' table, we see two tabs: * __main__ * address_info <nowiki> <img src="http://media.weblite.ca/files/photos/Picture 9.png?max_width=640"/> <img src="http://media.weblite.ca/files/photos/Picture 10.png?max_width=640"/> </nowiki> ''__main__'' is the name assigned to the default tab (for all fields that don't have a tab defined explicitly. ===Customizing the tab labels=== Next we will customize the tab labels by adding the following to the beginning of the [[fields.ini file]]: <code> [tab:__main__] label="Personal Information" [tab:address_info] label="Address Information" </code> <nowiki> <img src="http://media.weblite.ca/files/photos/Picture 11.png?max_width=640"/> <img src="http://media.weblite.ca/files/photos/Picture 12.png?max_width=640"/> </nowiki> ===Reordering the tabs=== If we want to reorder the tabs so that the ''address_info'' tab comes first, we would just reorder the definitions of the tabs: <code> [tab:address_info] label="Address Information" [tab:__main__] label="Personal Information" </code> <nowiki> <img src="http://media.weblite.ca/files/photos/Picture 13.png?max_width=640"/> </nowiki> ===Try This Example App=== You can try this tiny sample application out [http://dev.weblite.ca/tab_test here]. en 0 Troubleshooting 49 Troubleshooting ==Xataface Troubleshooting== This document is intended to help Xataface developers through some of the most common issues. [[toc]] ==All I get is a blank white screen!== The most common issue mentioned in the forums is that an application comes up with a blank white screen in the web browser. This can happen for a number of reasons but the most common reason is because PHP has encountered a fatal error and your PHP installation is not set up to display errors. The first step to troubleshooting this problem must be to find out what the error is. You can do that in one of the following ways: # Check your Apache error log if you know where it is. One common location on many linux installations is <code> /var/log/httpd/error_log </code> but your system may have it located elsewhere. If you cannot find your error log, continue to the next option. # Turn on the ''display_errors'' flag in your ''php.ini'' file. I.e., in your ''php.ini'' file, find where it says <code> display_errors Off </code> and change it to <code> display_errors On </code>. After this is done, restart your apache webserver. If you don't know where your ''php.ini'' file is located see the section later in this document on locating your ''php.ini'' file. If you don't have access to your php.ini file, move on to the next option. # In your application's ''.htaccess'' file, add the following directives to enable displaying errors:<code> php_flag display_errors on </code> . Note that this method will only work if your apache config file allows you to override these values at the directory level. If you still get a blank white screen after this, continue to the next option. # At the beginning of your application's index.php file, add the following:<code> <?php error_reporting(E_ALL); ini_set('display_errors', 'on'); </code> . Note that if the error occurs in the parsing or compiling of your PHP files you will still get a blank screen. But this will at least display runtime errors on the page. Once you can see the error messages that caused the blank white screen you are in a much better position to solve the problem. ==Locating your php.ini file== Locating your ''php.ini'' file is actually quite easy. The quickest way is to create a php script with the following contents: <code> <?php phpinfo(); </code> then navigate to this page in your web browser. This look at the line where it says the ''php.ini file''. It will list the path there. en 0 __field__permissions 50 __field__permissions This method can be used to set the default permissions for all fields in a designated table, when specified in that table's delegate class. It comes in handy in situations when you want to deny access to all fields except for those designated, rather then specifying each field to deny individually. For example, to revoke edit permissions from all fields but one, the user must first have edit permissions to the table overall, otherwise the Edit tab/action will not appear. Then, use this __field_permissions method to revoke edit permissions from all fields. Finally, use the fieldname__permissions method (see below) to allow access to only those fields needed. === Also See: === * [[How_to_granulate_permissions_on_each_field]] * [[fieldname__permissions]] en 0 fieldgroup_template 51 fieldgroup_template ==Using a custom template for a field group on the edit form== [[toc]] Xataface allows you to partition your fields into ''groups'' so that similar fields are grouped together on the edit form. The default layout of the fields remains simply vertical, but you can customize this layout (on a per-group basis) by creating a custom template and then assigning this template to the field group with the ''template'' directive. ===Example=== For example, in your [[fields.ini file]] if you wanted to group your address fields together you might have: <code> [fieldgroup:address] label="Address Information" template="AddressInformationGroup.html" [address_1] group=address [city] group=address [state] group=address </code> Then you would add the a template named ''AddressInformationGroup.html'' to your application's ''templates'' directory to display how the fields are laid out: <code> <table width="100%"> <tr><th>Address 1:</th> <td>{$elements.address_1.html}</td> <th>City:</th> <td>{$elements.city.html}</td> <th>State:</th> <td>{$elements.state.html}</td> </tr> </table> </code> This would display all of the fields in this group in a single row (horizontally) instead of vertically. Note that this is an over-simplified example that doesn't take account for display error messages, required notices, grouped fields, and other information that you can obtain from the {$elements} array. en 0 How_to_Add_Custom_Sections_to_View_Tab 52 How_to_Add_Custom_Sections_to_View_Tab ==How to Add Custom Sections to the View tab== [[toc]] The ''View'' tab is intended to give the user a detailed view of the contents of a record. By default it shows the values of each non-empty field grouped into their appropriate field groups. It also shows the most recent 5 related records from each relationship in the record. You can also add your own sections by implementing the [[section__xxx]] method of the delegate class. ==Example 1: A "Hello World" Section== We'll start by adding a simple section that simply displays "Hello World" to the user. In the delegate class for your table, add the following method: <code> function section__hello(&$record){ return array( 'content' => 'Hello World!!!', 'class' => 'main' ); } </code> Now if you reload our application and click on the "View" tab for any of the records in the database, you'll notice a section labelled ''hello'' with the text ''Hello World!!!'' in it. Let's dissect the above code so that we can better understand what is going on here. # The function ''section__hello()'' defines a section named ''hello''. If you wanted to define a section named ''foo'' you would call the function ''section__foo()'' # This function returns an array with the keys ''content'', and ''class''. # The ''content'' key points to the actual HTML content of the section. In this case it is simply the text ''Hello World!!!''. # The ''class'' key defines where the section should be displayed. It accepts values of ''left'' and ''main'' only. If it is set to ''left'', then the section will be displayed in the left column. A value of ''main'' indicates that it should be displayed in the main column. ===Customizing the Section Label=== ''hello'' is a boring label, so let's add our own custom label by adding the ''label'' key to the array returned by our method: <code> function section__hello(&$record){ return array( 'content' => 'Hello World!!!', 'class' => 'main', 'label' => 'Message of the Day' ); } </code> Now if you load the view tab of your application, you'll notice that the section has a heading "Message of the Day". ===Customizing the Section Order=== A section can also specify an ''order'' attribute to define the order in which this section should appear. It defaults to 0 which may cause the section to appear at the top of the view tab. You can push it to the bottom of the view tab by assiging a higher number to the ''order'' attribute: <code> <code> function section__hello(&$record){ return array( 'content' => 'Hello World!!!', 'class' => 'main', 'label' => 'Message of the Day', 'order' => 10 ); } </code> Now if you reload the view tab you'll notice that the section has moved to the bottom of the page. en 0 fieldname__permissions 53 fieldname__permissions ==fieldname__permissions() method== [[toc]] The fieldname__permissions() methods will allow you to define custom permissions on a particular field in the [[delegate class]]. For example to specify permissions on a field named ''foo'' you would define the ''foo__permissions()'' method, and to define permissions on a field named ''role'' you would define the ''role__permissions()'' method. ==Example #1== (Note this example needs to be refined to be more clear) <code> function approval_level__permissions(&$record){ return array('edit'=>0); //this is will merge with what the permissions for the normal record } </code> Here we are targeting the ''approval_level'' field of the [[delegate class]]. The permissions method takes a return value an array of permissions. So for example: <code> $permissions['new'] = 0; $permissions['edit'] = 0; </code> Would be an example of an array of permissions which the key being the permission name and the value being a boolean to specify whether they have (1) or don't (0) have permissions to that field. We don't have to specify a complete array of permissions (ie. permission of edit, new, readonly, etc, etc), but rather only the ones we want specifically. The reason being that the permissions array in the return value gets merged with the permissions that this record normally gets from the record permissions. So if the record normally gives the permissions new=0, edit=1. Then the return value from approval_level will merge with the original permissions to produce an array like this: <code> $permissions['new'] = 0; $permissions['edit'] = 1; </code> === Also See: === * [[How_to_granulate_permissions_on_each_field]] * [[__field__permissions]] en 0 blob 55 blob en 0 struct 56 struct en 0 Selected_Records_Actions 58 Selected_Records_Actions ==Creating a Custom ''Selected Records'' Action== [[toc]] If you view the ''list'' tab in any of your Xataface applications, you'll notice that there is a checkbox next to each row of the list, and there are a number of actions listed at the bottom of the list that you can perform on the selected records. Xataface comes pre-built with only a few of these actions: # Delete selected # Update selected # Copy selected However it is quite easy to add your own actions here that are performed on selected records. This article describes exactly how to do this. ===What is a ''Selected Record'' action?=== A ''Selected Record'' action is no different than any other action in Xataface, except that it is meant to act on the records that have been selected in the list tab. ==Example Action: Approve Records== Consider a news site where news stories are automatically imported into the database en masse, but each news story has a field ''approved'' to indicate whether the store has been approved to appear on the site yet. The usage pattern of this application involves a lot of looking through lists of news stories and approving them. Therefore it would be convenient if the user could just select the rows that he wants to approve and click a button to approve them all. Out of the box Xataface would allow the user to select the records, click ''update selected records'', then update them all via the ''update selected records'' form. But avoiding this extra step will improve usability greatly. ===Step 1: Design the Action=== First we need to specifically decide how our action will work. In this case, the flow goes as follows: # User selects the news items they want to approve. # User clicks the ''Approve Selected'' button. (to be created) # Our action approves the selected records. # User is automatically redirected back to the list tab with a message stating how many records were successfully approved, and whether there were any errors. ===Step 2: Gather Our Tools=== Before we actually create the action, let's look at a few tools that we'll be using from the Xataface framework to make this happen. # In the [[actions.ini file]], the ''[[selected_result_actions]]'' category is reserved for actions that act on selected records of the list tab. E.g.<code> [delete_selected] ... category=selected_result_actions ... </code> # The [http://dataface.weblite.ca/df_get_selected_records df_get_selected_records()] function returns an array of [http://dataface.weblite.ca/Dataface_Record Dataface_Record] objects that represent the rows that were selected to initiate the action. E.g.<code> $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $records = df_get_selected_records($query); foreach ($records as $record){ ... } </code> # The [http://dataface.weblite.ca/checkPermission Dataface_Record::checkPermission()] method allows us to see if the current user has access to a specific permission on the given record. We'll use this method to ensure that the user has permission to approve the news record. E.g.<code> if ( !$record->checkPermission('edit', array('field'=>'approved')) ){ return PEAR::raiseError("You don't have permission to edit the approved field for this record."); } </code> # The Xataface will pass the redirect URL where your action should send the user upon completion of the action as the ''--redirect'' attribute of the ''POST'' variables. This value is base64_encoded so you'll need to decode it before redirecting. E.g.:<code> if ( @$_POST['--redirect'] ) $url = base64_decode($_POST['--redirect']); $url .= '&--msg='.urlencode($updated.' records were deleted.'); header('Location: '.$url); exit; </code> ===Step 3: Create the Action=== We will call our action ''approve_news'' so we'll place it in the ''actions/approve_news.php'' file of our application: <code> <?php class actions_approve_news { function handle(&$params){ // First get the selected records $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $records =& df_get_selected_records($query); $updated = 0; // Count the number of records we update $errs = array(); // Log the errors we encounter foreach ($records as $rec){ if ( !$rec->checkPermission('edit'), array('field'=>'approved')) ){ $errs[] = Dataface_Error::permissionDenied( "You do not have permission to approve '". $rec->getTitle(). "' because you do not have the 'edit' permission."); continue; } $rec->setValue('approved', 1); $res = $rec->save(true /*secure*/); if ( PEAR::isError($res) ) $errs[] = $res->getMessage(); else $updated++; } if ( $errs ){ // Errors occurred. Let's let the user know. // The $_SESSION['--msg'] content will be displayed to the user as a message // in the next page request. $_SESSION['--msg'] = 'Errors Occurred:<br/> '.implode('<br/> ', $errs); } else { $_SESSION['--msg'] = "No errors occurred"; } $url = $app->url('-action=list'); // A default URL in case no redirect was supplied if ( @$_POST['--redirect'] ) $url = base64_decode($_POST['--redirect']); $url .= '&--msg='.urlencode($updated.' records were deleted.'); // Redirect back to the previous page header('Location: '.$url); exit; } } </code> ===Step 4: Add the action to your actions.ini file=== The actions.ini file allows us to specify how and where this action is used, and by whom. We can specify permissions that are required to perform the action, conditions that are required to display the action, confirmation messages that are to be displayed to the user when they are about to perform the action, and more. Our [[actions.ini file]] entry looks like: <code> [approve_news] label="Approve" description="Approve selected records" permission = edit category=selected_result_actions confirm="Are you sure you want to approve the selected records?" icon="${dataface_site_url}/images/approve.gif" condition="$query['-table'] == 'news'" </code> This should be fairly straight forward. The only special items here are the ''category'' and ''confirm'' directives. The ''condition'' directive tells Xataface that this action should only be shown for the ''news'' table. The ''confirm'' directive defines a confirmation message that should be displayed to the user when they attempt to approve records. The ''icon'' directive allows you to specify the path to an icon to display for the action. In our case we have an icon located in the images directory of our application. ===Step 5: Trying it out=== Now when we go to the ''list'' tab of the ''news'' table there is an ''Approve'' button along the bottom where it says "With Selected". You we can click on this button to approve any of the selected rows. en 0 no_access_text 59 no_access_text Whenever the NO_ACCESS permission is given for a field, normally the text NO ACCESS appears. But we might want to display another text. Here is an example of the text subscribe is used instead of NO ACCESS whenever the NO_ACCESS permissions is given. <code>function no_access_text(&$record){ return "Subscribe"; } </code> en 0 widget:type_textarea 60 widget:type_textarea en 0 Customizing_the_look_and_feel_of_a_row_or_a_cell 62 Customizing_the_look_and_feel_of_a_row_or_a_cell ==How to customize the look and feel of elements in the list view== ===Create a method in a delegate class=== In the delegate class, the method ''css__tableRowClass'' is implemented, like in this example : <code>class tables_journal_interventions { function css__tableRowClass(&$record){ if ( !$record->val('fermeture')){ return 'intervention_close'; } else return ''; } } </code> Here the function tests a condition : is there a value in the field ''fermeture'' ? ===Add the class in a CSS stylesheet=== Now the class is created in a CSS stylesheet. <code>td.intervention_close { background-color: #FFE6E6 !important; } </code> This is a class for each cell, the <td> tag. The ''!important'' attribute is added to be sure that this information has precedence over all the others. It is better to add this class in a [http://xataface.com/documentation/how-to/custom_javascripts custom CSS stylesheet]. ===Remarks=== Beware that some versions of IE don't respect the background-color property on the <tr> tag, so it is probably better to write: <code> tr.intervention_close td { background-color: #FFE6E6; }</code> i.e. to apply the background color to the individual cells. en 0 How_to_granulate_permissions_on_each_field 63 How_to_granulate_permissions_on_each_field ==How to granulate permissions on each field== To reach this aim, there is the method fieldname__permissions to place into the delegate class of the table. ===Getting the role=== First it is necessary to know the user's role. For this, the method getUser() is added in the class : <code>function getUser(&$record){ $auth =& Dataface_AuthenticationTool::getInstance(); $user =& $auth->getLoggedInUser(); return $user; }</code> ===Setting up the permissions for each field=== Next, the permissions are built for each column or field where they are needed, like in this example where the method name is formed with the field name, followed by 2 underscores then by ''permissions'' : <code>function fieldname__permissions(&$record){ $the_user =$this->getUser($record); $user=$the_user->val('identifiant'); if ( !$user) return Dataface_PermissionsTool::NO_ACCESS(); if ( $user=='demande' ){ return Dataface_PermissionsTool::ALL(); } elseif ($user=='admin'){ return Dataface_PermissionsTool::ALL(); } else { return Dataface_PermissionsTool::READ_ONLY(); } }</code> === Also See === * [[viewable_editable_fields]] - How to make a field editable for some users and only viewable for some other users * [[no_access_text]] - Replace the default NO ACCESS permission text with another text. * [[__field__permissions]] - Returns the default permissions for a field of a given record. * [[Delegate_class_methods#toc5|Permissions]] - other Delegate class methods en 0 How_to_authenticate_users_with_LDAP_or_Active_Directory 64 How_to_authenticate_users_with_LDAP_or_Active_Directory ==How to authenticate users with LDAP or Active Directory== en 0 table 66 table When using widget:type table, it will store the data as XML. So the field type must be TEXT (or varchar... but text is better). You can decide which columns you want in the table by creating sub-fields in your fields.ini file as follows: Suppose you want a column called 'name' and a column called 'url' <code> [myfield] widget:type=table [myfield:name] [myfield:url] </code> Now when you access the stored value using the Dataface API, the value of myfield will be stored as an array of associative arrays. e.g. <code> foreach ( $record->val('myfield') as $vals){ echo $vals['name'].' -- '.$vals['url']; } </code> en 0 grid 67 grid ==widget:type = grid== Suppose we have two tables, tbl_organisation and tbl_individuals, in the edit view for a record in the organisations table (tbl_organisations) we also want to be able to view and edit the individuals within this organisation we can use widget:type=grid In the /tables/tbl_organisation/fields.ini we create a transient field by adding: <code> [Individuals] widget:label = "Individuals" transient=1 relationship=individuals widget:type=grid widget:columns="ind_firstname,ind_lastname,ind_tel" </code> The above assumes we have a relationship entry in our /tables/tbl_organisation/relationships.ini that looks like this: <code> [individuals] __sql__ = "SELECT * FROM tbl_individual WHERE org_id='$org_id'" </code> The fields.ini will show the three columns shown in widget:columns from the table tbl_individual Correct permissions need to be set to enable editing and deletion etc of these records. en 0 checkbox 69 checkbox ==The checkbox widget== In the [[fields.ini file]] you can specify a field to be edited using a checkbox widget by setting [[widget:type]] to [[checkbox]]. A checkbox widget can function in 2 different ways depending on the parameters that you assign to the field. [[toc]] ===Example 1: A TinyInt (boolean) field=== Suppose our table has a tinyint field named "Active" which specifies whether the record is currently in use. This field will store a value of either 0 or 1. So we configure this field in our [[fields.ini]] file to use a checkbox widget as follows: <code> [Active] widget:type=checkbox </code> Results: [[Image:http://media.weblite.ca/files/photos/Picture%2024.png?max_width=640]] ===Example 2: A repeating field (multiple checkboxes for one field=== Checkboxes can store multiple values in a single field by setting the [[vocabulary]] directive and applying it to a varchar or text field. In this case there will be one value saved per line. In this example, suppose we have a varchar field named '''categories''' which uses the '''categories''' [[valuelist]] to specify the different categories that can be checked at any given time. Our [[valuelists.ini file]] might look like: <code> [categories] __sql__ = "select id,name from categories" </code> And our [[fields.ini file]] looks like: <code> [categories] widget:type=checkbox vocabulary=categories </code> * Note that you don't need to name the field the same as the valuelist. It just worked out this way. Now if we save a record with categories 1, 3, and 5 checked, then the categories column of our row in the database will store something like: <code> 1 3 5 </code> i.e. one category id per line. Note that using this method, your database will not be normalized because you are storing multiple values in a single field. However in many applications this is sufficient. Results: [[Image:http://media.weblite.ca/files/photos/Picture%2025.png?max_width=640]] ===Example 3: Using a "Categories" relationship=== """(Note: This example requires Xataface version 1.2 or higher)""" Example 2 above shows how we can easily add and remove a record from multiple categories using checkboxes. However it required multiple pieces of information to be stored in a single database field which may or may not be advantageous for your database design. If you're looking for a more normalized database schema you would probably design your database as follows for this case: # Books table - Stores all of the books. # Categories table - Stores all of the categories # Book_Categories table - Stores mapping of books to categories. With out table structure we will first want to define a relationship from Books to Categories to reflect the connection between books and categories. The [[relationships.ini file]] for this might look like: <code> [categories] Books.Book_ID="$Book_ID" Book_Categories.Category_ID=Categories.Category_ID </code> And our [[fields.ini file]] for the Books table might look like: <code> [categories] widget:type=checkbox transient=1 relationship=categories </code> * Note that there is no need for our field to be named the same as our relationship. It just turned out this way. Also note that we used the transient=1 flag here because the Books table no longer has a categories field in the database. This field is defined purely for the benefit of the edit form so that we will get a checkbox group to select the book's categories. Results: [[Image:http://media.weblite.ca/files/photos/Picture%2025.png?max_width=640]] ==Related Parameters== # [[vocabulary]] - Assigns a valuelist to be used as the options for this checkbox group. # [[repeat]] - A boolean value indicating whether this field should be treated as a 'repeating field'. A repeating field is one with multiple checkboxes. By default the checkbox widget operates as a single checkbox that controls a boolean value. # [[relationship]] - (Only applicable to [[transient]] fields). If the [[relationship]] directive is set then this field can be used to add/remove records from a relationship. en 0 Creating_Printable_Reports 82 Creating a Custom Printable Report ==Creating a Printable Report== [[toc]] It is often useful to provide your users with a printable report that is generated from your database. Although Xataface doesn't include an explicit reporting module to allow the end users to create their own reports, you (the developer) can still quite easily produce a report by creating a custom action. This report will be subject to the user's sorting and searching preferences. E.g. if the user searches for only books about "frogs", then when he clicks on your printable report it will only display those records that match the query (i.e. only books about frogs). ===Requirements for our report=== # Report will be run against the "products" table (using the WebAuction application). # Report should be accessible by clicking an icon in the top right of the list view (i.e. the resultlist actions). # Report should display the product ID, product name, photo, and description. One product per page. ===Adding the Icon to our Application=== We'll start out by finding an appropriate icon to use for our action. There are loads of free icons that you can download (please observe and respect the license agreement of any icon library that you use). Two good free icon libraries include: # [http://www.famfamfam.com/lab/icons/silk/ FamFamFam Silk Icons] # [http://tango.freedesktop.org/Tango_Icon_Library Tango Icon Library] Once you have found the icon you want to use, just upload it somewhere inside your application's directory. It might be a good idea to create a directory to store your images if you haven't already. An appropriate name might by ''images''. For this example, we'll use the [[Image:http://dev.weblite.ca/phpimageserver/photos/icons/printer.png]] icon from the FamFamFam icon library. So we upload this icon to %APPLICATION_PATH%/images/printer.png Next we need to create an entry in our application's [[actions.ini file]] so that Xataface knows about our action, and where we want its icon to be displayed. We'll start out with a basic definition that just specifies the icon for the action, and the ''category'' of the action. <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" </code> The ''result_list_actions'' category setting means that the icon for our action will be included along with the result list actions, which are located in the top right corner in the list tab. Now if we reload our application and look at the "list" tab, you'll see that the icon group in the top right now includes our icon: [[Image:http://media.weblite.ca/files/photos/Picture%20-5.png?max_width=640]] If you don't see this icon, but see the text "printable_report" instead, then you have entered an incorrect path to the icon in the ''icon'' directive. If you don't see an icon at all or any text, then your ''category'' directive may be incorrect. Check that it is exactly "result_list_actions". If you mouse over your icon you'll see the text that you specified as your ''description'' directive for the action: [[Image:http://media.weblite.ca/files/photos/Picture%20-6.png?max_width=640]] You'll notice, if you try to click on your icon, that nothing happens. This is because we haven't yet specified a URL for your action. We'll wait to specify our URL, until we've built the back-end of our action (i.e. the actual report). ===Creating the Actual Report=== Most reports involve the following pieces: # Fetch the found set of records from the database. # Loop through the found set and output some information about each record. # Optionally use a template to integrate the report into your application's look and feel. All reports will be placed in the framework of a custom Xataface action. In our case we add a file to our application ''actions'' directory named after our action: %APPLICATION_PATH%/actions/printable_report.php with the following contents: <code> <?php class actions_printable_report { function handle(&$params){ echo "Hello world!!!"; } } </code> Please note the following about this snippet: # The action was placed in a file ''actions/printable_report.php'' because the action is named ''printable_report'' (referring to our definition in the ''[[actions.ini file]]''. If the action was named ''foo'', then we would place our action in file ''actions/foo.php''. # The ''printable_report.php'' file contains a single class named ''actions_printable_report'' after the name of the action. # The action class contains a single method ''handle'' which handles the request for the action (i.e. outputs the report the way we like). This method must exist and me named exactly ''handle''. # The ''handle'' method takes a single ''&$params'' parameter which contains some parameters that may be passed to the action. We won't be dealing with these in this example. Before proceeding, let's try accessing our action just to make sure that we're on the right track. Point your browser to http://example.com/yourapplication/index.php?-action=printable_report Note that you don't point our web browser directly to your action php file (in the ''actions'' directory. Rather you point it to your application's entry point (index.php file), and specify the action via the ''-action'' GET parameter. Your web browser should display something like: [[Image:http://media.weblite.ca/files/photos/Picture%204.png?max_width=640]] If you get a blank white screen, then you should check your error log to see where the error is occuring. See [[Troubleshooting]] for general Xataface troubleshooting strategies in this case. Now that we have all of the formalities out of the way, we can proceed to meat of our report. ====Retrieving the Found Set==== Let's build onto our action now. First we will load the found set of records as follows: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); } } </code> Things to note in this snippet: # We start be loading a reference to the ''Dataface_Application'' object. # We then use the ''Dataface_Application'' object to load the current query. This is essentially an associative array of all of the GET parameters, but with some guaranteed attributes such as ''-table'' and ''-action''. # In our particular action we are designing it to only work for the ''products'' table so we do a check on the query parameters to make sure that this is the case. If someone tries to run this action from outside the products table (e.g. if -action=foo) then an error will be displayed. # We use the df_get_records_array() function to return all matching records on the products table. It returns an array of [[Dataface_Record]] objects. ====Overriding -skip and -limit==== Xataface allows the user to specify the number of records to display and the position in the found set to start from by adding the ''-skip'' and ''-limit'' GET parameters to a request. If these are omitted, then default values of 0 and 30 are used respectively. You may notice that if you click "Next" in list view, you see '-skip' and '-limit' parameters automatically added to the URL. ''df_get_records_array'' respects the -limit and -skip parameters that are specified in the query. I.e. if -skip and -limit are omitted it will return only the first 30 records from the found set. If -skip=1 and -limit=10 then it will return 10 records starting from the 2nd record (2nd becuase -skip=0 would point to the first record). This may be desired behavior for your report, but in some reports you may want to print off the entire found set. If this is the case, you will want to explicitly set the -skip and -limit parameters in the ''$query'' array before passing it to ''df_get_records_array''. E.g.: <code> $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; $products = df_get_records_array('products', $query); </code> ====Looping through and Printing Product Info==== Now comes the fun part. We're just going to loop through our found set and print off the product information: <code> foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } </code> The entire action at this point will look like: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } } } </code> Now we refresh our action in the web browser, or point the browser again to: http://example.com/yourapplication/index.php?-action=printable_report&-table=products It should display something like: [[Image:http://media.weblite.ca/files/photos/Picture%205.png?max_width=640]] If you get a blank white screen, please check out the [[Troubleshooting]] section for general Xataface troubleshooting strategies. ====Adding a Little Style==== It is a good idea to at least provide the proper HTML HEAD and BODY tags for your report. And to help make things a little nicer looking we're going to add some CSS styles to: # Make the table field labels vertically aligned to the top. # Change the font to helvetica. This is easy to do with simple echo statements: <code> echo '<html><head>' .'<title>Printable Report</title>' .'<style type="text/css">' .' th { vertical-align: top}' .'</style>' .'</head>' .'<body>'; //... </code> So our finished action looks like: <code> <?php class actions_printable_report { function handle(&$params){ $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $query['-skip'] = 0; $query['-limit'] = 10000; if ( $query['-table'] != 'products' ){ return PEAR::raiseError('This action can only be called on the Products table.'); } $products = df_get_records_array('products', $query); echo '<html><head>' .'<title>Printable Report</title>' .'<style type="text/css">' .' th { vertical-align: top}' .'</style>' .'</head>' .'<body>'; foreach ($products as $p){ echo '<table>' .'<tr><th>Product ID</th><td>'.$p->htmlValue('product_id').'</td></tr>' .'<tr><th>Product Name</th><td>'.$p->htmlValue('product_name').'</td></tr>' .'<tr><th>Description</th><td>'.$p->htmlValue('product_description').'</td></tr>' .'<tr><th>Photo</th><td>'.$p->htmlValue('product_image').'</td></tr>' .'</table>'; } echo '</body></html>'; } } </code> ===Connecting the Icon to the Action=== FInally it is time to connect our Icon to our Action. We do this by adding a ''url'' directive for the action in the ''[[actions.ini file]]'': <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" </code> Explanation of the ''url'' directive in this snippet: * The ''url'' method of the ''[[Dataface_Application]]'' object is used to generate a URL with the user's current query settings, but with the ''-action'' parameter set to ''printable_report''. Now if we reload our application, go to the list tab of the ''products'' table and click on our icon, it should take us to our action: [[Image:http://media.weblite.ca/files/photos/Picture%207.png?max_width=640]] ===Trying out the action on different found sets with different sort orders=== One of the cool things about this action is that it is tied directly into the Xataface find settings so that th user is able to search for a subset of products and run our report on only those products that were found. The user can also perform a sort on any column and this sort will be respected by our report. ===Hiding Icon from Other Tables=== Since our action is only intended to operate on the ''products'' table it probably isn't a good idea to make the icon visible for every other table. For example, if you go to the list view of the ''users'' table, you'll see the printer icon in the top right just like it appears for the ''products'' table. Clicking on it should display our error: [[Image:http://media.weblite.ca/files/photos/Picture%206.png?max_width=640]] We will use a ''condition'' directive for our action to hide it from tables other than the ''products'' table as follows: condition="$query['-table'] == 'products'" So our action will now look like: <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" condition="$query['-table'] == 'products'" </code> Now if you reload the list for the ''users'' table you'll notice that the printer icon is now gone. But returning to the ''products'' table shows our action still alive and well. ===Locking Down our Action with Permissions=== In our case we don't want our action to be accessible to all users. Only administrators. Xataface permissions and all its possibilities are beyond the scope of this tutorial, but we still want to demonstrate how to lock down this action. The WebAuction application into which this action is being installed defines a permission called ''reports'' which only administrators have. We will use this permission to limit access to this action as follows in the actions.ini file: permission=reports So the actions.ini file will now look like: <code> [printable_report] icon="{$site_url}/images/printer.png" category=result_list_actions description="See this product list in a printable format" url="{$app->url('-action=printable_report')}" condition="$query['-table'] == 'products'" permission=reports </code> Now only administrators will see our icon, and if non-administrators attempt to access out action by typing in its URL directly, they will receive an "Access Denied" message. en http://xataface.com/documentation/how-to/site_with_backoffice_How_to_build_a_site_with_a_backoffice_ 84 A site with a backoffice ==A site with a backoffice== To create a site with a backoffice for the administrator, so that the visitors do not have to log in to read the pages, you add this code in the ApplicationDelegate.php file in the conf directory : <code> function getPermissions(&$record){ if ( isAdmin() ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::READ_ONLY(); } </code> en http://xataface.com/documentation/how-to/site_with_backoffice 85 How to build a site with an optional login form ==How to build a site with an optional login form== To publish a public site with data without any need to login to access, here is the code : <code> function getPermissions(&$record){ if ( isAdmin() ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::READ_ONLY(); } </code> In this way, you still can login to administrate your data. en site_with_backoffice 86 ==How to build a site with an optional login form== To publish a public site with data without any need to login to access, here is the code : <code> function getPermissions(&$record){ if ( isAdmin() ) return Dataface_PermissionsTool::ALL(); else return Dataface_PermissionsTool::READ_ONLY(); } </code> In this way, you still can login to administrate your data. en file 89 ==Dynamic select boxes== To create two select boxes whose one is dependent (slave) of the other (master), we need to use some javascript with Jason. Create the valuelists.ini: <code> ;valuelist for the slave [slaves_list] __sql__ = "select slave_id, slave_name, master_id from slaves" ; valuelist for the masters [masters_list] __sql__ = "select master_id,master_name from masters" </code> fields.ini: <code> [master] vocabulary=masters_list [slave] vocabulary=slaves_list </code> delegate class in the table directory : <code> ... function block__after_new_record_form(){ echo <<<END <script language="javascript"><!-- var slave_field= document.getElementById('slave'); var master_field = document.getElementById('master'); END; // Let's get all the slaves available. $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $table =& Dataface_Table::loadTable($query['-table']); $slaves = $table->getValuelist('slaves_list'); $slave_masters = $table->getValuelist('slaves_list__meta'); // Note that the slaves_list__meta valuelist is automatically created // because we had three columns in the slaves valuelist. // The first and third columns effectively create a 2nd valuelist // named 'slaves_list__meta' // $slaves is an array with keys slave_id and values slave_name // slave_masters is an array with keys slave_id and values master_id import('Services/JSON.php'); $json =& new Services_JSON(); // A JSON encoder to allow us to easily // convert PHP arrays to javascript arrays. echo ' var slaves_options = '.$json->encode($slaves).'; var slaves_master = '.$json->encode($slave_masters).'; '; echo <<<END master_field.onchange = function(){ var selected_master = master_field.options[master_field.selectedIndex].value; slave_field.options.length = 0; var index = 0; for ( slave_id in slaves_options){ if ( selected_master == slaves_master[slave_id] ){ slave_field.options[index++] = new Option(slaves_options[slave_id], slave_id); } } }; //--></script> END; } // Also place this javascript after an edit record form... function block__after_edit_record_form(){ return $this->block__after_new_record_form(); } </code> en Dynamic_select_boxes 90 ==Dynamic select boxes== To create two select boxes whose one is dependent (slave) of the other (master), we need to use some javascript with Jason. Create the valuelists.ini: <code> ;valuelist for the slave [slaves_list] __sql__ = "select slave_id, slave_name, master_id from slaves" ; valuelist for the masters [masters_list] __sql__ = "select master_id,master_name from masters" </code> fields.ini: <code> [master] vocabulary=masters_list [slave] vocabulary=slaves_list </code> delegate class in the table directory : <code> ... function block__after_new_record_form(){ echo <<<END <script language="javascript"><!-- var slave_field= document.getElementById('slave'); var master_field = document.getElementById('master'); END; // Let's get all the slaves available. $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); $table =& Dataface_Table::loadTable($query['-table']); $slaves = $table->getValuelist('slaves_list'); $slave_masters = $table->getValuelist('slaves_list__meta'); // Note that the slaves_list__meta valuelist is automatically created // because we had three columns in the slaves valuelist. // The first and third columns effectively create a 2nd valuelist // named 'slaves_list__meta' // $slaves is an array with keys slave_id and values slave_name // slave_masters is an array with keys slave_id and values master_id import('Services/JSON.php'); $json =& new Services_JSON(); // A JSON encoder to allow us to easily // convert PHP arrays to javascript arrays. echo ' var slaves_options = '.$json->encode($slaves).'; var slaves_master = '.$json->encode($slave_masters).'; '; echo <<<END master_field.onchange = function(){ var selected_master = master_field.options[master_field.selectedIndex].value; slave_field.options.length = 0; var index = 0; for ( slave_id in slaves_options){ if ( selected_master == slaves_master[slave_id] ){ slave_field.options[index++] = new Option(slaves_options[slave_id], slave_id); } } }; //--></script> END; } // Also place this javascript after an edit record form... function block__after_edit_record_form(){ return $this->block__after_new_record_form(); } </code> The 2.0 version has a [http://xataface.com/dox/modules/depselect/latest| depselect module] to produce cascading dynamic select boxes very simply. en setSecurityFilters 91 setSecurityFilter() method == Example == In the delegate class for the users table: <code> <?php class tables_users { function init(&$table){ if ( !isAdmin() ){ $table->setSecurityFilter(array('group_id'=>10)); } } } </code> This will only set the filter on non-admin users (assuming that you have defined a function isAdmin() to tell you if the current user is an admin user. en meta:class 127 meta:class relationships.ini file directive Return to [[relationships.ini file]] [[toc]] The ''meta:class'' directive allows you to ascribe special meaning to a relationship which Xataface can use in various parts of your application to provide enhanced capabilities. For example you can specify a relationship as a "parent" relationship, thereby using the relationship to obtain the "parent" of records of this table. This can be used to help build breadcrumbs. You can also specify a relationship as a "children" relationship which would treat records in the relationship as children of the current record. This can be used in conjunction with the [[list:type]]=treetable directive of the [[relationships.ini file]] to build a tree table that navigates all child records and subtrees. The Dataface_Record class contains some methods for retrieving the parent and children of records and these methods will take into account any settings you make here. ===Allowed Values=== {| class="listing listing2" |- ! Name ! Description ! Version |- | parent | Designates the relationship as a 'parent' relationship, meaning that the first record in this relationship will be treated as the parent of the current record. This setting can be overridden by the [[getParent]] method of the table delegate class if implemented. | 0.8 |- | children | Designates the relationship as a 'children' relationship meaning that records of the the relationship will be treated as a children. This setting can be overridden by the [[getChildren]] method of the table delegate class if implemented. | 0.8 |} ==See Also== # '''[[list:type]]''' - [[relationships.ini file]] directive to use a treetable for the related record list of a relationship. # '''[[getChildren]]''' - Delegate class method to explicitly define the Dataface_Record objects that are to be considered as child records of the current record. # '''[[getParent]]''' - Delegate class method to explicitly define the Dataface_Record object that is to be considered as the parent record of the current record. en list:type 128 list:type relationships.ini file directive Return to [[relationships.ini file]] [[toc]] The list:type directive allows you to override the default list that is used to display related records. As of Xataface 1.3 there is only one possible value that will have any effect on this directive: "treetable". Setting <code> list:type=treetable </code> will cause the related records to be displayed as an expandable/collapsible tree table as shown here: <nowiki><img src="http://media.weblite.ca/files/photos/Screen%20shot%202011-04-29%20at%2011.49.33%20AM.png?max_width=640"/></nowiki> ===Prerequisites=== The TreeTable component needs to be able to figure out the logical children of each record in order to know what to show when a row is expanded. You can use either the [[meta:class]] directive of the [[relationships.ini]] file to specify a relationship as a "children" relationship, or you can implement the [[getChildren]] method of the table delegate class to manually define a record's child elements. ==See Also== * [[getChildren]] * [[meta:class]] * [[getParent]] en init 140 init() Delegate Class Method == Synopsis == This method is called once, just after the table is loaded for the first time. It allows you to specify initialization details, such as [[setSecurityFilters|security filters]]. Note that it takes a single parameter: a Dataface_Table object of the table that is being initialized. == Example == <code> function init(&$table){ .... } </code> en test_page_34 177 Hello World Hello world en Clean_the_html_for_the_export 178 Clean the HTML to export data ==Clean HTML tags and entities to export your data== #Override the display() of the field to strip the tags... but this would affect all parts of the application where the HTML fields are displayed. #Create a grafted field, then override its display to show the stripped contents of the HTML area field. e.g. in the fields.ini: <code> __sql__ = "select t.*, null as stripped_field from mytable t" [original_field] widget:type=htmlarea visibility:csv=hidden [stripped_field] visibility:csv = visible visibility:list=hidden visibility:browse=hidden visibility:find=hidden </code> Then in the delegate class: <code> function stripped_field__display($record){ return html_entity_decode(strip_tags($record->val('original_field')), ENT_QUOTES, 'UTF-8'); } </code> en viewable_editable_fields 180 How to make a field editable for some users and only viewable for some other users If we want only some users to edit a field and some other users only to view that field, then we need to define a '''fieldX__permissions()''' method for that field which gives desired permissions for specific users. One solution is as below. ==permissions.ini== <code> [Field Viewer] view=1 edit=0 new=0 [Field Editor extends Field Viewer] new=1 edit=1 </code> ==TableX.php (Delegate class of TableX)== <code> function fieldX__permissions(&$record) { $user=&Dataface_AuthenticationTool::getInstance()->getLoggedInUser(); if($user) { if($user->val('usernameField')=="UserX") $role='Field Viewer'; else if($user->val('usernameField')=="UserY") $role='Field Editor'; return Dataface_PermissionsTool::getRolePermissions($role); } return Dataface_PermissionsTool::NO_ACCESS(); } </code> en