getFeed 42 getFeed ==getFeed() Delegate Class Method== [[toc]] ===Synopsis:=== The getFeed() method of a table [[Delegate class methods|delegate class]] or [[Application Delegate Class|application delegate class]] returns an associative array of parameters to configure the [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]] for a particular table . An RSS feed consists of the following components: # '''title''' - The title of the RSS feed as it should appear in the subscribers' feed list. # '''description''' - Describes the RSS feed. # '''link''' - A link to the RSS feed # '''syndicationURL''' - The URL to this RSS feed's site. ===Parameters=== # '''array''' $query - The HTTP query. Contains information like the current table, current action, and search parameters. This allows you to customize your RSS feed depending on the user's query parameters. ===Return Value=== The getFeed() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys: {| class="listing listing2" ! Name ! Description ! Version |- | title | The title for the RSS feed. If this omitted, it will try to use the ''title'' directive of the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will try to generate an appropriate title for the feed depending on the current query. | 1.0 |- | description | A Description for this RSS feed. If this is omitted, it will try to use the ''description'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |- | link | A link to the source page of the RSS feed. If this is omitted, it will try to use the ''link'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |- | syndicationURL | A link to the source page of the RSS feed. If this is omitted, it will try to use the ''syndicationURL'' directive of the ''[_feed]'' section of the [[conf.ini file]]. | 1.0 |} ===Example=== <code> function getFeed(&$query){ return array( 'title' => "RSS feed for the ".$query['-table']." table.", 'description' => "News and updates for automobiles", 'link' => df_absolute_url(DATAFACE_SITE_HREF), 'syndicationURL' => df_absolute_url(DATAFACE_SITE_HREF) ); } </code> '''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''. ===See Also:=== * '''[[getFeedItem]]''' - A delegate class method available to both the [[Delegate class methods|table delegate classes]] to configure parameters for the particular items of the RSS feed. * '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list. * '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method. * '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support. en 0 getFeedItem 41 getFeedItem ==getFeedItem() Delegate Class Method== [[toc]] ===Synopsis:=== The getFeedItem() method of a table [[Delegate class methods|delegate class]] returns an associative array of parameters for a record as it should appear as part of an [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]]. An RSS feed item consists of the following components: # '''title''' - The title of the record as it appears in the RSS feed. # '''description''' - The description of the record for the RSS feed. This is really the body of the RSS feed item. # '''link''' - The linkback URL if users want to know more about the record. # '''date''' - The date that the record was posted/modified. # '''author''' - The name of the person who posted this record. # '''source''' - URL to the site where record originated from. ===Parameters=== # '''Dataface_Record''' &$record - The record that is being represented in an RSS feed. ===Return Value=== The getFeedItem() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys: {| class="listing listing2" ! Name ! Description ! Version |- | title | The record title as it appears in RSS feeds. If this is omitted, the RSS feed will simply use the output of [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getTitle getTitle()] method. | 1.0 |- | description | The record description. This is used in the main body of the RSS feed. If this is omitted, the RSS feed will use an HTML table that shows all of the field data in the record. This value can also be overridden using the [[getRSSDescription]] method of the delegate class. | 1.0 |- | link | The URL to this record. If this is omitted it just points to the ''view'' tab for this record. However you can direct it anywhere you like. When the user clicks on the "More Info" link in his RSS reader it will direct him to this link. | 1.0 |- | date | The date that this record was posted or last modified. This is the date that an RSS reader will use to decide if it has already loaded the record yet. If this is omitted it will try the [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getLastModified getLastModified()] method to obtain the last modified date of the record. Failing that, it will use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreated getCreated()] method to try to obtain the creation date of the record. This date should be a unix timestamp. | 1.0 |- | author | The name of the user who posted this record. If this is omitted, then it will try to use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreator getCreator()] method. Failing that, it will use the value of the ''default_author'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. If that is not defined, then it simply uses the string "Site Administrator". | 1.0 |- | source | The source URL where the feed is to have originated. If none is specified, then it will use the value of the ''source'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will simply use the URL to the application. Note that you can alternatively define this value using the [[getFeedSource]] method. | 1.0 |} ===Example=== <code> function getFeedItem(&$record){ return array( 'title' => "News Item: ".$record->getTitle(), 'description' => $record->display('News Body'), 'link' => $record->getPublicLink(), 'date' => strtotime($record->val('last_modified')), 'author' => $record->val('posted_by'), 'source' => 'http://www.example.com' ); } </code> '''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''. ===See Also:=== * '''[[getFeed]]''' - A delegate class method available to both the [[Application Delegate Class]] and the [[Delegate class methods|table delegate classes]] to configure the RSS feed as a whole (not just for an individual item in the RSS feed. * '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list. * '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method. * '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support. en 0 getRegistrationActivationEmailInfo 17 getRegistrationActivationEmailInfo ==getRegistrationActivationEmailInfo() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default information that is used to send the registration activation email (the email that the user receives when they register). This should return an associative array with the keys: * subject - The subject of the activation email. * message - The message body of the activation email. * parameters - The parameters to be used in the mail() function for the activation email. * headers - The headers to use in the mail() function for the activation email. ===Signature=== function getRegistrationActivationEmailInfo( Dataface_Record &$record, string $activationURL ) : array ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ return array( 'subject' => 'Welcome to the site.. Activation required', 'message' => 'Thanks for registering. Visit '.$activationURL.' to activate your account', 'headers' => 'From: webmaster@example.com' . "\r\n" . 'Reply-To: webmaster@example.com' . "\r\n" . 'X-Mailer: PHP/' . phpversion() ); } } </code> ===Example 2: Only override the subject=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ return array( 'subject' => 'Welcome to the site.. Activation required' ); } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 getRegistrationActivationEmailMessage 19 getRegistrationActivationEmailMessage ==getRegistrationActivationEmailSubject() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default registration activation email message body (the email that the user receives when they register). ===Signature=== function getRegistrationActivationEmailSubject( Dataface_Record &$record, string $activationURL ) : string ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ return 'Thanks for registering. Please visit '.$activationURL.' to activate.'; } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 getRegistrationActivationEmailSubject 18 getRegistrationActivationEmailSubject ==getRegistrationActivationEmailSubject() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default registration activation email subject line (the email that the user receives when they register). ===Signature=== function getRegistrationActivationEmailSubject( Dataface_Record &$record, string $activationURL ) : string ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function getRegistrationActivationEmailInfo(&$record, $activationURL){ reeturn 'Welcome to the site.. Activation required'; } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[sendRegistrationActivationEmail]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] 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 group 28 group ==group directive in [[fields.ini file]]== The group directive allows you to declare that certain fields of your table should be grouped together on the edit form and the view tab (and other logical places). For example, fields like address, city, state, country, postal_code would likely be grouped together as address_info. Grouping the fields together will make the fields appear in a section of their own in the view tab and the edit form. E.g. In your fields.ini file: <code> [address] group=address_info [city] group=address_info [state] group=address_info [country] group=address_info [postal_code] group=address_info </code> ===Configuring the Group as a Whole=== You can also configure your group in the fields.ini file by adding a '''fieldgroup:NAME''' section, where '''NAME''' is the name of the group. E.g. <code> [fieldgroup:address_info] label="Address Information" description = "Please enter your address information below" </code> ====See also:==== * [[fields.ini file]] - Scroll down to the '''Field Groups''' section. en 0 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 How_to_build_a_PHP_MySQL_Application_with_4_lines_of_code 38 How to build a PHP MySQL Application with 4 lines of code '''The [http://xataface.com Xataface Application Framework] allows you to convert your existing MySQL database into a full-fledged with as little as 4 lines of code. And it's Not a code generator.''' [[toc]] This article is intended to spark interest in the [http://xataface.com Xataface Application Framework] amongst PHP developers by showing how easy it is to set up a full-featured front-end for your MySQL database. If you are a PHP developer, surly you can identify with the situation where you've built a snazzy website with PHP and MySQL but you need to create some way the website users to administer it. I.e., you need to make an administrative back-end for your users. You need to do this because PHP admin is too technical for your users, and it is an aweful lot of tedious work to create all of the necessary forms and lists for your users to edit the data themselves. ===Features for our Application=== * Create, edit and delete records using simple web forms. * Browse through database and find records without any SQL. * Lots of great widgets for editing records including html editors, select lists, grids, checkboxes, calendars and more. * Sort records. * Export result sets as CSV or XML. * Fully configurable and extendable by you to implement more [[about|features]]. ===Creating the Application=== Here are 6 steps to a full-featured front-end for your database: # Create a directory for your application on your webserver. Call it ''myapp''. # Download the latest version of [http://xataface.com Xataface] and copy it into your application directory that we just created. (i.e. ''myapp/xataface''. # Create a configuration file named ''conf.ini'' inside your application directory (i.e. ''myapp/conf.ini'') to store your database connection info:<code> [_database] host=localhost name=mydb user=username password=mypass [_tables] ;; This section lists the tables to include in your application menu table1=Label for table 1 table2=Label for table 2 </code> # Create an .htaccess (i.e. ''myapp/.htaccess'') file to prevent Apache from serving your ''conf.ini'' file:<code> <FilesMatch "\.ini$"> Deny from all </FilesMatch> </code> '''Note: If you are not using Apache as your web server you'll need to block access to the .ini files using a different mechanism. E.g. On IIS you can create a Web.config file to block this access and place it inside your application's directory.''' Download a sample Web.config file [http://weblite.ca/svn/dataface/core/trunk/site_skeleton/Web.config here]. # Create an index.php file (i.e. ''myapp/index.php'') to serve as an access point for your application:<code> <?php // Include the Xataface API require_once 'xataface/dataface-public-api.php'; // Initialize Xataface framework df_init(__FILE__, 'xataface')->display(); // first parameter is always the same (path to the current script) // 2nd parameter is relative URL to xataface directory (used for CSS files and javascripts) </code> # Create a ''templates_c'' directory to store cached smarty templates or your application (i.e. ''myapp/templates_c'', and make sure that it is writable by the webserver: $ mkdir templates_c $ chmod 777 templates_c That's all there is to it! Point your web browser to the index.php file we just made, and check out your new app! ===Screenshots of Our App=== ====Find Form==== [[Image:http://media.weblite.ca/files/photos/people-find.png?max_width=400]] ====New Record Form==== [[Image:http://media.weblite.ca/files/photos/people-new-record.png?max_width=400]] ====List View==== [[Image:http://media.weblite.ca/files/photos/people-list.png?max_width=400]] ===Where to go now=== # Sign up for the Xataface mailing list to receive exclusive development tips (see the left column for a signup form). # Check out the [[about|About Xataface]] page for more information about features and requirements. # Use the [http://xataface.com/documentation/getting_started Getting Started Tutorial] to get started making your own application. # [http://xataface.com/videos Watch screencasts] showing Xataface in action. tutorial, getting started, installation, first app, 4 lines of code 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 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 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 index_page 1 index_page ==Documentation== [[toc]] ===Introductory=== * [[about|About Xataface]] * [http://xataface.com/documentation/tutorial/getting_started Getting Started Tutorial] * [[How to build a PHP MySQL Application with 4 lines of code]] * [[Troubleshooting]] ===Reference=== * [http://dataface.weblite.ca API Docs] * [[conf.ini file]] directives * [[fields.ini file]] directives * [[valuelists.ini file]] directives * [[relationships.ini file]] directives * [[Delegate class methods]] * [[Application Delegate Class]] * [[permissions.ini file]] directives * [[actions.ini file]] directives * [[preferences|User Preferences]] - options for customizing the application further via the getPreferences() method. * [[xataface templates|templates]] * '''[[URL Conventions]]''' - Learn how to use Xataface's URL conventions to form URLs that return exactly the result set that you want. * '''[[Roadmap]]''' - What is planned for the next releases of Xataface ===Cook Book=== * [[Customizing Theme Based on IP Address]] - An article on storing IP addresses in the database and showing users a different theme depending on which range of IP addresses they are connecting from. ===By Topic=== ====Installation==== * '''[http://xataface.com/documentation/tutorial/getting_started/installation Xataface Installation Instructions]''' - This document explains how to install Xataface on your system. It does not describe how to create an application with Xataface. * '''[http://xataface.com/documentation/tutorial/getting_started/first_application Creating your first App]''' - How to create an application using Xataface (from the Getting Started Tutorial) * '''[[about|About Xataface]]''' - Quick overview of Xataface. Includes a 6 step example of creating an application with Xataface. ====Configuration==== * '''[http://xataface.com/documentation/tutorial/getting_started/customizing Customizing field labels, descriptions, and widgets]''' - This document explains how to customize some basic aspects of your application's edit forms. (From the Getting Started tutorial). * '''[http://xataface.com/documentation/tutorial/getting_started/valuelists Using Valuelists]''' - How to use valuelists to set up options for your select lists and checkbox groups. * '''[http://xataface.com/documentation/how-to/list_tab Configuring and customizing the list tab]''' - This document explains how to customize the display of the list tab using INI files, templates, and delegate classes. ====Internationalization==== * '''[[Contribute to Xataface Translation Project]]''' - We need translators to help us keep the Xataface translations up to date. This page shows how you can help. * '''[http://xataface.com/documentation/tutorial/internationalization-with-dataface-0.6 Internationalization with Xataface]''' (tutorial) * '''[http://xataface.com/documentation/how-to/how-to-internationalize-your-application How to internationalize your application]''' (how to) - Xataface 0.6 contains a LanguageTool class that allows your applications to be presented in multiple languages * '''[http://xataface.com/documentation/how-to/use-translations How to use other translations]''' - Xataface 0.7 includes German and French translations. This document explains how to allow your application to use these and other translations, rather than the default English translation. * '''[http://xataface.com/documentation/how-to/unicode How to enable unicode support]''' - As of Xataface 0.6, unicode is fully supported so that your dataface application will work with any and multiple languages simultaneously. * '''[http://weblite.ca/svn/dataface/core/trunk/lang Download latest language files out of SVN]''' - If you want to make sure that you have the latest translations, you can download them from SVN and place them into your xataface lang directory. ====User Interface Customization==== * '''[[preferences|User Preferences]]''' - You can hide, show, enable, and disable features of the application selectively. * '''[http://xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing the Look and Feel]''' - Change the way your application looks by adding custom headers, footers, and sections, and by overriding the default templates with your own custom templates. (From the Getting Started tutorial). * [[xataface templates|templates]] * '''[http://xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Customizing the Xataface look and feel]''' tutorial * '''[[Customizing the look and feel of a row or a cell| Customizing the look and feel of an element in the list view]]''' - Personnalize the aspect of each part of your list according to its content. * '''[http://xataface.com/documentation/how-to/custom_javascripts How to include custom javascripts and stylesheets]''' - Use the custom_javascripts and custom_stylesheets blocks to include your own custom javascript and CSS files in your application. * '''[http://xataface.com/documentation/how-to/hide_search How to hide the search box]''' - The full-text search box that appears in the upper right can easily be removed. * '''[http://xataface.com/documentation/how-to/list_tab Configuring and customizing the list tab]''' - This document explains how to customize the display of the list tab using INI files, templates, and delegate classes. * '''[[How to Add Custom Sections to View Tab]]''' - The ''View'' tab in a Xataface application can be configured in many ways. This tutorial shows you how to add your own custom sections to the view tab. * '''[[Creating a Dashboard]]''' - Create a dashboard action for your users to so that they have a logical starting point in your application. * '''[[Grafted fields]]''' - Add a grafted field to your table for user convenience. You can use it also to be able to sort columns with relative tables content. * '''[[Clean the html for the export]]''' - Clean the HTML tags and entities for the export in CSV or XML. ====Using the API==== * '''[[Introduction to the Xataface API]]''' - A short introduction to the classes, methods, and functions available in the Xataface API. * '''[http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields]''' ====Security==== * '''[[authentication]]''' - Overview of Xataface Authentication * '''[[registration form]]''' - Enabling User Registration in Xataface * '''[[permissions.ini file]]''' - Reference of the permissions.ini file directives. * '''[http://xataface.com/documentation/tutorial/getting_started/permissions Permissions]''' - Use sessions and delegate classes to define permissions at the record and field level. (From the Getting Started tutorial). * '''[[Cached permissions]]''' - Use cached perms for complex queries inside getPermissions() * '''[[Delegate_class_methods#toc5|Delegate class methods]]''' - Permissions-related functions * '''[[Relationship Permissions]]''' - Guide to permissions on related records. * '''[http://xataface.com/documentation/how-to/disallow_tables How to disallow access to tables]''' * '''[[site_with_backoffice]]''' - A site with a backoffice without obligation to log in * '''[http://xataface.com/documentation/how-to/security_filters Security Filters]''' - Use security filters to block users from seeing certain records. * '''[[How to granulate permissions on each field]]''' - Decide for each field who can edit, read... ** '''[[no_access_text]]''' - Replace the default NO ACCESS permission text with another text. * '''[[LDAP or Active Directory]]''' - How to authenticate users with LDAP or Active Directory... ====Performance==== * '''[http://xataface.blogspot.com/2009/06/using-query-caching-in-xataface.html Using Query Caching]''' - Query caching can drastically improve performance of busy applications with large databases. This article explains how to enable this caching in your Xataface application. * '''[[_output_cache]]''' - 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. ====Modules==== * [[modules]] - Available Xataface Modules. This includes such things as CAPTCHA validation, editable javascript grids, and more. * [[Module Developers Guide]] - A guide / Tutorial on how to develop your own Xataface modules. ====Preferences==== ====Relationships==== * '''[http://xataface.com/documentation/tutorial/getting_started/relationships Relationships]''' - Xataface allows you to define relationships between tables using the relationships.ini file. (From the Getting Started Tutorial) * '''[http://xataface.com/documentation/how-to/how-to-assign-order-to-related-records How to assign order to related records]''' - Sometimes it is desirable for the records in a relationship to take on a particular default order. Dataface 0.6 makes this easy if you follow a few conventions. * '''[[Drag and Drop Reordering of Relationships]]''' - A more in-depth tutorial about adding ordering to relationships. * '''[[relationships.ini file]] reference * '''[[Relationship Permissions]] ====Forms==== * '''[http://xataface.com/documentation/how-to/DisableEnterKeyInFields How to disable the enter key in forms]''' * '''[http://xataface.com/documentation/tutorial/getting_started/customizing Customizing field labels, descriptions, and widgets]''' - This document explains how to customize some basic aspects of your application's edit forms. (From the Getting Started tutorial). * '''[http://xataface.com/documentation/tutorial/getting_started/valuelists Using Valuelists]''' - How to use valuelists to set up options for your select lists and checkbox groups. (From the Getting Started tutorial) * '''[http://xataface.com/documentation/tutorial/getting_started/validation Form Validation]''' - Xataface allows you to add validation rules to fields using the fields.ini file. (From the Getting Started tutorial). * '''[http://xataface.com/documentation/how-to/how-to-handle-file-uploads How to handle file uploads]''' - Xataface allows you to store file uploads in BLOB fields or on the file system. * '''[http://xataface.com/documentation/how-to/custom_validation How to add custom validation with delegate classes]''' - If the standard validators (e.g., required, email, regex, etc..) don't quite cut it for your validation rules, Xataface allows you to define custom validation methods in the delegate class. * '''[http://xataface.com/documentation/how-to/regex_validation Validating with regular expressions]''' - How to validate input into a field using regular expressions. * '''[[Dynamic select boxes]]''' - How to create two dynamic javascript select boxes from the valuelists. ====Importing==== * '''[http://xataface.com/documentation/how-to/import_filters Import Filters]''' - It is common to need to import records en masse into a database. This is what import filters are for. (Since 0.7). ====Actions==== * '''[http://xataface.com/documentation/tutorial/getting_started/dataface_actions Actions I: The Basics]''' - Web Lite's actions framework allows you to customize existing actions (e.g. new, edit, find) and create your own new actions. (From the Getting Started Tutorial). * '''[http://xataface.com/documentation/how-to/after_action_triggers Adding triggers to actions]''' - Xataface 0.6.1 adds some triggers to actions so that the developer can define custom functionality to be performed after an action has successfullly taken place. * '''[[Calendar Action]]''' - Using the built-in calendar action to add a full-fledged event calendar to your application. * '''[[Creating a Dashboard]]''' - Create a dashboard action for your users to so that they have a logical starting point in your application. * '''[[Selected Records Actions]]''' - Create custom actions that are performed on records that have been selected in the list tab. * '''[[Creating Printable Reports]]''' - Create a custom printable report using a custom action. * '''[[Using RecordGrid]]''' - Using Dataface_RecordGrid to print data in tabular form. ====History==== * '''[http://xataface.com/documentation/how-to/history-howto How to activate history logging]''' - Xataface 0.6.9 comes with support for managing the history of your records. This how-to shows you how to enable and use this feature. ====RSS Feeds==== * '''[[Introduction to RSS Feeds in Xataface]]''' - Xataface provides RSS feeds to any found set in your application. This tutorial shows how it works and how you can configure these feeds to get your desired results. ====Event Calendar==== * '''[[Calendar Action]]''' - Introduction to the Xataface calendar action which can be used to convert your application into a full-fledged event calendar. en 0 Internet_Media_Manager 8 Internet Media Manager '''Manage your videos and photos all in one place''' [[toc]] ===Watch the Guided Tour (6 minutes)=== <nowiki> <embed src="http://media.weblite.ca/lib/flvplayer.swf" width="640" height="448" bgcolor="#FFFFFF" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" flashvars="file=http%3A%2F%2Fs3.amazonaws.com%2Fweblite_media%2Fintro_video.flv&image=http%3A%2F%2Fmedia.weblite.ca%2Ffiles%2Fphotos%2Fintro_video.flv.AbpY0Y.jpg&showdigits=true&autostart=false" /> </nowiki> ===Introduction=== The Internet Media Manager is a web-based database application that allows webmasters to centrally store their images and videos to be served on their website(s). It provides a Youtube-like interface whereby users can simply copy and paste code snippets to embed images and videos into their web pages. It also provides a photo gallery component that allows users to easily embed a gallery of images into their web pages by simply copying and pasting a snippet of javascript code. ===Purpose=== I created this application because: # I didn't want to have to resize images in Photoshop anymore before uploading them to the web. # I wanted to be able to embed videos, images, and photo galleries into my web pages without having to muck around with HTML code. IMM (Internet Media Manager) allows you to resize your photos to any size you want, and embed these resized images in your web pages by copying and pasting a snippet of HTML. Similarly it makes embedding videos and photo galleries into your website a snap. ===Features=== * Add/Edit/Delete/Categorize images and videos in a searchable database. * Import multiple images or videos at once by uploading a ZIP file. * Large file imports via FTP/SSH. * Embed video and images directly into other web pages by copying and pasting HTML snippets (like Youtube). * Resize images and videos. * FLV video support (like Youtube). * Search media by content type, category, keyword, etc.. * Includes javascript photo gallery component that can be embedded into any web page. * Amazon Simple Storage Service (S3) integration. ===Requirements=== * [http://www.php.net|PHP] 5.2+ * [http://www.mysql.com|MySQL] 4.1+ * [http://ca.php.net/gd|GD_Image_Processing_Library] * [http://ffmpeg.mplayerhq.hu/|FFMPEG] (optional - if you want to automatically generate poster images for videos). ===Download=== * [https://sourceforge.net/projects/immgr/files/|Internet Media Manager 0.3] ===Installation=== # Download the latest version from Sourceforge. # Extract the files and copy to your web server. # Point your web browser to the install.php and follow the instructions. ===Screenshots=== <nowiki> <script language="javascript" type="text/javascript" src="http://media.weblite.ca/index.php?-action=gallery&-table=files&categories=3&-cursor=0&-skip=0&-limit=30&-mode=list&-photo_max_width=500&--format=js"></script> <div style="clear:both"></div> </nowiki> ===Screencasts=== How to import multiple images at once in a ZIP archive. <nowiki><iframe title="YouTube video player" width="640" height="510" src="http://www.youtube.com/embed/0gfRJ5HkRsI" frameborder="0" allowfullscreen></iframe></nowiki> ===Support=== Visit the [http://xataface.com/forum/viewforum.php?f=12|Support_forum]. Internet Media Manager,resize photos,image gallery,photo gallery,video gallery 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 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 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 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 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 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 sendRegistrationActivationEmail 16 sendRegistrationActivationEmail ==sendRegistrationActivationEmail() Hook== A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the sending of an activation email to the user. ===Signature=== function sendRegistrationActivationEmail( Dataface_Record &$record, string $activationURL ) : mixed ====Parameters==== {| class="listing listing2" ! Name ! Description |- | &$record | A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration. |- | $activationURL | The URL where the user can go to activate their account. |- | returns | Mixed. If this method returns a PEAR_Error object, then registration will fail with an error. |} ===Example=== <code> <?php class conf_ApplicationDelegate { function sendRegistrationActivationEmail(&$record, $activationURL){ // mail the admin to let him know that the registration is occurring. $username = $record->val('username'); $email = $record->val('email'); mail($email, 'Welcome to the team', 'Welcome '.$record->val('username'). '. You have been successfully registered. Please visit '.$activationURL.' to activate your account' ); } } </code> ===See Also=== * [[beforeRegister]] * [[afterRegister]] * [[validateRegistrationForm]] * [[getRegistrationActivationEmailInfo]] * [[getRegistrationActivationEmailSubject]] * [[getRegistrationActivationEmailMessage]] * [[getRegistrationActivationEmailParameters]] * [[getRegistrationActivationEmailHeaders]] en 0 ShoppingCart 31 ShoppingCart ==Xataface Shopping Cart Module== [[toc]] Status: Under development Current Version: 0.2 ===Synopsis=== Add a shopping cart to your xataface application. You can treat any record as a product that can be sold. Includes Paypal connectivity, shipping calculation, and more. ===Requirements=== * Xataface 1.0 or higher * PHP 5 or higher * MySQL 4.1 or higher ===Installation Instructions=== # Download the ShoppingCart module, extract it, and place the ShoppingCart directory in your Xataface modules directory. (i.e. /path/to/xataface/modules/ShoppingCart). # Add the following line to the [_modules] section of your [[conf.ini file]]:<code> modules_ShoppingCart=modules/ShoppingCart/ShoppingCart.php </code> # Add the following to the beginning of your [[index.php file]]:<code> function __autoload($class){ if ( $class == 'ShoppingCart' ) require_once 'modules/ShoppingCart/lib/ShoppingCart/ShoppingCart.class.php'; } </code> # In the [[fields.ini file]] for any table whose records you wish to represent items for sale, add the following:<code> [__implements__] InventoryItem=1 </code> # Specify which fields should be used for the item description, price, width, height, length, and weight in the [[fields.ini file]] for each table whose records you wish to represent items for sale by adding the following directives to the appropriate fields:<code> ShoppingCart.description=1 ShoppingCart.unitPrice=1 ShoppingCart.weight=1 ShoppingCart.width=1 ShoppingCart.height=1 ShoppingCart.length=1 </code> E.g. if your table has a field named ""price"" that you want to represent the unit price, you would have something like:<code> [price] ShoppingCart.unitPrice=1 </code> The shopping cart module will make its best guess on which fields to use for these values if they are not explicitly specified. # Specify the paypal account where money should be deposited by adding the following to your application's [[actions.ini file]]:<code> [view_cart] paypal.account="youremail@example.com" </code> ===Usage Instructions=== Once the Shopping Cart module is installed you can: # Add items to your shopping cart # View your cart contents # Checkout and pay with paypal ====Adding Items to the Cart==== In the View tab of any salable record, you'll notice a little block on the left side of the page with the heading "Add Item to Cart". This includes a field to specify the quantity and a button to add the item to the shopping cart. ====Viewing Cart Contents==== The Shopping Cart module automatically introduces an action to view the cart contents. This action is named "view_cart". Hence you can always view the cart contents by entering the URL: index.php?-action=view_cart . ====Checking Out==== # View the cart contents. # Click "Check out" # This will take you to a paypal page to pay for your items. ==Actions== This module adds the following actions to your application. {| class="listing listing2" |- ! Name ! Content-type ! Description ! Version |- | checkout | text/html | Sends user to paypal to pay for the contents of their cart. | 0.1 |- | calculate_shipping | text/html | Calculates the shipping charges for the cart. | 0.1 |- | add_to_cart | text/html | Adds an item to the cart. | 0.1 |- | clear_cart | text/html | Empties the shopping cart. | 0.1 |- | get_shipping_provinces | text/json | Returns JSON array of provinces for a given country. | 0.1 |- | invoices | text/html | Displays the current user's invoices. | 0.1 |- | payment_complete | text/html | Page that is displayed after a successful payment on paypal. | 0.1 |- | paypal_ipn | none | Handles paypal events such as successful payments. | 0.1 |- | refresh_shipping_methods | text/html | Refreshes the shipping methods available to the system. | 0.1 |- | set_shipping_method | text/html | Sets the selected shipping method to a particular method. | 0.1 |- | view_cart | text/html | View the cart contents. | 0.1 |} ==Blocks and Slots== This module adds the following blocks and slots to your applications. {| class="listing listing2" |- ! Name ! Description ! Version |- | shipping_method | A block with a form to select the shipping method. | 0.1 |- | add_to_cart | A block with a form to add a record/item to the shopping cart. | 0.1 |} ==Application Delegate Class Hooks== You can modify the shopping cart behavior by defining the following methods to the application delegate class. {| class="listing listing2" |- ! Name ! Description ! Version |- | isShippingMandatory | Returns a boolean value indicating whether the user must select a shipping method. | 0.1 |- | getDefaultShippingMethod | Returns a string with the name of the default shipping method to be used. | 0.1 |} ==Table Delegate Class Hooks== You can modify the behavior of the shopping cart by defining the following methods to the delegate class of any table that implements the InventoryItem ontology (i.e. any table that is to be used to store products that can be added to the cart). {| class="listing listing2" |- ! Name ! Description ! Version |- | field__taxes | A calculated field that returns an associative array of all applicable taxes for a product. | 0.1 |} ==Internal Storage== This module creates the following tables to store its data: ===dataface__invoices=== The dataface__invoices table stores the actual invoices for purchases made. An invoice is automatically created as soon as the user "checks out". {| class="listing listing2" |- ! Column Name ! Data Type ! Description ! Version |- | InvoiceID | int(11) | Auto incrementing primary key for the invoice. | 0.1 |- | dateCreated | datetime | The date that the invoice was created. | 0.1 |- | dateModified | datetime | The date that the invoice was last modified | 0.1 |- | status | enum | The status of the invoice (either PENDING, PAID, or APPROVED). | 0.1 |- | amount | decimal(10,2) | The total amount on the invoice. | 0.1 |- | paymentMethod | varchar(32) | The name of the payment method used. | 0.1 |- | referenceID | varchar(64) | ?? | 0.1 |- | username | varchar(32) | The username of the user who owns this invoice. | 0.1 |- | firstName | varchar(32) | The first name of the payer. | 0.1 |- | lastName | varchar(32) | The last name of the payer. | 0.1 |- | address_name | varchar(100) | The name on the shipping address. | 0.1 |- | address1 | varchar(100) | The shipping address line 1. | 0.1 |- | address2 | varchar(100) | The shipping address line 2. | 0.1 |- | city | varchar(40) | The shipping address city. | 0.1 |- | province | varchar(2) | The shipping province or state. | 0.1 |- | country | varchar(2) | The shipping country. | 0.1 |- | postalCode | varchar(32) | The shipping postal code. | 0.1 |- | shipping_method | varchar(50) | The name of the shipping method to use. | 0.1 |- | phone | varchar(32) | The phone number of the payer. | 0.1 |- | email | varchar(127) | The email address of the buyer. | 0.1 |- | data | text | Serialize shopping cart data. | 0.1 |} ===dataface__shipping_methods=== Stores the available shipping methods. {| class="listing listing2" |- ! Column Name ! Data Type ! Description ! Version |- | shipping_method_id | int(11) | Auto increment ID for a shipping method. | 0.1 |- | shipping_method_name | varchar(50) | The name of the shipping method. | 0.1 |- | shipping_method_label | varchar(100) | The label for the shipping method (displayed to the user). | 0.1 |- | shipping_method_enabled | tinyint(1) | Whether or not this shipping method is currently enabled. | 0.1 |- | shipping_method_module | varchar(32) | The name of the handler that this shipping method belongs to. | 0.1 |} ==Payment Handlers== Information about payment handlers to be added here. ==Shipping Handlers== The Shopping Cart module is itself modular, allowing you to develop custom shipping handlers for different types of shipping. A shipping handler is responsible for calculating shipping costs to a destination address. Currently only a UPS shipping handler has been created, but it is not difficult to create other handlers. ===Shipping Handler Public Interface=== {| class="listing listing2" |- ! Method ! Description ! Version |- | calculateShipping | Calculates the shipping cost for the current shopping cart, and adds the shipping cost to the cart as a line item. | 0.1 |- | getInfo | Returns an array of shipping methods that can be handled by this handler. | 0.1 |} en 0 struct 56 struct en 0 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 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 templates:tags:use_macro 24 templates:tags:use_macro ==use_macro Template Tag== ===Synopsis=== The use_macro tag includes another template into the current template with the option to override certain sections. ===Parameters=== {| class="listing listing2" |- ! Name ! Description ! Version |- | file | The path the template to include (within the templates directory). | 0.6 |} ===Example=== In this example we will create a template for a user profile, but this template will include a slot that can be overridden by other templates to customize the user bio. ====user-profile.html==== <code> <html> <head> <title>User profile</title> </head> <body> <h1>User bio</h1> <div id="bio"> {define_slot name="bio"} This text will be overridden by other templates to place the correct bio information. {/define_slot} </body> </html> </code> ====steve-profile.html==== <code> {use_macro file="user-profile.html"} {fill_slot name="bio"} This is Steve's bio. It will override the text in the bio slot. {/fill_slot} {/use_macro} </code> ===See also:=== * [[xataface templates|Xataface templates]] * [[templates:tags:define_slot|The define_slot tag]] * [[templates:tags:fill_slot|The fill_slot tag]] * [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 en 0 testpage2 2 testpage2 Another test page [[testpage]] en 0 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 relationship 68 The relationship fields.ini directive [[fields.ini file|Return to fields.ini file directives]] [[toc]] ===Synopsis=== Certain types of widgets (e.g. grid (v1.0) and checkbox (v1.2)) support the relationship directive which allows them to effectively add/remove records from a specified relationship. This directive only works with transient fields. ===Example 1: Checkboxes to add/remove categories=== (Note: This example requires Xataface 1.2 or higher to work) Suppose we have a database that keeps track of courses and the branch of research that they belong to. A course can be part of multiple branches. We want to be able to select the branches that a particular course belongs to on the edit form for that course using checkboxes. Table Structure: <code> courses: course_id : int (primary key) course_title : varchar branches: branch_id : int (primary key) branch_name : varchar branch_description: text course_branches: course_id : int branch_id : int </code> Relationship definition: (from the tables/courses/[[relationships.ini file]]): <code> [branches] course_branches.course_id="$course_id" course_branches.branch_id=branches.branch_id </code> Field definitions: (from tables/courses/[[fields.ini file]]): <code> [branches] transient=1 relationship=branches widget:type=checkbox </code> Things to notice: # This is a many-to-many relationship (hence the need for the course_branches join table. # The [branches] field is a transient field. # The relationship directive from the [[fields.ini file]] references our branches relationship that was defined in the [[relationships.ini file]]. # You can call the field anything that you like. There is no need for it to have the same name as the relationship. It just turned out that way in this example. ===Example 2: Using a grid widget=== Let's modify example 1 slightly to use a grid widget instead of checkboxes. The grid widget will allow us edit the records in a relationship using dynamic table. It automatically uses the correct widget for each column of the table according to the definition in the target table's [[fields.ini file]]. Most of the definition can remain the same. We only change the [[fields.ini file]] directive: <code> [branches] transient=1 relationship=branches widget:type=grid widget:columns="branch_name,branch_description" </code> In this case we are able to edit the branch name and description in each row of the grid. ===See Also=== * [[grid|The grid widget]] * [[checkbox|The checkbox widget]] * [[relationships.ini file|The relationships.ini file]] * [[fields.ini file|The fields.ini file]] grid widget, relationship, checkbox en 0 _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