User profile


   {define_slot name=""bio""}
        This text will be overridden by other templates to place the correct
        bio information.
   {/define_slot}

====steve-profile.html====


{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}

===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.


[fieldname]
    widget:type=lookup
    widget:table=mytable

'''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.widget:filters:-limit=100 to show 100 records at a time. | 1.0 |- | widget:filters:-sort | Specifies the columns to sort the results on. E.g. widget:filters:-sort=category_name asc, year desc | 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). widget:filters:country=Canada 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. widget:filters:country_id=""$country_id"" 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:

[appointee]
    widget:type=lookup
    widget:table=contacts

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 reCAPTCHA_module,99,"The reCAPTCHA module","[[toc]] ===Synopsis=== The Xataface reCAPTCHA module CAPTCHA support to any Xataface form that is rendered to the public (i.e. when users are not logged in). This is particularly useful for the [[registration form]] as a means of spam prevention. Below is a screenshot of a registration form with the reCAPTCHA module installed: [[Image:http://media.weblite.ca/files/photos/Picture%2038.png?max_width=640]] For more information about reCAPTCHA see [http://recaptcha.net/]. ===Installation=== # Download/extract the module directory into your xataface/modules directory. Currently this module is only available in SVN (http://weblite.ca/svn/dataface/modules/reCAPTCHA/trunk/) # Add the following to the [_modules] section of your [[conf.ini file]].


[_modules]
    modules_reCAPTCHA=modules/reCAPTCHA/reCAPTCHA.php

# Add the following section to your conf.ini file.


[reCAPTCHA]
    public_key=""xxxxxxx""
    private_key=""xxxxxxx""

Where public_key, private_key are your keys from your reCAPTCHA account. '''(Note that you need to register for a free reCAPTCHA account at [http://recaptcha.net/] in order for this to work.''' ===Usage=== If you are NOT logged in, you will now see a reCAPTCHA validation image before the submit button for all webforms in your Xataface application. If you fail to enter the captcha text correctly the form will not validate. If you are logged in this module has no effect. ===See Also=== * [[registration_form|Enabling User Registration in Xataface]] * [[modules|Xataface Modules]] ","captcha, registration, validation",en, 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:


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

Relationship definition: (from the tables/courses/[[relationships.ini file]]):


[branches]
    course_branches.course_id=""$course_id""
    course_branches.branch_id=branches.branch_id

Field definitions: (from tables/courses/[[fields.ini file]]):


[branches]
  transient=1
  relationship=branches
  widget:type=checkbox

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:


[branches]
  transient=1
  relationship=branches
  widget:type=grid
  widget:columns=""branch_name,branch_description""

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","

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.

[[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]]:


[_output_cache]
    enabled=1

===How do I disable the Cache?=== Simply comment out or remove the ''[_output_cache]'' section of your [[conf.ini file]]. E.g.


;[_output_cache]
;   enabled=1

===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 timestamp,44,timestamp,"Return to [[fields.ini file]] A very simple sample of this could be your table contains the table date_created as a type of date. In your fields.ini, you would include this:


[date_created]
timestamp=insert
widget:type=hidden

The widget:type=hidden will make the field not visible during entry and editing. And the timestamp=insert causes the field to be filled upon insertion of a new record. ===Possible Values=== * '''update''' - Causes timestamp to be updated whenever the record is modified. * '''insert''' - Causes the timestamp to be updated only when the record is first inserted.","timestamp, date, datetime",en,0 GettingStarted:triggers,81,Triggers,"==Triggers== Triggers are methods that can be defined to carry out custom behaviors when certain events occur in the application (e.g., when records are saved, inserted, or deleted). Triggers are generally regarded as one of the more advanced features of database applications. Despite the ""advanced"" status of triggers, however, they are very simple to use and can be leveraged by Xataface developers to add powerful functionality to their applications. So what can you do with a trigger? * Send a confirmation email every time a new record is inserted into a table. * Delete records related to a record that is being deleted (to maintain the consistency of the database). * Add custom logging functionality. * Add extra permissions or validation rules (although these are probably better handled with the validation framework). You can really do just about anything you want with a trigger. A trigger is essentially just a custom PHP method that is called by Xataface when certain events occur. ===What triggers are available?=== As of version 0.5.3 Xataface supports the following triggers: * '''beforeSave''' : called just before a record is saved (either inserted or updated). * '''afterSave''' : called just after a record is saved (either inserted or updated). * '''beforeInsert''' : called just before a record is inserted. * '''afterInsert''' : called just after a record is inserted. * '''beforeUpdate''' : called just before a record is updated. * '''afterUpdate''' : called just after a record is updated. * '''beforeDelete''' : called just before a record is deleted. * '''afterDelete''' : called just after a record is deleted. * '''beforeAddRelatedRecord''' : called just before a related record (new or existing) is added to a relationship. * '''afterAddRelatedRecord''' : called just after a related record (new or existing) is added to a relationship. * '''beforeAddNewRelatedRecord''' : called just before a new related record is added. * '''afterAddNewRelatedRecord''' : called just after a new related record is added. * '''beforeAddExistingRelatedRecord''' : called just before an existing related record is added. * '''afterAddExistingRelatedRecord''' : called just after an existing related record is added. ===How do you define a trigger?=== Triggers are always defined as methods of the delegate class for a table. As an example, suppose we wanted to add a trigger to send a the administrator a notification email every time a new record is inserted into the 'Course' table. The steps would be as follows: # Create a delegate class for the 'Course' table (if one does not already exist) by creating a file named 'Course.php' inside the 'tables/Course' directory. # Add the following to the Delegate class file to make it a valid delegate class:


# Okay, we want our trigger to be called every time a record is inserted. There are 2 possible triggers that can be defined, then:

beforeInsert
afterInsert

In this case it is probably more appropriate to define the afterInsert trigger because we really only want to send the notification email after the insert has successfully taken place. Therefore, we will define the afterInsert() method in our delegate class as follows:


# That's all for now. The afterInsert() method defined above will automatically be called every time a record is inserted into the Course table. This method, as we have defined it, will send a notification email to the administrator email.

===Sending feedback to the user===

The above example sends the email without any feedback to the application's user of whether the email succeeded or not. When the user inserts a new Course he will only see that the record was succesfully saved, but no mention is made of the email. The following example does the same thing as the previous one, except that it sends a confirmation to the user when the email has been successfully sent:

function afterInsert(&$record){
    $response =& Dataface_Application::getResponse();
        // get reference to response array

    if ( mail('shannah@sfu.ca', 'Subject Line', 'Message Body') ){
        $response['--msg'] .= ""\nEmail sent to shannah@sfu.ca successfully."";
    } else {
        $response['--msg'] .= ""\nMail could not be sent at this time."";
    }
}


Now, when the user inserts a new record he will see a confirmation as follows:

[[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/trigger-after-insert-confirm.gif]]

Notice that we used the Dataface_Application::getResponse() function to obtain a reference to the application's response array. The response array is just a global array that is shared by the entire application that allows you to pass information easily from one part of the application to another. The '--msg' index of array is where you can place text that you wish to have displayed to the user as a confirmation.

'''Note''': It is important to use '=&' to assign the result of Dataface::getResponse() and not just '='. e.g.:

$response =& Dataface_Application::getResponse(); // correct!
$response = Dataface_Application::getResponse(); // WRONG!!


This is because we need a reference to the response array, not a copy. That way when we assign a value to the '--msg' index it is applied to the actual response array and not a copy of it.

===Handling Errors===

The above method of sending messages to the user is useful for notifications and confirmations. However, in some cases you want to inform the user that an error occurred and cancel further operations. For example you may want to disallow a record to be inserted if a confirmation email cannot be sent. In this case we define the beforeInsert() trigger and return a PEAR_Error object if the email fails as follows:



This trigger is called just before a course record is inserted into the database. If the mail succeeds, then the user sees a success message. If it fails, on the other hand, the insert is cancelled, and the user will see a message as follows:

[[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/trigger-error.gif]]


'''Note''': Notice the use of the DATAFACE_E_NOTICE constant as a second parameter for PEAR::raiseError(). This is important as without it Xataface will display a less user-friendly error message complete with stack trace. If the error is such that you want a complete stack trace, you can use the DATAFACE_E_ERROR constant instead.","triggers, beforeSave, afterSave, beforeInsert, afterInsert,sending email",en,
Troubleshooting,49,Troubleshooting,"==Xataface Troubleshooting==

This document is intended to help Xataface developers through some of the most common issues.

[[toc]]

==All I get is a blank white screen!==

The most common issue mentioned in the forums is that an application comes up with a blank white screen in the web browser.  This can happen for a number of reasons but the most common reason is because PHP has encountered a fatal error and your PHP installation is not set up to display errors.  

The first step to troubleshooting this problem must be to find out what the error is.  You can do that in one of the following ways:

# Check your Apache error log if you know where it is.  One common location on many linux installations is 
/var/log/httpd/error_log
 but your system may have it located elsewhere.  If you cannot find your error log, continue to the next option.
# Turn on the ''display_errors'' flag in your ''php.ini'' file.  I.e., in your ''php.ini'' file, find where it says 
display_errors Off
 and change it to 
display_errors On
.  After this is done, restart your apache webserver.  If you don't know where your ''php.ini'' file is located see the section later in this document on locating your ''php.ini'' file.  If you don't have access to your php.ini file, move on to the next option.
# In your application's ''.htaccess'' file, add the following directives to enable displaying errors:
php_flag display_errors on
 .  Note that this method will only work if your apache config file allows you to override these values at the directory level.  If you still get a blank white screen after this, continue to the next option.
# At the beginning of your application's index.php file, add the following:
 .  Note that if the error occurs in the parsing or compiling of your PHP files you will still get a blank screen.  But this will at least display runtime errors on the page.

Once you can see the error messages that caused the blank white screen you are in a much better position to solve the problem.

==Locating your php.ini file==

Locating your ''php.ini'' file is actually quite easy.  The quickest way is to create a php script with the following contents:


then navigate to this page in your web browser.  This look at the line where it says the ''php.ini file''.  It will list the path there.",,en,0
URL_Conventions,37,URL_Conventions,"==Xataface URL Conventions==

[[toc]]

Xataface adheres to a few simple URL conventions for all of its actions.  When you understand how Xataface URLs work you begin to get far more out of your applications.  By specifying the appropriate query parameters to can jump directly to any point in your application, or produce a specific result set.

For example, the URL ''index.php?-table=people'' will take you to the ''people'' table (and since the default action for a Xataface application is ''list'', it will take you to the ''list'' view.

You could be more explicit by specifying the action in the URL directly: ''index.php?-table=people&-action=list''.  This would take you to the same screen.  From this example, you see that you can specify such things as the table and action via GET parameters.  Xataface accepts many more GET parameters also, as you'll see in the next section.

===Available GET Parameters===


{| class=""listing listing2""
|-
! Name
! Description
! Default
! Version
|-
| -action
| Specifies the action to perform.  E.g. ''browse'', ''list'', ''find'', ''edit'', ''new'', ... etc..
| list
| all
|-
| -table
| The name of the table to use as the context table.
| The first table in the [_tables] section of your [[conf.ini file]]
| all
|-
| -skip
| Skip a certain number of results in the current found set to display.  E.g. If there are 100 records in the table and you want to start browsing from the 30th record, you would set ''-skip=29''.

Not to be confused with the ''-cursor'' parameter which is used to specify which record to view in the ''details'' tab.
| 0
| all
|-
| -limit
| The maximum number of records in the found set to display.
| 30
| all
|-
| -cursor
| The index of the record in the current found set that is treated as the ""current"" record.  This is used in the ''details'' tab to identify which record to act on.  E.g. which record to view or edit.
| 0
| all
|-
| -sort
| A comma-delimited list of columns to sort the result set on.
| null
| all
|-
| -relationship
| If we are browsing related records, this specifies the name of the relationship.
| null
| all
|-
| -related:start
| If we are browsing related records, this is the first record in the relationship to show.
| 0
| all
|-
| -related:limit
| If we are browsing related records, this is the number of records to show per page.
| 30
| all
|-
| -search
| A keyword search term to filter the found set on.  Any row containing any field that matches the query will be returned.
| null
| all
|-
| --no-query=1
| A flag to indicate that xataface should not query the database by default.  This flag is used in the new record form to prevent the form parameters from being interpreted as query parameters to search in the database.  If you set this flag, it likely result in a message saying ""No records found"".  Generally you would only use this in a custom action where you are not relying on Xataface's default found set.
| 0
| 1.3
|}

There are many other GET parameters that are used in various contexts but the above parameters are available throughout the entire application.

===Finding Records using the URL===

Notice that all of the GET parameters mentioned in the previous section begin with a hyphen (i.e. '-').  This is a convention Xataface uses to distinguish directives from search queries.  All parameters that do not begin with '-' are treated as a query to filter the found set.

For example, ''first_name=bob'' used as a GET parameter would cause the found set to be filtered so that only records where the ''first_name'' column contains the phrase ""bob"" are returned.  Putting this all together, suppose we wanted to show the list tab for the ''people'' table, but only wanted to show the people with first names containing ""bob"":

index.php?-action=list&-table=people&first_name=bob

====Exact, Range, and Pattern Matching====

By default, queries on text columns look for partial matches.  I.e. if you search for ""bob"" it will match ""bob"", ""bobby"", ""rubob"", and any other text that contains ""bob"".  If you are only interested in finding records that match ''exactly'' ""bob"", then you can prepend an ""="" to the query.  E.g. ''first_name==bob'', or the full URL:

index.php?-action=list&-table=people&first_name==bob

This should show the ''list'' tab for the ''people'' table with only records with first name exactly ""bob"".

There are a number of modifiers that you can prepend to your query to modify how it is executed.  They are as follows:

=====Search Operators=====

{| class=""listing listing2""
|-
! Prefix
! Usage Example
! Description
|- 
| >
| age=>10
| Match records greater than search parameter.
|-
| <
| age=<10
| Match records less than search parameter.
|-
| >=
| age=>=10
| Match records greater than or equal to the search parameter.
|-
| <=
| age=<=10
| Match records less than or equal to the search parameter.
|-
| ..
| age=10..20
| Match records in a given range.
|-
| =
| first_name==bob
| Match records that exactly match the search parameter (if there is no prefix then it will search for partial matches on text/varchar/char fields.).
|-
| ~
| first_name=~a%
| Exact match, but you can include wildcards such as '%' and '?' in your search.
|}


=====Search Examples=====

Given the following data set:

{| class=""listing listing2""
|-
! first_name
! age
|-
| Bob
| 10
|-
| Cindy
| 12
|-
| Julie
| 6
|-
| Jake
| 8
|-
| Kabob
| 16
|}

Here are some example queries on this data set and their results:

{| class=""listing listing2""
|-
! Query
! Matches
|- 
| age=>10 
| match records where ''age'' is greater than 10.  This includes ''Cindy'' and ''Kabob''.
|-
| age=<10 
| match records where ''age'' is less than 10.  This includes ''Julie'' and ''Jake''
|-
| age=>=10 
| match records where ''age'' is greater or equal to 10.  This includes ''Bob'', ''Cindy'', and ''Kabob''.
|-
| age=<=10
| match records where ''age'' is less than or equal to 10. This includes ''Bob'', ''Julie'', and ''Jake''.
|-
| age=8..10
| match records where ''age'' is between 8 and 10.  This includes ''Bob'' and ''Jake''.
|-
| first_name=bob
| Matches records where ''first_name'' contains ""bob"".  This includes ''Bob'' and ''Kabob''.
|-
| first_name==bob
| Matches records where ''first_name'' is exactly ""bob"".  This includes ''Bob'' only.
|-
| first_name=~J%
| Matches records that begin with ""J"".  This includes ''Jake'' and ''Julie''
|}

====Matching on Related Records====

It is also possible to match records based on their related data (i.e. data that is not physically stored in the record itself, but in related records via a relationship).  For example if we want to find authors who have written about a particular topic, we would normally have to first find all of the articles that contain a topic, and then cross-reference that result against the ''authors'' table.  With Xataface we can perform this query directly from the ''authors'' table using something like the following query:
 index.php?-table=authors&articles/title=sports
This assumes that the ''authors'' table has a relationship named ''articles'' that contains all of the articles that an author has written.  So the above query returns precisely those authors who have written at least one article whose ''title'' field contains the phrase ""sports"".


=====Anatomy of a Related Query=====

 %relationship%/%field%=%query%
This matches all records in the current table such that at least one record in its '''' relationship matches the query: ''%field%=%query%''.


====Using the ''OR'' Operator====

Xataface allows you to search for more than one value at a time using the ''OR'' operator.  E.g.
 first_name=bob+OR+steve
Would match all records with ''first_name'' containing ""bob"" or ""steve"".
 first_name=bob+OR+=steve
Would match all records with ''first_name'' containing ""bob"" or exactly matching ""steve""
 age=<10+OR+>20
Would match all records with age less than 10 or greater than 20.

====Combining Multiple Queries in One Request====

Xataface allows you to filter on more than one field at a time.  If you combine multiple queries in the same request it has the effect of strengthening the filter, matching only those rows that match ''both'' queries.  E.g.
 age=>10&first_name=bob
would match all records where ''age'' is greater than 10 '''AND''' that have ''first_name'' containing ""bob"".

=====Examples of Combined Queries=====

Given the same data set as the previous set of examples:

{| class=""listing listing2""
|-
! first_name
! age
|-
| Bob
| 10
|-
| Cindy
| 12
|-
| Julie
| 6
|-
| Jake
| 8
|-
| Kabob
| 16
|}

 first_name=bob&age=11
would return no matches because there are no records that contain both ''first_name'' ""bob"" and ''age'' 11.  However
 first_name=bob&age=10
would return only ''Bob'' and
 first_name=bob&age=16
would return only ''Kabob''.

====Special Common Queries====

=====Search For Null or Blank Value=====

Searching for a null value or a blank value is an exact match for """".  Therefore you can simply search for ""="".  E.g. To find records with a null or blank first_name you would use the query ''first_name==''.  Or the full query:
 index.php?-table=people&first_name==

=====Search for Non-blank Value=====

Searching for a non-blank value is the same as searching for a value greater than """".  Therefore you can simply search for "">"".  E.g. if you wanted to find records with a first_name, you would use the query ''first_name=>''.  Or the full query:
 index.php?-table=people&first_name=>

==Preserved vs Non-preserved Parameters==

As mentioned above any parameters that are prefixed by a hyphen (i.e. ""="") are treated as directives rather than search filters.  Hence if you want to use your own GET parameters you should always prefix them with a ""-"" to ensure that Xataface does not attempt to apply it as a search filter.  In order to keep a consistent context for users, all browsing within the same table preserves both search queries and directives.  Hence if you go to the URL:
 index.php?-table=people&-action=list&first_name=bob
It will show you the ''list'' tab of the ''people'' table with only those records with ''first_name'' ""bob"".  Now if you click on the ''details'' tab it will preserve your query ''first_name''.  The query will become something like:
 index.php?-table=people&-action=details&first_name=bob&...etc... more parameters
(Although the parameters may appear in a different order).  This allows you to navigate forward and back to previous and next records and stay within the same found set.  It also ensures that if you click on the ''list'' tab to return to the list view, it will retain your place in the list.

Note that navigating within the same table it will also preserve your directives.  E.g. If you specify the ''-limit'' directive to show 100 records per page:
 index.php?-table=people&-action=list&-limit=100
And then you click on the ''details'' tab, it will retain your ''-limit'' parameter.  Of course the ''-limit'' parameter is not actually used by the ''details'' action because it works on only one record at a time (it uses the ''-cursor'' parameter instead), when you click back on the ''list'' tab it will still show you 100 records per page.

Because of this, we call the ''-limit'' parameter a preserved parameter.  It is retained when navigating within the same table.  '''Note:''' parameters are retained in the HTTP Query string, not in sessions or cookies.  This ensures that there are no surprises when you enter a URL to your Xataface application.

===Unpreserved Parameters===

If you ''don't'' want Xataface to preserve one of your parameters, you should prefix two hyphens to the parameter name.  I.e. ""--"".  One example of an unpreserved parameters throughout Xataface applications is the ''--msg'' parameter.  The value of this parameter will be displayed on the page as an info message to the user.  Clearly you don't want this parameter preserved across requests, as you only want the user to see a message once.  E.g.
 index.php?--msg=Record+Successfully+saved.
Would didsplay the mesage ""Record Successfully Saved"" at the top of the page.  If you click on any link in the application, it will not retain the ''--msg'' parameter so you will not see the message on subsequent requests.

This parameter is useful if you want to give feedback to the user about an action that has been carried out.

===Summary===

{| class=""listing listing2""
|-
! Parameter Type
! Prefix
! Examples
! Description
|-
| Preserved
| -
| -limit, -skip, -cursor, -action, -table
| Parameter value is preserved when user navigates away from the page (within the same table).
|-
| Unpreserved Parameters
| --
| --msg
| Parameter is ''NOT'' retrained with the user navigates away from the page.
|}





","URL Conventions, GET Parameters, POST parameters, Request Parameters",en,0
Using_RecordGrid,115,"Using RecordGrid","==Xataface RecordGrid Class and Template==

Also see [http://lamp.weblite.ca/dataface-0.6/docs/index.php?-table=Classes&-action=browse&ClassID=30| RecordGrid in the API Doc].


[[toc collapse=0]]

===Introduction===
As we learned in '''[http://xataface.com/documentation/tutorial/getting_started/dataface_actions Actions I: The Basics]''', we can retrieve custom data from the DB in action via queries. This site deals with showing data in tabular form, like it could be received from even such a query. It is done by using Dataface_RecordGrid.


===First Example===

class actions_testTableAction {

	// Will be called from Xataface, if this action is called
	function handle(&$params){
		$this->app =& Dataface_Application::getInstance();  // reference to Dataface_Application object

		// Custom query
		$result = mysql_query(""select * from testTable"", $this->app->db());
		$body = ""

"";
		
		if(!$result)
		{
			// Error handling
			$body .= ""MySQL Error ..."";
		}else
		{
			while($row = mysql_fetch_assoc($result))	// Fetch all rows
			{
				// Maybe do something with the single rows
				$data[] = $row;	// Add singe row to the data
			}
			mysql_free_result($result); // Frees the result after finnished using it

			$grid = new Dataface_RecordGrid($data);	// Create new RecordGrid with the data
			
			$body .= $grid->toHTML();	// Get the HTML of the RecordGrid
		}

		// Shows the content (RecordGrid or error message) in the Main Template
		df_display(array('body' => $body), 'Dataface_Main_Template.html');
	}
}


You get your data from the query, fetch it into an associative array, create with it an RecordGrid and use the toHTML function. This is sure better than manually create the html tags around the data.

=====Screenshot: Blank RecordGrid=====




=====Screenshot: ResultList=====






===Colored Example===

As you see above, the resultlist has colored rows, our First Example not. But you can easily change this, when you override the Dataface_RecordGrid.html template:



		{foreach from=$labels item=label}
		
		{/foreach}
		
		{section name=row loop=$data}
		
			{foreach from=$columns item=col}
			
			{/foreach}
		
		{/section}
	
	
		{$label}
	
	{$data[row][$col]}



The magic happens in 
The {cycle values=""odd,even""} value cycles these two values and creates so the alternating row classes, like they are in the RecordList. By the way, {cycle ...} is a Smarty Function, see [http://www.smarty.net/docsv2/en/language.custom.functions.tpl| Smarty Doc].

(Find fruther information to template overriding in the tutorial and its links: [http://xataface.com/documentation/tutorial/getting_started/changing-look-and-feel| Changing the Look and Feel])

=====Screenshot: colored RecordGrid=====






===Example completly imitating ResultList===

The Colored Example doesn't look like the ResulList? Its rows aren't as high as theres? That's a styling matter or rather in this case a cause of the checkboxes. Here an example with checkboxes and added (empty) links, so it looks completly like the ResultList:

Change the part in action.php

			while($row = mysql_fetch_assoc($result))	// Fetch all rows
			{
				// Maybe do something with the single rows
				$row[''] = '';
				$data[] = $row;	// Add singe row to the data
			}
			mysql_free_result($result); // Frees the result after finnished using it

			$grid = new Dataface_RecordGrid($data,	// Create new RecordGrid with the data
				  array('', 'testID', 'name', 'description', 'number'),	
				//Order and selection of the colums
				  null);	// No other labels defined -> it uses keys of the associative array
			
			$body .= $grid->toHTML();	// Get the HTML of the RecordGrid


Dataface_RecordGrid.html template


		{foreach from=$labels item=label}
		
		{/foreach}
		
		{section name=row loop=$data}
		
			{foreach from=$columns item=col}
			
			{/foreach}
		
		{/section}
	
	
		{$label}
	
	{$data[row][$col]}



=====Screenshot: RecordGrid completly imitating ResultList=====





=====Screenshot: ResultList=====





===Try it out===

Use the following code with static test data and any template in this article (or even without overriding it) to try it out.


class actions_testTableAction {

	// Will be called from Xataface, if this action is called
	function handle(&$params){
		$this->app =& Dataface_Application::getInstance();  // reference to Dataface_Application object

		$result_dummy = array(
			array('testID' => '1', 'name' => 'testname', 
				'description' => 'a short description', 'number' => '258'),
			array('testID' => '2', 'name' => 'another name', 
				'description' => 'a bit longer description to this data set', 'number' => '946'),
			array('testID' => '3', 'name' => 'dummy name', 
				'description' => 'yea, a dummy data set!', 'number' => '1342'),
			array('testID' => '4', 'name' => 'not empty', 
				'description' => 'this data set isn\'t empty ...', 'number' => '282'),
			array('testID' => '5', 'name' => 'your entry', 
				'description' => 'this entry is only for you', 'number' => '79'),
			array('testID' => '6', 'name' => 'no idea', 
				'description' => 'running out of ideas ...', 'number' => '203'),
			array('testID' => '7', 'name' => 'the last one', 
				'description' => 'the end', 'number' => '26841')
		);
		$body = ""

"";
		
		foreach($result_dummy as $row)	// Fetch all rows
		{
			// Maybe do something with the singe rows
			$row[''] = '';
			$data[] = $row;	// Add singe row to the data
		}

		$grid = new Dataface_RecordGrid($data,	// Create new RecordGrid with the data
			array('', 'testID', 'name', 'description', 'number'),	
			//Order and selection of the colums
			  null);	// No other labels defined -> it uses keys of the associative array

		$body .= $grid->toHTML();	// Get the HTML of the RecordGrid

		// Shows the content (RecordGrid or error message) in the Main Template
		df_display(array('body' => $body), 'Dataface_Main_Template.html');
	}
}

","RecordGrid, Dataface_RecordGrid, data in tabular form",en,
GettingStarted:valuelists,77,"Using Valuelists","==Using Value-lists==

Value-lists serve as vocabularies that can be used for fields such as select lists, checkbox groups, and auto-complete fields.

So far we have not used any enumerated fields such as select lists, checkbox groups, or auto-completion fields in our examples. This is because we are missing a key ingredient that is required by all of these widget types: a vocabulary. We need a way to define options for these fields.

This is where 'valuelists' come into play. A valuelists is essentially a list of key-value pairs that can be used as a vocabulary in enumerated fields like checkbox groups, select lists, and auto-completion fields. Valuelists are defined in the valuelists.ini file in each table's configuration directory.

===Example 1: Use a select list for the Subject field in the Course table===

The ""Subject"" field in the ""Course"" table really shouldn't be a free-form field that will accept any value. The user should just be able to pick from a finite list of subjects in a select list. To make these changes we will follow these steps:

# Create the configuration directory for the ""Course"" table if it does not exist yet.
# Create a file named 'fields.ini' inside the Course table's configuration directory (i.e., tables/Course/fields.ini), if it does not already exist.
# Create a file named 'valuelists.ini' inside the Course table's configuration directory (i.e., tables/Course/valuelists.ini) if it does not already exist.
Your application directory structure should now look like:
[[Image:http://xataface.com/documentation/tutorial/getting_started/application-structure-valuelists.gif]]
# Edit the valuelists.ini file so that it looks like:
[Subjects]
	ENGL = English
	MATH = Math
	PHYS = Physics
	CHEM = Chemistry
 This defines a valuelist named 'Subjects' with values {ENGL, MATH, PHYS, CHEM} and associated labels {English, Math, Physics, Chemistry}. The values (i.e., ENGL, MATH, etc..) represent what will be stored in the database, and the values is a user-friendly representation that will be displayed on the screen.
# Now we edit the fields.ini file so that it looks like:
[Subject]
	widget:type = select
	vocabulary = Subjects
 This tells Xataface that we want to use a select widget to edit the ""Subject"" field, and its values should be drawn from the ""Subjects"" valuelist.
#Navigate to the ""Course"" table in our application and select ""new record"" from the ""Actions to be performed menu"" in the top left.
[[Image:http://xataface.com/documentation/tutorial/getting_started/actions-menu-1.gif]]

This will bring up a form to create a new Course record, so that we can see what the form looks like. It should look like:
[[Image:http://xataface.com/documentation/tutorial/getting_started/new-course-form-1.gif]]
Notice that the ""Subject"" field is represented by a select widget, its options are as follows:
[[Image:http://xataface.com/documentation/tutorial/getting_started/course-subject-pulldown-1.gif]]
 And if you look at the HTML source code for this select list, it would look like:



===Example 2: Using a checkbox group for the 'Subject' field===

In Example 1, we showed how to use a select list for the 'Subject' field in the 'Course' table. This is great if each course can only be one subject. But what if a course can be categorized in 2 subject areas. Then we will need a widget the allows you to select multiple items. Checkbox groups work well for this.
Make a change to the 'fields.ini' file for the 'Course' table to change the widget:type attribute of the 'Subject' field to 'checkbox' as follows:
[Subject]
widget:type = checkbox
vocabulary = Subjects


Now load the form again and notice that the 'Subject' field is now represented by checkboxes.

[[Image:http://xataface.com/documentation/tutorial/getting_started/checkbox-group-1.gif]]

You may be wondering how we store multiple values in a single field. In this case Subject is treated as a 'repeat' field where each value is on a separate line. I.e., with the form above, if we clicked 'save' and checked the values stored in the database we would see:
PHYS
CHEM


As the value in the 'Subject' field. Please note that if you are going to use a repeating field like this, you should make sure that the field is 'big' enough to store all of the values. E.g., I think my Subject field was a VARCHAR(64) (64 characters long), so the sum of the lengths of all of the values 'checked' for 'Subject' should be less than 64.

===Example 3: Dynamic Valuelists based on the results of SQL queries===

Example 1 & 2 demonstrated the basic idea of valuelists and how they can be used as values for select lists and checkbox groups. However defining valuelists ""statically"" inside the valuelists.ini file doesn't really seem to offer anything over using and ENUM or SET field in the MySQL database. In many cases we want the user to be able to choose from a number of options that are pulled from the database. For example, we may want the user to be able to specify the Program that a Course belongs to, using a pull-down list.

Recall that when we created the 'Course' table we included a field named 'ProgramID' to store the ID number of the Program that this course belongs to. It would be unreasonable to expect the users of your application to remember the ID number of the Program to which the course belongs when they are filling in the 'Course' form. It would be much better if the user could choose the program from a list of available programs. Fortunately, this functionality is simple to add:

# Add a valuelist named 'Programs' to the valuelists.ini file for the 'Course' table as follows:
[Programs]
	__sql__ = ""SELECT ProgramID, ProgramName FROM Program ORDER BY ProgramName""
 '''Note: Make sure you use two underscores on either side of 'sql' in the above example. It should be '__sql__' not '_sql_'.'''This valuelist will be a list of the records in the 'Program' table in alphabetical order on the program name. Note that this query selects 2 columns. The first column is always taken to be the ID column of the value-list and the 2nd column (if specified) is the Name column of the valuelist. The ID column is what will actually be stored in the database, and the Name column is what will be shown to the user in place of the ID.
# Add a field definition for the ProgramID field in the fields.ini file of the 'Course' table as follows:
[ProgramID]
	widget:type = select
	vocabulary = Programs


Now we can load up our form and see what it looks like:

[[Image:http://xataface.com/documentation/tutorial/getting_started/programid-select-list.gif]]

We can see that the ProgramID field now appears with a select list of all of the programs in the database. The HTML code for the select list is:


===Download Source Files===

[http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-7-tar.gz Download application source files as tar.gz archive]

These source files reflect the application's state at this point in the tutorial. As changes are made to the application in later sections, modified source archives will be available to be downloaded.

===Summary===

In this section, we have learned how to use valuelists to add selection lists and checkbox groups to our web forms. We also shows how valuelists can be dynamically defined using SQL. Using valuelists in this way is like defining a many-to-one relationship to our database (in example 3, it was many 'Course' records to one 'Program' record). In the next section we will learn how to add many-to-many and one-to-many relationships to our database in such a way that records can be easily added and removed from relationships using Xataface.","valuelists, __sql__, select lists, checkbox options,checkbox groups,vocabularies",en,
GettingStarted:using_first_app,75,"Using Your First Application","==Using Your First Application==

A Web Lite application, at its core, provides 4 standard operations: Add new records, edit existing records, delete records, and find records. This section gives a brief overview of how to use your first Dataface application.
When you first create your Xataface application and there are no records in the database, the application will look quite plain. If you point your web browser to your newly created application it will look something like:

[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-application-1.gif]]

You may be wondering why it says ""No records matched your request"" when you haven't even really made a request. This is because the 'default' request that is performed if no other request is specified is to show the first record from the first table in the navigation menu. Since there are no records, it is true that there are NO records matching the default request.
So what can you do with this application anyways? Essentially there are 4 operations you will want to perform:

# Create new records
# Edit Existing records
# Find records
# Delete records

==Basic Navigation==

The navigation tabs (aka Navigation menu) at the top left represent the tables in your database. You can navigate to any of the tables in this list by clicking on that table:

[[Image:http://xataface.com/documentation/tutorial/getting_started/navmenu-1.gif]]

There are 3 ""views"" associated with tables in the database:

* '''Details''' - Shows the details of a single record in the table
* '''List''' - Shows the records in the current ""found set"" as a list. (in a table).
* '''Find''' - Allows users to find records matching certain criteria.

You can toggle between these 3 views using the tabs at the top of the page:

[[Image:http://xataface.com/documentation/tutorial/getting_started/basic-tabs-1.gif]]

===The ""Found Set""===

Throughout this tutorial you will see the phrase ""found set"" an awful lot, so it is important to understand just what this means. A ""found set"" is the set of all records in the current table that match the current ""find criteria"". This begs the question, ""what is 'find criteria'?"". By default there is no find criteria. When you perform a search or a find on the current table, you add ""find criteria"" so that only the records satisfying these criteria will be included in the ""found set"".

For example, if you click on the ""find"" tab, you will get a search form that allows you to search for records that match certain criteria. The ""find"" tab for the ""Course"" table in our application looks like:

[[Image:http://xataface.com/documentation/tutorial/getting_started/find-form-1.gif]]

If you type in ""English"" in the ""Subject"" field and click ""Find"", then the ""found set"" will consist of only records that contain the word ""English"" in their subject fields.

On the top left of the application window there will always be a ""Found"" line that indicates how many records are currently in the found set. e.g., 

This indicates that there are 256 records in the current table (which is the 'Groups' table). There are currently only 225 records in the current ""found set"" (meaning that we have performed a ""find"" operation and it matched 225 of the records). It also indicates that the currently displayed record is record number 1 out of the 225 found records.

===The Actions Menu===

Just below the view tabs ('details', 'list', and 'find') there are a few buttons that allow you to perform actions such as create new records, clear find parameters (i.e. Show All), and delete records.

[[Image:http://xataface.com/documentation/tutorial/getting_started/actions-menu-1.gif]]

'''Descriptions:'''

* '''new record''' - Creates a new record in the current table.
* '''show all''' - Clears all find criteria on current table so that all records are shown.
* '''delete''' - Deletes the current record in the table.
* '''delete found records''' - Deletes all records in the current ""found set"". If no find criteria is specified this will delete all records in the table. 

===Creating new records===

The basic FacultyOfWidgetry application that we created in the previous section isn't very interesting when it doesn't contain any records, so let's create some Program records.

# Select the ""Program"" table by clicking on the ""Program"" option of the navigation menu.
# Click ""new record"" in the actions menu (top left).
# This will bring up a form to insert a new record that looks like: 
[[Image:http://xataface.com/documentation/tutorial/getting_started/new-record-1.gif]]
# Fill in the form and click ""Save"". If everything went OK, you will see the same form again, but with a ""success"" message at the top of the page: 
[[Image:http://xataface.com/documentation/tutorial/getting_started/successfully-saved-1.gif]]

===Editing an existing record===

The ""details"" view allows you to view details or edit the current record. There should be at least 2 sub-tabs: 'View' and 'Edit'. If you click on the 'Edit' tab, you will be presented with a form to edit the record. The form is identical to the ""create new record"" form.

===Deleting records===

If the 'list' tab is selected, then you will see a button called 'delete found records' in the actions menu (just below the view tabs). Alternatively if the 'details' tab is selected, you will see a button called simply 'delete'. 

[[Image:http://xataface.com/documentation/tutorial/getting_started/actions-menu-1.gif]]

Select ""delete"" to delete only the current record you are viewing in the ""details"" view.

Select ""delete found records"" to delete all of the records in the current found set. 

In either case, you will be prompted to confirm your decision before the records are actually deleted.

===Interface Overview===

Xataface applications provide an intuitive and consistent interface throughout. The following screenshot contains a map of some comment interface components along with some explanations:

[[Image:http://xataface.com/documentation/tutorial/getting_started/interface-schematic.png]]


Other topics
This short section is only intended to get you acquainted with the basics of Xataface applications. As your application becomes more complex with relationships and value-lists, there will be other usage scenarios of interest.","""find form"",""edit form"",""delete record"",""user interface"",ui,template,look and feel",en,
validateRegistrationForm,15,validateRegistrationForm,"==validateRegistrationForm() hook==

A hook that validates the input into the user registration form to make sure that the input is valid.

===Signature===

function validateRegistrationForm( array $values ) : mixed

====Parameters====

{| class=""listing listing2""
! Name
! Description
|-
| $values
| An associative array of the input values of the registration form.
|-
| returns
| Mixed. If this method returns a PEAR_Error object then the validation will fail - and the user will be asked to correct his input.
|}

===Example===




===Validation via the Users table Delegate class===

Note that since the registration form is just a ""new record form"" for the users table, it is also possible (and preferred) to do validation through the users [[table delegate class]].

===See Also===

* [[afterRegister]]
* [[beforeRegister]]
* [[sendRegistrationActivationEmail]]
* [[getRegistrationActivationEmailInfo]]
* [[getRegistrationActivationEmailSubject]]
* [[getRegistrationActivationEmailMessage]]
* [[getRegistrationActivationEmailParameters]]
* [[getRegistrationActivationEmailHeaders]]",,en,0
validators,95,"validators:NAME fields.ini directive","Return to [[fields.ini file]]

[[toc]]

===Synopsis===

In the fields.ini file you can specify validation rules to be applied to any field by adding the validators:NAME directive in that field's section of the [[fields.ini file]].

===Available Validators===

{| class=""listing listing2""
|-
! Name
! Description
! Value
! Version
|-
| required
| Field is required
| 1
| All
|-
| maxlength
| Maximum number of characters allowed.
| $length
| All
|-
| minlength
| Minimum number of characters allowed.
| $length
| All
|-
| rangelength
| Range (min and max) characters allows
| $min,$max
| All
|-
| email
| Input must be syntactically correct email address.
| 1
| All
|-
| emailorblank
| Accepts an email address or a blank field.
| 1
| All
|-
| regex
| Input must match the provided regular expression.
| A regular expression
| All
|-
| lettersonly
| Input must contain only letters (i.e. [a-zA-Z]
| 1
| All
|-
| numeric
| The input must contain a valid positive or negative integer or decimal number.
| 1
| All
|-
| nopunctuation
| The input must not contain any of these characters: ( ) . / * ^ ? # ! @ $ % + = , "" ' > < ~ [ ] { }.
| 1
| All
|-
| nonzero
| The input must not begin with zero.
| 1
| All
|-
| uploadedfile
| The element must contain a successfully uploaded file.
| 1
| All
|-
| maxfilesize
| The uploaded file must be no more than $size bytes.
| $size
| All
|-
|filename
| The uploaded file must have a filename that matches the regular expression $file_rx.
| $file_rx
| All
|}


===Examples===

To make a the first_name field required we add the following to the [[fields.ini file]]:

[first_name]
    validators:required=1


'''Note that fields that are declared NOT NULL in the database are required by default.'''.  If you wanted to remove the ''required'' validator from a field that is NOT NULL in the database you would add the following to the [[fields.ini file]]:

[first_name]
    validators:required=0


===See Also===

* [[fieldname__validate]] - For more complex validation you can define the [[fieldname__validate]] method in the [[Delegate class methods|Table Delegate Class]].
* [http://www.devarticles.com/c/a/Web-Graphic-Design/Using-HTML-Quickform-for-Form-Processing/12/ HTML_QuickForm article] going over HTML_Quickform validation.  Dataface's forms are built on HTML_QuickForm.
* [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section from getting started tutorial introducing form validation in a tutorial format.

","validation, form validation, validators,validator:name",en,
validators:VALIDATOR_NAME:message,96,"validators:VALIDATOR_NAME:message directive for the fields.ini file","Return to [[fields.ini file]]

[[toc]]

===Synopsis===

If you want to customize the error message associated with a particular [[validator|validation rule]] you can use the validators:VALIDATOR_NAME:message directive in the fields.ini file.

===Format===


[myfield]
    validators:VALIDATOR_NAME:message = MESSAGE


===Examples===

If you don't like the default error message that is displayed when you make the first_name field required, you can customize it with your own message.  E.g.

[first_name]
    validators:required=1
    validators:required:message = ""Please enter your first name""


===See Also===

* [[validators]] - The [[fields.ini file]] directive for adding a validation rule to a field.  This directive must be used in conjunction with [[validators]].
* [[fieldname__validate]] - For more complex validation rules you can define them in the table delegate class.
* [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section in the Getting Started tutorial on form validation.","validation messages,error messages,form validation rules",en,
valuelists.ini_file,5,valuelists.ini_file,"==valuelists.ini file Reference==

[[toc]]

The valuelists.ini file stores value lists that can be used as [[vocabulary|vocabularies]] for select lists, checkbox groups, and other widgets the provide the user with options to choose from.

Each table can have an associated valuelists.ini file located in its [[table configuration directory]]. E.g. for a table named ""people"" its valuelists.ini file will be stored in ""tables/people/valuelists.ini"".

In addition you can define an application-wide valuelists.ini file in the root of your application's directory, whose valuelists can be used by any table.

===Syntax===

The valuelists.ini file uses [[INI file syntax]], where a valuelist is defined by a single section of the INI file.  E.g.


[colors]
    r=Red
    b=Blue
    g=Green


This example would define a single valuelist named ""colors"" with 3 values: r,g, and b (with corresponding labels ""Red"", ""Green"", and ""Blue).  The values (the left of the equals sign) are stored in the database, while the labels are rendered on screen for the user's convenience.

===Dynamic Valuelists===

It is often advantageous to load valuelists from the database rather than store them directly in the valuelists.ini file.  The __sql__ directive allows you to specify an SQL query which selects up to 2 columns (the first is the id and the second, the label).

E.g.


[colors]
    __sql__ = ""select colorCode, colorName from colors""



===Defining Valuelists in a Delegate Class===

If you require more flexibility with the definition of your valuelists than can be gained from the valuelists.ini file, you can define your valuelist using PHP inside a delegate class.  Essentially you just create a method that returns an associative array, where the keys are the IDs that are stored in the database, and the values are the values that are visible in the select list.

e.g.  In either the application delegate class or a table delegate class:


function valuelist__colors(){
    return array(
        'r'=>'Red',
        'g'=>'Green',
        'b'=>'Blue'
    );
}


This method is called each time the valuelist is about to be used, so if your method performs any sort of intensive processing, it is a good idea to use a caching scheme so that it only runs the critical code once per request.  For example, you could use a static variable as follows:


function valuelist__colors(){
    static $colors = -1;
    if ( !is_array($colors) ){
        $colors = array();
        $res = mysql_query(""select colorCode, colorName from colors"", df_db());
        if ( !$res ) throw new Exception(mysql_error(df_db()));
        while ($row = mysql_fetch_row($res) ) $colors[$row[0]] = $row[1];
    }
    return $colors;
}


In this example the database query is only executed once per request to load the $colors variable.  The rest of the time it simply loads the cached value from $colors.","valuelists, dynamic valuelists, programmatically defined valuelists",en,0
visibility:fieldName,47,visibility:fieldName,"==Example==

visibility:ConferenceID = hidden

This will make the ConferenceID in the relationship list view disappear.",,en,0
GettingStarted:Why_Use_Xataface,72,"Why Use Xataface","==Why Use Xataface?==

Some simple examples similar to those that are frequently encountered by web developers, and how dataface can be used to acheive a solution.
As a web services developer in the Faculty of Applied Sciences at Simon Fraser University, I am frequently getting requests to build websites that are manageable by the site owner. Most of these requests also specify certain types of content that must be stored on the website, and much of this content needs to be n-ary (i.e., there will be multiple instances of each type of content). Let me give you an example.

===Example 1: Website for Faculty of Widgetry===

The Faculty of Widgetry needs a website to publish information about its undergraduate programs. It is important for them to be able to publish admission requirements, and program overviews for each program. It is also important to have course outlines and timetables for each course. The Faculty of Widgetry has 12 undergraduate programs and over 100 courses offered.

====Solution 1: Static HTML====

To build this web site using only static HTML pages using Dreamweaver or some other HTML editor would require at least 112 pages to be created (one for each course and program). However, once we recognize that there are only 2 types of pages required (one for courses and one for programs), we can reduce the task down to creating 2 templates and filling in the main content for each program and course individually. Most HTML editors have some templating ability so you can make changes to the template and have the changes propogated to all pages that use that template with the click of a button.

This works great, but courses are added frequently, and outlines are changed. Do you really want to receive requests to update all of these pages every time there are changes to make? (If your answer is 'yes', then you probably won't be interested in reading the rest of this tutorial). Whether the Dean of the faculty knows it or not, it is very important for the program assistants to be able to update these web pages on their own. To acheive these goals you can:

* Install Dreamweaver on the Program Assistants' computers, teach them how to use it, and allow them to perform updates.
* Install Contribute, which is a scaled down version of Dreamweaver to make it easier for the Program Assistants to edit the content.
* Use another solution that is equivalent to one of the above 2 solutions.

Installing Dreamweaver for each Program Assistant is a little overkill, and since it has the ability to do much more than just update content. In addition, Dreamweaver is really a developer's tool - not a secretary's tool, so it can be difficult to learn at first. The best reason NOT to install Dreamweaver on the Program Assistant's computer, however, is that it enables him/her to muck things up by accident (believe me, I has happened to me more times than I care to count).

Admittedly, Contribute is a viable option as it controls access to only certain portions of web pages to be edited, and it is targetted at secretaries (not developers) so it is easier to use. In fact, given the requirements for this web site (as stated above), this is a perfectly good solution. However you better hope that none of the following requirements are added:

* Each program web page should contain an up-to-date list of all of the courses required for the program, along with a link to the course outline for that course.
* Course outlines should be available in PDF format as well as HTML format.
* An index page showing all of the courses available should be added. This page must allow courses to be organized by program, course subject, or course number.
* Any other requirement that would have information formatted in more than one way.

If any of these requirements are likely to be added (EVER) then you would be well-advised to look into solutions that use a database back-end.

====Solution 2: Use a Content Management System (CMS)====

There are hundreds of content management systems available that will allow you to store and update content through the web (TTW). Some of them even have an assortment of add-ons that will allow you to store more specific types of information. Some good CMS's include Plone, Drupal, and Xoops. Suppose we want to develop the Faculty of Widgetry website using one of these CMS's. Any good CMS will allow you to create and edit HTML documents easily (without having to write any custom products). However, it is often the case that our documents require the content to be structured. For example, each program has some common data associated with it: Program Name, Admission Deadline, Program Description, Outline, Courses, etc... If we want to properly separate data from presentation, we would need to build a special content-type to store our programs. Most CMS's allow you to develop custom content-types using the underlying programming language and an API (Application Programming Interface). Some API's are easier to use than others and some are documented better than others. The common element is that each has its own proprietary interface for writing these add-ons.

If you are using a CMS and you are proficient in the creation of add-on content-types, then you will be able to build the Faculty of Widgetry website without great difficulty. However there are a number of reasons why you may choose NOT to use a CMS:

* Steep learning curve: Depending on the CMS it can be very time consuming and difficult to learn how to use and modify the CMS to suit you purposes.
* It is over-kill: Most CMS's are filled with features and modules that you will never need. In fact it can even be a pain to turn them off if you don't want them.
* You can get tied into the CMS: When you are using a CMS, you will start developing for the CMS. With all of your content in the CMS it may be difficult to migrate to a different solution later on. (The truth of this statement will vary for different CMS's). Choose your CMS carefully.

====Solution 3: Use an existing Application====

OK, OK, let's not get too carried away with trying to develop the website until we have checked the market to see if someone else has already done it better. Maybe there is already a PHP application that makes websites for Faculties easy. I mean, I can't be the first person that needed to build a website for a Faculty. In fact if you do a search or go to Hotscripts.com, you will probably find a handful of applications or scripts that almost do what you need. If you're lucky, maybe you can find an application that does exactly what you need (but frankly, I've never been that lucky). If you find one, maybe it's worth taking it for a test drive. But beware. Using a system that almost does what you need but is difficult to modify to your needs can be worse than building it by scratch. Make sure that you are able to modify the application to suit your needs exactly.

====Solution 4: Use PHP and MySQL====

If all we want to do is separate the data from the presentation and allow the Program Assistants to update data on the website, why not just design a MySQL database with the appropriate tables and fields to store the required data. In our case we will need 2 tables:

'''Programs''': 

* Fields:
** ProgramID : int
** ProgramName : varchar
** ProgramDescription: text
** AdmissionDeadline: date
** Outline_HTML : text
** Outline_PDF : blob


'''Courses''':
* Fields:
** CourseID : int
** CourseSubject : varchar
** CourseTitle : varchar
** CourseNumber : int
** ProgramID : int
** CourseDescription : text
** Outline_HTML : text
** Outline_PDF : blob


Now it's easy to create a few web pages that extract data from the database and displays it as HTML. In fact if there is an existing page template that you can use for the header and footer, you can develop the entire Faculty website in under an hour (you just have to create 3 pages).

'''Question''': How will the Program Assistants update the information in the database?

'''Answer''': OK, let's assume that you're not going to teach them SQL and that a DB Admin tool will also be too difficult to learn. Then you have to create HTML forms to update records in the database.

Ouch! What was easy just became hard. Making HTML forms is a real pain, because you have to validate the input, deal with file uploads, and also make sure that everything is stored to the database OK without losing any information. Such a basic task, but it can be very difficult. This is when it is time to use Xataface.

====Solution 5: Use Xataface====

OK, this isn't really its own solution. It is more like ""Solution 4 Part II"", because Xataface is intended to complement your custom application you built with solution 4, by providing an easy-to-use, configurable user interface that is targeted at secretaries and normal users (as opposed to database administrators). A Xataface application takes only seconds to set up and it will provide you with a full user interface for your users to edit information in the database.","introduction motivation why",en,
widget:atts,46,widget:atts,"==widget:atts Directive Reference==

The widget:atts directive in the fields.ini file allows any arbitrary HTML attributes to be added to any of the fields.  It may also be used to specify javascript event handler functions that the widget should call upon the specified event.  In particular, here are some examples of possible widget:atts directives:

===Available Widget Event Handlers===

{| class=""listing listing2""
|-
! name
! description
! version
|-
| [[field_size|widget:atts:size]]
| This directive sets the length of the input area a text box field, but it does not limit the number of characters that can be entered.  For example: 
widget:atts:size = 50
| ?
|-
| [[field_maxlength|widget:atts:maxlength]]
| This directive limits the maximum number of characters that can be entered into a text box field.  For example: 
widget:atts:maxlength = 25
| ?
|-
| [[field_style|widget:atts:style]]
| This directive specifies the style (font-size, font-family, etc.) for the field.  For example: 
widget:atts:style = ""font-size: 24pt; font-family: Apple Chancery""
| ?
|-
| [[field_rows|widget:atts:rows]]
| This directive specifies the number of rows for a text area field to display.  For example: 
widget:atts:rows = 10
| ?
|-
| [[field_cols|widget:atts:cols]]
| This directive specifies the number of columns for a text area input field (1 character = 1 column).  For example: 
widget:atts:cols = 10
| ?
|-
| [[field_javascript_onchange|widget:atts:onchange]]
| This directive will cause the specified javascript function to be called with the value of the field whenever its value is changed (i.e. when you change the field and tab out of it).  For example: 
widget:atts:onchange = ""doJsFunction();""
| ?
|-
| [[field_javascript_onclick|widget:atts:onclick]]
| This directive will cause the specified javascript function to be called with the value of the field whenever it is clicked.  For example: 
widget:atts:onclick = ""doJsFunction();""
| ?
|}

===Helpful tutorials===

See the bottom of this page in the Getting Started tutorial for more details on the basic directives above:

[http://xataface.com/documentation/tutorial/getting_started/customizing Customizing Field labels, descriptions, and widgets]

This tutorial talks about how to use the javascript directives:

[http://xataface.com/documentation/how-to/custom_javascripts]",,en,0
widget:editor,35,widget:editor,"==widget:editor fields.ini directive==

Return to [[fields.ini file]]

[[toc]]

The widget:editor directive is applicable in the [[fields.ini file]].  It specifies the type of HTML editor that should be used.  This directive is only used when [[widget:type]] is set to [[widget:type htmlarea|htmlarea]].  Xataface currently supports FCKEditor, TinyMCE, and NicEdit.

===Allowed Values===

{| class=""listing listing2""
|-
! Value
! Description
! Version
|-
| fckeditor
| Use [http://www.fckeditor.net/ FCKEditor].  This is the default value.
| all
|-
| tinymce 
| Use [http://tinymce.moxiecode.com/ TinyMCE editor].
| 0.6
|-
| nicedit
| Use [http://www.nicedit.com/ NicEdit].
| 1.0.5
|}

===Examples===

====Example 1: Using FCKEditor====

Given a field 'content' that you wish to be able to edit with FCKEditor, you would have the following section in your [[fields.ini file]]:


[content]
    widget:type=htmlarea
    widget:editor=fckeditor


Note that since FCKEditor is the default editor, the above would give the same result as:


[content]
    widget:type=htmlarea


====Example 2: Using TinyMCE====

Further from example 1, if we wanted to use TinyMCE editor, we would change our directive to:


[content]
    widget:type=htmlarea
    widget:editor=tinymce


====Example 3: Using NicEdit====

Further from example 1:


[content]
    widget:type=htmlarea
    widget:editor=nicedit


==Enabling Image Uploads==

By default image uploads are disabled in these WYSIWYG editors.

===Enabling Image Uploads in FCKEditor===

# Create a directory named ''uploads'' inside your application directory. e.g.
cd /path/to/myapp/uploads

# Make the ''uploads'' directory writable by the webserver. e.g. 
chmod 777 /path/to/myapp/uploads

# Edit the ''lib/FCKeditor/editor/filemanager/connectors/php/config.php'' file inside your ''xataface'' directory so that:
$Config['Enabled'] = true ;
$Config['UserFilesPath'] = '/url/to/myapp/uploads/' ;
    // The path portion of the URL to your uploads directory.
    // e.g. if your uploads directory is accessible at
    // http://example.com/myapp/uploads, then this value should
    // be /myapp/uploads/
$Config['UserFilesAbsolutePath'] = '/path/to/myapp/uploads/' ;
    // The absolute file system path to your uploads directory.
    // e.g. if your uploads directory is located at
    // /home/myhome/www/myapp/uploads, then this value should be
    // /home/myhome/www/myapp/uploads

# Now when you click on the ""Add Image"" link in your HTML editor, it will allow you to upload images and browse existing uploaded images.

",,en,0
widget:type,4,widget:type,"==widget:type Directive Reference==

The widget:type directive in the [[fields.ini file]] specifies the type of widget that should be used to edit a particular field in HTML forms.  Xataface uses [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm] for its form generation so theoretically any widget supported by HTML_QuickForm should work with Xataface.

===Available Widget Types===

{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| [[advmultiselect]]
| Two select lists with add/remove buttons.  Selected items appear in the right select list.  Options may be selected from the left select list.
| 1.0
|-
| [[autocomplete]]
| An autocomplete. text field.  This is not to be confused with the [[yui_autocomplete]] widget.  The main difference is that this widget does not provide a drop-down list of possibilities, it just tries to complete what the user is typing inside the text field based on a valuelist.
| all
|-
| [[calendar]]
| A DHTML pop-up calendar to select the date.  [[Image:http://media.weblite.ca/files/photos/calendar_widget.png?max_width=400]]
| 0.5.3
|-
| [[checkbox]]
| A checkbox or checkbox group. 

Example 1: Checkbox as boolean on Tinyint field.

[[Image:http://media.weblite.ca/files/photos/checkbox_widget.png?max_width=400]]

Example 2: Checkbox group to allow multiple selections.

[[Image:http://media.weblite.ca/files/photos/checkbox-group_widget.png?max_width=500]]
| all
|-
| [[date]]
| Select lists for month, year, day, hour, etc...
| all
|-
| [[file]]
| A file widget (default type for [[container]] fields and [[blob]] fields.  [[Image:http://media.weblite.ca/files/photos/file_widget.png?max_width=400]]

| all
|-
| [[grid]]
| A grid widget for editing multiple rows of related records inside the edit form.  Supports adding/removing/reordering. As of version 1.2.5, file uploads are not supported in the grid widget.

[[Image: http://media.weblite.ca/files/photos/grid_widget.png?max_width=500]]
| 1.0
|-
| [[group]]
| A compound widget for editing multiple fields but storing the data in a single XML field.
[[Image:http://media.weblite.ca/files/photos/group_widget.png?max_width=400]]
| all
|-
| [[hidden]]
| A hidden field 
| all
|-
| [[htmlarea]]
| A WYSIWYG (What you see is what you get) HTML editor.  This defaults to [http://www.fckeditor.net/ FCKeditor], but [http://tinymce.moxiecode.com/ TinyMCE] is also supported.  [[Image:http://media.weblite.ca/files/photos/htmlarea_widget.png?max_width=400]]
| all
|-
| [[lookup]]
| A field that allows users to look-up a record from another table.  THis is a good alternative to a select list.  It doesn't use a vocabulary, so this is appropriate when vocabularies would be unpractical (for large vocabularies).  You do, however need to specify the widget:table directive for the field so that the lookup knows from which table to load the records.
[[Image:http://media.weblite.ca/files/photos/Picture%2023.png?max_width=640]]

| 1.2
|-
| [[password]]
| A password field.

[[Image:http://media.weblite.ca/files/photos/password_widget.png?max_width=400]]
| all
|-
| [[select]]
| A select list.

Example 1: A single select.

[[Image:http://media.weblite.ca/files/photos/select_widget.png?max_width=400]]

Example 2: A multi-select.  To use a multi-select, add repeat=1 to your fields.ini.

[[Image:http://media.weblite.ca/files/photos/multi-select_widget.png?max_width=500]]
| all
|-
| [[table]]
| A compound widget for editing tabular data.  This widget dictates the storage format as XML.

[[Image:http://media.weblite.ca/files/photos/table_widget.png?max_width=400]]
| all
|-
| [[text]]
| A text field

[[Image:http://media.weblite.ca/files/photos/text_widget.png?max_width=400]]
| all
|-
| [[textarea]]
| A text area (multi-line text field)

[[Image:http://media.weblite.ca/files/photos/textarea_widget.png?max_width=400]]
| all
|-
| [[time]]
| A select list of times separated by a specified interval (default 30 minutes).
| 0.7
|-
| [[yui_autocomplete]]
| An autocomplete widget ported from the [http://developer.yahoo.com/yui/autocomplete/ Yahoo UI Library].

[[Image:http://media.weblite.ca/files/photos/yui_autocomplete.png?max_width=400]]
| 1.0
|}",,en,0
widget:type_textarea,60,widget:type_textarea,,,en,0
Writing_Custom_Authentication_Plugins,22,Writing_Custom_Authentication_Plugins,"==Writing a Custom Authentication Plugin for Xataface==

[[toc]]

Xataface has a pluggable [[authentication]] framework that allows you to easily write your own custom [[authentication]] modules to tie in with other systems.  Several plugins have already been created including:

* [[CAS Authentication Module|Yale CAS]]
* [[LDAP Authentication Module|LDAP]]
* [[Facebook Authentication Module|Facebook]]
* [[HTTP Authentication Module|HTTP]]

===Example: Creating a custom authentication plugin===

Before we begin, a couple of conventions:

# '''%XATAFACE_ROOT%''' refers to your Xataface installation directory.  This is where all of the Xataface files are located includeing dataface-public-api.php
# '''%SITE_ROOT%''' refers to your Xataface application's installation directory.  This is where your conf.ini file, index.php, and other application files are stored.

====About our plugin====

Our plugin will be the simplest, most useless authentication plugin you can imagine.  It simply checks an array of usernames and passwords to see if the password that the user supplied is valid.

====Creating our plugin====

# Create the '''%XATAFACE_ROOT%/modules/Auth''' directory if it doesn't exist already.  This directory will store all of our Xataface authentication plugins.
#Create the '''%XATAFACE_ROOT%/modules/Auth/XDB''' directory if it doesn't exist already. This directory will house all of the scripts and files associated with our custom plugin.
#Create a new PHP file named '''XDB.php''' inside our '''XDB''' directory that we just created, with the following contents:
class dataface_modules_XDB {
    var $passwords = array(
        'steve' => 'stevespass',
        'mike' => 'foo'
    );
    function checkCredentials(){
        $auth =& Dataface_AuthenticationTool::getInstance();
        $creds = $auth->getCredentials();
        if ( @$this->passwords[$creds['UserName']] == $creds['Password'] ){
            return true;
        } else {
            return false;
        }
    }
}

# Now, change the '''[_auth]''' section of the conf.ini file to let Xataface know that we want to use our custom module:
[_auth]
    auth_type=XDB

# Try to log into your application.  You'll notice that the only username/password combinations that are accepted are the ones that we specified in our '''$passwords''' array in our module.

This is just a simple example, but you can see how this can be expanded to provide more complex modules.

===checkCredentials() not enough?===

Some authentication plugins will need more control than simply checking credentials.  Some plugins may want to make use if their own login forms, or redirect to other sites to handle the authentication.  Xataface's [http://dataface.weblite.ca/Dataface_AuthenticationTool authentication tool] is up to the task, as virtually all parts of the login/logout process can be overridden and customized in your module.  The previous example shows how the getCredentials() method can be overridden, but there are other methods that can be implemented to customize the login process as well.

e.g.

* showLoginPrompt() - This method is called when it is time to display the login prompt for the user.  It could also be made to redirect to another site that has a login prompt.
* logout() - This is called when the user tries to log out.  If there are any special cookies of variables that need to be cleaned up to facilitate a successful logout, you could implement this method.
* [http://dataface.weblite.ca/getLoggedInUser getLoggedInUser()]
* [http://dataface.weblite.ca/getLoggedInUsername getLoggedInUsername()]
* getCredentials() - Handles the obtaining of credentials from the request or from the environment.
* authenticate() - Handles the whole login process

===See Also:===

* [[Application Delegate Class]] for before/after login/logout triggers that may be more appropriate in some circumstances than creating a custom authentication plugin.
* [[authentication|Xataface Authentication]]",,en,0
modules,30,"Xataface Modules","[[toc]]

Xataface provides a number of hooks that allow developers to create modules to extend its functionality.  This page lists a handful of the currently available modules.

* [[ShoppingCart|Shopping Cart]] - Converts your application into a shopping cart.
* [[Filemaker]] - Export record sets as Filemaker XML.
* [[DataGrid|Data Grid]] - Editable Datagrid.
* [[Email]] - Convert your database into a email list.  Send email to any found set.
* [[reCAPTCHA module]] - A reCAPTCHA module to add CAPTCHA support to your Xataface forms.
* [[XataJax]] - Platform for building Web 2.0 AJAX applications with Xataface.  Will be a standard component for Xataface starting with version 1.3.

==Module Installation==

You can add modules in either:

# DATAFACE_PATH/modules directory (since 1.0)
# DATAFACE_SITE_PATH/modules directory (since 1.3)

Modules in the DATAFACE_SITE_PATH directory will supersede modules in the DATAFACE_PATH/modules directory (since 1.3).

To activate a module for your application you also need to add an entry to the [[_modules]] section of your [[conf.ini file]].  Each module will come with its own installation instructions.

==Authentication Modules==

Modules to add alternative authentication methods are added to the modules/Auth directory.

==Developing Your Own Modules==

See [[Module Developers Guide]].","modules, captcha",en,0
xataface_templates,23,xataface_templates,"==Xataface Templates==

[[toc]]

Xataface uses the [http://smarty.php.net Smarty Template Engine] to power all of its templates.  Templates are stored in the one of the following locations:

* %XATAFACE_ROOT%/Dataface/templates
* %SITE_ROOT%/templates

Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application.

You may also have subdirectories within these templates directories.

===Cascading Templates===

Xataface uses a simple cascading technique for deciding which template to use.  If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory.  In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory.

The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...).  Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired.

===Useful Smarty Tags introduced by Xataface===

In addition to the standard set of Smarty tags, Xataface templates provide some of its own.

==Xataface Templates==

Xataface uses the [http://smarty.php.net Smarty Template Engine] to power all of its templates.  Templates are stored in the one of the following locations:

* %XATAFACE_ROOT%/Dataface/templates
* %SITE_ROOT%/templates

Where %XATAFACE_ROOT% is the Xataface directory (includes files such as dataface-public-api.php), and %SITE_ROOT% is the path to your application.

You may also have subdirectories within these templates directories.

===Cascading Templates===

Xataface uses a simple cascading technique for deciding which template to use.  If there are templates in the %SITE_ROOT%/templates and %XATAFACE_ROOT%/Dataface/templates directories with the same name, then Xataface will use the one in the %SITE_ROOT%/templates directory.  In this way, you are able to override any of Xataface's core templates by adding one of the same name to your %SITE_ROOT%/templates directory.

The most common template to override is the Dataface_Main_Template.html template which defines the look and feel for the entire application (e.g. header, footer, etc...).  Hence, if you wanted to customize the look & feel of your application, you would likely start by copying %XATAFACE_ROOT%/Dataface/templates/Dataface_Main_Template.html into the %SITE_ROOT%/templates directory and make modifications to it as desired.

===Useful Smarty Tags introduced by Xataface===

In addition to the standard set of Smarty tags, Xataface templates provide some of its own.

{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| [[templates:tags:use_macro|use_macro]]
| Include another template with the option to override certain sections.
| 0.6
|-
| define_slot
| Marks a section that can be overridden by other templates that include this one via the use_macro tag.
| 0.6
|-
| fill_slot
| Overrides content in a template that has been included via the use_macro tag.
| 0.6
|-
| block
| Marks an insertion point where content can be inserted by delegate classes and modules.
| 0.6
|-
| load_record
| Loads a [http://dataface.weblite.ca Dataface_Record] object from the database to be used in the template.
| 0.6
|-
| group
| Groups an array of records together based on a field value.
| 0.6
|-
| img
| Displays a thumbnail of an image.
| 0.6
|-
| actions
| Loads an associative array of actions defined in the actions.ini file, based on certain criteria.
| 0.6
|-
| actions_menu
| Displays a menu of actions based on certain criteria.
| 0.6
|-
| record_actions
| A specialization of the actions_menu tag.  This displays a menu of actions only in the record_actions category.
| 0.6
|-
| record_tabs
| A specialization of the actions_menu tag.  This displays a menu of actions only in the record_tabs category.
| 0.6
|-
| result_controller
| Displays the paging controls for the current table's records.   Use this for any listing of records.
| 0.6
|-
| result_list
| Displays the result list (from the list tab) for the current request.
| 0.6
|-
| related_list
| Displays the related records list for the current request.
| 0.6
|-
| bread_crumbs
| Displays the bread crumbs for the current request.
| 0.6
|-
| search_form
| Displays the find form for the current table.
| 0.6
|-
| language_selector
| Displays a menu to select the user's preferred language.
| 0.6
|-
| next_link
| Displays a link to the next XXX records.
| 0.6
|-
| prev_link
| Displays a link to the previous XXX records.
| 0.6
|-
| jump_menu
| Displays the select list of the records found in this found-set so that the user can jump directly to any record.
| 0.6
|-
| limit_field
| Displays a text field for the user to select the number of records to display per page.
| 0.6
|-
| result_index
| Displays the index of pages (1 to XXX) for this query.
| 0.6
|-
| summary_list
| Displays a list of records in the current found set using a summary format rather than the regular table format.
| 0.6
|-
| sort_controller
| Displays a control to sort the results on any column.
| 0.6
|-
| glance_list
| Displays a simple, brief list of records matching certain criteria.
| 0.6
|-
| record_view
| Loads structured data for a record as required for the view tab.
| 0.6
|-
| feed
| Generates a link to an RSS feed based on certain criteria.
| 0.6
|-
| translate
| Display a section of text in the user's selected language. (i18n).
| 0.6
|-
| if_allowed
| The contents of this block are shown only if the user has certain permissions.
| 0.6
|-
| editable
| Make a section of the page editable using AJAX.
| 0.6
|-
| abs
| Convert a URL into an absolute URL.
| 0.6
|}


===Useful Template Variables===

Xataface makes certain variables available to every template:

{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| $ENV.REQUEST
| Reference to the $_REQUEST array (HTTP Request parameters, both GET and POST)
| 0.6
|-
| $ENV.SESSION
| Reference to the $_SESSION array (the session variables)
| 0.6
|-
| $ENV.DATAFACE_PATH
| The file system path to the Xataface directory (i.e. the directory containing all of the Xataface files such as dataface-public-api.php).
| 0.6
|-
| $ENV.DATAFACE_URL
| The URL to the Xataface directory.
| 0.6
|-
| $ENV.DATAFACE_SITE_PATH
| The file system path to your application directory. (i.e. the directory containing your conf.ini and index.php files).
| 0.6
|-
| $ENV.DATAFACE_SITE_URL
| The URL to your application directory.
| 0.6
|-
| $ENV.DATAFACE_SITE_HREF
| The URL to your application's script.  This differs from the $ENV.DATAFACE_SITE_URL variable in that this also includes the script name.
| 0.6
|-
| $ENV.SCRIPT_NAME
| Same as $ENV.DATAFACE_SITE_HREF
| 0.6
|-
| $ENV.APPLICATION
| A reference to the application's conf array (i.e. the parsed contents of the conf.ini file).
| 0.6
|-
| $ENV.APPLICATION_OBJECT
| A reference to the Dataface_Application object for the application.
| 0.6
|-
| $ENV.SERVER
| A reference to the $_SERVER array.
| 0.6
|-
| $ENV.QUERY
| A reference to the current query (i.e.  Dataface_Application::getInstance()->getQuery())
| 0.6
|-
| $ENV.action
| The name of the current action as specified by the -action REQUEST parameter.
| 0.6
|-
| $ENV.table
| The name of the current table as specified by the -table REQUEST parameter.
| 0.6
|-
| $ENV.table_object
| A reference to the current table.
| 0.6
|-
| $ENV.relationship
| The name of the current relationship as specified by the -relationship REQUEST parameter.
| 0.6
|-
| $ENV.limit
| The value of the -limit REQUEST parameter.  This is the number of records to show per page.
| 0.6
|-
| $ENV.start
| The value of the -start REQUEST parmeter.  This is the starting point in the result set which is currently being displayed.
| 0.6
|-
| $ENV.resultSet
| A reference to the [http://dataface.weblite.ca/Dataface_QueryTool Dataface_QueryTool] object for this result set.
| 0.6
|-
| $ENV.record
| A reference to the [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object that is matched by the current query.
| 0.6
|-
| $ENV.mode
| The name of the current mode.  e.g. find, list, browse
| 0.6
|-
| $ENV.language
| The 2-digit ISO language code that is currently selected as the user's preferred language.
| 0.6
|-
| $ENV.prefs
| A reference to the preferences array ($conf['_prefs'])
| 0.6
|-
| $ENV.search
| The value of the current full-text search (i.e. the search that was entered into the upper right search field.
| 0.6
|}


==Smarty Plugins==

One of the most powerful features of [http://www.smarty.net Smarty] is its pluggable architecture.  You can easily add your own custom plugins to a registered ""plugins"" directory to add functions, modifiers, blocks, and other features to your templates.

Prior to Xataface 2.0, you Smarty plugins could only be placed in the  ''lib/Smarty/plugins'' directory of the Xataface distribution folder.  This is not very conducive to Xataface updates, though.  In general it is best practice to not change anything inside the xataface directory.  Most other configuration and extensions can be handled by making changes to your application's directory which override corresponding functionality in Xataface.

As of Xataface 2.0, you can create a directory named ''plugins'' to your application directory, Smarty knows to look in this directory for plugins.

For versions of Xataface prior to 2.0, you can make a small modification to the SkinTool to also add support as desribed in [http://xataface.com/forum/viewtopic.php?f=4&t=6722 this post].

===Example Plugin===

The following is an example Smarty plugin adapted from [http://www.smarty.net/docs/en/plugins.functions.tpl this page] but modified slightly to work in Xataface.  It is a simple ""eightball"" plugin that adds a tag {eightball} to Xataface that you can use in any of your templates.  Whenever this tag is rendered it outputs one of a set of predefined strings randomly.

# Add a ''plugins'' directory to your application directory.  i.e.  ''path/to/app/plugins''
# Add a file inside this ''plugins'' directory called ''function.eightball.php'' with the following content:

# If you compare this function to the original example in [http://www.smarty.net/docs/en/plugins.functions.tpl the smarty tutorial] you'll notice that the 2nd parameter has been changed to type ''Dataface_SkinTool'' from ''Smarty_Internal_Template''. If you don't make this change, you will get a fatal error when you try to use the tag.  This function defines an ''{eightball}'' tag that can be added to any Smarty template in Xataface.
# Next we'll create a template that uses this tag.  If your application doesn't have a ''templates'' directory, create one now (i.e. path/to/app/templates).
# Add a file inside your templates directory called ''testing.html'' with the following content:
The eight ball says {eightball}

# Now we need to display this template somewhere in our interface.  In this case, we'll choose the ''before_record_content'' block.  (This will render the template before the main section of the view tab).  Add the following method to your [[Application_Delegate_Class]]:
function block__before_record_content(){
    df_display(array(), 'testing.html');
}

# Now if you load your application in a web browser and navigate to the details view for a record, you should see something like the following:


===See also:===

* [http://www.xataface.com/documentation/tutorial/getting_started/changing-look-and-feel Changing the Look & Feel of Xataface] (From the Getting Started Tutorial)
* [http://www.xataface.com/documentation/tutorial/customizing-the-dataface-look-and-feel Cusomizing the Xataface Look & Feel] Tutorial","templates, plugins, smarty",en,0
_auth,97,"_auth section of the conf.ini file","[[conf.ini file|Return to conf.ini file]]

[[toc]]

===Synopsis===

The ''_auth'' section of the conf.ini file includes configuration directives to enable authentication in a Xataface application.  For more information about authentication and registration see [[authentication]].  This section may include the following directives:

===Directives===

{| class=""listing listing2""
|-
! Directive
! Description
! Required
! Default
! Version
|-
| users_table
| The name of the table that contains your user accounts.
| Yes
| None
| 0.6
|-
| username_column
| The name of the column that stores the username.
| Yes
| None
| 0.6
|-
| password_column
| The name of the column that stores the password.
| Required if using basic authentication.
| None
| 0.6
|-
| auth_type
| Specifies the authentication module that is being used.  E.g. basic, cas, ldap, http, facebook, etc...
| No
| basic
| 0.6
|-
| allow_register
| Flag to enable user registration.  If this is set to 1, then a ''register'' link will appear below the login form.
| No
| 0
| 0.8
|-
| session_timeout
| Number of seconds of inactivity after which the user will be logged out. Note: Arithmetic don't work in the conf.ini, use seconds.
| No
| 86400 (=> 24*60*60 (24 hours))
| 1.3rc4
|}

===See Also===

* [[authentication]] - Overview of Xataface Authentication
* [[conf.ini file]] - Directives available in the conf.ini file.","_auth,authentication,conf.ini file,allow_register",en,
__field__permissions,50,__field__permissions,"This method can be used to set the default permissions for all fields in a designated table, when specified in that table's delegate class. It comes in handy in situations when you want to deny access to all fields except for those designated, rather then specifying each field to deny individually. For example, to revoke edit permissions from all fields but one, the user must first have edit permissions to the table overall, otherwise the Edit tab/action will not appear. Then, use this __field_permissions method to revoke edit permissions from all fields. Finally, use the fieldname__permissions method (see below) to allow access to only those fields needed.

=== Also See: ===

* [[How_to_granulate_permissions_on_each_field]]
* [[fieldname__permissions]]",,en,0
__global__,106,"__global__ section for the fields.ini file","Return to [[fields.ini file]]

[[toc]]

===Synopsis===

The fields.ini file supports a __global__ section that applies to all fields in the current table.  This is particularly useful for setting up default functionality that you wish to see on all fields except a few.  For example you may wish to have all fields hidden from list view by default, and only explicitly enable a few.  Same for CSV export or the details form.

===Example 1: Hiding All Fields from List View===

In the fields.ini file:

[__global__]
    ;; hide all of the fields from list view
    visibility:list=hidden

[first_name]
    ;; show the first name in list view 
    visibility:list=visible

[last_name]
    visibility:list=visible

;;.... etc....


In the above example we used the __global__ section to declare that we want all fields to be hidden from list view by default.  Then we explicitly showed first_name and last_name in list view. In this case only first_name and last_name will appear in the list view.

==See Also==

*[[fields.ini file]]
*[[visibility:list]]","__global__, fields.ini, visibility:list",en,
__prefs__,9,__prefs__,"==__prefs__ fields.ini Section==

A global section of the [[fields.ini file]] that sets the preferences for the given table and its records.

E.g.

[__prefs__]
    hide_posted_by=1 ; Hides the ""Posted by"" text in glance lists (e.g. related records in the view tab).
    hide_updated=1 ; Hides the ""Updated"" text in glance lists (e.g. the related records in the view tab).



===Available Preferences===

Ultimately, all of the preferences available at a global level should be available here, however currently this is not the case and only selected preferences are available at the table level.

{| class=""listing listing2""
! Name
! Description
! Version
|-
| [[hide_posted_by]]
| HIdes the ''posted_by'' text in glance lists.  E.g. In the view tab of a record, the related records are shown in the left column.  This will hide the ''posted_by'' text next to each related record.
| 1.0b4
|-
| [[hide_updated]]
| Hides the ''updated'' text in glance lists.  E.g. In the view tab of a record, the related records are shown in the left column.  This will hide the ''updated'' text next to each related record.
| 1.0b4
|-
|}",,en,0
sql_delegate_method,87,"__sql__ Delegate Method","return to [[Delegate class methods]]

===Synopsis===

The __sql__ delegate class method can be defined in any delegate class to specify the SQL query that should be used to fetch records for a given table.  This method overrides the [[__sql__]] directive of the fields.ini file.  This strategy is primarily used to graft columns from another table onto the base table.

=====Use Caution=====

This is an advanced feature and, if used incorrectly, can muck up your application. Make sure that your SQL query includes a superset of the columns in the base table, and is a row-for-row match for the rows in the base table.  I.e. you should never use an internal join.  Always use a left join so that all of the rows of the base table are returned even if the join table doesn't have a corresponding row.

If you want to simply filter a table's records, and don't need to graft any additional columns onto the table, you should use the [[setSecurityFilters]] method.

===Example===

Given the table foo, its delegate class:


class tables_foo {
    function __sql__(){
        return ""select f.*, c.category_name from foo f left join categories c on f.category_id=c.category_id"";
    }
}


This effectively grafts a column ""category_name"" onto the foo table based on a join with the categories table.

","__sql__, SQL queries, delegate class",en,

User bio