file
89
==Dynamic select boxes==
To create two select boxes whose one is dependent (slave) of the other (master), we need to use some javascript with Jason.
Create the valuelists.ini:
<code>
;valuelist for the slave
[slaves_list]
__sql__ = "select slave_id, slave_name, master_id from slaves"
; valuelist for the masters
[masters_list]
__sql__ = "select master_id,master_name from masters"
</code>
fields.ini:
<code>
[master]
vocabulary=masters_list
[slave]
vocabulary=slaves_list
</code>
delegate class in the table directory :
<code>
...
function block__after_new_record_form(){
echo <<<END
<script language="javascript"><!--
var slave_field= document.getElementById('slave');
var master_field = document.getElementById('master');
END;
// Let's get all the slaves available.
$app =& Dataface_Application::getInstance();
$query =& $app->getQuery();
$table =& Dataface_Table::loadTable($query['-table']);
$slaves = $table->getValuelist('slaves_list');
$slave_masters = $table->getValuelist('slaves_list__meta');
// Note that the slaves_list__meta valuelist is automatically created
// because we had three columns in the slaves valuelist.
// The first and third columns effectively create a 2nd valuelist
// named 'slaves_list__meta'
// $slaves is an array with keys slave_id and values slave_name
// slave_masters is an array with keys slave_id and values master_id
import('Services/JSON.php');
$json =& new Services_JSON(); // A JSON encoder to allow us to easily
// convert PHP arrays to javascript arrays.
echo '
var slaves_options = '.$json->encode($slaves).';
var slaves_master = '.$json->encode($slave_masters).';
';
echo <<<END
master_field.onchange = function(){
var selected_master = master_field.options[master_field.selectedIndex].value;
slave_field.options.length = 0;
var index = 0;
for ( slave_id in slaves_options){
if ( selected_master == slaves_master[slave_id] ){
slave_field.options[index++] = new Option(slaves_options[slave_id], slave_id);
}
}
};
//--></script>
END;
}
// Also place this javascript after an edit record form...
function block__after_edit_record_form(){
return $this->block__after_new_record_form();
}
</code>
en
Dynamic_select_boxes
90
==Dynamic select boxes==
To create two select boxes whose one is dependent (slave) of the other (master), we need to use some javascript with Jason.
Create the valuelists.ini:
<code>
;valuelist for the slave
[slaves_list]
__sql__ = "select slave_id, slave_name, master_id from slaves"
; valuelist for the masters
[masters_list]
__sql__ = "select master_id,master_name from masters"
</code>
fields.ini:
<code>
[master]
vocabulary=masters_list
[slave]
vocabulary=slaves_list
</code>
delegate class in the table directory :
<code>
...
function block__after_new_record_form(){
echo <<<END
<script language="javascript"><!--
var slave_field= document.getElementById('slave');
var master_field = document.getElementById('master');
END;
// Let's get all the slaves available.
$app =& Dataface_Application::getInstance();
$query =& $app->getQuery();
$table =& Dataface_Table::loadTable($query['-table']);
$slaves = $table->getValuelist('slaves_list');
$slave_masters = $table->getValuelist('slaves_list__meta');
// Note that the slaves_list__meta valuelist is automatically created
// because we had three columns in the slaves valuelist.
// The first and third columns effectively create a 2nd valuelist
// named 'slaves_list__meta'
// $slaves is an array with keys slave_id and values slave_name
// slave_masters is an array with keys slave_id and values master_id
import('Services/JSON.php');
$json =& new Services_JSON(); // A JSON encoder to allow us to easily
// convert PHP arrays to javascript arrays.
echo '
var slaves_options = '.$json->encode($slaves).';
var slaves_master = '.$json->encode($slave_masters).';
';
echo <<<END
master_field.onchange = function(){
var selected_master = master_field.options[master_field.selectedIndex].value;
slave_field.options.length = 0;
var index = 0;
for ( slave_id in slaves_options){
if ( selected_master == slaves_master[slave_id] ){
slave_field.options[index++] = new Option(slaves_options[slave_id], slave_id);
}
}
};
//--></script>
END;
}
// Also place this javascript after an edit record form...
function block__after_edit_record_form(){
return $this->block__after_new_record_form();
}
</code>
The 2.0 version has a [http://xataface.com/dox/modules/depselect/latest| depselect module] to produce cascading dynamic select boxes very simply.
en
encryption
29
encryption
==encryption [[fields.ini file]] directive==
The '''encryption''' directive is meant to be used on password fields only. It specifies that a certain type of encryption is to be used in the storing of values in this field. For example, many PHP/MySQL applications use MD5 encryption to store their passwords. If you want your Xataface application to be able to use the same users tables, then you'll need to specify the '''encryption''' directive for the password field.
===Possible Values===
{| class="listing listing2"
|-
! Value
! Meaning
! Version
|-
| md5
| MD5 encryption
| 0.6
|-
| sha1
| SHA1 encryption
| 1.0
|-
| encrypt
| MySQL encrypt function
| 1.0
|-
| password
| MySQL password encryption
| 1.0
|}
===E.g. in the users table [[fields.ini file]]===
<code>
[password]
encryption=md5
</code>
en
0
visibility:fieldName
47
visibility:fieldName
==Example==
<code>visibility:ConferenceID = hidden</code>
This will make the ConferenceID in the relationship list view disappear.
en
0
fieldname__permissions
53
fieldname__permissions
==fieldname__permissions() method==
[[toc]]
The fieldname__permissions() methods will allow you to define custom permissions on a particular field in the [[delegate class]]. For example to specify permissions on a field named ''foo'' you would define the ''foo__permissions()'' method, and to define permissions on a field named ''role'' you would define the ''role__permissions()'' method.
==Example #1==
(Note this example needs to be refined to be more clear)
<code>
function approval_level__permissions(&$record){
return array('edit'=>0); //this is will merge with what the permissions for the normal record
}
</code>
Here we are targeting the ''approval_level'' field of the [[delegate class]]. The permissions method takes a return value an array of permissions. So for example:
<code>
$permissions['new'] = 0;
$permissions['edit'] = 0;
</code>
Would be an example of an array of permissions which the key being the permission name and the value being a boolean to specify whether they have (1) or don't (0) have permissions to that field. We don't have to specify a complete array of permissions (ie. permission of edit, new, readonly, etc, etc), but rather only the ones we want specifically. The reason being that the permissions array in the return value gets merged with the permissions that this record normally gets from the record permissions.
So if the record normally gives the permissions new=0, edit=1. Then the return value from approval_level will merge with the original permissions to produce an array like this:
<code>
$permissions['new'] = 0;
$permissions['edit'] = 1;
</code>
=== Also See: ===
* [[How_to_granulate_permissions_on_each_field]]
* [[__field__permissions]]
en
0
fields.ini_file
3
fields.ini_file
==fields.ini File Reference==
[[toc]]
===Overview===
The fields.ini file is a configuration file which is associated with a single table of a database application. It provides metadata about the table's fields to help Xataface dictate how they should be included in the application. This includes metadata such as
* [[widget:type|Widget type]] - To specify the type of widget that should be used to edit content in the field (e.g. text, select, checkbox).
* [[widget:label|Label]] - The labels that can be used in column headers and on forms.
* [[widget:description|Help text]] - for forms to inform the user how data should be entered.
* [[group|Field Groupings]]
* [[widget:atts|widget:atts]] - To use javascripts in event handlers
* and more
Although a table doesn't need to have an associated fields.ini file in order for the application to work, each table can have one; and it is always located in the [[table configuration directory]]. For example, the fields.ini file for the [[people]] table would be located at [[Site Root]]/tables/people/fields.ini file.
===Syntax===
The fields.ini file uses [[standard INI syntax]] (just like the php.ini file), where each section corresponds to a column in the table.
For example, consider a table "people" with columns "first_name", "last_name", and "age". The fields.ini file for the people table could then contain sections for each of its columns as follows:
<code>
[first_name]
[last_name]
[age]
</code>
In this example the sections are empty (i.e. they have no directives, but we could easily add some directives:
<code>
[first_name]
widget:description="Please enter your first name"
widget:label="Given Name"
...etc...
</code>
Here we have told Xataface that the first name field should include some help text (using the [[widget:description]] directive) on its edit form.
===Example fields.ini file===
<code>
;; Global directives applied to every field (requires Xataface 1.2.6)
[__global__]
visibility:list=hidden
[isbn]
widget:label = ISBN
visibility:list=visible
[copyright_year]
widget:label = "Year"
widget:atts:size=4
visibility:list=visible
[categories]
widget:type=checkbox
vocabulary = book_categories
[media]
widget:type=checkbox
vocabulary = book_media
[borrower_id]
widget:type=select
vocabulary=users
[due_date]
widget:description = "The date that the book is due to be returned to the library"
visibility:list=visible
[cover_art_url_small]
visibility:browse=hidden
[cover_art_url_medium]
;visibility:browse=hidden
[cover_art_url_large]
visibility:browse=hidden
visibility:find=hidden
[amazon_description]
widget:label = Description
[amazon_reviews]
[amazon_url]
[amazon_refresh_timestamp]
widget:type=static
[date_created]
timestamp=insert
widget:type = static
[date_modified]
timestamp=update
widget:type=static
[created_by]
widget:type=static
[modified_by]
widget:type=static
[notes]
</code>
This is an example from the [http://apps.weblite.ca/index.php?-action=view&-table=packages&package_id=%3D2 Library DB] application for the books table.
===Field Directives===
The following directives may be added to a field's section of the fields.ini file to customize the field's behavior. Some directives are not applicable to all fields.
{| class="listing listing2"
|-
! Name
! Description
! Version
|-
| [[column:label]]
| Specifies a custom label to use in list view for the column. If this is not specified, then the value of [[widget:label]] will be used.
| 1.3
|-
| [[column:legend]]
| Adds a small amount of help text to the column header for this field in list view. Default is blank. E.g. <nowiki><br/><img src="http://media.weblite.ca/files/photos/Screen%20shot%202011-02-08%20at%205.05.55%20PM.png?max_width=640"/><br/></nowiki>In this photo it shows the text "*Paper Uploaded" set as the [[column:legend]] for "field 1".
| 1.3
|-
| [[date_format]]
| Specifies how the field should be formatted when displayed. Takes same parameters as PHP [http://php.net/strftime strftime] function.
| 2.0
|-
| [[display]]
| Specifies the layout of the field on the edit form. Most fields have an implicit value of "inline" meaning the widget and its label appear on the same line. Textareas and htmlareas have an implicit value of "block" meaning that the label and widget appear in separate rows (label above the widget). You can set this value explicitly also to override the layout of a field.
| 0.8
|-
| [[display_format]]
| A pattern that can be used to define the display format of the field. This takes the same parameters as the PHP [http://php.net/sprintf sprintf] function.
| 2.0
|-
| [[encryption]]
| Primarily used with password fields, indicates the type of encryption that should be used to save the field. Supports "md5", "sha1", "encrypt", and "password".
| 0.6
|-
| event.date
| For use by the [[Calendar Action]]. Indicates that the field stores the date of the record when interpreted as an event. Possible values "0" or "1".
| 1.0
|-
| event.start
| For use by the [[Calendar Action]]. Indicates that the field stores the start time of the record when interpreted as an event. Possible values "0" or "1".
| 1.0
|-
| event.end
| For use by the [[Calendar Action]]. Indicates that the field stores the end time of the record when interpreted as an event. Possible values "0" or "1".
| 1.0
|-
| event.location
| For use by the [[Calendar Action]]. Indicates that the field stores the location of a record when interpreted as an event. Possible values "0" or "1".
| 1.0
|-
| [[filter]]
| Boolean value (0 or 1) indicating whether this field should be [[filterable]] in [[list view]].
| 0.8
|-
| [[frozen_description]]
| The field description shown when the widget is frozen (i.e. uneditable). If this is not specified, no field description is shown in this case.
| 1.2
|-
| [[group]]
| The name of the field group that this field belongs to. Fields with the same "group" value will be rendered in the same field group on the form.
| 0.5
|-
| [[Key]]
| If you are using a View for the table you need to explicitly mark the fields that comprise the primary key. E.g. Key=PRI
| 0.6
|-
| [[label_link]]
| An optional URL for the field label to link to. This would usually be some "help" page that explains what the field is for. The link will be a link in both the view and edit tabs.
| 1.1.3
|-
| [[ignore]]
| Boolean value (0 or 1) indicating whether this field should be ignored on the edit form. This is handy if the field is going to be constantly updated in the background (via a cron job perhaps) and you don't want the edit form to interfere.
| 1.0
|-
| [[logo]]
| Boolean value (0 or 1) to indicate if this field should be treated as a logo field. Logo fields are displayed in the upper left of the [[view tab]] for a record, and are assumed to contain an image. If no logo field is explicitly specified, Xataface will make a best guess as to which field should be used.
| 0.7
|-
| [[money_format]]
| For fields containing monetary amounts, this specifies the format. Takes same parameters as PHP [http://php.net/money_format money_format] function.
| 2.0
|-
| [[noLinkFromListView]]
| Boolean value (0 or 1) to indicate if this field should be linked when in list view (or in a related list). Default value is 0 to indicate that the field IS linked. It is common to use this directive when using a custom xxx__renderCell() method that contains its own links.
| 1.1
|-
| [[not_findable]]
| A flag to indicate that this field can not be used as part of a query. This is helpful if you want a field to remain completely confidential to prevent people from finding records based on the value of this field. This flag is even necessary if the permissions for the field don't permit viewing the value of the field.
| 1.1
|-
| [[number_format]]
| For numeric fields, this indicates the number of decimal places to display when displaying this field. E.g. 2
| 2.0
|-
| [[order]]
| The order of the field when laid out on forms and lists. Can contain any floating point number or integer (e.g. 0, 10, -10, 235.4)
| 0.6
|-
| [[relationship]]
| Used only with complex fields that involve editing related records (e.g. [[grid]]). This is the name of the relationship that the field should be edited.
| 0.8
|-
| [[repeat]]
| Boolean value (0 or 1) used in conjunction with a select widget to indicate whether to enable a multi-select.
| ?
|-
| [[section]]
| The name of the section that this field should belong to in the [[view tab]].
| 0.7
|-
| [[secure]]
| A boolean flag for use with [[container fields]] to indicate that it should use secure URLs for the file downloads (i.e. it will obey the application permissions). Without this directives, uploaded files are served directly by apache and don't obey the Xataface permissions defined per record.
| 1.3
|-
| [[struct]]
| A boolean (0 or 1) value indicating whether this field is considered a structure. A value of 1 indicates that this field is a structure and should not be truncated under any circumstances. Normally fields are truncated at 255 chars in list view. This is useful if the field contains XML or other structured data so that attempts to truncate it would destroy integrity.
| 1.1.2
|-
| [[tab]]
| If tabbed forms are enabled, then this specifies the name of the tab that this field belongs to on the edit form.
| 0.8
|-
| [[timestamp]]
| Indicates when a timestamp should be set in the field (only applicable for date and time fields). Possible values are "insert" and "update"
| 0.7
|}
{| class="listing listing2"
|-
! Name
! Description
! Version
|-
| [[title]]
| Boolean value (0 or 1) indicating whether this field should be treated as a title field.
| 0.7
|-
| [[transient]]
| Boolean value (0 or 1) indicating whether this field is a transient field or not. A transient field is a field that is defined in the fields.ini file but not in the database. Hence the values that are input into this field on the edit form are not saved to the database.
| 0.8
|-
| [[Type]]
| The data type of the field (note the capital "T" as Xataface is case sensitive). This value is only overridden for [[container]] fields, however its value can be accessed programmatically for any field.
| 0.5
|-
| [[validators|validators:VALIDATOR_NAME]]
| A prefix for a validation type on the current field. (Replace "VALIDATOR_NAME" with the name of the validator to be used. e.g. required). There are many validators available to be used.
| 0.5
|-
| [[validators:VALIDATOR_NAME:message]]
| The message the should be displayed if the form fails to validator due to the "VALIDATION_NAME" validation rule.
| 0.5
|-
| [[viewgroup]]
| The name of the field grouping that this field will belong to in the view tab. If this is not present, then it will be grouped according to the [[group]] directive.
| 1.0
|-
| [[visibility:browse]]
| Indicates whether the field should be visible in browse mode (i.e. in the "view" tab). Possible values are "visible" and "hidden".
| 0.6
|-
| [[visibility:csv]]
| Indicates whether the field should be included in CSV exports. Possible values are "visible" and "hidden". (1.0 beta 4)
| 1.0b4
|-
| [[visibility:find]]
| Indicates whether the field should be visible in find mode. Possible values are "visible" and "hidden"
| 1.0
|-
| [[visibility:list]]
| Indicates whether the field should be visible in list view. Possible values are "visible" and "hidden".
| 0.6
|-
| [[visibility:update]]
| Indicates whether the field should be included in update and copy/replace forms. Possible values are "visible" and "hidden".
| 1.3
|-
| [[vocabulary]]
| The [[valuelist]] that should be used as the options to select. This is only applicable for fields that have options to select like a select list or a checkbox group.
| 0.5
|-
| [[widget:atts]]
| A namespace for attributes that should be added to the HTML widget. This allows you to specify things like javascript events, styles, widget size, etc..
| 0.5
|-
| [[widget:columns]]
| For checkbox groups, this specifies the number of columns to use for laying out the checkboxes.
| 1.0
|-
| [[widget:description]]
| Help text to give the user a hint about how to edit the field's content.
| 0.1
|-
| [[widget:editor]]
| The type of HTML editor that should be used. This is used only when [[widget:type]] is set to [[widget:type htmlarea|htmlarea]]
Acceptable values include:
* [http://www.fckeditor.net/ fckeditor] (default)
* [http://tinymce.moxiecode.com/ tinymce] (version 0.6 or higher)
* [http://www.nicedit.com/ nicedit] (version 1.0 or higher)
| all
|-
| [[widget:editvalues]]
| Used with select lists to allow users to add values to the select list. E.g. widget:editvalues=1
| 0.8
|-
| widget:focus
| Sets default focus. 0 or 1. (Javascript focus in a form)
| 0.6
|-
| [[widget:label]]
| The label that should be used for the current field on edit forms, column headings, and other relevant locations.
| 0.1
|-
| [[widget:question]]
| Text displayed just before the widget. This is almost the same as [[widget:description]] except that this text is guaranteed to be displayed before the widget, whereas [[widget:description]] may be displayed below or beside the widget.
| 0.1
|-
| [[widget:type]]
| The type of widget that should be used (e.g. checkbox, select, text, etc..)
| 0.1
|-
| [[xml]]
| A flag for use with calculated fields (i.e. fields defined in the [[delegate class]] via the [[field__fieldname]] method) that will include the field in XML output produced by the [[export xml action]]. Default is 0, but setting this value to 1 wil cause the field to be included.
| 1.2.7
|}
===Applying Directives to All fields (__global__)===
Xataface 1.2.6 includes support for a [[__global__]] section that allows you to specify directives that should be applied to all fields. These directives can be overridden on a field by field basis. The [[__global__]] section can take all the same directives that a normal field section takes.
===widget:atts:class Values===
The widget:atts:class directive allows you to assign a CSS class to a field's widget. There
are certain CSS classes that have meaning to Xataface and will cause additional functionality
to automatically be added to the field. These built-in classes are listed below:
{| class="listing listing2"
|-
! Name
! Description
! Version
|-
| [[passwordTwice]]
| Applicable only to password fields. If you set widget:atts:class=passwordTwice, then this will convert the password field into two fields whereby both fields need to match in order for submission to continue on the edit form. This operates as a password verification field."
| 1.3rc2
|}
===Global Directives===
The following directives can be added to the beginning of the fields.ini file (before any field sections) to customize field groups and the table as a whole.
{| class="listing listing2"
|-
! Name
! Description
! Version
|-
| [[__dependencies__]]
| A comma-delimited list of tables that this table is dependent upon for caching purposes. E.g. if any table in this list is modified, then the query cache is cleared for queries on this table. See this [http://xataface.blogspot.com/2009/06/using-query-caching-in-xataface.html blog article] for more information about query caching.
| 1.2
|-
| [[__isa__]]
| The name of the parent table of the current table. This directive allows you to have a heirarchical structure amongst the tables in your application.
| 0.8
|-
| [[__source_tables__]]
| A comma-delimited list of tables that this table/view is derived from. This is used with the query caching feature and is necessary to use this directive if the table is actually a view. If this directive is not set, then any queries involving this view will not use the query cache because Xataface would have no way to discern the update time of the view. See this [http://xataface.blogspot.com/2009/06/using-query-caching-in-xataface.html blog article] for more information about query caching.
| 1.2
|-
| [[__sql__]]
| Defines a custom select query to override the default select query for the current table. (The default select query is generally "select * from tablename").
| 0.7
|-
| [[__prefs__]]
| Sets preferences for this table and its records.
| 1.0b4
|}
===Field Groups===
The [[group]] directive allows you to group multiple fields together so that they will be rendered in the same field group on forms.
You can also configure these groups as a whole by defining a section named "[fieldgroup:GROUPNAME]" (where GROUPNAME is the name of the field group, corresponding to the [[group]] directive values for the fields)
in the fields.ini file. This section provides a few basic directives to customize some aspects of the field group:
* label
* order
* description
* template
* more...
The most common use of these sections is to customize the label or order of groups, especially when there are multiple field groups in the table.
For example, suppose we have a table "people" with fields "first_name", "last_name", "phone", "fax", "email", "address", "city", and "country".
Suppose these fields are grouped as follows:
* "first_name" and "last_name"
* "phone", "fax", and "email"
* "address", "city", and "country"
so that the fields.ini file looks like:
<code>
[first_name]
group=name
[last_name]
group=last_name
[phone]
group=contact
[fax]
group=contact
[email]
group=contact
[address]
group=address
[city]
group=address
[country]
group=address
</code>
By default, the "name" group will appear first in the form, followed by "contact" and "address". If we want to place "address" first we could add the following section to our fields.ini file:
<code>
[fieldgroup:address]
order=-1
</code>
Since the default order value is 0 on other groups, setting the "order" parameter to -1 will place the "address" group before all others.
====Field Group Directives====
The following directives are applicable in a fieldgroup section:
{| class="listing listing2"
|-
! name
! description
! version
|-
| [[fieldgroup order|order]]
| Specifies the order of the group with respect to other groups on the form. Accepts any numerical value (e.g. 0, 1, -1, 25.43), with lower values appearing first. Default value is 0.
| 0.6
|-
| [[fieldgroup label|label]]
| Specifies the label that should be used for the field group.
| 0.6
|-
| [[label_link]]
| Specifies a URL that the field group label should link to.
| 1.1.3
|-
| [[fieldgroup template|template]]
| The path to a custom template that should be used to render the fields of the field group.
| 1.0
|-
| [[fieldgroup collapsed|collapsed]]
| Boolean value (0 or 1) indicating whether the field group should be collapsed by default (user can expand it).
| 1.0
|}
fields.ini directives
en
0
GettingStarted:validation
79
Form Validation
==Form Validation==
Xataface allows you to add validation rules to fields using the fields.ini file
A common requirement for forms is to have some validation rules. Here are some example validation rules:
* The Username field is required.
* The Username must be between 6 and 16 characters long.
* The password must have at least one letter and one digit.
* The Email field must contain a valid email address.
There is no end to the types of things that you will need to validate. Xataface takes care of most of this for you with both client-side (javascript) and server-side validation. All you have to do is define some validation rules in the fields.ini file.
===Example 1: Make 'Username' a required field===
<code>
[Username]
validators:required = true
validators:required:message = "Username is required"
</code>
Placing the above inside the fields.ini file will cause the Username field to be a required field.
===Example 2: Username must be between 6 and 16 characters long===
For this rule we will use a regular expression.
<code>
[Username]
validators:regex = "/^.{6,16}$/"
validators:regex:message = "Username must be between 6 and 16 characters long"
</code>
===Example 3: Email field must contain a valid email address===
<code>
[Email]
validators:email = true
validators:regex:message = "Email must contain a valid email address"
</code>
===Available validation rules===
Xataface uses the PEAR library HTML_Quickform for validation, so any of the validators available in this package will be available in Xataface. Some of the available validation rules include:
* required
* maxlength
* rangelength
* regex
* email
* emailorblank
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
===Default validation rules===
There are certain validation rules that are automatically applied to fields of with certain characteristics. For example, any field designated NOT NULL in the SQL table definition will automatically be a 'required' field. At the time of this writing, that is the only 'default' validation rule applied, but more may be added in the future if their addition makes sense.
form validation,required field,validation rules
en
getFeed
42
getFeed
==getFeed() Delegate Class Method==
[[toc]]
===Synopsis:===
The getFeed() method of a table [[Delegate class methods|delegate class]] or [[Application Delegate Class|application delegate class]] returns an associative array of parameters to configure the [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]] for a particular table . An RSS feed consists of the following components:
# '''title''' - The title of the RSS feed as it should appear in the subscribers' feed list.
# '''description''' - Describes the RSS feed.
# '''link''' - A link to the RSS feed
# '''syndicationURL''' - The URL to this RSS feed's site.
===Parameters===
# '''array''' $query - The HTTP query. Contains information like the current table, current action, and search parameters. This allows you to customize your RSS feed depending on the user's query parameters.
===Return Value===
The getFeed() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys:
{| class="listing listing2"
! Name
! Description
! Version
|-
| title
| The title for the RSS feed. If this omitted, it will try to use the ''title'' directive of the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will try to generate an appropriate title for the feed depending on the current query.
| 1.0
|-
| description
| A Description for this RSS feed. If this is omitted, it will try to use the ''description'' directive of the ''[_feed]'' section of the [[conf.ini file]].
| 1.0
|-
| link
| A link to the source page of the RSS feed. If this is omitted, it will try to use the ''link'' directive of the ''[_feed]'' section of the [[conf.ini file]].
| 1.0
|-
| syndicationURL
| A link to the source page of the RSS feed. If this is omitted, it will try to use the ''syndicationURL'' directive of the ''[_feed]'' section of the [[conf.ini file]].
| 1.0
|}
===Example===
<code>
function getFeed(&$query){
return array(
'title' => "RSS feed for the ".$query['-table']." table.",
'description' => "News and updates for automobiles",
'link' => df_absolute_url(DATAFACE_SITE_HREF),
'syndicationURL' => df_absolute_url(DATAFACE_SITE_HREF)
);
}
</code>
'''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''.
===See Also:===
* '''[[getFeedItem]]''' - A delegate class method available to both the [[Delegate class methods|table delegate classes]] to configure parameters for the particular items of the RSS feed.
* '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list.
* '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method.
* '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support.
en
0
getFeedItem
41
getFeedItem
==getFeedItem() Delegate Class Method==
[[toc]]
===Synopsis:===
The getFeedItem() method of a table [[Delegate class methods|delegate class]] returns an associative array of parameters for a record as it should appear as part of an [[Introduction_to_RSS_Feeds_in_Xataface|RSS feed]]. An RSS feed item consists of the following components:
# '''title''' - The title of the record as it appears in the RSS feed.
# '''description''' - The description of the record for the RSS feed. This is really the body of the RSS feed item.
# '''link''' - The linkback URL if users want to know more about the record.
# '''date''' - The date that the record was posted/modified.
# '''author''' - The name of the person who posted this record.
# '''source''' - URL to the site where record originated from.
===Parameters===
# '''Dataface_Record''' &$record - The record that is being represented in an RSS feed.
===Return Value===
The getFeedItem() method returns an associative array with the components of the RSS feed. This array does not need to contain all possible keys, or even any keys. Any keys that are omitted will simply use default values in the RSS feed. The array may contain the following keys:
{| class="listing listing2"
! Name
! Description
! Version
|-
| title
| The record title as it appears in RSS feeds. If this is omitted, the RSS feed will simply use the output of [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getTitle getTitle()] method.
| 1.0
|-
| description
| The record description. This is used in the main body of the RSS feed. If this is omitted, the RSS feed will use an HTML table that shows all of the field data in the record. This value can also be overridden using the [[getRSSDescription]] method of the delegate class.
| 1.0
|-
| link
| The URL to this record. If this is omitted it just points to the ''view'' tab for this record. However you can direct it anywhere you like. When the user clicks on the "More Info" link in his RSS reader it will direct him to this link.
| 1.0
|-
| date
| The date that this record was posted or last modified. This is the date that an RSS reader will use to decide if it has already loaded the record yet. If this is omitted it will try the [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getLastModified getLastModified()] method to obtain the last modified date of the record. Failing that, it will use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreated getCreated()] method to try to obtain the creation date of the record. This date should be a unix timestamp.
| 1.0
|-
| author
| The name of the user who posted this record. If this is omitted, then it will try to use [http://dataface.weblite.ca/Dataface_Record Dataface_Record's] [http://dataface.weblite.ca/getCreator getCreator()] method. Failing that, it will use the value of the ''default_author'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. If that is not defined, then it simply uses the string "Site Administrator".
| 1.0
|-
| source
| The source URL where the feed is to have originated. If none is specified, then it will use the value of the ''source'' parameter in the ''[_feed]'' section of the [[conf.ini file]]. Failing that, it will simply use the URL to the application.
Note that you can alternatively define this value using the [[getFeedSource]] method.
| 1.0
|}
===Example===
<code>
function getFeedItem(&$record){
return array(
'title' => "News Item: ".$record->getTitle(),
'description' => $record->display('News Body'),
'link' => $record->getPublicLink(),
'date' => strtotime($record->val('last_modified')),
'author' => $record->val('posted_by'),
'source' => 'http://www.example.com'
);
}
</code>
'''Note that RSS feeds will work perfectly well without defining this method. This just allows you to customize one or more parameters of the RSS feed'''.
===See Also:===
* '''[[getFeed]]''' - A delegate class method available to both the [[Application Delegate Class]] and the [[Delegate class methods|table delegate classes]] to configure the RSS feed as a whole (not just for an individual item in the RSS feed.
* '''[[getRelatedFeed]]''' - A [[Delegate class methods|delegate class method]] available to both the [[Application Delegate Class|application delegate class]] and the [[Delegate class methods|table delegate classes]] to configure the [[Introduction to RSS Feeds in Xataface|RSS feed]] for a related records list.
* '''[[getRSSDescription]]''' - A delegate class method to override the description that appears for a particular record in an RSS feed. (The same as the ''description'' parameter of the [[getFeedItem]] method.
* '''[[Introduction to RSS Feeds in Xataface]]''' - An overview of Xataface's RSS feed support.
en
0
getRegistrationActivationEmailInfo
17
getRegistrationActivationEmailInfo
==getRegistrationActivationEmailInfo() Hook==
A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default information that is used to send the registration activation email (the email that the user receives when they register).
This should return an associative array with the keys:
* subject - The subject of the activation email.
* message - The message body of the activation email.
* parameters - The parameters to be used in the mail() function for the activation email.
* headers - The headers to use in the mail() function for the activation email.
===Signature===
function getRegistrationActivationEmailInfo( Dataface_Record &$record, string $activationURL ) : array
====Parameters====
{| class="listing listing2"
! Name
! Description
|-
| &$record
| A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration.
|-
| $activationURL
| The URL where the user can go to activate their account.
|-
| returns
| Mixed. If this method returns a PEAR_Error object, then registration will fail with an error.
|}
===Example===
<code>
<?php
class conf_ApplicationDelegate {
function getRegistrationActivationEmailInfo(&$record, $activationURL){
return array(
'subject' => 'Welcome to the site.. Activation required',
'message' => 'Thanks for registering. Visit '.$activationURL.' to activate your account',
'headers' => 'From: webmaster@example.com' . "\r\n" .
'Reply-To: webmaster@example.com' . "\r\n" .
'X-Mailer: PHP/' . phpversion()
);
}
}
</code>
===Example 2: Only override the subject===
<code>
<?php
class conf_ApplicationDelegate {
function getRegistrationActivationEmailInfo(&$record, $activationURL){
return array(
'subject' => 'Welcome to the site.. Activation required'
);
}
}
</code>
===See Also===
* [[beforeRegister]]
* [[afterRegister]]
* [[validateRegistrationForm]]
* [[sendRegistrationActivationEmail]]
* [[getRegistrationActivationEmailSubject]]
* [[getRegistrationActivationEmailMessage]]
* [[getRegistrationActivationEmailParameters]]
* [[getRegistrationActivationEmailHeaders]]
en
0
getRegistrationActivationEmailMessage
19
getRegistrationActivationEmailMessage
==getRegistrationActivationEmailSubject() Hook==
A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default registration activation email message body (the email that the user receives when they register).
===Signature===
function getRegistrationActivationEmailSubject( Dataface_Record &$record, string $activationURL ) : string
====Parameters====
{| class="listing listing2"
! Name
! Description
|-
| &$record
| A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration.
|-
| $activationURL
| The URL where the user can go to activate their account.
|-
| returns
| Mixed. If this method returns a PEAR_Error object, then registration will fail with an error.
|}
===Example===
<code>
<?php
class conf_ApplicationDelegate {
function getRegistrationActivationEmailInfo(&$record, $activationURL){
return 'Thanks for registering. Please visit '.$activationURL.' to activate.';
}
}
</code>
===See Also===
* [[beforeRegister]]
* [[afterRegister]]
* [[validateRegistrationForm]]
* [[sendRegistrationActivationEmail]]
* [[getRegistrationActivationEmailInfo]]
* [[getRegistrationActivationEmailSubject]]
* [[getRegistrationActivationEmailParameters]]
* [[getRegistrationActivationEmailHeaders]]
en
0
getRegistrationActivationEmailSubject
18
getRegistrationActivationEmailSubject
==getRegistrationActivationEmailSubject() Hook==
A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the default registration activation email subject line (the email that the user receives when they register).
===Signature===
function getRegistrationActivationEmailSubject( Dataface_Record &$record, string $activationURL ) : string
====Parameters====
{| class="listing listing2"
! Name
! Description
|-
| &$record
| A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration.
|-
| $activationURL
| The URL where the user can go to activate their account.
|-
| returns
| Mixed. If this method returns a PEAR_Error object, then registration will fail with an error.
|}
===Example===
<code>
<?php
class conf_ApplicationDelegate {
function getRegistrationActivationEmailInfo(&$record, $activationURL){
reeturn 'Welcome to the site.. Activation required';
}
}
</code>
===See Also===
* [[beforeRegister]]
* [[afterRegister]]
* [[validateRegistrationForm]]
* [[sendRegistrationActivationEmail]]
* [[getRegistrationActivationEmailInfo]]
* [[getRegistrationActivationEmailMessage]]
* [[getRegistrationActivationEmailParameters]]
* [[getRegistrationActivationEmailHeaders]]
en
0
Grafted_fields
158
Grafted fields
==Grafted Fields==
===Introduction===
When there are numerous tables, it is difficult for the user to see get an information that will help one to enter the right data in the right field. So instead of navigating in the relative tables and lose some time, it is more convenient to add a grafted field from that relative table in the table. To be able to sort a column by the content displayed when this content is extracted form a relative table, a grafted field is necessary because the real content is just an id, not the most convenient to sort in human-readable way.
===Procedure===
Two ways to add a grafted filed
* The first one is to add a __sql__ statement at the beginning of fields.ini, including the grafted field through a join.
<code>__sql__ = "select p.*, d.total from programmation p left join dev d on p.id_programmation=d.id_programmation" </code>
* The second one is to create the function __sql__ in the delegate class
<code>function __sql__(){
return "select p.*, d.total from programmation p left join dev d on p.id_programmation=d.id_programmation";
}
</code>
===Sorting order based on relationship===
The solution is to hide the field with the id and to add the grafted field with the name in the fields.ini
<code>[name_programmation]
order=10
[id_programmation]
visibility:list=hidden
</code>
===Debugging===
A couple of things to check for:
*1. If you have set blanket default permissions for your fields using the __field__permissions() method you could be disallowing access to the field.
*2. If you have set default field visibility in the fields.ini file via the [__global__] section....
*3. Check to make sure that your __sql__ directive is at the beginning of the file and that it is __sql__ and not _sql_
*4. Try to enter an obviously invalid SQL query for the __sql__ directive to see if you get an error (to confirm that it is picking up the __sql__ directive at all).
grafted fields, grafted, sorting columns, sort, relative records, relative tables
en
group
28
group
==group directive in [[fields.ini file]]==
The group directive allows you to declare that certain fields of your table should be grouped together on the edit form and the view tab (and other logical places). For example, fields like address, city, state, country, postal_code would likely be grouped together as address_info. Grouping the fields together will make the fields appear in a section of their own in the view tab and the edit form.
E.g. In your fields.ini file:
<code>
[address]
group=address_info
[city]
group=address_info
[state]
group=address_info
[country]
group=address_info
[postal_code]
group=address_info
</code>
===Configuring the Group as a Whole===
You can also configure your group in the fields.ini file by adding a '''fieldgroup:NAME''' section, where '''NAME''' is the name of the group. E.g.
<code>
[fieldgroup:address_info]
label="Address Information"
description = "Please enter your address information below"
</code>
====See also:====
* [[fields.ini file]] - Scroll down to the '''Field Groups''' section.
en
0
How_to_Add_Custom_Sections_to_View_Tab
52
How_to_Add_Custom_Sections_to_View_Tab
==How to Add Custom Sections to the View tab==
[[toc]]
The ''View'' tab is intended to give the user a detailed view of the contents of a record. By default it shows the values of each non-empty field grouped into their appropriate field groups. It also shows the most recent 5 related records from each relationship in the record. You can also add your own sections by implementing the [[section__xxx]] method of the delegate class.
==Example 1: A "Hello World" Section==
We'll start by adding a simple section that simply displays "Hello World" to the user. In the delegate class for your table, add the following method:
<code>
function section__hello(&$record){
return array(
'content' => 'Hello World!!!',
'class' => 'main'
);
}
</code>
Now if you reload our application and click on the "View" tab for any of the records in the database, you'll notice a section labelled ''hello'' with the text ''Hello World!!!'' in it.
Let's dissect the above code so that we can better understand what is going on here.
# The function ''section__hello()'' defines a section named ''hello''. If you wanted to define a section named ''foo'' you would call the function ''section__foo()''
# This function returns an array with the keys ''content'', and ''class''.
# The ''content'' key points to the actual HTML content of the section. In this case it is simply the text ''Hello World!!!''.
# The ''class'' key defines where the section should be displayed. It accepts values of ''left'' and ''main'' only. If it is set to ''left'', then the section will be displayed in the left column. A value of ''main'' indicates that it should be displayed in the main column.
===Customizing the Section Label===
''hello'' is a boring label, so let's add our own custom label by adding the ''label'' key to the array returned by our method:
<code>
function section__hello(&$record){
return array(
'content' => 'Hello World!!!',
'class' => 'main',
'label' => 'Message of the Day'
);
}
</code>
Now if you load the view tab of your application, you'll notice that the section has a heading "Message of the Day".
===Customizing the Section Order===
A section can also specify an ''order'' attribute to define the order in which this section should appear. It defaults to 0 which may cause the section to appear at the top of the view tab. You can push it to the bottom of the view tab by assiging a higher number to the ''order'' attribute:
<code>
<code>
function section__hello(&$record){
return array(
'content' => 'Hello World!!!',
'class' => 'main',
'label' => 'Message of the Day',
'order' => 10
);
}
</code>
Now if you reload the view tab you'll notice that the section has moved to the bottom of the page.
en
0
How_to_authenticate_users_with_LDAP_or_Active_Directory
64
How_to_authenticate_users_with_LDAP_or_Active_Directory
==How to authenticate users with LDAP or Active Directory==
en
0
http://xataface.com/documentation/how-to/site_with_backoffice
85
How to build a site with an optional login form
==How to build a site with an optional login form==
To publish a public site with data without any need to login to access, here is the code :
<code>
function getPermissions(&$record){
if ( isAdmin() ) return Dataface_PermissionsTool::ALL();
else return Dataface_PermissionsTool::READ_ONLY();
}
</code>
In this way, you still can login to administrate your data.
en
site_with_backoffice
86
==How to build a site with an optional login form==
To publish a public site with data without any need to login to access, here is the code :
<code>
function getPermissions(&$record){
if ( isAdmin() ) return Dataface_PermissionsTool::ALL();
else return Dataface_PermissionsTool::READ_ONLY();
}
</code>
In this way, you still can login to administrate your data.
en
Customizing_the_look_and_feel_of_a_row_or_a_cell
62
Customizing_the_look_and_feel_of_a_row_or_a_cell
==How to customize the look and feel of elements in the list view==
===Create a method in a delegate class===
In the delegate class, the method ''css__tableRowClass'' is implemented, like in this example :
<code>class tables_journal_interventions {
function css__tableRowClass(&$record){
if ( !$record->val('fermeture')){
return 'intervention_close';
}
else return '';
}
}
</code>
Here the function tests a condition : is there a value in the field ''fermeture'' ?
===Add the class in a CSS stylesheet===
Now the class is created in a CSS stylesheet.
<code>td.intervention_close {
background-color: #FFE6E6 !important;
} </code>
This is a class for each cell, the <td> tag. The ''!important'' attribute is added to be sure that this information has precedence over all the others. It is better to add this class in a [http://xataface.com/documentation/how-to/custom_javascripts custom CSS stylesheet].
===Remarks===
Beware that some versions of IE don't respect the background-color property on the <tr> tag, so it is probably better to write:
<code>
tr.intervention_close td {
background-color: #FFE6E6;
}</code>
i.e. to apply the background color to the individual cells.
en
0
How_to_granulate_permissions_on_each_field
63
How_to_granulate_permissions_on_each_field
==How to granulate permissions on each field==
To reach this aim, there is the method fieldname__permissions to place into the delegate class of the table.
===Getting the role===
First it is necessary to know the user's role. For this, the method getUser() is added in the class :
<code>function getUser(&$record){
$auth =& Dataface_AuthenticationTool::getInstance();
$user =& $auth->getLoggedInUser();
return $user;
}</code>
===Setting up the permissions for each field===
Next, the permissions are built for each column or field where they are needed, like in this example where the method name is formed with the field name, followed by 2 underscores then by ''permissions'' :
<code>function fieldname__permissions(&$record){
$the_user =$this->getUser($record);
$user=$the_user->val('identifiant');
if ( !$user) return Dataface_PermissionsTool::NO_ACCESS();
if ( $user=='demande' ){
return Dataface_PermissionsTool::ALL();
} elseif ($user=='admin'){
return Dataface_PermissionsTool::ALL();
}
else {
return Dataface_PermissionsTool::READ_ONLY();
}
}</code>
=== Also See ===
* [[viewable_editable_fields]] - How to make a field editable for some users and only viewable for some other users
* [[no_access_text]] - Replace the default NO ACCESS permission text with another text.
* [[__field__permissions]] - Returns the default permissions for a field of a given record.
* [[Delegate_class_methods#toc5|Permissions]] - other Delegate class methods
en
0
GettingStarted:Installation
73
Installation
==Installation==
Download and installation instructions for the Web Lite framework.
Xataface is a 100% PHP Framework that comes with all dependencies as part of the installation. The framework itself lives inside a single directory that should be placed inside the document root of your web server so that it can be accessed from the web. You can install a single copy of Xataface to be used by multiple applications on your web server. Each application just "requires" the key files from the Web Lite framework.
===Downloading===
# Go to the Xataface Sourceforge project file releases page
# Download the latest file release.
===Installing===
# Unpack the gzipped tar archive that you downloaded somewhere in your web server's document root (i.e., make sure that the 'dataface' directory is in a web-accessible location).
# Make the dataface/Dataface/templates_c directory writable by the web server. An unsafe way to do this is to
chmod 777 Dataface/templates_c
But it would be better to just give write access to the web server user.
# Confirm that the installation worked by pointing the web browser to http://yourdomain.com/path/to/dataface/dataface_info.php . If it worked OK, you should receive a web page that says "Dataface is installed correctly", along with some basic instructions for creating a Xataface Application. (Note: Sometimes this page will give you a false positive. i.e., it may say the installation worked but then your Xataface application receives errors. Check the troubleshooting section below to deal with these issues).
===Troubleshooting===
If your installation is not going as planned, don't panic. There is a possiblity that your system has a slightly different configuration and you have to make some small adjustments to make the installation work.
The general procedure for troubleshooting the installation is as follows:
# Check the [[Troubleshooting]] page.
# Look through the [http://xataface.com/forum forum] to see if others have experienced the same thing.
# Post your question in the forum if you can't find the answer already.
installation troubleshooting downloading
en
Introduction_to_RSS_Feeds_in_Xataface
40
Introduction_to_RSS_Feeds_in_Xataface
==Introduction to RSS Feeds in Xataface==
[[toc]]
A default Xataface application provides RSS feeds to any found set in your application. This article explains a little bit about RSS and how you can configure Xataface to give you the desired results for your RSS feed.
===What is RSS?===
From [http://en.wikipedia.org/wiki/RSS_(file_format) Wikipedia's RSS article]:
"RSS is a family of Web feed formats used to publish frequently updated works such as blog entries, news headlines, audio, and videoin a standardized format.[2] An RSS document (which is called a "feed", "web feed",[3] or "channel") includes full or summarized text, plus metadata such as publishing dates and authorship. Web feeds benefit publishers by letting them syndicate content automatically. They benefit readers who want to subscribe to timely updates from favored websites or to aggregate feeds from many sites into one place. RSS feeds can be read using software called an "RSS reader", "feed reader", or "aggregator", which can be web-based or desktop-based. A standardized XML file format allows the information to be published once and viewed by many different programs. The user subscribes to a feed by entering the feed's URI (often referred to informally as a "URL", although technically, those two terms are not exactly synonymous) into the reader or by clicking an RSS icon in a browser that initiates the subscription process. The RSS reader checks the user's subscribed feeds regularly for new work, downloads any updates that it finds, and provides a user interface to monitor and read the feeds."
In a way RSS replaces email subscriptions so that you can subscribe to receive updates when content is added or changed on websites that you monitory. This way you can monitory these changes in your RSS reader so that your email box doesn't get clogged up.
===Using RSS in Xataface===
Xataface allows you to subscribe to:
# Entire tables
# Any found set
# Changes to a particular record
# Related record lists
====Example 1: Subscribing to receive news updates====
A user wants to be alerted whenever a new item is inserted into the ''news'' table, so he navigates to the ''list'' tab of the ''news'' table, and clicks the RSS Feed icon in the upper right. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for the ''news'' table. When new records are inserted, he'll receive alerts in his RSS reader.
====Example 2: Subscribing to receive found set updates====
A user wants to be alerted whenever a new item is inserted into the ''news'' table that contains the phrase "Buffalo Bills", because he is a Buffalo Bills fan. So he navigates to the ''news'' table, and does a search for the phrase "Buffalo Bills". Then he clicks on the "RSS Feed" icon in the upper right of the result set list. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for ''news'' items containing the phrase "Buffalo Bills". Whenever a new item is posted with this phrase, he will be notified via RSS of the new record.
====Example 3: Subscribing to a related list====
Suppose you want to receive updates whenever a particular author adds a book to his list of published works. Further suppose this is represented by a relationship between the ''authors'' table and the ''books'' table named ''publications''. You can subscribe to the RSS feed for his publications by navigating to the ''publications'' tab for that author, then clicking on the "RSS Feed" icon in the upper right. Now whenever this author adds a new book to his publications list, you'll be notified via RSS.
===Example usage in Xataface===
# A user wants to be alerted whenever a new item is inserted into the ''news'' table, so he navigates to the ''list'' tab of the ''news'' table, and clicks the RSS Feed icon in the upper right. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for the ''news'' table. When new records are inserted, he'll receive alerts in his RSS reader.
# A user wants to be alerted whenever a new record about "Wayne Gretzky" is inserted in to the ''news'' table. He navigates to the ''news'' table, then performs a search for "Wayne Gretzky" using the top right search box. Then, he clicks on the "RSS Feed" icon in the upper right of the result list. Now, whenever a new item is inserted with the phrase "Wayne Gretzky", the user will be notified via RSS.
===Configuring RSS Feeds===
As with everything else in Xataface, you can configure your RSS feeds to appear just as you want them to. The following delegate class methods are available to be defined in the table delegate class for your feed:
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[getFeedItem]]
| For RSS Feeds, overrides the defaults and returns an associative array with feed elements for a particular record
| 1.0
|-
| [[getFeed]]
| For RSS feeds, overrides the default feed for a query, returning an array of feed items.
| 1.0
|-
| getFeedSource
| Overrides the default feed source parameter for an RSS feed.
| 1.0
|-
| getRSSDescription
| Overrides the default generated RSS description for a record.
| 1.0
|-
| [[getSingleRecordSearchFeed]]
| Overrides the default feed for a subsearch within a record. This works identically to the [[getFeed]] method except that it takes 2 parameters: one for the current record, and a second parameter for the query.
| 1.2.3
|}
==Example Configuration==
There are 2 parts to configuring your RSS feeds.
# Configuring the feed as a whole
# Configuring the feed items (that is each record that will appear in your RSS feed).
===Configuring the Feed as a whole===
For configuring the feed as a whole, we have 2 options. We can specify the title, description, and link for the feed in the ''[_feed]'' section of your [[conf.ini file]]. This is sort of a "one size fits all" approach where all feeds generated from your application will share the same title.
E.g.
<code>
[_feed]
title="My Site News"
description="News updates from my site"
link="http://www.example.com"
</code>
However, if we want our feed's information to depend on the user's query (e.g. what the user was searching for, or which table the feed is generated on, we have more flexibility if we define the [[getFeed]] method in either the [[Application Delegate Class|application delegate class]] or the [[Delegate class methods|table delegate class]]. E.g.
<code>
function getFeed($query=array()){
$params = array();
if ( @$query['-search'] ) $params['title'] = '"'.$query['-search'].'" results';
else $params['title'] = 'All records from my table';
return $params;
}
</code>
Notice that I don't need to define all possible parameters. Any parameters that I don't define will be provided automatically by Xataface, or it will simply use the values specified in your ''[_feed]'' section of the [[conf.ini file]].
===Configuring Feed Items===
Configuring the feed items is quite important for ensuring that subscribers are seeing what you want them to see in the RSS feed. Xataface tries to guess appropriate content for your feed items if you don't specify it explicitly, but you'll likely want to tweak it a little bit to make the feed look more polished for your purposes.
Use the [[getFeedItem]] [[Delegate class methods|delegate class method]] to specify how a feed item behaves (e.g. the title, content, date, author, link).
E.g.
<code>
function getFeedItem(&$record)){
return array(
'description' => $record->val('body')
);
}
</code>
Once again, notice that we don't need to specify all available options. Only those options that we want to override. In this case we want the description of the feed item to simply display the body of our news item. The description of an RSS feed item is effectively the body text that the user sees why they click on an item in their news reader, so this is quite important.
RSS Feeds
en
0
relationships.ini_file
20
relationships.ini_file
==relationships.ini File Reference==
[[toc]]
===Overview===
The relationship.ini file is a configuration file which is associated with a single table of a database application. It provides metadata about the table's relationships to other tables to help Xataface dictate how they should be included in the application.
===Field Directives===
The following directives may be added to a field's section of the relationship.ini file to customize the field's behavior. Some directives are not applicable to all fields.
{| class="listing listing2"
|-
! Name
! Description
! Version
|-
| __sql__
| The SQL query that defines this relationship.
| all
|-
| [[action:visible]]
| A boolean value (0 or 1) that indicates whether this relationship should be visible in the record tabs.
| all
|-
| [[action:condition]]
| An expression that evaluates to a boolean that determines at runtime whether the relationship's tab should appear in the record tabs.
| all
|-
| [[action:delegate]]
| The name of an alternative action that can be used instead of the standard related records list. One possible value for this would be "related_records_checkboxes" which would provide the user with a checkbox group to select the records that should be part of the relationship rather than the usual related record list.
| 1.0
|-
| [[section:limit]]
| Integer. The number of records to show in the related record sections (in the view tab). Default is 5.
| 1.0
|-
| [[section:visible]]
| Boolean value (0 or 1) indicating whether the relationship information should appear as a section on the left side of the table.
| all
|-
| [[actions:addexisting]]
| Boolean value (0 or 1) indicating whether the action to add existing records should exist in this relationship.
| all
|-
| [[actions:addnew]]
| Boolean value (0 or 1) indicating whether the action to add news records should exist in this relationship.
| all
|-
| [[action:label]]
| The label that appears in the relationship tab for this relationship.
| all
|-
| [[list:type]]
| Optional type of list to use for the related record list. Possible value: "treetable"
| 0.8
|-
| [[meta:class]]
| An optional special class to assign to the relationship. E.g. "parent" or "children".
| 0.8
|-
| [[metafields:order]]
| If the relationship should have a default order this specifies the field that should be used for this sort.
| all
|-
| [[visibility:fieldName]]
| If given the value hidden will make that particular fieldName disappear in the relationship. This will only be applied for that particular relationship.
| all
|-
| [[visibility:find]]
| If given the value hidden this will cause the related fields to not appear on the find form. Normally each relationship is provided a section of the find form to enable users to find records that contain at least one match in the related records.
| 1.3rc4
|-
| [[vocabulary:existing]]
| Specifies a valuelist that can be used to provide the set of records that can be added to this relationship. If target table has a single column primary key then the valuelist should use the primary key for the value. If it has a multi-column primary key, then the value should be in the form key1=value1&key2=value2 etc... See also [[relationshipname__getAddableValues]] delegate class method for a programatic solution.
| 1.0
|}
==Relationship Permissions==
See [[Relationship Permissions]]
==See Also==
* [http://xataface.com/documentation/tutorial/getting_started/relationships Getting started with relationships]
relationships.ini file, relationships
en
0
GettingStarted:relationships
78
Relationships
==Relationships==
Xataface allows you to define relationships between tables using the relationships.ini file.
Xataface applications without relationships between tables can be quite boring. In our FacultyOfWidgetry application, we have implicitly defined a relationship between the Program table and the Course table by adding a ProgramID field to the Course table. In the previous section we saw how to configure this relationship from the context of a 'Course' by adding a select list to the Course table form to select the Program that the Course belongs to.
From the 'Program' side it is a little bit more complicated. There are no fields in the 'Program' table that can be edited to add a 'Course' to the list of courses in a 'Program', and it would be highly inconvenient to have to edit a 'Course' record in order to add the course to a 'Program'. What we want is a sort of 'Add Course' button to add a course to a 'Program'.
===Concepts, Definitions, and Terminology===
Before we can delve into examples, it will help to go over some of the concepts and terminology involved in relationships using Xataface. Xataface relationships are always defined in a one-way fashion from the point of view of one table. For example, if you define a one-to-many relationship from the 'Program' table to the 'Course' table, the mirror (many-to-one) relationship from 'Course' to 'Program' is not automatically created. This method of defining relationships allows us to unambiguously refer to the source and destination tables of a relationship.
'''Definition 1:''' The ''source table'' of a relationship is the table on which a relationship is defined. For example if we define a relationship named 'Courses' on the 'Program' table to associate courses in a given program, then the 'Program' table would be considered the source table of the relationship, and the 'Course' table would be a destination table of the relationship.
'''Definition 2:''' The ''destination table'' of a relationship a table from which related records are selected.
There may be multiple destination tables in a given relationship but only one source table. If there are multiple destination tables, then one of these tables is designated as the domain table and the remaining destination tables are called join tables.
'''Definition 3:''' A ''domain table'' is a destination table which stores the object of the relationship. For example if we define a many-to-many relationship between the 'Program' table and the 'Course' table, (i.e., each program can contain multiple courses and each course can be part of multiple programs), then we would need to add a join table to map 'Course' records to 'Program' records. Let's call this table 'ProgramCourses'. Each record of the 'ProgramCourses' table would contain a 2 fields: a 'ProgramID' field (to reference the program) and a 'CourseID' field to reference the course. If we define the relationship from the point of view of a 'Program' then the 'Program' table would be the source table, the 'ProgramCourses' table would be the join table, and the 'Course' table would be the domain table.
Don't worry if these definitions and terms aren't clear at this point. Use this section as a reference for when you run across the terms later in the tutorial.
===Defining a relationship===
To define a relationship in Xataface, all you need to do is tell Xataface how to select the related records using SQL. Xataface will be able to figure out how to add/remove records to the relationship from this information. This information is defined inside a the 'relationships.ini' file inside the configuration folder for the table.
====Example 1: Adding a 'Courses' relationship to the 'Program' table====
We want to be able to associate multiple courses with each program. We do this by defining a relationship on the 'Program' table as follows:
# Add a file named 'relationships.ini' to the 'Program' table's configuration folder (i.e., tables/Program/relationships.ini). Your application's directory structure should now look like:<nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-relationships.gif]]<nowiki><br/></nowiki>Notice, in particular the addition of the 'relationships.ini' file in the 'Program' directory.
# Add the following to the 'relationships.ini' file:<code>
[Courses]
Course.ProgramID = "$ProgramID"
</code>
This little snippet defines a relationship named 'Courses' on the 'Program' table. 'Program' is the source table. 'Course' is the destination table. There are no join tables because this is only a one-to-many relationship. You may be wondering what the $ProgramID means. This is a variable that represents the value of the 'ProgramID' field in the source record. This relationship specifies that courses whose 'ProgramID' field matches the value of the 'ProgramID' field in the source record, are related to the source record. The english language makes this seem more difficult and complex than it really is.
Let's check out our changes. Since we have defined the relationship on the 'Program' table, we will click on the 'Program' link in the navigation menu:
[[Image:http://xataface.com/documentation/tutorial/getting_started/course-relationship-defined-1.gif]]
Notice that there is now a 'course' tab at the top of the page. Click on this tab to see the courses that are related to this Program (as defined by our 'Courses' relationship). If it says that "No records matched the request" or something to that effect, then you don't have any Course records in the relationship yet. Just click the "Add New Courses Record" button in the upper left to add a course. If there are courses in the relationship, then the Courses tab will look something like:
[[Image:http://xataface.com/documentation/tutorial/getting_started/courses-related-records.gif]]
Currently there is only one course in the program, but we can add more. If you click on the "Add New Courses" button in the upper left, you will be presented with a new course form that will allow you to add a new course in this Program.
===Example 2: Making the 'Courses' relationship a Many-to-Many relationship===
Example 1 shows how Xataface can handle a one-to-many relationship. Now we will alter the database a little bit and turn this into a many-to-many relationship.
# Add a table named 'ProgramCourses' to the database. The SQL table definition for this table should be something like:<code>
CREATE TABLE `ProgramCourses` (
`ProgramID` INT( 11 ) NOT NULL ,
`CourseID` INT( 11 ) NOT NULL ,
PRIMARY KEY ( `ProgramID` , `CourseID` )
)
</code><nowiki><p>Note that it is important for ALL of your tables to have Primary keys. If a table is missing its primary keys, some strange behavior may occur with relationships involving that table.</p>
<p>
The above defined table will serve as a join table between 'Program' and 'Course'
</p></nowiki>
# Since this is now going to be a many-to-many relationship, we no longer need the 'ProgramID' field in the 'Course' table. (Do not confuse this with the ProgramID field in the 'Program' table. That field is important and needed.). Before removing this field, we will transfer the information across so that the existing relationships are maintained. The following SQL query will effectively all of the old one-to-many relationships into equivalent many-to-many relationships:<code>
INSERT INTO ProgramCourses( ProgramID, CourseID )
SELECT ProgramID, CourseID
FROM Course
</code><nowiki><p>
And now we can remove the 'ProgramID' field from the 'Course' table.
ALTER TABLE Course DROP ProgramID</p></nowiki>
# Finally, we will need to modify the relationship definition in the relationships.ini file of the 'Program' table:<code>
[Courses]
Course.CourseID = ProgramCourses.CourseID
ProgramCourses.ProgramID = "$ProgramID"
</code><nowiki><p>
This means that all courses for which a (ProgramID, CourseID) pair matches the CourseID of the course and the ProgramID of the source Program record are included in the relationship.</p></nowiki>
# Now we can check our application for changes. Go to the 'Program' table in your application (using your web browser) and click on the 'courses' tab once again:<nowiki><br/></nowiki>[[Image:http://xataface.com/documentation/tutorial/getting_started/multi-relationship.gif]]<nowiki>
<p>
This looks almost the same as before. Notice, however that now there is an "Add Existing Courses Record" button at the top. This is because with a many-to-many relationship, you are able to add related records in 2 ways:</p></nowiki>
## Adding a completely new record that did not exist before.
## Selecting a record that already exists and adding it to the relationship.
===Example 3: Defining Relationships using SQL===
The previous examples used a simple INI file syntax to define relationships. However, some people may be more comfortable defining their relationships using SQL. This is also possible. Let's look at the relationships.ini file from example 1:<code>
[Courses]
Course.ProgramID = "$ProgramID"
</code>
This also could have been defined as follows:<code>
[Courses]
__sql__ = "SELECT * FROM Course WHERE ProgramID='$ProgramID'"
</code>
'''Note: Make sure you use two underscores on either side of 'sql' in the above example. It should be '__sql__' not '_sql_'.'''
The two syntaxes are equivalent. In fact, the former will be converted into the later by Xataface behind the scenes.
Now let's look at example 2's relationships.ini file:<code>
[Courses]
Course.CourseID = ProgramCourses.CourseID
ProgramCourses.ProgramID = "$ProgramID"
</code>
This could have been written as:<code>
[Courses]
__sql__ = "SELECT *
FROM ProgramCourses, Course
WHERE Course.CourseID = ProgramCourses.CourseID
AND ProgramCourses.ProgramID = '$ProgramID'"
</code>
The two are equivalent. This example, however, shows how defining a relationship using SQL can be beneficial. The above SQL query will work but it can be done better using Joins as follows:<code>
[Courses]
__sql__ = "SELECT *
FROM ProgramCourses pc
INNER JOIN Course c ON pc.CourseID = c.CourseID
WHERE pc.ProgramID = '$ProgramID'"
</code>
All of these 3 methods will produce the same results, but the last one will probably give a little bit better performance.
===Relationship Restrictions===
Xataface has built-in logic to figure out how to add new and existing records to relationships that you define, as long as your relationships obey a few guidelines.
# All tables must have a Primary key
# The WHERE clause of your SQL definition for the relationship must contain only '=' comparisons, and 'AND' conjunctions. i.e., it cannot receive an 'OR' conjunction, nor can comparisons be done using '>', or '<'. This is because given 'AND' and '=' conjunctions it is easy for Xataface to be able to add records that will satisfy the relationship. If an 'OR' conjunction is used, it makes it ambiguous (though this will probably be corrected in future Xataface releases.
===Download Source Files===
[http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-8-tar.gz Download the source files for this application as a tar.gz archive]
relationships
en
sendRegistrationActivationEmail
16
sendRegistrationActivationEmail
==sendRegistrationActivationEmail() Hook==
A hook that can be implemented in the [[Application Delegate Class]] or the [[Table Delegate Class]] to override the sending of an activation email to the user.
===Signature===
function sendRegistrationActivationEmail( Dataface_Record &$record, string $activationURL ) : mixed
====Parameters====
{| class="listing listing2"
! Name
! Description
|-
| &$record
| A Dataface_Record object encapsulating the record that is being inserted in the users table for this registration.
|-
| $activationURL
| The URL where the user can go to activate their account.
|-
| returns
| Mixed. If this method returns a PEAR_Error object, then registration will fail with an error.
|}
===Example===
<code>
<?php
class conf_ApplicationDelegate {
function sendRegistrationActivationEmail(&$record, $activationURL){
// mail the admin to let him know that the registration is occurring.
$username = $record->val('username');
$email = $record->val('email');
mail($email, 'Welcome to the team',
'Welcome '.$record->val('username').
'. You have been successfully registered.
Please visit '.$activationURL.' to activate your account'
);
}
}
</code>
===See Also===
* [[beforeRegister]]
* [[afterRegister]]
* [[validateRegistrationForm]]
* [[getRegistrationActivationEmailInfo]]
* [[getRegistrationActivationEmailSubject]]
* [[getRegistrationActivationEmailMessage]]
* [[getRegistrationActivationEmailParameters]]
* [[getRegistrationActivationEmailHeaders]]
en
0
tab
48
tab
==tab directive of the fields.ini file==
[[toc]]
The ''tab'' directive of the [[fields.ini file]] specifies which tab of the record edit form a field should be displayed on. Xataface supports multiple tabs on the edit form by way of this ''tab'' directive. If no fields contain the ''tab'' directive then all fields are displayed in a single tab (named ''__main__'').
==Example 1: Placing address info on separate tab==
Consider the following ''people'' table:
<code>
CREATE TABLE `people` (
person_id int(11) not null auto_increment primary key,
first_name varchar(32) not null,
last_name varchar(32) not null,
address varchar(100),
city varchar(100),
province varchar(100),
country varchar(100),
postal_code varchar(20)
)
</code>
We want to split the fields into two tabs:
* Personal Info
* Address Info
===Splitting form into tabs===
We'll do this in two steps. We use the ''tab'' directive to assign all address-related fields to the ''address_info'' tab. In the tables/people/fields.ini file:
<code>
[address]
tab=address_info
[city]
tab=address_info
[province]
tab=address_info
[country]
tab=address_info
[postal_code]
tab=address_info
</code>
Now, when we load the edit form of the ''people'' table, we see two tabs:
* __main__
* address_info
<nowiki>
<img src="http://media.weblite.ca/files/photos/Picture 9.png?max_width=640"/>
<img src="http://media.weblite.ca/files/photos/Picture 10.png?max_width=640"/>
</nowiki>
''__main__'' is the name assigned to the default tab (for all fields that don't have a tab defined explicitly.
===Customizing the tab labels===
Next we will customize the tab labels by adding the following to the beginning of the [[fields.ini file]]:
<code>
[tab:__main__]
label="Personal Information"
[tab:address_info]
label="Address Information"
</code>
<nowiki>
<img src="http://media.weblite.ca/files/photos/Picture 11.png?max_width=640"/>
<img src="http://media.weblite.ca/files/photos/Picture 12.png?max_width=640"/>
</nowiki>
===Reordering the tabs===
If we want to reorder the tabs so that the ''address_info'' tab comes first, we would just reorder the definitions of the tabs:
<code>
[tab:address_info]
label="Address Information"
[tab:__main__]
label="Personal Information"
</code>
<nowiki>
<img src="http://media.weblite.ca/files/photos/Picture 13.png?max_width=640"/>
</nowiki>
===Try This Example App===
You can try this tiny sample application out [http://dev.weblite.ca/tab_test here].
en
0
checkbox
69
checkbox
==The checkbox widget==
In the [[fields.ini file]] you can specify a field to be edited using a checkbox widget by setting [[widget:type]] to [[checkbox]]. A checkbox widget can function in 2 different ways depending on the parameters that you assign to the field.
[[toc]]
===Example 1: A TinyInt (boolean) field===
Suppose our table has a tinyint field named "Active" which specifies whether the record is currently in use. This field will store a value of either 0 or 1. So we configure this field in our [[fields.ini]] file to use a checkbox widget as follows:
<code>
[Active]
widget:type=checkbox
</code>
Results:
[[Image:http://media.weblite.ca/files/photos/Picture%2024.png?max_width=640]]
===Example 2: A repeating field (multiple checkboxes for one field===
Checkboxes can store multiple values in a single field by setting the [[vocabulary]] directive and applying it to a varchar or text field. In this case there will be one value saved per line.
In this example, suppose we have a varchar field named '''categories''' which uses the '''categories''' [[valuelist]] to specify the different categories that can be checked at any given time. Our [[valuelists.ini file]] might look like:
<code>
[categories]
__sql__ = "select id,name from categories"
</code>
And our [[fields.ini file]] looks like:
<code>
[categories]
widget:type=checkbox
vocabulary=categories
</code>
* Note that you don't need to name the field the same as the valuelist. It just worked out this way.
Now if we save a record with categories 1, 3, and 5 checked, then the categories column of our row in the database will store something like:
<code>
1
3
5
</code>
i.e. one category id per line. Note that using this method, your database will not be normalized because you are storing multiple values in a single field. However in many applications this is sufficient.
Results:
[[Image:http://media.weblite.ca/files/photos/Picture%2025.png?max_width=640]]
===Example 3: Using a "Categories" relationship===
"""(Note: This example requires Xataface version 1.2 or higher)"""
Example 2 above shows how we can easily add and remove a record from multiple categories using checkboxes. However it required multiple pieces of information to be stored in a single database field which may or may not be advantageous for your database design. If you're looking for a more normalized database schema you would probably design your database as follows for this case:
# Books table - Stores all of the books.
# Categories table - Stores all of the categories
# Book_Categories table - Stores mapping of books to categories.
With out table structure we will first want to define a relationship from Books to Categories to reflect the connection between books and categories. The [[relationships.ini file]] for this might look like:
<code>
[categories]
Books.Book_ID="$Book_ID"
Book_Categories.Category_ID=Categories.Category_ID
</code>
And our [[fields.ini file]] for the Books table might look like:
<code>
[categories]
widget:type=checkbox
transient=1
relationship=categories
</code>
* Note that there is no need for our field to be named the same as our relationship. It just turned out this way. Also note that we used the transient=1 flag here because the Books table no longer has a categories field in the database. This field is defined purely for the benefit of the edit form so that we will get a checkbox group to select the book's categories.
Results:
[[Image:http://media.weblite.ca/files/photos/Picture%2025.png?max_width=640]]
==Related Parameters==
# [[vocabulary]] - Assigns a valuelist to be used as the options for this checkbox group.
# [[repeat]] - A boolean value indicating whether this field should be treated as a 'repeating field'. A repeating field is one with multiple checkboxes. By default the checkbox widget operates as a single checkbox that controls a boolean value.
# [[relationship]] - (Only applicable to [[transient]] fields). If the [[relationship]] directive is set then this field can be used to add/remove records from a relationship.
en
0
filter
27
filter
==The filter attribute of the [[fields.ini file]]==
The filter attribute with a value of 1 specifies that a field should be used as a filter field in list view. In list view, any filter fields will provide a select list with all of the possible values in that field. Selecting one of the items in this list will filter the results to only show records of that value.
===Example 1: Year, Make, Model===
The Fuel Economy Database has three fields with filter=1 : Year, Make, and Model. I.e., in their fields.ini file we have something like:
<code>
[Year]
filter=1
[Make]
filter=1
[Model]
filter=1
</code>
This causes 3 select lists to appear in list view. See the application [http://fueleconomydb.com/index.php?-action=list here] and notice the select lists for Year, Make, and Model just above the list of results.
If you are filtering on a field where an ID is stored in the DB but you are using a vocabulary to associate it with a value, then it will still be sorted on the ID.
If you want to sort on value then you should add a [[Grafted fields|grafted field]] with the value using the __sql__ directive of the fields.ini file, then use that grafted field as your filter field, like the following:
<code>
__sql__ = "select a.*, b.foo_name from a left join b on a.foo_id=b.foo_id"
[foo_name]
filter=1
</code>
en
0
permissions.ini_file
26
permissions.ini_file
==The permissions.ini File==
[[toc]]
The permissions.ini file stores custom permissions and roles that can be used by an application. It is an optional file that should be placed in the application root directory (i.e. the same directory where your conf.ini, and index.php files are located).
The permissions.ini file allows you to define two things:
# Permissions
# Roles (i.e. sets of permissions).
Permissions and roles are used throughout Xataface to limit access to actions, records, fields, and relationships. For example, each action in your application can specify a permission that is necessary to perform the action. Your delegate classes may include getPermissions() methods to define what permissions a user gets when interacting with different records. This file (permissions.ini) simply defines the permissions that can be used by your application. It doesn't actually assign those permissions. Assigning permissions is the job of the getPermissions() (or getRoles()) method.
===Defining Permissions===
Permissions are defined by standalone properties in the beginning of the permissions.ini file. For example, if you were desiging a proof-reading application, you might need permissions for "submit_for_proof", or "approve_text" to correspond with the submitting a document to be proof-read, and approving a document's proof. In this case we would have the following at the beginning of our permissions.ini file:
<code>
submit_for_proof = Submit a document to be proofread
approve_text = "Approve this document's proof"
</code>
The left side of the equals sign is the name of the permission. The right side contains a human readable description of the permission and what it is for.
===Limiting Access to Actions based on Permissions===
At this point these permissions don't do anything. In order to be useful we need reference these permissions from an action or a section. For example, let's create an action called "submit_for_proof" which displays a form for a user to submit a document record to be proofread.
Our actions.ini file entry might look something like:
<code>
[submit_for_proof]
url="{$this->url('-action=submit_for_proof')}"
label="Submit document for proof"
category=record_actions
permission=submit_for_proof
template=submit_for_proof.html
</code>
And for completeness, since this make-believe action specifies th "submit_for_proof.html" template, we'll create the "submit_for_proof.html" template in the templates directory:
<code>
<html><body>You have permission to perform this action.</body></html>
</code>
===Defining Who Get's Which Permissions===
Finally, in order to benefit from permissions, your application has to decide that it is going to use permissions (unless you define a getPermissions() method, users are granted ALL permissions by default. Hence if you try to access our submit_for_proof action, we'll see it without any problem. Regardless of who we are. So let's create a simple, but restrictive getPermissions() method in our application delegate class:
<code>
<?php
class conf_ApplicationDelegate {
function getPermissions(&$record){
return Dataface_PermissionsTool::READ_ONLY();
}
}
</code>
Now if we try to access our submit_for_proof action it will give us a "Permission Denied" message, because we are only granted READ ONLY permissions (which is a role that includes the view permission and some others - but not our custom "submit_for_proof" permission.
Now we'll make a small modification to our getPermissions() method to provide us with our submit_for_proof permission:
<code>
<?php
class conf_ApplicationDelegate {
function getPermissions(&$record){
$perms = Dataface_PermissionsTool::READ_ONLY();
$perms['submit_for_proof'] = 1;
return $perms;
}
}
</code>
Now if we try to access our submit_for_proof action, it will show us our template with no error messages (hopefully).
===Roles===
Roles are sets of permissions. They are defined in the permissions.ini file as sections with lists of included permissions. It might be handy to create roles such as EDITOR or MANAGER which contain sets of permissions that are meant to be assigned to users of those types. For example an EDITOR may have the view and edit permissions, but not the delete permission. A MANAGER might have the view, edit, and delete permissions. You can define these two roles in the permissions.ini file as follows:
<code>
[EDITOR]
view=1
edit=1
[MANAGER]
view=1
edit=1
delete=1
</code>
Then we could assign these roles to users using the Dataface_PermissionsTool::getRolePermissions() method:
<code>
function getPermissions(&$record){
$user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
if ( $user and $user->val('role') == 'EDITOR' ){
return Dataface_PermissionsTool::getRolePermissions('EDITOR');
} else if ( $user and $user->val('role') == 'MANAGER' ){
return Dataface_PermissionsTool::getRolePermissions('MANAGER');
}
return Dataface_PermissionsTool::READ_ONLY();
}
</code>
Or equivalently we could use the getRoles() method of our delegate class instead of getPermissions():
<code>
function getRoles(&$record){
$user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
if ( $user and $user->val('role') == 'EDITOR' ){
return 'EDITOR';
} else if ( $user and $user->val('role') == 'MANAGER' ){
return 'MANAGER'
}
return 'READ ONLY';
}
</code>
===Xataface Core Permissions & Roles===
Xataface is distributed with its own permissions.ini file that defines some core permissions and roles. You can look at this permissions.ini file (located in the Xataface directory) to see what the format should look like. Any settings you place in your application's permissions.ini file will augment or override settings in Xataface's file.
Some core permissions include:
{| class="listing listing2"
|-
! Name
! Description
! Version
|-
| view
| Permission to view a record or field. This permission is required to access the view tab, and several other details tabs.
| 0.6
|-
| list
| Permission to access the list tab.
| 0.6
|-
| calendar
| Permission to access the calendar tab.
| 0.6
|-
| edit
| Permission to edit a record or field. This also gives access to the edit tab.
| 0.6
|-
| new
| Permission to edit a record or field for the purpose of creating a new record. This permission is required to access the new record form.
| 0.6
|-
| select_rows
| Permission to select rows in list view to perform actions on them.
| 0.6
|-
| post
| Permission to post a record using HTTP POST
| 0.6
|-
| copy
| Permission to copy a record.
| 0.6
|-
| update_set
| Permission to perform an update on a result set (i.e. access the update set action).
| 0.8
|-
| add new related record
| Permission to add a new record to a relationship. See [[Relationship Permissions]]
| 0.6
|-
| add existing related record
| Permission to add an existing record to a relationship. See [[Relationship Permissions]]
| 0.6
|-
| view related records
| Permission to view the records in a relationship. See [[Relationship Permissions]]
| 1.0
|-
| delete
| Permission to delete a record.
| 0.6
|-
| delete found
| Permission to access the delete found set action (to delete multiple records at a time).
| 0.6
|-
| show all
| Permission to access show all records action.
| 0.6
|-
| remove related record
| Permission to remove a record from a relationship. See [[Relationship Permissions]]
| 0.6
|-
| delete related record
| Permission to delete a record in a relationship. This is stronger than the remove related record permission in that it allows the user to delete the record from the database. See [[Relationship permissions]]
| 0.6
|-
| find
| Permission to perform the find action.
| 0.6
|-
| import
| Permission to perform the import action (to import records into the database).
| 0.6
|-
| export_csv
| Permission to perform the Export CSV action (to export the result set in comma-separated-value format).
| 0.6
|-
| export_xml
| Permission to perform the Export XML action (to export the result set as XML).
| 0.8
|-
| translate
| Permission to translate a record into another language. This permission provides access to the "translate" tab.
| 0.8
|-
| history
| Permission to view history information for a record (e.g. the history tab). This requires that history be enabled.
| 0.8
|-
| edit_history
| Permission to edit history information such as undo/redo support for a record.
| 0.8
|-
| navigate
| Permission to navigate through records of a table.
| 0.6
|-
| reorder_related_records
| Permission to reorder the records of a relationship (this is different than just sorting). It sets a default order for the records. Requires the metafields:order directive to be set for the relationship.
| 0.6
|-
| ajax_save
| Permission to save a record through AJAX.
| 0.8
|-
| ajax_load
| Permission to load a record through AJAX.
| 0.8
|-
| ajax_form
| Permission to access the inline editing ajax form for a record.
| 0.8
|-
| find_list
| Permission to search current table.
| 0.6
|-
| find_multi_table
| Permission to perform a site-wide search.
| 0.8
|-
| register
| Permission to register for an account.
| 0.8
|-
| xml_view
| Permission to view a result set as xml.
| 0.8
|-
| view_xml
| View the XML for an individual record.
| 0.8
|-
| manage_output_cache
| Management permission to clear the output cache.
| 0.8
|-
| manage_migrate
| Permission to access the migration tool to migrate between versions.
| 0.8
|-
| manage
| Permission to access the management control panel.
| 0.8
|-
| manage_build_index
| Permission to rebuild the search index.
| 0.8
|-
| expandable
| Whether the record can be expanded in the left nav menu
| N/A
|}
Some core roles include:
{| class="listing listing2"
|-
! Name
! Permissions Included
! Version
|-
| READ ONLY
| view, list, calendar, view xml, show all, find, navigate, ajax_load, find_list, find_multi_table, rss, export_csv, export_xml, and export_json
| 0.6
|-
| EDIT
| All permissions in READ ONLY, and edit, add new related record, add existing related record, add new record, remove related record, reorder_related_records, import, translate, new, ajax_save, ajax_form, history, edit_history, copy, update_set, and select_rows
| 0.6
|-
| DELETE
| All permissions in EDIT, and delete and delete found.
| 0.6
|-
| OWNER
| All permissions in DELETE except navigate, new, and delete found.
| 0.6
|-
| REVIEWER
| All permissions in READ ONLY, and edit and translate.
| 0.6
|-
| USER
| All permissions in READ ONLY, and add new related record.
| 0.6
|-
| ADMIN
| All permissions in DELETE and xml_view
| 0.6
|-
| MANAGER
| All permissions in ADMIN and manage, manage_output_cache, manage_migrate, manage_build_index, and install.
| 0.6
|}
===Extending and Overriding Roles===
The cleanest and easiest way to define a new role is to extend an existing role. Xataface allows you to extend roles via the '''extends''' keyword. For example, if you wanted to create a role '''TEST ROLE''' that contained all of the same permissions as the READ ONLY role, you could define it as follows in your application's permissions.ini file:
<code>
[TEST ROLE extends READ ONLY]
</code>
If we wanted it to contain the same permissions as READ ONLY but to also allow the edit permission we would define it as:
<code>
[TEST ROLE extends READ ONLY]
edit=1
</code>
If we wanted to disallow the list permission, we would do something like:
<code>
[TEST ROLE extends READ ONLY]
edit=1
list=0
</code>
===Overriding Existing Roles===
You can also redefine existing roles:
<code>
[READ ONLY extends READ ONLY]
my_permission=1
</code>
This is handy if you have added your own custom permissions that you feel should be included in a core role.
Note that there are some caveats regarding the order of how these roles are defined. Please refer to this forum post for more details:
[http://www.xataface.com/forum/viewtopic.php?t=6187 Overriding Roles / Permissions]
==See Also==
* [[Relationship Permissions]]
* [[getPermissions]] - The getPermissionsMethod
* [[Delegate class methods]] - Delegate class methods.
* [http://xataface.com/documentation/tutorial/getting_started/permissions Getting started with Xataface permissions]
permissions.ini, getPermissions, permissions
en
0
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:<code><?
class tables_Course {}
</code>
# Okay, we want our trigger to be called every time a record is inserted. There are 2 possible triggers that can be defined, then:<nowiki>
<ul>
<li>beforeInsert</li>
<li>afterInsert</li>
</ul>
<p>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:</p>
</nowiki><code>
<?
class tables_Course {
....
/**
* Trigger that is called after Course record is inserted.
* @param $record Dataface_Record object that has just been inserted.
*/
function afterInsert(&$record){
mail('admin_email@yourdomain.com','Subject Line', 'Message body');
}
}
</code>
# 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:
<code>
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.";
}
}
</code>
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.:
<code>
$response =& Dataface_Application::getResponse(); // correct!
$response = Dataface_Application::getResponse(); // WRONG!!
</code>
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:
<code>
<?
class tables_Course {
function beforeInsert(&$record){
$response =& Dataface_Application::getResponse();
if ( mail('shannah@sfu.ca', 'Notification', 'Your record was created')){
$response['--msg'] .= "\nEmail sent successfully to shannah@sfu.ca";
} else {
return PEAR::raiseError(
"Errors occurred while sending email. Record could not be inserted",
DATAFACE_E_NOTICE
);
}
}
}
</code>
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