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
DataGrid
32
DataGrid
==Xataface DataGrid Module==
Created by Steve Hannah, [http://weblite.ca Web Lite Solutions Corp.]
===Synopsis===
The Xataface DataGrid module uses the Ext DataGrid component (http://extjs.com) to add an editable grid component to your Xataface application.
[[toc collapse=0]]
===Requirements===
* PHP 4.3+
* MySQL 4.1+
* Xataface 0.8+
===License===
This module is distributed with ExtJS 2.2, which is distributed under the GPL v 3 (http://extjs.com/products/license.php).
In order to be compatible with the ExtJS license, this module is also distributed under the terms of the GPL v3 (http://www.gnu.org/copyleft/gpl.html).
===Demo Video===
<nowiki>
<embed src="http://media.weblite.ca/lib/flvplayer.swf" width="640" height="500" bgcolor="#FFFFFF" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" flashvars="file=http%3A%2F%2Fs3.amazonaws.com%2Fweblite_media%2FDataGrid-640x480.flv&image=http%3A%2F%2Fmedia.weblite.ca%2Ffiles%2Fphotos%2FDataGrid-640x480.flv.jpg&showdigits=true&autostart=false" />
</nowiki>
===Screenshots===
Click on image to enlarge
<nowiki>
<script language="javascript" type="text/javascript" src="http://media.weblite.ca/index.php?-action=gallery&-table=files&categories=8&-cursor=0&-skip=0&-limit=30&-mode=list&-photo_max_width=640&--format=js"></script>
<div style="clear:both"> </div>
</nowiki>
===Demo===
# LibrarianDB Demo: http://demo.weblite.ca/apps/librariandb/index.php?-table=books&-action=DataGrid_view , '''Log in with username "admin" and password "password"'''
===Download===
* [https://sourceforge.net/project/platformdownload.php?group_id=250381 DataGrid-0.2]
* SVN Repository: http://weblite.ca/svn/dataface/modules/DataGrid
===Installation===
# Download and extract the DataGrid directory into your xataface/modules directory.
# Add the following line to the [_modules] section of your application's [[conf.ini file]]:<code>
modules_DataGrid=modules/DataGrid/DataGrid.php
</code>
# Ensure that your [[permissions]] are set up appropriately to allow your users to access the grid action (see next section).
===Setting Up Permissions===
This module defines the following [[permissions]]:
* DataGrid:view_grid - Permission to view the data grid for a table.
* DataGrid:create_grid - Permission to create a new data grid
* DataGrid:edit_grid - Permission to edit an existing data grid
* DataGrid:update - Permission to update records via the grid
* DataGrid:manage_grids - Permission to access the datagrid control panel
In order for a user to access/use the grid he must be granted at least the Datagrid:view_grid and DataGrid:update [[permissions]]. Both of these [[permissions]] are included in the following system roles by default:
* EDIT
* EDIT AND DELETE
* DELETE
* ADMIN
* MANAGER
And of course these [[permissions]] are included with the call to Dataface_PermissionsTool::ALL() .
If you have assigned your own custom roles and want to enable access to the grid, you can simply add the following to your role definition in your [[permissions.ini file]]:
<code>
[MY ROLE]
DataGrid:view_grid=1
DataGrid:update=1
</code>
If you want to explicitly disable the grid for a role, you can extend the role and deny those same [[permissions]]:
<code>
[MY ROLE extends MY ROLE]
DataGrid:view_grid=0
DataGrid:update=0
</code>
===Usage===
Once installed, log in as a user that has permission to access the grid. You should notice a new tab along with "details", "list", and "find", called "grid". Click on the "grid" tab to access the grid.
You can double click on any field to edit it. Modified fields will be marked in red, and automatically saved every 5 seconds - after the changes are saved the field is no longer marked in red.
===Limitations===
Currently only fields with the following widget types are available to be edited in the grid:
# text
# textarea
# select
# date/datetime/time
Other types of fields will simply not be included in the grid.
===Support/Questions===
Visit the Xataface forum at http://xataface.com/forum
en
0
Delegate_class_methods
7
Delegate_class_methods
==Delegate Class Reference==
[[toc]]
A delegate class is a PHP class that complements a particular table with custom bahaviors. Basic table metadata can be supplied using the [[fields.ini file]], however some things are better customized using PHP.
===Delegate Class Location===
The delegate class should be located in a file named TABLENAME.php (where TABLENAME is the name of the table with which the delegate class is associated) inside the table's [[table configuration directory|configuration directory]]. E.g. given a table named "people", you would place the delegate class in the file "tables/people/people.php"
===Basic Delegate Class===
<code>
<?php
class tables_people {}
?>
</code>
===Available Methods===
====Table Settings====
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[sql delegate method|__sql__]]
| Defines the SQL query that can be used to fetch records of this table. This is identical to the [[fields.ini file]] [[__sql__]] directive, except that by defining it in the delegate class you have more flexibility.
| 1.0
|}
====Permissions====
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[getPermissions]]
| Returns the permissions available for a given record.
| 0.6
|-
| getRoles
| Returns the roles allowed for a given record.
| 1.0
|-
| [[__field__permissions]]
| Returns the default permissions for a field of a given record.
| 1.0
|-
| __field__roles
| Returns the default roles for a field of a given record.
| 1.0
|-
| [[fieldname__permissions]]
| Returns the permissions that are allowed for the field "fieldname" on a given record.
| 0.7
|-
| fieldname__roles
| Returns the roles that are allowed for the field "fieldname" on a given record.
| 1.0
|-
| rel_relationshipname__permissions
| Returns the permissions pertaining to the relationship ''relationshipname'' on a given record.
| 1.0
|-
| rel_relationshipname__roles
| Returns the role or roles pertaining to the relationship ''relationshipname'' on a given record.
| 1.0
|}
====Triggers====
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[after_action_edit]]
| Trigger called after the edit action is succesfully completed.
| 0.7
|-
| [[after_action_new]]
| Trigger called after the new action is successfully completed.
| 0.7
|-
| [[after_action_delete]]
| Trigger called after the delete action is successfully completed.
| 0.7
|-
| [[afterAddExistingRelatedRecord]]
| Trigger called after an existing related record is added.
| 0.5
|-
| [[aftereAddNewRelatedRecord]]
| Trigger called after a new related record is added.
| 0.5
|-
| [[afterCopy]]
| Trigger called after a record is copied.
| 1.3
|-
| [[afterDelete]]
| Trigger called after a record is deleted.
|0.5
|-
| [[afterAddRelatedRecord]]
| Trigger called after a related record of this table is added (either an existing record or a new record).
| 0.5
|-
| [[afterRemoveRelatedRecord]]
| Trigger called after a related record is removed from a relationship.
| 1.1.6
|-
| [[afterInsert]]
| Trigger called after a given record is inserted.
| 0.5
|-
| [[afterSave]]
| Trigger called after a given record is saved (insert or update).
| 0.5
|-
| [[afterUpdate]]
| Trigger called after a given record is updated.
| 0.5
|-
| [[beforeAddExistingRelatedRecord]]
| Trigger called before an existing related record is added.
| 0.5
|-
| [[beforeAddNewRelatedRecord]]
| Trigger called before a new related record is added.
| 0.5
|-
| [[beforeAddRelatedRecord]]
| Trigger called before a related record of this table is added (either an existing record or a new record).
| 0.5
|-
| [[beforeCopy]]
| Trigger called before a record is copied.
| 1.3
|-
| [[beforeDelete]]
| Trigger called before a record is deleted.
| 0.5
|-
| [[beforeRemoveRelatedRecord]]
| Trigger called before a related record is removed.
| 1.1.6
|-
| [[beforeSave]]
| Trigger called before a given record is saved (insert or update).
| 0.5
|-
| [[beforeInsert]]
| Trigger called before a given record is inserted.
| 0.5
|-
| [[beforeUpdate]]
| Trigger called before a given record is updated.
| 0.5
|-
| [[init]]
| This method is called the first time the table is loaded. It allows you to specify initialization details.
| 0.8
|}
====Field Filters====
{| class="listing listing2"
! Name
! Description
! Version
|-
| fieldname__htmlValue
| Returns the value of the field "fieldname" for a given record as HTML.
| 0.5
|-
| fieldname__display
| Returns the value of the field "fieldname" appropriate for displaying.
| 0.5
|-
| [[fieldname__default]]
| Returns the default value for the field ''fieldname''. New record forms will be prepopulated with this value.
| 0.7
|-
| [[fieldname__validate]]
| Validates the input for the field ''fieldname''.
| 0.6
|-
| fieldname__parse
| Parses the input value for the field ''fieldname''. This is called by Xataface inside the setValue() method or each record to normalize input values before they are stored in the object (not the database).
| 0.5
|-
| fieldname__toString
| Converts the value of the field ''fieldname'' to a string. This string representation is used as the basis for most higher level data retrieval methods (such as serialize and display). This could be treated as an inverse to the [[fieldname__parse]] method.
| 0.5
|-
| fieldname__serialize
| Converts a value of the field ''fieldname'' to be saved in the database. This should return a string representation of the value that is suitable for database storage.
| 0.5
|-
| fieldname__link
| A link that appears beside the field ''fieldname'' on the edit form.
| 0.6
|-
| [[field__pushValue]]
| Converts form input for field ''fieldname'' to be ready to store in a Dataface_Record.
| 0.6
|-
| [[field__pullValue]]
| Converts a value for field ''fieldname'' in a Dataface_Record object to be ready to be inserted as a value on an HTML form.
| 0.6
|-
| [[field__fieldname]]
| Effectively creates a calculated field named "fieldname" available on the given record.
| 0.6
|-
| [[no_access_text]]
| Replace the default NO ACCESS permission text with another text.
| 1.1.6
|-
| [[no_access_link]]
| Replace the default link of the NO ACCESS permission link with another link.
| 1.1.6
|}
====Template Customization====
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[block__blockname]]
| Outputs content that is meant to override a slot or a block named "blockname".
| 0.6
|}
====List Tab Customization====
{| class="listing listing2"
! Name
! Description
! Version
|-
| css__tableHeaderCellClass
| Returns a custom CSS class for a table header cell (th tag) in the list view. Takes the name of a table column as a parameter.
| 2.0alpha2
|-
| css__tableRowClass
| Returns a custom CSS class for a table row (tr tag) in list view. Takes a Dataface record as a parameter.
| 1.2
|-
| fieldname__renderCell
| Overrides the table cell content for the "fieldname" field in list view with custom HTML.
| 1.0
|-
| renderRow
| Overrides the the html used for a row in list view for the given record.
| 0.7
|-
| renderRowHeader
| Overrides the header for the table in list view.
| 0.7
|-
| renderRelatedRow
| Overrides the html used for a row in a related record list for a given related record.
| 1.0 beta 4
|-
| renderRelatedRowHeader
| Overrides the html used for the header in a related list.
| 1.0 beta 4
|}
====Record Metadata====
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[getBreadCrumbs]]
| Returns the bread crumbs (i.e. you are here) for a given record as an associative array of path parts.
| 0.6
|-
| [[getChildren]]
| Returns a list of Dataface_Record objects that are to be considered children of the given record.
| 0.8
|-
| [[getCreated]]
| Returns a unix timestamp marking the date that a record was created.
| 0.9
|-
| getDescription
| Returns a string description summary of this record. This is used for indexing, RSS feeds, and anywhere that a brief summary of a record is appropriate.
| 0.7
|-
| getPublicLink
| Returns the public URL of this record (in case it is different than the standard URL).
| 0.8
|-
| getTitle
| Returns the title for a given record. The title is used in various parts of the application to represent the record.
| 0.5
|-
| [[getURL]]
| Overrides the getURL() method for a record. Returns the URL that should be used to display the given record.
| 0.6
|-
| titleColumn
| Returns a string SQL select expression that is used to describe the title of records.
| 0.5
|}
====View Tab Customization====
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[How_to_Add_Custom_Sections_to_View_Tab|section__sectionname]]
| Defines a section to be displayed in the view tab for the given record.
| 0.7
|}
====Search Setup====
{| class="listing listing2"
! Name
! Description
! Version
|-
| getSearchableText
| If [[_index|Indexing]] is turned on, then this returns the text that should be stored in the index for this record for searchability.
| 1.0
|}
====RSS Feed Customization====
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[getFeedItem]]
| For RSS Feeds, overrides the defaults and returns an associative array with feed elements for a particular record
| 1.0
|-
| [[getFeed]]
| For RSS feeds, overrides the default feed for a query, returning an array of feed items.
| 1.0
|-
| getFeedSource
| Overrides the default feed source parameter for an RSS feed.
| 1.0
|-
| [[getRelatedFeed]]
| For RSS feeds, overrides the default feed for a related feed.
| 1.0
|-
| getRSSDescription
| Overrides the default generated RSS description for a record.
| 1.0
|}
===XML Output Customization===
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[toXML]]
| Overrides the default XML produced for a record in the [[export xml]] action. Returns an XML string.
| 1.2.7
|-
| [[getXMLHead]]
| Returns a string to be included at the beginning of XML output for a particular record. (just inside the opening tag).
| 1.2.7
|-
| [[xmlTail]]
| Returns a string to be included at the end of XML output for a particular record. (just inside the closing tag).
| 1.2.7
|}
====Valuelist Customization====
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[valuelist__valuelistname]]
| Defines a valuelist named ''valuelistname''.
| 0.7
|}
====Importing Records====
{| class="listing listing2"
! Name
! Description
! Version
|-
| [[__import__filtername]]
| Defines an import filter to named ''filtername'' which is used to import records into the table.
| 0.7
|}
RSS,Feeds,delegate classes, triggers
en
0
documentation_guide
70
Documentation Guide
Xataface uses a wiki to manage its online documentation which can be edited by anyone. All you have to do is [http://xataface.com/wiki/index.php?-action=login login with your forum username and password] ([http://xataface.com/forum/profile.php?mode=register register for the forum here]). Then when you are browsing a page of the wiki, you'll see an 'Edit' tab along the top. Click on this tab to start editing the page in your browser. Wiki markup is a little simpler than HTML and a little more complex than plain text. It is easy to get a handle on once you get started. If you aren't sure how to format it exactly how you want, don't worry. Someone may come by after you and improve on your formatting. That's what the community approach is all about.
==The Documentation Team==
Join the Xataface documentation team to help participate in the planning of the documentation. If you want to help out, contact [mailto:steve@weblite.ca Steve Hannah] and he'll add you to the documentation group where you can access the private documentation forums and meet the rest of the team.
==Using the Wiki==
The following is a brief guide in using the Xataface Wiki. All following instructions assume that you are already [http://xataface.com/wiki/index.php?-action=login logged in] to the wiki. You can use your forum username and password to login.
===Editing an Existing Page===
# Navigate to the page that you want to edit
# Click on the "Edit" tab along the top.
# Make changes to your page.
# Save the changes.
===Adding a New Page===
====Method 1: Add a link from an existing page===
# Navigate to an existing page that you want to link to your new page.
# Click on the "Edit" tab along the top.
# Somewhere in the content of the page, add a link to your new page (which doesn't exist yet), by adding the following markup<code>
[[The name of your new page]]
</code>
# Save your changes.
# Click on the "view" tab along the top and find the place where you added your link. It should be displayed with a '?' right after it. Click on the '?' and it will bring you to the "new page form".
# fill in the form with your page contents and click save.
====Method 2: Accessing new page form directly====
# Access the [http://xataface.com/wiki/index.php?-action=new&-table=wiki new page form] directly.
===Uploading Images===
Image can be uploaded at [http://media.weblite.ca The Web Lite Media Manager]. You'll need an account to access this site. If you are a member of the documentation team you can request an account from [mailto:steve@weblite.ca Steve Hannah] so that you can upload images here.
Steps:
# Log into [http://media.weblite.ca the Web Lite Media Manager].
# Click on "Add New File" in the menu on the left.
# Select a name for the file, and browse to the image you want to upload in the file upload field. You don't need to check any category boxes. Press save.
# Click on the "View" tab for your newly uploaded image.
# Copy the embed code for the image from the "Embed Code" field.
# In the wiki page add the embed code where you want your image to appear as follows:<code>
[[Image:EMBED_CODE]]
</code> Where EMBED_CODE is the URL for the image as you copied and pasted out of the media manager.
# Save your changes.
===Uploading Video===
===Adding Source Code Snippets===
documentation wiki
en
Drag_and_Drop_Reordering_of_Relationships
39
Drag_and_Drop_Reordering_of_Relationships
==Drag and Drop Reordering of Related Records in Xataface==
One powerful aspect of Xataface is its abstraction of relationships between tables. Once you define a relationship users can browse related records, add new and existing related records, and delete related records to or from the relationship. For example, suppose you have a ''people'' table and a ''publications'', you could define a relationship from ''people'' to ''publications'' to identify publications that belong to a particular person. The table's might look something like:
===people table===
{| class="listing listing2"
! person_id
! person_name
|-
| 1
| John Smith
|-
| 2
| Ben Stein
|-
| 3
| Harley Davidson
|-
| 4
| Trevor Linden
|}
===publications table===
{| class="listing listing2"
! publication_id
! owner_id
! pub_title
|-
| 1
| 2
| Introduction to widgetry
|-
| 2
| 2
| Intermediate Widgetry
|-
| 3
| 2
| Advanced Widgetry
|-
| 4
| 3
| How to play the violin
|}
See http://xataface.com/documentation/tutorial/getting_started/relationships for an introduction to relationships in Xataface, and how to define them.
Our relationship definition in the ''people'' table's [[relationships.ini file]] might look something like:
<code>
[my_pubications]
publications.owner_id="$person_id"
</code>
This indicates that any publication whose ''owner_id'' column matches the current ''people'' record's ''person_id'' field is considered part of the relationship. Using our example data above, this would mean that Ben Stein's ''my_publications'' relationship would contain 3 records: "Introduction to Widgetry", "Intermediate Widgetry", and "Advanced Widgetry". In our Xataface application this means that in the "Details" tab for the "Ben Stein" record, we would see a sub-tab ''My Publications'' which would contain a list of Ben Stein's publications.
===Adding Publication Order===
Now that we have our relationship, what if Ben Stein wants his publications to appear in a particular order whenever they are displayed to the user. Xataface allows us to specify an "order" column for our relationship, which will cause the related records to be orderable by drag and drop (if the user has appropriate permissions).
# Add a field to the ''publications'' table named "pub_order"
# Change the relationship definition in the people table's [[relationships.ini file]] to tell Xataface to use the pub_order field for sorting:<code>
[my_pubications]
publications.owner_id="$person_id"
metafields:order="pub_order"
</code>
Now load up your application and navigate to the "My Publications" tab for the "Ben Stein" record. Now you're able to drag and drop rows in your application to reorder them.
===Permission to Reorder Records===
Only users who have been assigned the ''reorder_related_records'' permission for a record's relationship are allowed to reorder records of that relationship. By default the ''EDIT'' role contains this permission, as does any role that permits the user to edit the parent record of the relationship. The ''READ ONLY'' role does not contain this permission. If you want to explicitly deny this permission for all relationships in a record, you can simply set this permission to 0 in the associated role within your application's [[permissions.ini file]]:
<code>
[MY ROLE]
reorder_related_records=0
</code>
For more information about permssions see:
* [[permissions.ini file|The Permissions.ini file reference]]
* [http://xataface.com/documentation/tutorial/getting_started/permissions Introduction to Permissions]
===Loading Related Records using the Xataface API===
The ordering that is set via this drag and drop method is also honoured by the Xataface API when fetching related records. You can load related records using the [http://dataface.weblite.ca/getRelatedRecordObjects getRelatedRecordObjects] method of the [http://dataface.weblite.ca/Dataface_Record Dataface_Record] class. E.g.
<code>
$benStein = df_get_record('people', array('person_id'=>2));
$pubs = $benStein->getRelatedRecordObjects('my_publications');
foreach ($pubs as $pub){
echo $pub->val('pub_title').'<br/>';
}
</code>
This will list up to the first 30 publications of Ben stein in the order prescribed by our drag and drop ordering scheme.
en
0
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
Email
54
Email
==Xataface Email Module==
[[toc]]
The Xataface Email module allows you to convert your database into a mailing list so that you can easily send email to any found set of records, as long as the records contain an email address to send to.
==Features==
* Send email to any found set.
* Mail merge macros
* HTML Email support (uses NicEdit WYSIWYG editor for email editing).
* Opt out support (allows recipients to opt out of your mailing list).
==Requirements==
* Xataface 1.0+
* MySQL 4.1+
* PHP 5+
==Download==
https://sourceforge.net/project/platformdownload.php?group_id=253820
==Installation==
# Download and extract Email directory so that it is located inside the xataface/modules directory (i.e. xataface/modules/Email)
# Add the following to the ''[_modules]'' section of your application's conf.ini file:<code>
modules_Email="modules/Email/Email.php"
</code>
# Configure the [email] action in your application's actions.ini file. See the section called 'Configuration' for configuration details.
# Add a line to your crontab file to send out pending email periodically. The line should look like:<code>
* * * * * /usr/bin/php <cronpath> <indexpath> <indexurl> mail
where <cronpath> is the absolute path to the cron.php script.
<indexpath> is the absolute path to your application's index.php script.
<indexurl> is the absolute url to your application's index.php script.
For example:
* * * * * /usr/bin/php /var/www/xataface/modules/Email/cron.php \
/var/www/myapp/index.php \
http://example.com/myapp/index.php \
mail
</code> If you want to see what this line should be like for your server, you can simply point your browser to the email_install action of your application (i.e. http://example.com/yourapp/index.php?-action=email_install) and it will generate this line to copy and paste into your crontab. Note that the /usr/bin/php portion of this line may vary according to your environment. It represents the path to your PHP binary.
# That's it! You're ready to send email. See the ''Usage'' section to see how to send email from your application.
==Configuration==
Though the email action may work out of the box, you will likely have to configure it to work the way you want. Some examples of things you will want to configure include:
# Limit the email action to only be available for certain tables.
# Apply permissions to the action so that only administrators can send email.
# Set the name of the column that contains email address (default is 'email').
# Change the name of the table that is used to store sent email messages.
===Overriding the ''[email]'' action===
The first thing you need to do to configure the email action is override it in your appliation's actions.ini file. You can do this by adding the following to your [[actions.ini file]]:
<code>
[email > email]
</code>
Now any directives you add in this section will override the email action.
====Examples:====
=====Limiting email action to certain tables=====
In your appliation's [[actions.ini file]]:
<code>
[email > email]
condition="$query['-table'] == 'Pledge' or $query['-table'] == 'User'"
</code>
=====Limiting email action by permission=====
By default your users require the ''email'' permission in order to have access to the email form. This permission is not included with any roles by default so you'll need to extend any roles that you want to have access to the email access and explicitly add the ''email'' permission. The exception to this rule is if you have assigned your users the ''Dataface_PermissionsTool::ALL()'' permissions in your ''getPermissions()'' method.
Suppose you want the ''READ ONLY'' role to have access to the email action, you could add the following to your application's [[permissions.ini file]]:
<code>
[READ ONLY extends READ ONLY]
email=1
</code>
=====Changing the name of the email address column=====
By default, the Email module will try to guess which column contains the email address for a table. Generally it looks for a column named ''email''. You can override this setting to explicitly tell the module which column contains the email address by overriding the ''email_column'' directive of the ''email'' action in your application's [[actions.ini file]]:
<code>
[email > email]
email_column = "emailAddress"
</code>
=====Changing the name of the table that stores the sent email====
Xataface automatically stores each sent email for your records. By default it stores these emails in a table named ''newsletters''. You can override this table name with the ''email_table'' directive in your application's [[actions.ini file]]. This table will be automatically created by Xataface when email is sent out.
<code>
[email > email]
email_table = "newsletters"
</code>
=====Altogether=====
<code>
[email > email]
condition="$query['-table'] == 'Pledge' or $query['-table'] == 'User'"
permission=email
email_column = "emailAddress"
email_table = "newsletters"
</code>
==Usage:==
===Sending Email to All Records of a Table===
# Navigate to a table for which your email module is enabled, and click on the ''list'' tab.
# Click on the "Email" icon in the upper right corner. This should display an email form.<nowiki>
<img src="http://media.weblite.ca/files/photos/email_icons.png"/>
</nowiki>
# Fill in the email form and press Save.<nowiki>
<div><img src="http://media.weblite.ca/files/photos/email_form.png?max_width=500"/></div>
</nowiki>
# You should receive a message saying that the email has been queued for delivery. Your cron script will automatically begin sending emails the next time around. So make sure that you have yoru cron script set up properly.
===Opting Out of the Email List===
If you have received an email that was sent via the email module you can easily opt out of the mailing list by clicking on the link at the end of the email. This link will bring you to a webpage that asks you to confirm that you no longer wish to receive email from this list.
==Using a View to add Email Action to Related Record List==
You can simulate a many-to-many [[relationships.ini file|relationship]] in a mysql view by creating a view with all possible combinations.
e.g. If you have a Many to Many [[relationships.ini file|relationship]] between books and authors your [[relationships.ini file|relationship]] from the books table might be something like:
<code>
[authors]
__sql__ = "select * from authors a inner join book_authors ab on a.author_id=ab.author_id where ab.book_id='$book_id'"
</code>
And your relationship from the authors table would be something like:
<code>
[books]
__sql__ = "select * from books b inner join book_authors ab on b.book_id=ab.book_id where ab.author_id='$author_id'"
</code>
Now if our goal was to be able to send email to all authors of a particular book (i.e. send to the authors relationship), we could create a view:
<code>
create view book_authors_maillist as
select * from authors a inner join book_authors ab on a.author_id=ab.author_id
</code>
This view can now be used in xataface like a regular table (if you add a [[fields.ini file]] for it and [[Key|mark the primary key columns]]). If you wanted to find all authors for a certain book you would just do:
index.php?-action=list&-table=book_authors_maillist&book_id=10
So you could easily create an action in the [[actions.ini file]] that would like to the mail action on the book_authors_maillist table with the parameters you wanted.
e.g.
<code>
[related_authors_mail]
category=related_list_actions
url="{$site_href}?-action=email&-table=book_authors_maillist&book_id={$record->val('book_id')}"
icon="{$dataface_url}/images/mail_icon.gif"
url_condition="$record"
condition="$query['-table']=='books' and $query['-relationship'] == 'authors'"
permission="email"
</code>
This action would send mail to only the authors related to the current books. It would be made available in the icons in the upper right on the related list view of only the authors of a book.
===Mail Merge===
The 'Embed Macro' shown above the email form lists the fields which may be included in the email.
Say you have a field called 'email_firstname'. You would type this into the message area like this: %email_firstname%
When the email is sent, this is substituted for the record of that recipient.
Eg. Dear %email_firstname% would be received by email as Dear Tom
If the particular record of the field you are merging is blank, then (in this case) the first name will not be shown.
Email,Email module,Sending Email,Maillist
en
0
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
examples
34
examples
==Xataface Examples==
[[toc]]
This section includes concrete examples of how Xataface has been used in the past.
===Demo Applications===
{| class="listing listing2"
|-
! Screenshot
! Title/Description
! Developed by
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://demo.weblite.ca/apps/librariandb/]]
| '''Librarian DB'''
A searchable database of library books. Useful for small libraries (e.g. Church Libraries).
Log in with:
username: admin
password: password
[http://demo.weblite.ca/apps/librariandb/ Try the app]
| [http://solutions.weblite.ca Web Lite Solutions Corp.]
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://demo.weblite.ca/apps/webauction/]]
| '''Web Auction'''
A simple web-based auction application for organizations to hold auctions.
Login with:
username: admin
password: password
[http://demo.weblite.ca/apps/webauction/ Try the app]
| [http://solutions.weblite.ca Web Lite Solutions Corp.]
|}
===Websites Powered by Xataface===
{| class="listing listing2"
|-
! Screenshot
! Title/Description
! Developed by
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://fueleconomydb.com]]
| '''Fuel Economy Database''' - A searchable database of gas mileage and fuel economy statistics for automobiles from 1986 to present.
[http://fueleconomydb.com Visit the site]
| [http://solutions.weblite.ca Web Lite Solutions Corp.]
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://physics.sfu.ca]]
| '''Department of Physics, Simon Fraser University'''
This website is completely powered by Xataface. It is backed by a MySQL database that stores faculty members, research groups, news, events, and more. Faculty members are able to update their personal profiles and research profiles through a Xataface administration console.
[http://physics.sfu.ca Visit the site]
| [http://fas.sfu.ca/ SFU Faculty of Applied Sciences]
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://science.ca]]
| '''Science.ca'''
The source for science in Canada. Includes profiles for prominent scientists as well as other useful science-related information. Xataface is used to power the bilingual (English/French) capabilities of this site. It includes web-based administrative console for the administrator to manage all content, and for translators to translate the content.
[http://science.ca Visit the site]
| Science.ca web team
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://translation.weblite.ca]]
| '''Simple Website Translation Engine'''
A service that allows website owners to easily convert their website into multiple languages. Support human and machine translation. This service is powered by Xataface, and provides an administrative console for users to manage their website translations.
[http://translation.weblite.ca Visit the Site]
[http://swete.weblite.ca More about this service]
| [http://translation.weblite.ca Web Lite Translation Corp.]
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://www.credituniondb.com]]
| '''Credit Union Database'''
A database of credit unions in the United States. This site is powered by Xataface.
[http://www.credituniondb.com Visit the site]
| Vlad
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://ierg.net/lessonplans/unit_plans.php]]
| '''IERG Lesson Plans Database'''
A searchable database of lesson plans created by the Imaginative Education Research Group. This database is managed by Xataface. It provides researchers with a web-based control panel to manage their lesson plans.
[http://ierg.net/lessonplans/unit_plans.php Visit the site]
| [http://solutions.weblite.ca Web Lite Solutions Corp.]
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://ierg.net/people/]]
| '''IERG People Database'''
A simple database to manage the contributors and associates of the Imaginative Education Research Group. Administrators have a web-based control panel to manage the people profiles in this database.
[http://ierg.net/people/ Visit the site]
| [http://solutions.weblite.ca Web Lite Solutions Corp.]
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://sustain-gradnetwork.envr.sfu.ca/]]
| '''Sustainability Research Database'''
A database at Simon Fraser University for grad students to post and share research profiles.
[http://sustain-gradnetwork.envr.sfu.ca/ Visit the site]
| [http://fas.sfu.ca Faculty of Applied Sciences Web Team]
|-
| [[Image:http://images.websnapr.com/?size=150&key=40f0knTakb1b&url=http://apps.weblite.ca/]]
| '''Web Lite Applications Catalog'''
A catalog of applications available through Web Lite Solutions. Allows users to set up their own online applications on Web Lite's servers. This site is completely powered by Xataface.
[http://apps.weblite.ca/ Visit the site]
| [http://solutions.weblite.ca Web Lite Solutions Corp.]
|}
examples, samples
en
0
fieldgroup_template
51
fieldgroup_template
==Using a custom template for a field group on the edit form==
[[toc]]
Xataface allows you to partition your fields into ''groups'' so that similar fields are grouped together on the edit form. The default layout of the fields remains simply vertical, but you can customize this layout (on a per-group basis) by creating a custom template and then assigning this template to the field group with the ''template'' directive.
===Example===
For example, in your [[fields.ini file]] if you wanted to group your address fields together you might have:
<code>
[fieldgroup:address]
label="Address Information"
template="AddressInformationGroup.html"
[address_1]
group=address
[city]
group=address
[state]
group=address
</code>
Then you would add the a template named ''AddressInformationGroup.html'' to your application's ''templates'' directory to display how the fields are laid out:
<code>
<table width="100%">
<tr><th>Address 1:</th>
<td>{$elements.address_1.html}</td>
<th>City:</th>
<td>{$elements.city.html}</td>
<th>State:</th>
<td>{$elements.state.html}</td>
</tr>
</table>
</code>
This would display all of the fields in this group in a single row (horizontally) instead of vertically.
Note that this is an over-simplified example that doesn't take account for display error messages, required notices, grouped fields, and other information that you can obtain from the {$elements} array.
en
0
fieldname__default
133
fieldname__default Delegate Class Method
Return to [[Delegate class methods]]
[[toc]]
===Synopsis===
Xataface allows you to pre-populate any particular field in a table by adding a fieldname__default method to the table's delegate class of the form:
<code>
function fieldname__default(){
return value;
}</code>
Returns the default value for the field fieldname. New record forms will be prepopulated with this value.
===Examples===
<code>
function minimum_bid__default(){
return 100;
}</code>
<code>
function mydatecol__default(){
return date('Y-m-d');
}</code>
<code>
function owner_id__default(){
$auth =& Dataface_AuthenticationTool::getInstance();
$user =& $auth->getLoggedInUser();
if ( isset($user) ) return $user->val('userid');
return null;
}</code>
===See Also===
* [http://xataface.com/forum/viewtopic.php?t=5028 Pre-entered Data] (forum thread) - setting defaults field values on general fields using the fieldname__default delegate class function
* [http://xataface.com/forum/viewtopic.php?t=4004 How to initialize a Date field to today's date?] (forum thread) - alternate methods to use specifically with a date/time field
* [http://xataface.com/forum/viewtopic.php?t=3988 Setting default select setting from users table] (forum thread) - solution to populate the current user
default, initialize, populate, pre-populate, delegate class default
en
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
fieldname__validate
94
fieldname__validate Delegate Class Method
Return to [[Delegate class methods]]
[[toc]]
===Synopsis===
Xataface allows you to add validation on any particular field in table by adding a fieldname__validate method to the table's delegate class of the form:
<code>
function myfield__validate(&$record, $value, &$params){
if ( $value != 'Steve' ){
$params['message'] = 'Sorry you must enter "Steve"';
return false;
}
return true;
}
</code>
===Parameters===
* &$record : A [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object encapsulating the record we are validating. Note that the values of this object correspond with the submitted values from the form, and not necessarily the actual values of the record in the database.
* $value : The value that is being inserted.
* &$params : An output array that can be used to pass back a message if validation fails. You would set this array's 'message' parameter to be a message.
===Returns===
Returns a boolean value. True if the value is ok and false if validation failed.
===See Also===
* [[validators]] - For simple validation rules you can use the [[validators|validator:VALIDATOR_NAME]] directive of the [[fields.ini file]].
* [http://xataface.com/documentation/tutorial/getting_started/validation Form Validation] - Section on form validation in the Getting Started tutorial.
validate, validation, delegate class validation, custom validator
en
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
field__fieldname
141
Defining Calculated Fields
Return to [[Delegate class methods]]
Xataface allows you to define calculated fields using the delegate class. These fields won't be visible in the UI by default, but they will be accessible to some modules (e.g. the HTML Reports Module) and they are always accessible to you via the API.
E.g. If you define a calculated field named ''year'', you would be able to access this value using the regular Dataface_Record syntax:
<code>
$record->val('year');
</code>
You could also define any number of filter methods and permissions on this field just as you can on regular fields.
e.g. <code>
function year__permissions($record){
// Return special permissions on the year field.
}
</code>
or <code>
function year__display($record){
// Override how the year is displayed in the UI.
return $record->val('year').' A.D.';
}
</code>
==How to Define a Calculated Field==
In the delegate class you simply create a method with the following naming convention:
<code>
function field__fieldname(Dataface_Record $record);
</code>
where the return value is the value that the given record should have for the field ''filedname''.
E.g.
<code>
function field__year($record){
$time = trtotime($record->strval('date'));
if ( $time ){
return date('Y', $time));
} else {
return '';
}
}
</code>
calculated fields, field__fieldname
en
field__pullValue
104
field__pullValue delegate class method
[[toc]]
The field__pullValue() delegate class method can be used to transform database from the database for use in an edit/new record form. Sometimes it is the case that we want users to be able to work with data differently than it is stored in the database.
This method should always be accompanied by a corresponding [[field__pushValue]] method which performs the inverse operation and is used to transform the value in an edit form into a format that can be stored in the database.
===Example===
Given a field ''start_ip'' that stores an IP address in the database as an unsigned INT, we want to be able to work with the data on the edit form in a friendlier format - the standard IP address dot notation, so we define pullValue and pushValue methods for the field in the table's delegate class.
<code>
class tables_ip_blocks {
/**
* @param Dataface_Record $record The record we are pushing the value
* into
* @param HTML_QuickForm_element $el The QuickForm widget that we are
* retrieving the value from.
*/
function start_ip__pushValue($record, $el){
$val = ip2long($el->getValue());
if ( $val !== false ){
return sprintf('%u', $val );
}
return null;
}
function start_ip__pullValue($record, $el){
$val = $record->val('start_ip');
if ( $val )
return long2ip($val);
return $val;
}
}
</code>
==References==
* [[Delegate class methods]]
* [[Application Delegate Class]]
* [[http://dataface.weblite.ca/Dataface_Record Dataface_Record API docs]
* [http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields] - A how-to document.
pushValue, pullValue
en
field__pushValue
105
[[toc]]
The field__pushValue() delegate class method can be used to transform a field value as entered in the edit form into a format that can be stored in the database.. Sometimes it is the case that we want users to be able to work with data differently than it is stored in the database.
This method should always be accompanied by a corresponding [[field__pullValue]] method which performs the inverse operation and is used to transform the value in the database into a format that can be edited in the edit form.
===Example===
Given a field ''start_ip'' that stores an IP address in the database as an unsigned INT, we want to be able to work with the data on the edit form in a friendlier format - the standard IP address dot notation, so we define pullValue and pushValue methods for the field in the table's delegate class.
<code>
class tables_ip_blocks {
/**
* @param Dataface_Record $record The record we are pushing the value
* into
* @param HTML_QuickForm_element $el The QuickForm widget that we are
* retrieving the value from.
*/
function start_ip__pushValue($record, $el){
$val = ip2long($el->getValue());
if ( $val !== false ){
return sprintf('%u', $val );
}
return null;
}
function start_ip__pullValue($record, $el){
$val = $record->val('start_ip');
if ( $val )
return long2ip($val);
return $val;
}
}
</code>
==References==
* [[Delegate class methods]]
* [[Application Delegate Class]]
* [[http://dataface.weblite.ca/Dataface_Record Dataface_Record API docs]
* [http://xataface.com/documentation/how-to/how-to-define-custom-serialization-for-fields How to define custom serialization for fields] - A how-to document.
pullValue, pushValue
en
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
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
getChildren
126
getChildren Delegate Class Method
Return to [[Delegate class methods]]
[[toc]]
The getChildren() method can be implemented in a table's delegate class to specify the logical "child" records of a given record which can be used when creating hierarchical applications. This method will effectively override the output of the Dataface_Record::getChildren() method for records of this table.
===Signature===
<code>
function getChildren( Dataface_Record $record) : Dataface_Record[]
</code>
===Parameters===
# '''$record''' - The Dataface_Record that is the subject of the query
===Returns===
This method should return an array of Dataface_Record objects that are considered to be children of the subject record.
===Examples===
<code>
function getChildren($record){
return df_get_records('webpages',
array(
'parent_id'=>'='.$record->val('webpage_id')
)
);
}
</code>
==See Also==
* '''[[getParent]]''' - A Delegate class method to return the logical parent of a given record.
getChildren Delegate class method
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
getNavItem
125
getNavItem Application Delegate Class Method
Return to [[Application Delegate Class]]
[[toc]]
===Synopsis===
The getNavItem() method of the application delegate class can be used to override the items that appear in the navigation menu (i.e. the menu that allows users to select the table via either tabs along the top or items along the side). It should return an associative array with characteristics of the navigation item including the href (i.e. link), label, and selected status.
Using this method it is now possible to have non-table navigation items as well. You would just add these items to the \[_tables\] section of the [[conf.ini file]] then override the item using this method.
'''Since 1.3'''
====How the Nav Menu Is Built====
Xataface builds the navigation menu by looping through each item in the [_tables] section of the conf.ini file, passing it to the getNavItem() method, and adding the resulting navigation item to the menu. If getNavItem() returns null, then that item will be skipped. If getNavItem throws an exception, then the default rendering for the menu item will take place.
===Signature===
<code>
function mixed getNavItem( string $key, string $label ) throws Exception
</code>
===Parameters===
* '''$key''' - The key of the nav item. In the case of a table, this would be the table name.
* '''$label''' - The label of the nav item (may be overridden).
===Returns===
This method should return either:
# An associative array with the properties of the nav item.
# null to indicate that this nav item should be omitted altogether. (e.g. if the user shouldn't have permission for it).
If returning an associative array, it should contain the following keys:
* '''href''' - (String) The URL where this nav item should point.
* '''label''' - (String) The label of this nav item.
* '''selected''' - (Boolean) True if the nav item is currently selected. False otherwise.
===Throws===
If you want to signal Xataface to just use default rendering for the current navigation item you can just throw an exception. The default rendering will link to the table named ''$key'', and the item's label will be the same as ''$label''.
==Examples==
Given the following conf.ini file:
<code>
...
[_tables]
people=People
books=Books
accounts=Accounts
reports=Reports
...
</code>
Suppose we want the navigation menu to only show the ''people'' and ''books'' options for regular users. Admin users can see all options.
In addition, the 'reports' option doesn't correspond with a table of the database. Instead we are just going to link it to a custom action named 'reports'.
Our getNavItem() method will look something like this:
<code>
function getNavItem($key, $label){
if (!isAdmin() ){
switch ($key){
case 'people':
case 'books':
// non-admin users can see these
throw new Exception("Use default rendering");
}
// Non-admin users can't see any other table.
return null;
} else {
//Admin users can see everything..
$query =& Dataface_Application::getInstance()->getQuery();
switch ($key){
case 'reports':
// reports is not a table so we need to return custom properties.
return array(
'href' => DATAFACE_SITE_HREF.'?-action=reports',
'label' => $label,
'selected' => ($query['-action'] == 'reports')
);
}
// For other actions we need to make sure that they aren't selected
// if the current action is reports because we want the 'reports'
// tab to be selected only in that case.
return array(
'selected' => ($query['-table'] == $key and $query['-action'] != 'reports')
);
}
}
</code>
===See Also===
* [[isNavItemSelected]] - Overrides default behavior of whether a navigation item is currently selected.
getNavItem, navigation menu
en
getPasswordChangedEmailInfo
121
getPasswordChangedEmailInfo Application Delegate Class Method
Return to [[Application Delegate Class]]
[[toc]]
===Synopsis===
Optional method to define the settings for the email that is sent to the user upon successful resetting of their password using the password reset function.
Introduced in Xataface 1.3. Exists in 1.3 or higher.
===Signature===
<code>
function getPasswordChangedEmailInfo(Dataface_Record $user, string $password){}
</code>
===Parameters===
* '''$user''' - The Dataface_Record of the user whose password has been changed.
* '''$password''' - The new temporary password that has been assigned to the user.
===Returns===
This method should return an associative array with 0 or more of the following keys:
* '''subject''' - The subject line of the email.
* '''message''' - The message content of the email.
* '''headers''' - The Email headers (as a string).
* '''parameters''' - Extra parameters for the mail function.
==See Also==
* [[getResetPasswordEmailInfo]] - A delegate class method to define the email that is sent to the user when they request a password reset. This is the step that immediately precedes the Password Changed email step.
forgot password, reset password
en
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
getResetPasswordEmailInfo
122
getResetPasswordEmailInfo Application Delegate Class Method
Return to [[Application Delegate Class]]
[[toc]]
===Synopsis===
Optional method to define the settings for the email that is sent to the user when they request to reset their password.
Introduced in Xataface 1.3. Exists in 1.3 or higher.
===Signature===
<code>
function getResetPasswordEmailInfo(Dataface_Record $user, string $reset_url){}
</code>
===Parameters===
* '''$user''' - The Dataface_Record of the user whose password has been changed.
* '''$reset_url''' - The URL where the user should go to reset their password. When they visit this URL they will receive a message saying that their password has been changed and the new password has been emailed to them. That subsequent email can be customized using the [[getPasswordChangedEmailInfo]] method.
===Returns===
This method should return an associative array with 0 or more of the following keys:
* '''subject''' - The subject line of the email.
* '''message''' - The message content of the email.
* '''headers''' - The Email headers (as a string).
* '''parameters''' - Extra parameters for the mail function.
==See Also==
* [[getPasswordChangedEmailInfo]] - A delegate class method to define the email that is sent to the user once their password has been reset to a temporary password. It informs the user of their new temporary password and should include instructions on how to change their password to their own choice. This step immediately follows the reset password step.
forgot password, reset password
en
GettingStarted:customizing
76
Customizing Field labels, descriptions, and widgets
==Customizing Field labels, descriptions, and widgets==
Using simple INI configuration files, you can customize the look and feel of your application. You can change widgets, labels, field descriptions, and more.
In the previous 2 sections we learned how to create a simple application by desiging a database and then installing the basic directory structure to make our application operational. Now it is time to "decorate" the application a little bit. Decoration occurs by way of simple configuration files that are placed in strategic locations in the application. We can customize such things as:
* Widget types (e.g., use a select list for a field rather than a text field)
* Labels (e.g., The ProgramName field's label can say "Program Name" instead of just "ProgramName")
* Field Descriptions . You can add descriptions to fields to help explain their meaning and how to use the application.
* HTML attributes. (e.g., Make a text field 50 characters wide)
===Table Configuration Directories===
You will recall, that when we used the 'makesite' script to generate the directory structure for our web application, it created a directory named 'tables', with subdirectories named after each of the tables in our database. The directory structure of the application looked like:
[[Image:http://xataface.com/documentation/tutorial/getting_started/directory-structure-1.gif]]
The 'tables/Program' and 'tables/Course' are refered to as "table configuration directories" . All of the configuration files a table in a Xataface application are stored in its associated table configuration directory. For example all configuration files for the 'Program' table are located in the 'tables/Program' directory.
There are 4 main files that are generally contained in a table's configuration directory:
* '''fields.ini''' - Contains configuration for the fields of the table (e.g., field labels, descriptions, widget types, etc...)
* ''valuelists.ini''' - Contains value lists (vocabularies) that can be used in the table to limit input into certain fields like select lists.
* '''relationships.ini''' - Defines the relationships between this table and other tables in the application.
* '''<TableName>.php''' (where <TableName> is the name of the table. - A delegate PHP class that allows you to further customize the behavior of the application with respect to this table. May contain custom fields, importing/exporting functionality, permissions information, and more...
===Customizing Labels and Descriptions===
We will start off by adding custom labels and descriptions to the 'Program' table of our 'FacultyOfWidgetry' application. This sort of customization settings are placed in a file named 'fields.ini' inside the table's configuration directory.
# Create the 'fields.ini' file in the Program table configuration directory (i.e., tables/Programs/fields.ini).
# Add the following to this file:<code>
[ProgramName]
widget:label = "Program Name"
widget:description = "Enter the name of the program"
</code><nowiki><br></nowiki>Now look at the "Edit Record" form in the Xataface application:
[[Image:http://xataface.com/documentation/tutorial/getting_started/program-name-label-1.gif]]
Notice how the label for the "ProgramName" now says "Program Name" (note the space between "Program" and "Name"). And its description matches the description specified in the fields.ini file.
The widget:label and widget:description attributes can be defined for any field in any table of the application.
===Using different widgets===
If no widgets are defined in the fields.ini file, a Xataface application will make a best guess at the type of widget that should be used to edit the value in a field. In general, the widgets used by default are as follows:
* VARCHAR, CHAR, INT : html text field
* DATE, DATETIME fields: calendar widget
* TEXT fields : html text area
* BLOB fields : html file upload field
* INT Fields with "AUTO INCREMENT" : html hidden field
* VARCHAR or CHAR fields with "Password" or "password" as part of the name : html password field
* ENUM fields : html select list
* SET fields : html checkbox group (not yet supported as of this writing).
You can change the widget that is used to edit a field by specifying a "widget:type" attribute for the field in the fields.ini file. For more information about the available widgets, see [[widget:type]].
====Example: Using HTML Editor to edit the HTMLOutline field====
Clearly the HTMLOutline field in the Program table is intended to store HTML content. By default our application only provides a text area to do the editing so the user is expected to enter the HTML markup by hand. It would be much better to provide the user with a WYSIWYG (What you see is what you get) HTML editor widget. That is exactly what we are going to do.
We will add a section to the fields.ini file so that it now looks like: <code>
[ProgramName]
widget:label = "Program Name"
widget:description = "Enter the name of the program"
[HTMLOutline]
widget:type = "htmlarea"
</code>
Now refresh the Xataface application in your web browser and look at the edit form for a record of the Program table:
[[Image:http://xataface.com/documentation/tutorial/getting_started/htmlarea-1.gif]]
As you can see, the HTMLOutline field now has an HTML Editor widget for editing. Most users will find this much nicer to work with than a normal text area. Xataface uses FCKEditor for its html editor widget.
There are a number of widgets that can be specified in the [[widget:type]] parameter:
* '''[[checkbox]]''' - An HTML checkbox (or checkbox group depending on context).
* '''[[date]]''' - Month/Day/Year select lists for selecting dates.
* '''[[calendar]]''' - A text field with a button that opens a small calendar widget when clicked.
* '''[[group]]''' - A complex widget type for editing multiple values as a group (useful for XML fields)
* '''[[hidden]]''' - a hidden field
* '''[[password]]''' - An HTML password widget
* '''[[select]]''' - An HTML select list (requires the 'vocabulary' attribute)
* '''[[static]]''' - an uneditable field
* '''[[table]]''' - A complex widget type for editing multiple values in a tabular format (Useful for XML fields)
* '''[[text]]''' - an html text field
* '''[[textarea]]''' - an html text area
===Changing HTML attributes of widgets===
Sometimes you may want even finer grained control of your widgets' appearance than to just specify the type, label, and desription. Perhaps you want to make a text field 50 characters wide, or to set the CSS class of the html element. This can be done using the 'widget:atts:' parameter for a field. A short example is the easiest way to explain how this works.
Modify the fields.ini for the Program table so it looks like:<code>
[ProgramName]
widget:label = "Program Name"
widget:description = "Enter the name of the program"
widget:atts:size = 50
widget:atts:style = "font-size: 24pt; font-family: Apple Chancery"
[HTMLOutline]
widget:type = htmlarea
</code>
We have added 2 lines:<code>
widget:atts:size = 50
widget:atts:style = "font-size: 24pt; font-family: Apple Chancery"
</code>
What this does is add the html attributes size="50" and style="font-size: 24pt; font-family: Apple Chancery" to the html text field that is used to edit the ProgramName field.
Look at the results:
[[Image:http://xataface.com/documentation/tutorial/getting_started/widget-atts-1.gif]]
The HTML tag for the text field now looks like:<code>
<input class="default" id="ProgramName" name="ProgramName"
type="text" size="50"
style="font-size: 24pt;
font-family: Apple Chancery"
value="Basic Widgetry"
/>
</code>
In fact you can add arbitrary attributes to any of the fields using the same convention. Some useful examples are:
* '''[[widget:atts:rows]]''' for text areas to set the number of rows of text they should display.
* '''[[widget:atts:cols]]''' for text areas to set the number of columns (1 character = 1 column)
You can even use javascript calls in here if you like:
* '''[[widget:atts:onclick]]''' = "doJsFunction();"
===Download source files===
[http://xataface.com/documentation/tutorial/getting_started/facultyofwidgetry-6-tar.gz Download the source files] for this application as a tar.gz archive
These source files reflect the state of the application at the current point of the tutorial. As changes are made to the application in later sections, downloads of those versions are made available for download also.
===Summary===
In this section we learned how to change the labels, descriptions, and widgets for fields. We also learned how to add HTML attributes to the widgets to achieve very fine-grained control over the display of our forms.
widget labels descriptions onclick handlers
en
GettingStarted:delegate_classes
80
Delegate Classes
==Delegate Classes==
Use Delegate classes to add permissions, custom serialization, display filters, calculated fields, import/export functionality, and other custom functionality to your application.
For many applications, the configuration files provide sufficient to make them fit the requirements. However, in some cases you may feel the need to "extend" or "bend" your application even more. For these situations, there are delegate classes.
===What is a delegate class?===
A delegate class is a PHP class that defines custom behavior, functions, and fields for a table in a Xataface application. A table may have only 1 delegate class.
What kinds of things can a delegate class do?
* Define permission rules for tables, records, and relationships.
* Define calculated fields.
* Define custom serialization/deserialization of fields (useful for XML storage)
* Define custom event handlers (actions to be performed when certain events take place)
* Define import / export filters.
* Define custom titles for records
* more ...
===How to create a delegate class===
I will describe the creation process with an example.
Referring back to our FacultyOfWidgetry application, let's add a delegate class for the 'Program' table. This is done as follows:
# Create a file named 'Program.php' in the Program table configuration directory (i.e., 'tables/Program/Program.php). Your application directory structure should now look like:<nowiki><br/></nowiki>[[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/delegate-class-fs-1.gif]]
# Add the following contents to your newly created 'Program.php' file:<code><?
class tables_Program {}
</code><nowiki><p>
In other words, you are creating a class named 'tables_Program'. The above delegate class doesn't do anything yet, but it is a start.
The fun part doesn't start until you start defining methods in your delegate class. There are prescribed interfaces that you will need to implement to make this work.</p></nowiki>
===Example 1: Creating a custom title for records===
The "Title" of a record is a string that represents the record. It is used by Xataface in the navigation controller (forward and back buttons) and in the "Jump" menu as well as various places around the interface for referring to that record. As an example, take a look at this partial screen shot of the 'details' tab in a Xataface application.
[[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/getTitle-1.gif]]
I have circled the parts of the interface that use a record's title in some way. (1), (2), and (4) show the title of the current record and (3) shows the title of the next record in the found set. You will notice that the title is just the value of the first field in the Program record. In fact, the way that Xataface generates titles is by selecting the first VARCHAR or CHAR field in the table to be the Title for records of that table. In the above example this seems like a good choice, but it may not always be what you want.
We can use our delegate class to customize the way that these titles are generated. By defining a method named getTitle(), we can customize the way that titles are generated. Let's add such a method to our delegate class as follows:
<code>
<?
class tables_Program {
function getTitle(&$record){
return $record->val('ProgramName').' Program';
}
}
</code>
OK, you are probably wondering what this $record object is. The $record object is a Dataface_Record object that represents a record of the 'Program' table (if you want to take a look at the source code for this class it can be found in the 'Dataface/Record.php' file). This object allows you to access all of the information about the record so that you can generate a title for the record.
The 'val' method simply returns the value of a field in the record.
In the above example, we are telling Xataface that the title of all records of the 'Program' table is the value of the ProgramName field with the string 'Program' appended to it. For example, if the ProgramName of a record was 'Foo', then its title woud be 'Foo Program'.
Lets take a look at our application now to see the changes that we have made.
[[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/getTitle-2.gif]]
Notice that the (1) now has 'Program' appended to the end of the title, but (2) and (3) do not. This is because (2) and (3) are part of the result controller (for navigating through results in the table) and it needs to be able to load hundreds of record titles at a time, but the getTitle() method requires that the entire record be loaded into memory for it to work which would be unfeasible when we need the title of hundreds of records. The result controller titles can also be customized, however, using the titleColumn() method, which simply returns the name of the column that should be used as the title. It can also return MySQL clauses that are equivalent to a column name (e.g., CONCAT('FirstName', ' ', 'LastName') would be valid).
Okay, let's add a titleColumn() method to our delegate class so that we can customize the way our records are represented in the result controller:
<code>
<?
class tables_Program {
function getTitle(&$record){
return $record->val('ProgramName').' Program';
}
function titleColumn(){
return 'AdmissionDeadline';
}
}
</code>
All that the titleColumn method does is return the name of a column to be used as the title for records of the 'Program' table. In this case, we making the 'AdmissionDeadline' field the title column which results in the result controller looking like this:
[[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/titleColumn-1.gif]]
This was a simple example, but it is possible to do more with the titleColumn() method than just specify the name of a column. Any valid MySQL calculation that can be placed in a SELECT list can be returned here. For example, we can make use of the MySQL 'CONCAT' function to append the string 'Program' to the 'ProgramName' field and achieve the same results as our previous getTitle() method:
<code>
<?
class tables_Program {
function getTitle(&$record){
return $record->val('ProgramName').' Program';
}
function titleColumn(){
return "CONCAT(ProgramName, ' Program')";
}
}
</code>
And now we can see the changes in our application:
[[Image:http://framework.weblite.ca/documentation/tutorial/getting_started/titleColumn-2.gif]]
It may seem a little bit inconvenient to have to define 2 methods to effectively customize the title of a record. Future versions may attempt to address this issue so that one or the other can be implemented, but for now, both methods must be implemented to effectively customize the title. In addition, future versions will likely add the 'titleColumn' functionality to an INI file since it is more or less static.
===Summary===
In this section we learned how to add a delegate class to our tables to customize the behavior of our applications. Delegate class become more important when you need very fine-grained customizations to your application, as you will see in later sections. One important feature of delegate classes is the ability to add security permissions to tables and records to limit who can view, edit, and delete certain records. This will be covered in the next section.
delegate classes,getTitle,getPermissions
en