Now if we try to access our submit_for_proof action, it will show us our template with no error messages (hopefully).
===Roles===
Roles are sets of permissions. They are defined in the permissions.ini file as sections with lists of included permissions. It might be handy to create roles such as EDITOR or MANAGER which contain sets of permissions that are meant to be assigned to users of those types. For example an EDITOR may have the view and edit permissions, but not the delete permission. A MANAGER might have the view, edit, and delete permissions. You can define these two roles in the permissions.ini file as follows:
[EDITOR]
view=1
edit=1
[MANAGER]
view=1
edit=1
delete=1
Then we could assign these roles to users using the Dataface_PermissionsTool::getRolePermissions() method:
function getPermissions(&$record){
$user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
if ( $user and $user->val('role') == 'EDITOR' ){
return Dataface_PermissionsTool::getRolePermissions('EDITOR');
} else if ( $user and $user->val('role') == 'MANAGER' ){
return Dataface_PermissionsTool::getRolePermissions('MANAGER');
}
return Dataface_PermissionsTool::READ_ONLY();
}
Or equivalently we could use the getRoles() method of our delegate class instead of getPermissions():
function getRoles(&$record){
$user =& Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
if ( $user and $user->val('role') == 'EDITOR' ){
return 'EDITOR';
} else if ( $user and $user->val('role') == 'MANAGER' ){
return 'MANAGER'
}
return 'READ ONLY';
}
===Xataface Core Permissions & Roles===
Xataface is distributed with its own permissions.ini file that defines some core permissions and roles. You can look at this permissions.ini file (located in the Xataface directory) to see what the format should look like. Any settings you place in your application's permissions.ini file will augment or override settings in Xataface's file.
Some core permissions include:
{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| view
| Permission to view a record or field. This permission is required to access the view tab, and several other details tabs.
| 0.6
|-
| list
| Permission to access the list tab.
| 0.6
|-
| calendar
| Permission to access the calendar tab.
| 0.6
|-
| edit
| Permission to edit a record or field. This also gives access to the edit tab.
| 0.6
|-
| new
| Permission to edit a record or field for the purpose of creating a new record. This permission is required to access the new record form.
| 0.6
|-
| select_rows
| Permission to select rows in list view to perform actions on them.
| 0.6
|-
| post
| Permission to post a record using HTTP POST
| 0.6
|-
| copy
| Permission to copy a record.
| 0.6
|-
| update_set
| Permission to perform an update on a result set (i.e. access the update set action).
| 0.8
|-
| add new related record
| Permission to add a new record to a relationship. See [[Relationship Permissions]]
| 0.6
|-
| add existing related record
| Permission to add an existing record to a relationship. See [[Relationship Permissions]]
| 0.6
|-
| view related records
| Permission to view the records in a relationship. See [[Relationship Permissions]]
| 1.0
|-
| delete
| Permission to delete a record.
| 0.6
|-
| delete found
| Permission to access the delete found set action (to delete multiple records at a time).
| 0.6
|-
| show all
| Permission to access show all records action.
| 0.6
|-
| remove related record
| Permission to remove a record from a relationship. See [[Relationship Permissions]]
| 0.6
|-
| delete related record
| Permission to delete a record in a relationship. This is stronger than the remove related record permission in that it allows the user to delete the record from the database. See [[Relationship permissions]]
| 0.6
|-
| find
| Permission to perform the find action.
| 0.6
|-
| import
| Permission to perform the import action (to import records into the database).
| 0.6
|-
| export_csv
| Permission to perform the Export CSV action (to export the result set in comma-separated-value format).
| 0.6
|-
| export_xml
| Permission to perform the Export XML action (to export the result set as XML).
| 0.8
|-
| translate
| Permission to translate a record into another language. This permission provides access to the ""translate"" tab.
| 0.8
|-
| history
| Permission to view history information for a record (e.g. the history tab). This requires that history be enabled.
| 0.8
|-
| edit_history
| Permission to edit history information such as undo/redo support for a record.
| 0.8
|-
| navigate
| Permission to navigate through records of a table.
| 0.6
|-
| reorder_related_records
| Permission to reorder the records of a relationship (this is different than just sorting). It sets a default order for the records. Requires the metafields:order directive to be set for the relationship.
| 0.6
|-
| ajax_save
| Permission to save a record through AJAX.
| 0.8
|-
| ajax_load
| Permission to load a record through AJAX.
| 0.8
|-
| ajax_form
| Permission to access the inline editing ajax form for a record.
| 0.8
|-
| find_list
| Permission to search current table.
| 0.6
|-
| find_multi_table
| Permission to perform a site-wide search.
| 0.8
|-
| register
| Permission to register for an account.
| 0.8
|-
| xml_view
| Permission to view a result set as xml.
| 0.8
|-
| view_xml
| View the XML for an individual record.
| 0.8
|-
| manage_output_cache
| Management permission to clear the output cache.
| 0.8
|-
| manage_migrate
| Permission to access the migration tool to migrate between versions.
| 0.8
|-
| manage
| Permission to access the management control panel.
| 0.8
|-
| manage_build_index
| Permission to rebuild the search index.
| 0.8
|-
| expandable
| Whether the record can be expanded in the left nav menu
| N/A
|}
Some core roles include:
{| class=""listing listing2""
|-
! Name
! Permissions Included
! Version
|-
| READ ONLY
| view, list, calendar, view xml, show all, find, navigate, ajax_load, find_list, find_multi_table, rss, export_csv, export_xml, and export_json
| 0.6
|-
| EDIT
| All permissions in READ ONLY, and edit, add new related record, add existing related record, add new record, remove related record, reorder_related_records, import, translate, new, ajax_save, ajax_form, history, edit_history, copy, update_set, and select_rows
| 0.6
|-
| DELETE
| All permissions in EDIT, and delete and delete found.
| 0.6
|-
| OWNER
| All permissions in DELETE except navigate, new, and delete found.
| 0.6
|-
| REVIEWER
| All permissions in READ ONLY, and edit and translate.
| 0.6
|-
| USER
| All permissions in READ ONLY, and add new related record.
| 0.6
|-
| ADMIN
| All permissions in DELETE and xml_view
| 0.6
|-
| MANAGER
| All permissions in ADMIN and manage, manage_output_cache, manage_migrate, manage_build_index, and install.
| 0.6
|}
===Extending and Overriding Roles===
The cleanest and easiest way to define a new role is to extend an existing role. Xataface allows you to extend roles via the '''extends''' keyword. For example, if you wanted to create a role '''TEST ROLE''' that contained all of the same permissions as the READ ONLY role, you could define it as follows in your application's permissions.ini file:
[TEST ROLE extends READ ONLY]
If we wanted it to contain the same permissions as READ ONLY but to also allow the edit permission we would define it as:
[TEST ROLE extends READ ONLY]
edit=1
If we wanted to disallow the list permission, we would do something like:
[TEST ROLE extends READ ONLY]
edit=1
list=0
===Overriding Existing Roles===
You can also redefine existing roles:
[READ ONLY extends READ ONLY]
my_permission=1
This is handy if you have added your own custom permissions that you feel should be included in a core role.
Note that there are some caveats regarding the order of how these roles are defined. Please refer to this forum post for more details:
[http://www.xataface.com/forum/viewtopic.php?t=6187 Overriding Roles / Permissions]
==See Also==
* [[Relationship Permissions]]
* [[getPermissions]] - The getPermissionsMethod
* [[Delegate class methods]] - Delegate class methods.
* [http://xataface.com/documentation/tutorial/getting_started/permissions Getting started with Xataface permissions]","permissions.ini, getPermissions, permissions",en,0
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:
[Year]
filter=1
[Make]
filter=1
[Model]
filter=1
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:
__sql__ = ""select a.*, b.foo_name from a left join b on a.foo_id=b.foo_id""
[foo_name]
filter=1
",,en,0
group,28,group,"==group directive in [[fields.ini file]]==
The group directive allows you to declare that certain fields of your table should be grouped together on the edit form and the view tab (and other logical places). For example, fields like address, city, state, country, postal_code would likely be grouped together as address_info. Grouping the fields together will make the fields appear in a section of their own in the view tab and the edit form.
E.g. In your fields.ini file:
[address]
group=address_info
[city]
group=address_info
[state]
group=address_info
[country]
group=address_info
[postal_code]
group=address_info
===Configuring the Group as a Whole===
You can also configure your group in the fields.ini file by adding a '''fieldgroup:NAME''' section, where '''NAME''' is the name of the group. E.g.
[fieldgroup:address_info]
label=""Address Information""
description = ""Please enter your address information below""
====See also:====
* [[fields.ini file]] - Scroll down to the '''Field Groups''' section.",,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]]===
[password]
encryption=md5
",,en,0
modules,30,"Xataface Modules","[[toc]]
Xataface provides a number of hooks that allow developers to create modules to extend its functionality. This page lists a handful of the currently available modules.
* [[ShoppingCart|Shopping Cart]] - Converts your application into a shopping cart.
* [[Filemaker]] - Export record sets as Filemaker XML.
* [[DataGrid|Data Grid]] - Editable Datagrid.
* [[Email]] - Convert your database into a email list. Send email to any found set.
* [[reCAPTCHA module]] - A reCAPTCHA module to add CAPTCHA support to your Xataface forms.
* [[XataJax]] - Platform for building Web 2.0 AJAX applications with Xataface. Will be a standard component for Xataface starting with version 1.3.
==Module Installation==
You can add modules in either:
# DATAFACE_PATH/modules directory (since 1.0)
# DATAFACE_SITE_PATH/modules directory (since 1.3)
Modules in the DATAFACE_SITE_PATH directory will supersede modules in the DATAFACE_PATH/modules directory (since 1.3).
To activate a module for your application you also need to add an entry to the [[_modules]] section of your [[conf.ini file]]. Each module will come with its own installation instructions.
==Authentication Modules==
Modules to add alternative authentication methods are added to the modules/Auth directory.
==Developing Your Own Modules==
See [[Module Developers Guide]].","modules, captcha",en,0
ShoppingCart,31,ShoppingCart,"==Xataface Shopping Cart Module==
[[toc]]
Status: Under development
Current Version: 0.2
===Synopsis===
Add a shopping cart to your xataface application. You can treat any record as a product that can be sold. Includes Paypal connectivity, shipping calculation, and more.
===Requirements===
* Xataface 1.0 or higher
* PHP 5 or higher
* MySQL 4.1 or higher
===Installation Instructions===
# Download the ShoppingCart module, extract it, and place the ShoppingCart directory in your Xataface modules directory. (i.e. /path/to/xataface/modules/ShoppingCart).
# Add the following line to the [_modules] section of your [[conf.ini file]]:
modules_ShoppingCart=modules/ShoppingCart/ShoppingCart.php
# Add the following to the beginning of your [[index.php file]]:
function __autoload($class){
if ( $class == 'ShoppingCart' ) require_once 'modules/ShoppingCart/lib/ShoppingCart/ShoppingCart.class.php';
}
# In the [[fields.ini file]] for any table whose records you wish to represent items for sale, add the following:
[__implements__]
InventoryItem=1
# Specify which fields should be used for the item description, price, width, height, length, and weight in the [[fields.ini file]] for each table whose records you wish to represent items for sale by adding the following directives to the appropriate fields:
ShoppingCart.description=1
ShoppingCart.unitPrice=1
ShoppingCart.weight=1
ShoppingCart.width=1
ShoppingCart.height=1
ShoppingCart.length=1
E.g. if your table has a field named """"price"""" that you want to represent the unit price, you would have something like:
[price]
ShoppingCart.unitPrice=1
The shopping cart module will make its best guess on which fields to use for these values if they are not explicitly specified.
# Specify the paypal account where money should be deposited by adding the following to your application's [[actions.ini file]]:
[view_cart]
paypal.account=""youremail@example.com""
===Usage Instructions===
Once the Shopping Cart module is installed you can:
# Add items to your shopping cart
# View your cart contents
# Checkout and pay with paypal
====Adding Items to the Cart====
In the View tab of any salable record, you'll notice a little block on the left side of the page with the heading ""Add Item to Cart"". This includes a field to specify the quantity and a button to add the item to the shopping cart.
====Viewing Cart Contents====
The Shopping Cart module automatically introduces an action to view the cart contents. This action is named ""view_cart"". Hence you can always view the cart contents by entering the URL: index.php?-action=view_cart .
====Checking Out====
# View the cart contents.
# Click ""Check out""
# This will take you to a paypal page to pay for your items.
==Actions==
This module adds the following actions to your application.
{| class=""listing listing2""
|-
! Name
! Content-type
! Description
! Version
|-
| checkout
| text/html
| Sends user to paypal to pay for the contents of their cart.
| 0.1
|-
| calculate_shipping
| text/html
| Calculates the shipping charges for the cart.
| 0.1
|-
| add_to_cart
| text/html
| Adds an item to the cart.
| 0.1
|-
| clear_cart
| text/html
| Empties the shopping cart.
| 0.1
|-
| get_shipping_provinces
| text/json
| Returns JSON array of provinces for a given country.
| 0.1
|-
| invoices
| text/html
| Displays the current user's invoices.
| 0.1
|-
| payment_complete
| text/html
| Page that is displayed after a successful payment on paypal.
| 0.1
|-
| paypal_ipn
| none
| Handles paypal events such as successful payments.
| 0.1
|-
| refresh_shipping_methods
| text/html
| Refreshes the shipping methods available to the system.
| 0.1
|-
| set_shipping_method
| text/html
| Sets the selected shipping method to a particular method.
| 0.1
|-
| view_cart
| text/html
| View the cart contents.
| 0.1
|}
==Blocks and Slots==
This module adds the following blocks and slots to your applications.
{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| shipping_method
| A block with a form to select the shipping method.
| 0.1
|-
| add_to_cart
| A block with a form to add a record/item to the shopping cart.
| 0.1
|}
==Application Delegate Class Hooks==
You can modify the shopping cart behavior by defining the following methods to the application delegate class.
{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| isShippingMandatory
| Returns a boolean value indicating whether the user must select a shipping method.
| 0.1
|-
| getDefaultShippingMethod
| Returns a string with the name of the default shipping method to be used.
| 0.1
|}
==Table Delegate Class Hooks==
You can modify the behavior of the shopping cart by defining the following methods to the delegate class of any table that implements the InventoryItem ontology (i.e. any table that is to be used to store products that can be added to the cart).
{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| field__taxes
| A calculated field that returns an associative array of all applicable taxes for a product.
| 0.1
|}
==Internal Storage==
This module creates the following tables to store its data:
===dataface__invoices===
The dataface__invoices table stores the actual invoices for purchases made. An invoice is automatically created as soon as the user ""checks out"".
{| class=""listing listing2""
|-
! Column Name
! Data Type
! Description
! Version
|-
| InvoiceID
| int(11)
| Auto incrementing primary key for the invoice.
| 0.1
|-
| dateCreated
| datetime
| The date that the invoice was created.
| 0.1
|-
| dateModified
| datetime
| The date that the invoice was last modified
| 0.1
|-
| status
| enum
| The status of the invoice (either PENDING, PAID, or APPROVED).
| 0.1
|-
| amount
| decimal(10,2)
| The total amount on the invoice.
| 0.1
|-
| paymentMethod
| varchar(32)
| The name of the payment method used.
| 0.1
|-
| referenceID
| varchar(64)
| ??
| 0.1
|-
| username
| varchar(32)
| The username of the user who owns this invoice.
| 0.1
|-
| firstName
| varchar(32)
| The first name of the payer.
| 0.1
|-
| lastName
| varchar(32)
| The last name of the payer.
| 0.1
|-
| address_name
| varchar(100)
| The name on the shipping address.
| 0.1
|-
| address1
| varchar(100)
| The shipping address line 1.
| 0.1
|-
| address2
| varchar(100)
| The shipping address line 2.
| 0.1
|-
| city
| varchar(40)
| The shipping address city.
| 0.1
|-
| province
| varchar(2)
| The shipping province or state.
| 0.1
|-
| country
| varchar(2)
| The shipping country.
| 0.1
|-
| postalCode
| varchar(32)
| The shipping postal code.
| 0.1
|-
| shipping_method
| varchar(50)
| The name of the shipping method to use.
| 0.1
|-
| phone
| varchar(32)
| The phone number of the payer.
| 0.1
|-
| email
| varchar(127)
| The email address of the buyer.
| 0.1
|-
| data
| text
| Serialize shopping cart data.
| 0.1
|}
===dataface__shipping_methods===
Stores the available shipping methods.
{| class=""listing listing2""
|-
! Column Name
! Data Type
! Description
! Version
|-
| shipping_method_id
| int(11)
| Auto increment ID for a shipping method.
| 0.1
|-
| shipping_method_name
| varchar(50)
| The name of the shipping method.
| 0.1
|-
| shipping_method_label
| varchar(100)
| The label for the shipping method (displayed to the user).
| 0.1
|-
| shipping_method_enabled
| tinyint(1)
| Whether or not this shipping method is currently enabled.
| 0.1
|-
| shipping_method_module
| varchar(32)
| The name of the handler that this shipping method belongs to.
| 0.1
|}
==Payment Handlers==
Information about payment handlers to be added here.
==Shipping Handlers==
The Shopping Cart module is itself modular, allowing you to develop custom shipping handlers for different types of shipping. A shipping handler is responsible for calculating shipping costs to a destination address. Currently only a UPS shipping handler has been created, but it is not difficult to create other handlers.
===Shipping Handler Public Interface===
{| class=""listing listing2""
|-
! Method
! Description
! Version
|-
| calculateShipping
| Calculates the shipping cost for the current shopping cart, and adds the shipping cost to the cart as a line item.
| 0.1
|-
| getInfo
| Returns an array of shipping methods that can be handled by this handler.
| 0.1
|}
",,en,0
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===
===Screenshots===
Click on image to enlarge
===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]]:
modules_DataGrid=modules/DataGrid/DataGrid.php
# 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]]:
[MY ROLE]
DataGrid:view_grid=1
DataGrid:update=1
If you want to explicitly disable the grid for a role, you can extend the role and deny those same [[permissions]]:
[MY ROLE extends MY ROLE]
DataGrid:view_grid=0
DataGrid:update=0
===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
after_action_new,33,after_action_new,"==after_action_new trigger==
[[toc]]
This trigger is called after the '''new''' action is successfully completed. This trigger can be defined in the table [[Delegate class methods|delegate class]] and is often used to redirect to a particular page after a new record is submitted. This should not be confused with the [[afterInsert]] trigger, which is executed after a record is inserted into the database (this can occur multiple times per request). The after_action_new trigger is only executed once after the 'new' action has been successfully completed. i.e. a maximum of once per request.
===Signature===
function after_action_new($params=array()){ ... } : return void
====Parameters====
This method takes a single associative array as a parameter. This array includes the following keys:
* '''record''' - The [http://dataface.weblite.ca/Dataface_Record Dataface_Record] object that was just inserted.
===Examples===
====Example 1: Redirect to the view tab for the inserted record====
function after_action_new($params=array()){
$record =& $params['record'];
header('Location: '.$record->getURL('-action=view').'&--msg='.urlencode('Record successfully inserted.'));
exit;
}
",,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
widget:editor,35,widget:editor,"==widget:editor fields.ini directive==
Return to [[fields.ini file]]
[[toc]]
The widget:editor directive is applicable in the [[fields.ini file]]. It specifies the type of HTML editor that should be used. This directive is only used when [[widget:type]] is set to [[widget:type htmlarea|htmlarea]]. Xataface currently supports FCKEditor, TinyMCE, and NicEdit.
===Allowed Values===
{| class=""listing listing2""
|-
! Value
! Description
! Version
|-
| fckeditor
| Use [http://www.fckeditor.net/ FCKEditor]. This is the default value.
| all
|-
| tinymce
| Use [http://tinymce.moxiecode.com/ TinyMCE editor].
| 0.6
|-
| nicedit
| Use [http://www.nicedit.com/ NicEdit].
| 1.0.5
|}
===Examples===
====Example 1: Using FCKEditor====
Given a field 'content' that you wish to be able to edit with FCKEditor, you would have the following section in your [[fields.ini file]]:
[content]
widget:type=htmlarea
widget:editor=fckeditor
Note that since FCKEditor is the default editor, the above would give the same result as:
[content]
widget:type=htmlarea
====Example 2: Using TinyMCE====
Further from example 1, if we wanted to use TinyMCE editor, we would change our directive to:
[content]
widget:type=htmlarea
widget:editor=tinymce
====Example 3: Using NicEdit====
Further from example 1:
[content]
widget:type=htmlarea
widget:editor=nicedit
==Enabling Image Uploads==
By default image uploads are disabled in these WYSIWYG editors.
===Enabling Image Uploads in FCKEditor===
# Create a directory named ''uploads'' inside your application directory. e.g.
cd /path/to/myapp/uploads
# Make the ''uploads'' directory writable by the webserver. e.g.
chmod 777 /path/to/myapp/uploads
# Edit the ''lib/FCKeditor/editor/filemanager/connectors/php/config.php'' file inside your ''xataface'' directory so that:
$Config['Enabled'] = true ;
$Config['UserFilesPath'] = '/url/to/myapp/uploads/' ;
// The path portion of the URL to your uploads directory.
// e.g. if your uploads directory is accessible at
// http://example.com/myapp/uploads, then this value should
// be /myapp/uploads/
$Config['UserFilesAbsolutePath'] = '/path/to/myapp/uploads/' ;
// The absolute file system path to your uploads directory.
// e.g. if your uploads directory is located at
// /home/myhome/www/myapp/uploads, then this value should be
// /home/myhome/www/myapp/uploads
# Now when you click on the ""Add Image"" link in your HTML editor, it will allow you to upload images and browse existing uploaded images.
",,en,0
about,36,about,"==About Xataface==
[[toc]]
Xataface is a flexible and shapable skin that sits on top of MySQL, making it accessible to every-day users. It automatically generates the appropriate forms, lists, and menus for a user to interact with the database without having to know any SQL.
It is a full-featured Web application framework, and gives developers the flexibility to customize the features and behavior of their application via configuration files (using the simple INI-file syntax), templates, and plug-ins. A generic application with no customizations is completely functional, but the developer is free to customize things at his leisure.
===Who is Xataface for?===
Xataface is for web developers and database administrators who would like to build a front-end for their MySQL database. However the resulting applications are targeted at non-technical users such as secretaries.
===Requirements===
====Xataface 1.1.x and below:====
* MySQL 3.23+
* PHP 4+
Some advanced features require MySQL version 4.1 or higher.
====Xataface 1.2 and higher====
* MySQL 3.23+
* PHP 5+
Some advanced features require MySQL version 5 or higher.
===At a Glance: Your first App===
# Create a directory for your app.
# Copy the ''xataface'' directory inside your application directory.
# Create a configuration file named ''conf.ini'' in your application directory with your database settings:
[_database]
host=localhost
name=mydb
user=me
password=mypass
[_tables]
; A list of tables to include in your application's menu
; These tables must already exist in your database
people=Profiles
news=News Articles
# Create an .htaccess file in your application directory to prevent access to your ''conf.ini'' file:
Deny from all
# Create a PHP script in your application directory as an access point for your app. We'll call it ''index.php'':
display()
# You're done. Your app is ready to use!
This is just the beginning, though. There is no limit to the customizations you can make on your application.
Read the [http://xataface.com/documentation/tutorial/getting_started Getting Started Tutorial] for more information on developing applications with Xataface.
===Product Comparison===
Xataface fits a niche that is not well covered by existing apps/frameworks. Xataface is '''NOT''':
* A database administration system like PHPMyAdmin
* Simply a software library/Framework like PHPCake
* Simply a content management system like Drupal
* A code generator
Xataface is a framework, but it is not a typical framework. Most frameworks require a substantial amount of development before you get a usable application. Xataface, on the other hand, provides you with a fully-functional application with as little as 4 lines of PHP code. It doesn't generate any code so it is easy to maintain your application and expand on it later.
As a development framework, Xataface most closely resembles Django, a python framework for building data-driven applications. As an application, Xataface most closely resembles Filemaker, a popular relational database that makes it easy for the end user to create layouts and manage their data.
===Features===
====General====
* '''Out-of-the-box Database Front-end''' - With as little as 4 lines of PHP code, you can have a full-featured web application for your database.
* '''Simple, Intuitive User interface''' - Default application is consistent and simple to use. There is a 'tables' menu, to select a table, and each table has ""details"", ""list"", and ""find"" tabs. Very easy to navigate.
* '''Powerful configuration options''' - You can configure your application details (such as widget types) using simple configuration files.
* '''Extendible''' - You can modify your application as you see fit using configuration files and PHP delegate classes.
* '''Hooks''' - By observing simple conventions you can extend Xataface's functionality with hooks, triggers, and events. E.g. add a function that is called after a record is inserted.
* '''Permissions''' - Powerful, pluggable permissions system.
* '''Authentication''' - Provides login/logout ability. You just specify which table your users are stored in.
* '''Relationships''' - Tell Xataface how your tables are related to one another and it will provide you with more logical functionality for managing your data.
* '''Themeable''' - Xataface uses the Smarty template engine as a base, but extends it with some powerful new features such as extendable templates and theming support.
* '''Modular''' - There are several add-on modules available to extend the features of Xataface even further, and a simple API for writing your own modules.
====Editing====
* '''Automatic Form Generation''' - Automatically generates appropriate web forms to add new records and edit existing records.
* '''Widgets''' - Support for many different widget types including text fields, text areas, checkboxes, select lists, html editors, grids, file uploads, and more.
* '''Configurable''' - Customize forms using configuration files and delegate classes.
* '''Personalizable''' - Show different forms to different users depending on their permissions and preferences.
* '''Add Related Records''' - Insert records and automatically track their relationships to other tables.
* '''Editable Data Grid''' - Manage your data like a spreadsheet using the DataGrid module.
* '''Copy''' - Copy sets of records.
* '''Update Found Set''' - Update multiple records with one swipe.
* '''Fine-grained Permissions''' - Assign editing permission based on table, record, or field.
* '''File uploads''' - Support for file uploads with storage either in a BLOB field or on the file system.
* '''Delete''' - Delete single record or delete the current found set.
====Searching====
* '''Automatic Find Form''' - The Xataface find form allows you to search a table on any field.
* '''Range Searches''' - Search for records matching values in a certain range (e.g. find all people between the ages of 20 and 30).
* '''Exact Matching''' - Search for exact matches.
* '''Partial Matching''' - Search for fields that contain a keyword phrase.
* '''Multi-field search''' - There is always a simple search field accessible which searches all fields in the current table. E.g. a search for ""Tom"" would match any record in the current table that contained the phrase ""Tom"" in any of its columns.
* '''Related Record Searches''' - Find records that contain related records matching a search term. (E.g. find all people who got an 'A' in a particular course).
====Browsing====
* '''Automatic Details View''' - Each record has user-friendly details page to browse the contents of the record.
* '''AJAX Record Tree''' - Provides optional AJAX record tree to browse the data in your database by relationships.
* '''Expand for More''' - Quickly expand a row in list view to see the full record details.
* '''Drag and Drop Reordering''' - The details view for a record can be broken up into related sections. Users can reorder these sections via drag and drop.
====Exporting====
* '''RSS''' - Support for RSS 1.0, 2.0 and Atom feeds of any found set.
* '''XML''' - Export any found set as XML so that the data can be interchanged with other products (e.g. desktop publishing suites).
* '''CSV''' - Export any found set to CSV (comma-separated-value) to open in a spreadsheet application like Excel.
* '''JSON''' - Export any found set to JSON. This feature makes Xataface a good choice for serving the next generation of Web 2.0 AJAX applications.
====Internationalization====
* '''String Internationalization''' - Xataface fully supports internationalizing your application. It provides you with language files to provide translations of all of the strings and labels in your application.
* '''Dynamic Data Translation''' - Xataface even allows you to internationalize your existing database data without having to change your database structure.
* '''Templates''' - Includes a {translate} tag for Smarty templates to easily translate template text.
* '''In the background''' - You can use Xataface to internationalize any PHP/MySQL website without having to make any drastic changes to your existing code. Just include Xataface as a library and use some of its useful internationalization functions to convert your application into multiple languages.
* '''Translation Form''' - If multiple languages are enabled, Xataface provides a simple translation form to translate content between languages.
* '''Translation Status Tracking''' - Track the status of translations to mark whether they need to be retranslated.
====Importing====
* '''Import Filter API''' - Using delegate classes, it is easy to define an import filter to import any type of data into the database.
* '''User Preview''' - User can preview imported data before confirming that he wants to import it.
====History====
* '''Optional History Support''' - If history is enabled, all changes made to any data are recorded.
* '''Undo/Redo Support''' - Easily revert to an earlier version of a record.
* '''View Snapshot''' - Browse previous versions of records.
* '''View Diffs''' - View differences/changes between versions of records, similar to a wiki.
====Caching====
* '''Output cache''' - Supports output cache that caches output of pages to improve performance dramatically for busy sites. Cache is automatically refreshed whenever changes are made to tables that are used to generate the page.
* '''APC Support''' - If APC (Alternate PHP Cache) is installed, Xataface will automatically use it to cache table configuration information. This tends to increase performance by about 20%.
====Security====
* '''Fine-grained permissions''' - Define permissions to the entire application, a single table, by the record, or by the field. Each feature has an associated permission that can be allowed or disallowed on a per-user basis.
* '''Cascading Permissions''' - You can very restrictive permissions to the application as a whole and then apply more permission permissions to specific tables or fields that you want uses to be able to access. Table permissions override application permissions. Field permissions override field permissions.
* '''Role-based permissions''' - You can define """"""roles"""""" which are sets of permissions that can be assigned to users.
* '''Extendable Permissions Model''' - You can easily define your own permissions and roles, extending existing roles, custom for your application.
* '''Built-in Authentication''' - It is easy to set up login/logout features for your application. Just tell Xataface which table you store your user records in, and Xataface will do the rest.
* '''Password Encryption''' - Xataface supports and is compatible with most of the standard password encryptions including MD5, SHA1, and MySQL Password.
* '''Pluggable Authentication''' - Easy to create your own authentication plugins in case you want to implement your own custom authentication.
* '''CAS''' - Module available for the Yale CAS (Central Authentication Service).
* '''LDAP''' - LDAP authentication module available.
* '''HTTP''' - Optional HTTP login support. Standard login uses a web-based login form, but you can also use HTTP headers for authentication.
====Relationships====
* '''Powerful Relationship Model''' - It is easy to define relationships between your tables using simple configuration files. Syntax is simple, but the results are powerful.
* '''Add New Related Record''' - Create a new record and add it to a parent record's relationship at the same time. (E.g. create a new ""course"" record and add it to a teacher's list of taught courses).
* '''Add Existing Related Record''' - Add an existing record to a parent record's relationship. (e.g. Add an existing course record to a teacher's list of taught courses).
* '''Remove related record''' - Remove a record from a relationship. (e.g. remove a course record from a teacher's list of taught courses).
====API====
Xataface includes a powerful API to allow you to more efficiently work with your database.
* '''Data Objects''' - Provides a simple API to work with database records. Searching, loading, saving, editing, and deleting records supported.
====Templates====
* '''Smarty Template Engine''' - Xataface uses the Smarty template engine as a base, one of the fastest PHP template engines available.
* '''Template Inheritance''' - You can create templates that inherit from other templates, and replace the content in specified ""slots"" of the original template. This drastically increases template reuse and development productivity.
* '''Cascading Support''' - All system templates are stored in the Dataface/templates directory. Your application can have its own templates directory where you can place templates to override system templates. All parts of the system can be overridden without modifying the original templates themselves.
====Themes====
Xataface includes a powerful themes API. You can create multiple looks for your application and switch between them with a simple configuration setting.
====REST Support====
Xataface's intelligent URL protocols make it a powerful platform for REST web services. You can specify a query directly in the URL to obtain the exact found-set that you want. This is also very useful in standard web applications because you can easily create links to desired parts of your application. Or you can use Xataface to provide missing functionality in your existing applications and link only to the parts of your Xataface app that you need.
===History===
Xataface (formerly Dataface) was originally created by Steve Hannah in 2005 to increase productivity created data-driven applications for Simon Fraser University. He came from faculty that used Filemaker extensively for their databases. As a PHP developer he preferred open technologies like MySQL as they provided fewer ""road blocks"", but it was hard to deny the benefits of filemaker when it came to providing users with an instant user interface for their databases. It was difficult to justify spending 3 weeks building an administration console for a MySQL application when it could have been done in 3 hours had Filemaker been used.
Xataface was designed to:
# Increase developer productivity to the point where MySQL applications could be created as quickly as Filemaker applications without sacrificing usability and functionality.
# Add an abstraction over a database to make is accessible to non-technical users. The secretary shouldn't need to know SQL in order to interact with a database.
# Test the limits of PHP and MySQL
As it was built with the intention of providing an alternative for Filemaker, many implementation details and concepts have been inspired by Filemaker. For example, Xataface's implementation of relationships is very similar to Filemaker relationships; as are valuelists. In addition the method of searching follows many Filemaker conventions.
The first application built with Xataface was a group content management system for the Faculty of Applied Sciences at Simon Fraser University. This system was used by faculty to manage their research profiles and their research groups. The database itself pre-existed the Xataface implementation. Xataface was used to build a new administrative interface to the system. Since then Xataface has been used to develop many systems for SFU including website content management systems, auctions, event registration systems, research databases, shopping carts, and more.
==Where to go from here==
* [http://xataface.com/documentation/tutorial/getting_started Getting Started Tutorial]
* [http://xataface.com/videos Watch Demonstration Videos of Xataface]
* Sign up for the Xataface Maillist to receive free updates and development tips. (See sign-up form in upper left of the page).",,en,0
URL_Conventions,37,URL_Conventions,"==Xataface URL Conventions==
[[toc]]
Xataface adheres to a few simple URL conventions for all of its actions. When you understand how Xataface URLs work you begin to get far more out of your applications. By specifying the appropriate query parameters to can jump directly to any point in your application, or produce a specific result set.
For example, the URL ''index.php?-table=people'' will take you to the ''people'' table (and since the default action for a Xataface application is ''list'', it will take you to the ''list'' view.
You could be more explicit by specifying the action in the URL directly: ''index.php?-table=people&-action=list''. This would take you to the same screen. From this example, you see that you can specify such things as the table and action via GET parameters. Xataface accepts many more GET parameters also, as you'll see in the next section.
===Available GET Parameters===
{| class=""listing listing2""
|-
! Name
! Description
! Default
! Version
|-
| -action
| Specifies the action to perform. E.g. ''browse'', ''list'', ''find'', ''edit'', ''new'', ... etc..
| list
| all
|-
| -table
| The name of the table to use as the context table.
| The first table in the [_tables] section of your [[conf.ini file]]
| all
|-
| -skip
| Skip a certain number of results in the current found set to display. E.g. If there are 100 records in the table and you want to start browsing from the 30th record, you would set ''-skip=29''.
Not to be confused with the ''-cursor'' parameter which is used to specify which record to view in the ''details'' tab.
| 0
| all
|-
| -limit
| The maximum number of records in the found set to display.
| 30
| all
|-
| -cursor
| The index of the record in the current found set that is treated as the ""current"" record. This is used in the ''details'' tab to identify which record to act on. E.g. which record to view or edit.
| 0
| all
|-
| -sort
| A comma-delimited list of columns to sort the result set on.
| null
| all
|-
| -relationship
| If we are browsing related records, this specifies the name of the relationship.
| null
| all
|-
| -related:start
| If we are browsing related records, this is the first record in the relationship to show.
| 0
| all
|-
| -related:limit
| If we are browsing related records, this is the number of records to show per page.
| 30
| all
|-
| -search
| A keyword search term to filter the found set on. Any row containing any field that matches the query will be returned.
| null
| all
|-
| --no-query=1
| A flag to indicate that xataface should not query the database by default. This flag is used in the new record form to prevent the form parameters from being interpreted as query parameters to search in the database. If you set this flag, it likely result in a message saying ""No records found"". Generally you would only use this in a custom action where you are not relying on Xataface's default found set.
| 0
| 1.3
|}
There are many other GET parameters that are used in various contexts but the above parameters are available throughout the entire application.
===Finding Records using the URL===
Notice that all of the GET parameters mentioned in the previous section begin with a hyphen (i.e. '-'). This is a convention Xataface uses to distinguish directives from search queries. All parameters that do not begin with '-' are treated as a query to filter the found set.
For example, ''first_name=bob'' used as a GET parameter would cause the found set to be filtered so that only records where the ''first_name'' column contains the phrase ""bob"" are returned. Putting this all together, suppose we wanted to show the list tab for the ''people'' table, but only wanted to show the people with first names containing ""bob"":
index.php?-action=list&-table=people&first_name=bob
====Exact, Range, and Pattern Matching====
By default, queries on text columns look for partial matches. I.e. if you search for ""bob"" it will match ""bob"", ""bobby"", ""rubob"", and any other text that contains ""bob"". If you are only interested in finding records that match ''exactly'' ""bob"", then you can prepend an ""="" to the query. E.g. ''first_name==bob'', or the full URL:
index.php?-action=list&-table=people&first_name==bob
This should show the ''list'' tab for the ''people'' table with only records with first name exactly ""bob"".
There are a number of modifiers that you can prepend to your query to modify how it is executed. They are as follows:
=====Search Operators=====
{| class=""listing listing2""
|-
! Prefix
! Usage Example
! Description
|-
| >
| age=>10
| Match records greater than search parameter.
|-
| <
| age=<10
| Match records less than search parameter.
|-
| >=
| age=>=10
| Match records greater than or equal to the search parameter.
|-
| <=
| age=<=10
| Match records less than or equal to the search parameter.
|-
| ..
| age=10..20
| Match records in a given range.
|-
| =
| first_name==bob
| Match records that exactly match the search parameter (if there is no prefix then it will search for partial matches on text/varchar/char fields.).
|-
| ~
| first_name=~a%
| Exact match, but you can include wildcards such as '%' and '?' in your search.
|}
=====Search Examples=====
Given the following data set:
{| class=""listing listing2""
|-
! first_name
! age
|-
| Bob
| 10
|-
| Cindy
| 12
|-
| Julie
| 6
|-
| Jake
| 8
|-
| Kabob
| 16
|}
Here are some example queries on this data set and their results:
{| class=""listing listing2""
|-
! Query
! Matches
|-
| age=>10
| match records where ''age'' is greater than 10. This includes ''Cindy'' and ''Kabob''.
|-
| age=<10
| match records where ''age'' is less than 10. This includes ''Julie'' and ''Jake''
|-
| age=>=10
| match records where ''age'' is greater or equal to 10. This includes ''Bob'', ''Cindy'', and ''Kabob''.
|-
| age=<=10
| match records where ''age'' is less than or equal to 10. This includes ''Bob'', ''Julie'', and ''Jake''.
|-
| age=8..10
| match records where ''age'' is between 8 and 10. This includes ''Bob'' and ''Jake''.
|-
| first_name=bob
| Matches records where ''first_name'' contains ""bob"". This includes ''Bob'' and ''Kabob''.
|-
| first_name==bob
| Matches records where ''first_name'' is exactly ""bob"". This includes ''Bob'' only.
|-
| first_name=~J%
| Matches records that begin with ""J"". This includes ''Jake'' and ''Julie''
|}
====Matching on Related Records====
It is also possible to match records based on their related data (i.e. data that is not physically stored in the record itself, but in related records via a relationship). For example if we want to find authors who have written about a particular topic, we would normally have to first find all of the articles that contain a topic, and then cross-reference that result against the ''authors'' table. With Xataface we can perform this query directly from the ''authors'' table using something like the following query:
index.php?-table=authors&articles/title=sports
This assumes that the ''authors'' table has a relationship named ''articles'' that contains all of the articles that an author has written. So the above query returns precisely those authors who have written at least one article whose ''title'' field contains the phrase ""sports"".
=====Anatomy of a Related Query=====
%relationship%/%field%=%query%
This matches all records in the current table such that at least one record in its '''' relationship matches the query: ''%field%=%query%''.
====Using the ''OR'' Operator====
Xataface allows you to search for more than one value at a time using the ''OR'' operator. E.g.
first_name=bob+OR+steve
Would match all records with ''first_name'' containing ""bob"" or ""steve"".
first_name=bob+OR+=steve
Would match all records with ''first_name'' containing ""bob"" or exactly matching ""steve""
age=<10+OR+>20
Would match all records with age less than 10 or greater than 20.
====Combining Multiple Queries in One Request====
Xataface allows you to filter on more than one field at a time. If you combine multiple queries in the same request it has the effect of strengthening the filter, matching only those rows that match ''both'' queries. E.g.
age=>10&first_name=bob
would match all records where ''age'' is greater than 10 '''AND''' that have ''first_name'' containing ""bob"".
=====Examples of Combined Queries=====
Given the same data set as the previous set of examples:
{| class=""listing listing2""
|-
! first_name
! age
|-
| Bob
| 10
|-
| Cindy
| 12
|-
| Julie
| 6
|-
| Jake
| 8
|-
| Kabob
| 16
|}
first_name=bob&age=11
would return no matches because there are no records that contain both ''first_name'' ""bob"" and ''age'' 11. However
first_name=bob&age=10
would return only ''Bob'' and
first_name=bob&age=16
would return only ''Kabob''.
====Special Common Queries====
=====Search For Null or Blank Value=====
Searching for a null value or a blank value is an exact match for """". Therefore you can simply search for ""="". E.g. To find records with a null or blank first_name you would use the query ''first_name==''. Or the full query:
index.php?-table=people&first_name==
=====Search for Non-blank Value=====
Searching for a non-blank value is the same as searching for a value greater than """". Therefore you can simply search for "">"". E.g. if you wanted to find records with a first_name, you would use the query ''first_name=>''. Or the full query:
index.php?-table=people&first_name=>
==Preserved vs Non-preserved Parameters==
As mentioned above any parameters that are prefixed by a hyphen (i.e. ""="") are treated as directives rather than search filters. Hence if you want to use your own GET parameters you should always prefix them with a ""-"" to ensure that Xataface does not attempt to apply it as a search filter. In order to keep a consistent context for users, all browsing within the same table preserves both search queries and directives. Hence if you go to the URL:
index.php?-table=people&-action=list&first_name=bob
It will show you the ''list'' tab of the ''people'' table with only those records with ''first_name'' ""bob"". Now if you click on the ''details'' tab it will preserve your query ''first_name''. The query will become something like:
index.php?-table=people&-action=details&first_name=bob&...etc... more parameters
(Although the parameters may appear in a different order). This allows you to navigate forward and back to previous and next records and stay within the same found set. It also ensures that if you click on the ''list'' tab to return to the list view, it will retain your place in the list.
Note that navigating within the same table it will also preserve your directives. E.g. If you specify the ''-limit'' directive to show 100 records per page:
index.php?-table=people&-action=list&-limit=100
And then you click on the ''details'' tab, it will retain your ''-limit'' parameter. Of course the ''-limit'' parameter is not actually used by the ''details'' action because it works on only one record at a time (it uses the ''-cursor'' parameter instead), when you click back on the ''list'' tab it will still show you 100 records per page.
Because of this, we call the ''-limit'' parameter a preserved parameter. It is retained when navigating within the same table. '''Note:''' parameters are retained in the HTTP Query string, not in sessions or cookies. This ensures that there are no surprises when you enter a URL to your Xataface application.
===Unpreserved Parameters===
If you ''don't'' want Xataface to preserve one of your parameters, you should prefix two hyphens to the parameter name. I.e. ""--"". One example of an unpreserved parameters throughout Xataface applications is the ''--msg'' parameter. The value of this parameter will be displayed on the page as an info message to the user. Clearly you don't want this parameter preserved across requests, as you only want the user to see a message once. E.g.
index.php?--msg=Record+Successfully+saved.
Would didsplay the mesage ""Record Successfully Saved"" at the top of the page. If you click on any link in the application, it will not retain the ''--msg'' parameter so you will not see the message on subsequent requests.
This parameter is useful if you want to give feedback to the user about an action that has been carried out.
===Summary===
{| class=""listing listing2""
|-
! Parameter Type
! Prefix
! Examples
! Description
|-
| Preserved
| -
| -limit, -skip, -cursor, -action, -table
| Parameter value is preserved when user navigates away from the page (within the same table).
|-
| Unpreserved Parameters
| --
| --msg
| Parameter is ''NOT'' retrained with the user navigates away from the page.
|}
","URL Conventions, GET Parameters, POST parameters, Request Parameters",en,0
How_to_build_a_PHP_MySQL_Application_with_4_lines_of_code,38,"How to build a PHP MySQL Application with 4 lines of code","'''The [http://xataface.com Xataface Application Framework] allows you to convert your existing MySQL database into a full-fledged with as little as 4 lines of code. And it's Not a code generator.'''
[[toc]]
This article is intended to spark interest in the [http://xataface.com Xataface Application Framework] amongst PHP developers by showing how easy it is to set up a full-featured front-end for your MySQL database. If you are a PHP developer, surly you can identify with the situation where you've built a snazzy website with PHP and MySQL but you need to create some way the website users to administer it. I.e., you need to make an administrative back-end for your users.
You need to do this because PHP admin is too technical for your users, and it is an aweful lot of tedious work to create all of the necessary forms and lists for your users to edit the data themselves.
===Features for our Application===
* Create, edit and delete records using simple web forms.
* Browse through database and find records without any SQL.
* Lots of great widgets for editing records including html editors, select lists, grids, checkboxes, calendars and more.
* Sort records.
* Export result sets as CSV or XML.
* Fully configurable and extendable by you to implement more [[about|features]].
===Creating the Application===
Here are 6 steps to a full-featured front-end for your database:
# Create a directory for your application on your webserver. Call it ''myapp''.
# Download the latest version of [http://xataface.com Xataface] and copy it into your application directory that we just created. (i.e. ''myapp/xataface''.
# Create a configuration file named ''conf.ini'' inside your application directory (i.e. ''myapp/conf.ini'') to store your database connection info:
[_database]
host=localhost
name=mydb
user=username
password=mypass
[_tables]
;; This section lists the tables to include in your application menu
table1=Label for table 1
table2=Label for table 2
# Create an .htaccess (i.e. ''myapp/.htaccess'') file to prevent Apache from serving your ''conf.ini'' file:
Deny from all
'''Note: If you are not using Apache as your web server you'll need to block access to the .ini files using a different mechanism. E.g. On IIS you can create a Web.config file to block this access and place it inside your application's directory.''' Download a sample Web.config file [http://weblite.ca/svn/dataface/core/trunk/site_skeleton/Web.config here].
# Create an index.php file (i.e. ''myapp/index.php'') to serve as an access point for your application:
display();
// first parameter is always the same (path to the current script)
// 2nd parameter is relative URL to xataface directory (used for CSS files and javascripts)
# Create a ''templates_c'' directory to store cached smarty templates or your application (i.e. ''myapp/templates_c'', and make sure that it is writable by the webserver:
$ mkdir templates_c
$ chmod 777 templates_c
That's all there is to it! Point your web browser to the index.php file we just made, and check out your new app!
===Screenshots of Our App===
====Find Form====
[[Image:http://media.weblite.ca/files/photos/people-find.png?max_width=400]]
====New Record Form====
[[Image:http://media.weblite.ca/files/photos/people-new-record.png?max_width=400]]
====List View====
[[Image:http://media.weblite.ca/files/photos/people-list.png?max_width=400]]
===Where to go now===
# Sign up for the Xataface mailing list to receive exclusive development tips (see the left column for a signup form).
# Check out the [[about|About Xataface]] page for more information about features and requirements.
# Use the [http://xataface.com/documentation/getting_started Getting Started Tutorial] to get started making your own application.
# [http://xataface.com/videos Watch screencasts] showing Xataface in action.
","tutorial, getting started, installation, first app, 4 lines of code",en,0
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:
[my_pubications]
publications.owner_id=""$person_id""
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:
[my_pubications]
publications.owner_id=""$person_id""
metafields:order=""pub_order""
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]]:
[MY ROLE]
reorder_related_records=0
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.
$benStein = df_get_record('people', array('person_id'=>2));
$pubs = $benStein->getRelatedRecordObjects('my_publications');
foreach ($pubs as $pub){
echo $pub->val('pub_title').'
';
}
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
Introduction_to_RSS_Feeds_in_Xataface,40,Introduction_to_RSS_Feeds_in_Xataface,"==Introduction to RSS Feeds in Xataface==
[[toc]]
A default Xataface application provides RSS feeds to any found set in your application. This article explains a little bit about RSS and how you can configure Xataface to give you the desired results for your RSS feed.
===What is RSS?===
From [http://en.wikipedia.org/wiki/RSS_(file_format) Wikipedia's RSS article]:
""RSS is a family of Web feed formats used to publish frequently updated works such as blog entries, news headlines, audio, and videoin a standardized format.[2] An RSS document (which is called a ""feed"", ""web feed"",[3] or ""channel"") includes full or summarized text, plus metadata such as publishing dates and authorship. Web feeds benefit publishers by letting them syndicate content automatically. They benefit readers who want to subscribe to timely updates from favored websites or to aggregate feeds from many sites into one place. RSS feeds can be read using software called an ""RSS reader"", ""feed reader"", or ""aggregator"", which can be web-based or desktop-based. A standardized XML file format allows the information to be published once and viewed by many different programs. The user subscribes to a feed by entering the feed's URI (often referred to informally as a ""URL"", although technically, those two terms are not exactly synonymous) into the reader or by clicking an RSS icon in a browser that initiates the subscription process. The RSS reader checks the user's subscribed feeds regularly for new work, downloads any updates that it finds, and provides a user interface to monitor and read the feeds.""
In a way RSS replaces email subscriptions so that you can subscribe to receive updates when content is added or changed on websites that you monitory. This way you can monitory these changes in your RSS reader so that your email box doesn't get clogged up.
===Using RSS in Xataface===
Xataface allows you to subscribe to:
# Entire tables
# Any found set
# Changes to a particular record
# Related record lists
====Example 1: Subscribing to receive news updates====
A user wants to be alerted whenever a new item is inserted into the ''news'' table, so he navigates to the ''list'' tab of the ''news'' table, and clicks the RSS Feed icon in the upper right. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for the ''news'' table. When new records are inserted, he'll receive alerts in his RSS reader.
====Example 2: Subscribing to receive found set updates====
A user wants to be alerted whenever a new item is inserted into the ''news'' table that contains the phrase ""Buffalo Bills"", because he is a Buffalo Bills fan. So he navigates to the ''news'' table, and does a search for the phrase ""Buffalo Bills"". Then he clicks on the ""RSS Feed"" icon in the upper right of the result set list. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for ''news'' items containing the phrase ""Buffalo Bills"". Whenever a new item is posted with this phrase, he will be notified via RSS of the new record.
====Example 3: Subscribing to a related list====
Suppose you want to receive updates whenever a particular author adds a book to his list of published works. Further suppose this is represented by a relationship between the ''authors'' table and the ''books'' table named ''publications''. You can subscribe to the RSS feed for his publications by navigating to the ''publications'' tab for that author, then clicking on the ""RSS Feed"" icon in the upper right. Now whenever this author adds a new book to his publications list, you'll be notified via RSS.
===Example usage in Xataface===
# A user wants to be alerted whenever a new item is inserted into the ''news'' table, so he navigates to the ''list'' tab of the ''news'' table, and clicks the RSS Feed icon in the upper right. If he has an RSS reader application set up, this is all he has to do to subscribe to the RSS feed for the ''news'' table. When new records are inserted, he'll receive alerts in his RSS reader.
# A user wants to be alerted whenever a new record about ""Wayne Gretzky"" is inserted in to the ''news'' table. He navigates to the ''news'' table, then performs a search for ""Wayne Gretzky"" using the top right search box. Then, he clicks on the ""RSS Feed"" icon in the upper right of the result list. Now, whenever a new item is inserted with the phrase ""Wayne Gretzky"", the user will be notified via RSS.
===Configuring RSS Feeds===
As with everything else in Xataface, you can configure your RSS feeds to appear just as you want them to. The following delegate class methods are available to be defined in the table delegate class for your feed:
{| class=""listing listing2""
! Name
! Description
! Version
|-
| [[getFeedItem]]
| For RSS Feeds, overrides the defaults and returns an associative array with feed elements for a particular record
| 1.0
|-
| [[getFeed]]
| For RSS feeds, overrides the default feed for a query, returning an array of feed items.
| 1.0
|-
| getFeedSource
| Overrides the default feed source parameter for an RSS feed.
| 1.0
|-
| getRSSDescription
| Overrides the default generated RSS description for a record.
| 1.0
|-
| [[getSingleRecordSearchFeed]]
| Overrides the default feed for a subsearch within a record. This works identically to the [[getFeed]] method except that it takes 2 parameters: one for the current record, and a second parameter for the query.
| 1.2.3
|}
==Example Configuration==
There are 2 parts to configuring your RSS feeds.
# Configuring the feed as a whole
# Configuring the feed items (that is each record that will appear in your RSS feed).
===Configuring the Feed as a whole===
For configuring the feed as a whole, we have 2 options. We can specify the title, description, and link for the feed in the ''[_feed]'' section of your [[conf.ini file]]. This is sort of a ""one size fits all"" approach where all feeds generated from your application will share the same title.
E.g.
[_feed]
title=""My Site News""
description=""News updates from my site""
link=""http://www.example.com""
However, if we want our feed's information to depend on the user's query (e.g. what the user was searching for, or which table the feed is generated on, we have more flexibility if we define the [[getFeed]] method in either the [[Application Delegate Class|application delegate class]] or the [[Delegate class methods|table delegate class]]. E.g.
function getFeed($query=array()){
$params = array();
if ( @$query['-search'] ) $params['title'] = '""'.$query['-search'].'"" results';
else $params['title'] = 'All records from my table';
return $params;
}
Notice that I don't need to define all possible parameters. Any parameters that I don't define will be provided automatically by Xataface, or it will simply use the values specified in your ''[_feed]'' section of the [[conf.ini file]].
===Configuring Feed Items===
Configuring the feed items is quite important for ensuring that subscribers are seeing what you want them to see in the RSS feed. Xataface tries to guess appropriate content for your feed items if you don't specify it explicitly, but you'll likely want to tweak it a little bit to make the feed look more polished for your purposes.
Use the [[getFeedItem]] [[Delegate class methods|delegate class method]] to specify how a feed item behaves (e.g. the title, content, date, author, link).
E.g.
function getFeedItem(&$record)){
return array(
'description' => $record->val('body')
);
}
Once again, notice that we don't need to specify all available options. Only those options that we want to override. In this case we want the description of the feed item to simply display the body of our news item. The description of an RSS feed item is effectively the body text that the user sees why they click on an item in their news reader, so this is quite important.
","RSS Feeds",en,0
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===
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'
);
}
'''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
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===
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)
);
}
'''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
Calendar_Action,43,Calendar_Action,"==Calendar Action==
[[toc]]
Xataface 1.0 includes a built-in calendar action that is disabled by default. If enabled, it allows you to view the records in any found set as a calendar of events, as follows:
![]()
===Features===
* Monthly display
* Hourly schedule for any day by clicking on it.
* Show record details instantly by clicking on it in the calendar.
* Recognizes dates, start and end times for records when interpreted as calendar events.
* Respects searches (i.e. you can filter the records and the calendar will only show those records in the found set).
===Requirements===
Your table records should contain at least dates in order for them to be interpreted as events that can be placed in a calendar.
===Setting up the Calendar===
Suppose I have a table called ''Lessons'' that stores information about scheduled music lessons. If I want to add the calendar to this table, then I would add an ''[[actions.ini file]]'' to the ''tables/Lessons'' directory with the following contents:
[calendar > calendar]
condition=""true""
This overrides the calendar action which is disabled by default, and enables it for the ''Lessons'' table.
Next I need to inform Xataface which fields store the event dates and times so that the records can be laid out in the calendar appropriately. (Note that if you skip this step, Xataface will make a best guess based on column types and names - but it is better to specify these explicitly).
In the ''Lessons'' table I have the following fields that are relevant here:
* ''lesson_date'' - A date field containing the date and start time of the event.
* ''start_time'' - A time field with the start time of the lesson.
We can tell Xataface to treat these fields accordingly by adding the following directives to the appropriate field sections of the [[fields.ini file]] for the ''Lessons'' table:
* ''event.date=1'' - Specifies that the field stores the date of the event.
* ''event.start=1'' - Specifies that the field stores the start time of the event.
So in our case we'll modify the [[fields.ini file]] as follows:
[lesson_date]
event.date=1
[start_time]
event.start=1
Now if we load up our application, we should now see a ''calendar'' tab along side ''list'', ''details'', and ''find'' for the ''Lessons'' table. Click on this tab to see your records displayed in a calendar.
===Using a datetime field to store both date and start time===
You can also use a single field to store both the date and start time for an event. In this case you just provide the ''event.date'' and ''event.start'' directives for the same field. For example if the ''lesson_date'' was a datetime field that marked the date and time of the lesson, we would modify our [[fields.ini]] file as follows:
[lesson_date]
event.date=1
event.start=1
===Available Fields===
The Calendar action will look for the following pieces of information in your records:
{| class=""listing listing2""
! Name
! Description
! Version
|-
| event.date
| Indicates that the field contains the date of the event.
| 1.0
|-
| event.start
| Indicates that the field contains the start time of the event.
| 1.0
|-
| event.end
| Indicates that the field contains the end time of the event.
| 1.0
|-
| event.location
| Indicates that the field contains the location of the event.
| 1.0
|-
| event.category
| Indicates that the field contains the category of the event.
| 1.0
|}",,en,0
timestamp,44,timestamp,"Return to [[fields.ini file]]
A very simple sample of this could be your table contains the table date_created as a type of date. In your fields.ini, you would include this:
[date_created]
timestamp=insert
widget:type=hidden
The widget:type=hidden will make the field not visible during entry and editing. And the timestamp=insert causes the field to be filled upon insertion of a new record.
===Possible Values===
* '''update''' - Causes timestamp to be updated whenever the record is modified.
* '''insert''' - Causes the timestamp to be updated only when the record is first inserted.","timestamp, date, datetime",en,0
_output_cache,45,"The Xataface Output Cache","Note: There was a bug in the output cache affecting Xataface version 1.0 to 1.3rc1. If you are using a version of Xataface older than 1.3rc2 then you should either disable the output cache, or replace the Dataface/OutputCache.php file with one from a newer version.
[[toc]]
Xataface does quite a bit of heavy lifting on each page request. If your application is getting a lot of traffic that is slowing your server down, you may want to look at enabling the Xataface output cache.
===Features===
* Improve speed of application dramatically - especially for seldom updated sites.
* Supports multiple languages.
* Supports multiple users (each user has own cache).
* Provides GZIP compression for improved performance.
===How it works?===
When you receive a request, Xataface will return a cached version of the page if the page has been accessed before. If the page doesn't yet exist in the cache it generates the page, saves it to the cache and outputs it to the user transparently. The cache is completely transparent to your users.
===Where is the cache stored?===
Xataface creates a table called ''__output_cache'' that stores all of the cached content for your application. This table stores both a GZIPed and regular version of each page. If the user's browser supports GZIP compression, Xataface will automatically return the GZIP version. This results in further performance improvements.
===What if I make changes to the database?===
Xataface records which tables were in use when a page is cached. If any of those tables are modified after the page is cached, Xataface will mark that cached page as ''out of date'' and regenerate it the next time that it is requested.
===What if I make changes to my configuration files and templates?===
The output cache will have to be manually cleared if you make any changes to your source files (e.g. PHP, templates, and INI files). Clearing the cache is as easy as deleting or emptying the ''__output_cache'' table.
===How do I enable the Cache?===
Add the following to your [[conf.ini file]]:
[_output_cache]
enabled=1
===How do I disable the Cache?===
Simply comment out or remove the ''[_output_cache]'' section of your [[conf.ini file]]. E.g.
;[_output_cache]
; enabled=1
===Configuration Options===
The following directives can be added to the ''[_output_cache]'' section of your [[conf.ini file]] to customize how your output cache works.
{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| lifeTime
| Number of seconds before cached page is considered ''out of date''.
| 0.7
|-
| tableName
| The name of the table to store the cached pages. Default '__output_cache'.
| 0.7
|-
| ignoredTables
| A comma-delimited list of tables that don't affect the output cache (i.e. these tables can be changed without causing the output cache to be refreshed.
| 0.7
|-
| observedTables
| A comma-delimited list of tables that should affect the status of the output cache for every page (whether the table is explicitly used by the page or not). This is a useful way to tell Xataface to refresh your cache.
| 0.7
|-
| exemptActions
| A comma-delimited list of actions that are exempt from the output cache (and thus should not be cached).
| 0.7
|}","output cache",en,0
widget:atts,46,widget:atts,"==widget:atts Directive Reference==
The widget:atts directive in the fields.ini file allows any arbitrary HTML attributes to be added to any of the fields. It may also be used to specify javascript event handler functions that the widget should call upon the specified event. In particular, here are some examples of possible widget:atts directives:
===Available Widget Event Handlers===
{| class=""listing listing2""
|-
! name
! description
! version
|-
| [[field_size|widget:atts:size]]
| This directive sets the length of the input area a text box field, but it does not limit the number of characters that can be entered. For example:
widget:atts:size = 50
widget:atts:maxlength = 25
widget:atts:style = ""font-size: 24pt; font-family: Apple Chancery""
widget:atts:rows = 10
widget:atts:cols = 10
widget:atts:onchange = ""doJsFunction();""
widget:atts:onclick = ""doJsFunction();""visibility:ConferenceID = hidden
This will make the ConferenceID in the relationship list view disappear.",,en,0
tab,48,tab,"==tab directive of the fields.ini file==
[[toc]]
The ''tab'' directive of the [[fields.ini file]] specifies which tab of the record edit form a field should be displayed on. Xataface supports multiple tabs on the edit form by way of this ''tab'' directive. If no fields contain the ''tab'' directive then all fields are displayed in a single tab (named ''__main__'').
==Example 1: Placing address info on separate tab==
Consider the following ''people'' table:
CREATE TABLE `people` (
person_id int(11) not null auto_increment primary key,
first_name varchar(32) not null,
last_name varchar(32) not null,
address varchar(100),
city varchar(100),
province varchar(100),
country varchar(100),
postal_code varchar(20)
)
We want to split the fields into two tabs:
* Personal Info
* Address Info
===Splitting form into tabs===
We'll do this in two steps. We use the ''tab'' directive to assign all address-related fields to the ''address_info'' tab. In the tables/people/fields.ini file:
[address]
tab=address_info
[city]
tab=address_info
[province]
tab=address_info
[country]
tab=address_info
[postal_code]
tab=address_info
Now, when we load the edit form of the ''people'' table, we see two tabs:
* __main__
* address_info
![]()
![]()
''__main__'' is the name assigned to the default tab (for all fields that don't have a tab defined explicitly.
===Customizing the tab labels===
Next we will customize the tab labels by adding the following to the beginning of the [[fields.ini file]]:
[tab:__main__]
label=""Personal Information""
[tab:address_info]
label=""Address Information""
![]()
![]()
===Reordering the tabs===
If we want to reorder the tabs so that the ''address_info'' tab comes first, we would just reorder the definitions of the tabs:
[tab:address_info]
label=""Address Information""
[tab:__main__]
label=""Personal Information""
![]()
===Try This Example App===
You can try this tiny sample application out [http://dev.weblite.ca/tab_test here].",,en,0
Troubleshooting,49,Troubleshooting,"==Xataface Troubleshooting==
This document is intended to help Xataface developers through some of the most common issues.
[[toc]]
==All I get is a blank white screen!==
The most common issue mentioned in the forums is that an application comes up with a blank white screen in the web browser. This can happen for a number of reasons but the most common reason is because PHP has encountered a fatal error and your PHP installation is not set up to display errors.
The first step to troubleshooting this problem must be to find out what the error is. You can do that in one of the following ways:
# Check your Apache error log if you know where it is. One common location on many linux installations is
/var/log/httpd/error_log
but your system may have it located elsewhere. If you cannot find your error log, continue to the next option.
# Turn on the ''display_errors'' flag in your ''php.ini'' file. I.e., in your ''php.ini'' file, find where it says
display_errors Off
and change it to
display_errors On
. After this is done, restart your apache webserver. If you don't know where your ''php.ini'' file is located see the section later in this document on locating your ''php.ini'' file. If you don't have access to your php.ini file, move on to the next option.
# In your application's ''.htaccess'' file, add the following directives to enable displaying errors:
php_flag display_errors on
. Note that this method will only work if your apache config file allows you to override these values at the directory level. If you still get a blank white screen after this, continue to the next option.
# At the beginning of your application's index.php file, add the following:
. Note that if the error occurs in the parsing or compiling of your PHP files you will still get a blank screen. But this will at least display runtime errors on the page.
Once you can see the error messages that caused the blank white screen you are in a much better position to solve the problem.
==Locating your php.ini file==
Locating your ''php.ini'' file is actually quite easy. The quickest way is to create a php script with the following contents:
then navigate to this page in your web browser. This look at the line where it says the ''php.ini file''. It will list the path there.",,en,0
__field__permissions,50,__field__permissions,"This method can be used to set the default permissions for all fields in a designated table, when specified in that table's delegate class. It comes in handy in situations when you want to deny access to all fields except for those designated, rather then specifying each field to deny individually. For example, to revoke edit permissions from all fields but one, the user must first have edit permissions to the table overall, otherwise the Edit tab/action will not appear. Then, use this __field_permissions method to revoke edit permissions from all fields. Finally, use the fieldname__permissions method (see below) to allow access to only those fields needed.
=== Also See: ===
* [[How_to_granulate_permissions_on_each_field]]
* [[fieldname__permissions]]",,en,0
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:
modules_Email=""modules/Email/Email.php""
# 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:
* * * * * /usr/bin/php mail
where is the absolute path to the cron.php script.
is the absolute path to your application's index.php script.
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
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]]:
[email > email]
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]]:
[email > email]
condition=""$query['-table'] == 'Pledge' or $query['-table'] == 'User'""
=====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]]:
[READ ONLY extends READ ONLY]
email=1
=====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]]:
[email > email]
email_column = ""emailAddress""
=====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.
[email > email]
email_table = ""newsletters""
=====Altogether=====
[email > email]
condition=""$query['-table'] == 'Pledge' or $query['-table'] == 'User'""
permission=email
email_column = ""emailAddress""
email_table = ""newsletters""
==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.
![]()
# Fill in the email form and press Save.
![]()
# 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:
[authors]
__sql__ = ""select * from authors a inner join book_authors ab on a.author_id=ab.author_id where ab.book_id='$book_id'""
And your relationship from the authors table would be something like:
[books]
__sql__ = ""select * from books b inner join book_authors ab on b.book_id=ab.book_id where ab.author_id='$author_id'""
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:
create view book_authors_maillist as
select * from authors a inner join book_authors ab on a.author_id=ab.author_id
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.
[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""
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
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:
[fieldgroup:address]
label=""Address Information""
template=""AddressInformationGroup.html""
[address_1]
group=address
[city]
group=address
[state]
group=address
Then you would add the a template named ''AddressInformationGroup.html'' to your application's ''templates'' directory to display how the fields are laid out:
Address 1:
{$elements.address_1.html}
City:
{$elements.city.html}
State:
{$elements.state.html}
This would display all of the fields in this group in a single row (horizontally) instead of vertically.
Note that this is an over-simplified example that doesn't take account for display error messages, required notices, grouped fields, and other information that you can obtain from the {$elements} array.",,en,0
How_to_Add_Custom_Sections_to_View_Tab,52,How_to_Add_Custom_Sections_to_View_Tab,"==How to Add Custom Sections to the View tab==
[[toc]]
The ''View'' tab is intended to give the user a detailed view of the contents of a record. By default it shows the values of each non-empty field grouped into their appropriate field groups. It also shows the most recent 5 related records from each relationship in the record. You can also add your own sections by implementing the [[section__xxx]] method of the delegate class.
==Example 1: A ""Hello World"" Section==
We'll start by adding a simple section that simply displays ""Hello World"" to the user. In the delegate class for your table, add the following method:
function section__hello(&$record){
return array(
'content' => 'Hello World!!!',
'class' => 'main'
);
}
Now if you reload our application and click on the ""View"" tab for any of the records in the database, you'll notice a section labelled ''hello'' with the text ''Hello World!!!'' in it.
Let's dissect the above code so that we can better understand what is going on here.
# The function ''section__hello()'' defines a section named ''hello''. If you wanted to define a section named ''foo'' you would call the function ''section__foo()''
# This function returns an array with the keys ''content'', and ''class''.
# The ''content'' key points to the actual HTML content of the section. In this case it is simply the text ''Hello World!!!''.
# The ''class'' key defines where the section should be displayed. It accepts values of ''left'' and ''main'' only. If it is set to ''left'', then the section will be displayed in the left column. A value of ''main'' indicates that it should be displayed in the main column.
===Customizing the Section Label===
''hello'' is a boring label, so let's add our own custom label by adding the ''label'' key to the array returned by our method:
function section__hello(&$record){
return array(
'content' => 'Hello World!!!',
'class' => 'main',
'label' => 'Message of the Day'
);
}
Now if you load the view tab of your application, you'll notice that the section has a heading ""Message of the Day"".
===Customizing the Section Order===
A section can also specify an ''order'' attribute to define the order in which this section should appear. It defaults to 0 which may cause the section to appear at the top of the view tab. You can push it to the bottom of the view tab by assiging a higher number to the ''order'' attribute:
function section__hello(&$record){
return array(
'content' => 'Hello World!!!',
'class' => 'main',
'label' => 'Message of the Day',
'order' => 10
);
}
Now if you reload the view tab you'll notice that the section has moved to the bottom of the page.",,en,0
fieldname__permissions,53,fieldname__permissions,"==fieldname__permissions() method==
[[toc]]
The fieldname__permissions() methods will allow you to define custom permissions on a particular field in the [[delegate class]]. For example to specify permissions on a field named ''foo'' you would define the ''foo__permissions()'' method, and to define permissions on a field named ''role'' you would define the ''role__permissions()'' method.
==Example #1==
(Note this example needs to be refined to be more clear)
function approval_level__permissions(&$record){
return array('edit'=>0); //this is will merge with what the permissions for the normal record
}
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:
$permissions['new'] = 0;
$permissions['edit'] = 0;
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:
$permissions['new'] = 0;
$permissions['edit'] = 1;
=== Also See: ===
* [[How_to_granulate_permissions_on_each_field]]
* [[__field__permissions]]",,en,0
blob,55,blob,,,en,0
struct,56,struct,,,en,0
Creating_a_Dashboard,57,Creating_a_Dashboard,"==Creating a Dashboard for your Users==
[[toc]]
Xataface allows you to build powerful data-driven applications quickly, but these applications may be daunting to your users if they don't know what they can do with the application. Most applications provide some sort of dashboard or control panel with some introductory instructions and links to commonly used actions in the application. This makes the application more intuitive for users so that they can start using it right away, even without instruction from the developer.
===Characteristics of a Dashboard===
# Should be the default page when someone visits the application.
# Should be customized to show menus and content that are relevant to the current user. (i.e. different users may see different links and content on their dashboard).
# Should contain at least some basic instructions so that the user understands what the application does when he visits the dashboard for the first time.
# Should contain links to frequently used actions.
===Strategies: 8 ways to skin the cat===
There are many viable strategies for adding a dashboard to your Xataface application. This article presents only one. It has been chosen because it satisfies all of the desired characteristics of a dashboard listed above, and it is easy to implement.
This strategy involves the following components:
# Create a dummy ''dashboard'' table.
# Create a dashboard action and associated template.
# Make sure our dashboard action is the default action for our application (more complex than just using the [[default_action]] directive in the [[conf.ini file]].
==Our Sample Application==
Consider our sample application, a publications management system for professors and research groups at a university. It allows users to manage their publications using either BibTex format or a web-based form, and embed those publications into their webpage in a slick sortable format. Currently, when the user accesses the application for the first time, they are shown the ''list'' tab of the ''bibliographies'' table. This isn't all that informative and it may not be obvious to the user that their first step should be to create a new bibliography via the ''new record'' button. Ideally we would like the user to go directly to a dashboard page with options to:
# Add New Bibliography
# Edit an Existing Bibliography
# Embed a Bibliography into their Webpage
And we want some basic instructions so that the user knows what to do when they first access the page.
==The Steps==
To create this dashboard we will follow the steps listed below (and mentioned above in the ''strategies'' section.
===Step 1: Create a dummy ''dashboard'' table===
This may seem unorthodox but it just happens to make our lives easier in the long run. By creating a dummy table we are able to cause that table to be listed first in the ''_tables'' section of the [[conf.ini file]] and thus be the default table when users visit our application.
CREATE TABLE dashboard (
dashboard_id int(11) not null auto_increment primary key
);
INSERT INTO dashboard values (1);
===Step 2: Make ''dashboard'' table default===
We now modify the conf.ini file to list the ''dashboard'' table first:
[_tables]
dashboard=Dashboard
bibliographies=Bibliographies
===Step 3: Create a Dashboard action and associated template===
This is the step where we actually create our dashboard action. There are three parts to this story:
====Creating Action PHP Class====
The actual action will be located in the ''actions/dashboard.php'' file of our application, and looks like:
$bibs), 'dashboard.html');
}
}
All this does is loads the ''bibliographies'' records owned by the current user. Elsewhere we are using security filters so that the user can only see ''his'' bibliographies, which is why we don't need to specify any query here in the ''df_get_records_array'' function.
It then passes those bibliographies to the ''dashboard.html'' template that we create next.
====Creating the Action's Template====
The template for our action is located in the ''templates/dashboard.html'' file:
{use_macro file=""Dataface_Main_Template.html""}
{fill_slot name=""main_column""}
Welcome to the BibTeX Publication Management System (BPMS)
This system allows you to manage your publications and publish
them on the web. Some common actions you may perform with this system
include:
![]()
Create New Bibliography
![]()
Edit existing bibliography:
![]()
Embed your bibliography in a webpage:
{/fill_slot}
{/use_macro}
A few key things to notice in this template:
# It extends the ''Dataface_Main_Template.html'' template placing its content in the ''main_column'' slot. This allows our action to still display within the header and footer of our application.
# It makes use of the {$ENV.DATAFACE_SITE_URL} and {$ENV.DATAFACE_SITE_HREF} variables to refer to the site's base url and create links to the desired common actions.
# It provides a direct link to the ''new bibliography record'' form.
# It uses some slick javascript combined with select lists to allow the user to select any of his current bibliogaphies and edit them, or embed them into a webpage.
====Adding entry to the actions.ini file====
Currently our dashboard action has no permissions attached to it so users can see it whether they are logged in or not. In this particular application we want to require users to log in, and we have set permissions for all logged in users to NO_ACCESS(). Unfortunately this permission setting is only helpful if our action requires a particular permission to access it. We'll require the 'view' permission for this action, by adding the following to the actions.ini file:
[dashboard]
permission=view
===Step 4: Specify permissions===
We still want to specify permissions for our ''dashboard'' table to ensure that only logged in users can access the dashboard. So we create a delegate class for the ''dashboard'' table at ''tables/dashboard/dashboard.php'' with the following contents:
'''Note that we have defined the getUser() function elsewhere as a means of obtaining the current user and checking if a user is indeed logged in.'''
Notice that this [[getPermissions]] method returns all permissions only if the user is logged in. Otherwise it returns null, which means that it should use the same permissions as the rest of the application as defined in the [[Application Delegate Class]].
===Step 6: Make ''dashboard'' the default action for the ''dashboard'' table===
Now we just have one more detail that needs to be taken care of. We want the ''dashboard'' action to be the default action for the ''dashboard'' table only. By default we would see the ''list'' action which isn't helpful at all, so we will want to add a rule in our application delegate class to ensure that the user only sees our custom ''dashboard'' action if they access the ''dashboard'' table. We define a beforeHandleRequest() method in our conf/ApplicationDelegate.php (the application delegate class) file for this purpose:
getQuery();
if ( $query['-table'] == 'dashboard' and ($query['-action'] == 'browse' or $query['-action'] == 'list') ){
$query['-action'] = 'dashboard';
}
}
...
}
This simply checks to see if the table is ''dashboard'' and changes the current action to ''dashboard'' if so.
===Step 7: Try it out===
At this point, we are ready to try out our new dashboard to see how it works. When we load our application it should now go to the dashboard action that we created. We should also see ''Dashboard'' listed as the first table in the tables menu.
This dashboard presents a major improvement to our application as it is now much more user friendly.
![]()
",dashboard,en,0
Selected_Records_Actions,58,Selected_Records_Actions,"==Creating a Custom ''Selected Records'' Action==
[[toc]]
If you view the ''list'' tab in any of your Xataface applications, you'll notice that there is a checkbox next to each row of the list, and there are a number of actions listed at the bottom of the list that you can perform on the selected records. Xataface comes pre-built with only a few of these actions:
# Delete selected
# Update selected
# Copy selected
However it is quite easy to add your own actions here that are performed on selected records. This article describes exactly how to do this.
===What is a ''Selected Record'' action?===
A ''Selected Record'' action is no different than any other action in Xataface, except that it is meant to act on the records that have been selected in the list tab.
==Example Action: Approve Records==
Consider a news site where news stories are automatically imported into the database en masse, but each news story has a field ''approved'' to indicate whether the store has been approved to appear on the site yet. The usage pattern of this application involves a lot of looking through lists of news stories and approving them. Therefore it would be convenient if the user could just select the rows that he wants to approve and click a button to approve them all.
Out of the box Xataface would allow the user to select the records, click ''update selected records'', then update them all via the ''update selected records'' form. But avoiding this extra step will improve usability greatly.
===Step 1: Design the Action===
First we need to specifically decide how our action will work. In this case, the flow goes as follows:
# User selects the news items they want to approve.
# User clicks the ''Approve Selected'' button. (to be created)
# Our action approves the selected records.
# User is automatically redirected back to the list tab with a message stating how many records were successfully approved, and whether there were any errors.
===Step 2: Gather Our Tools===
Before we actually create the action, let's look at a few tools that we'll be using from the Xataface framework to make this happen.
# In the [[actions.ini file]], the ''[[selected_result_actions]]'' category is reserved for actions that act on selected records of the list tab. E.g.
[delete_selected]
...
category=selected_result_actions
...
# The [http://dataface.weblite.ca/df_get_selected_records df_get_selected_records()] function returns an array of [http://dataface.weblite.ca/Dataface_Record Dataface_Record] objects that represent the rows that were selected to initiate the action. E.g.
$app =& Dataface_Application::getInstance();
$query =& $app->getQuery();
$records = df_get_selected_records($query);
foreach ($records as $record){
...
}
# The [http://dataface.weblite.ca/checkPermission Dataface_Record::checkPermission()] method allows us to see if the current user has access to a specific permission on the given record. We'll use this method to ensure that the user has permission to approve the news record. E.g.
if ( !$record->checkPermission('edit', array('field'=>'approved')) ){
return PEAR::raiseError(""You don't have permission to edit the approved field for this record."");
}
# The Xataface will pass the redirect URL where your action should send the user upon completion of the action as the ''--redirect'' attribute of the ''POST'' variables. This value is base64_encoded so you'll need to decode it before redirecting. E.g.:
if ( @$_POST['--redirect'] )
$url = base64_decode($_POST['--redirect']);
$url .= '&--msg='.urlencode($updated.' records were deleted.');
header('Location: '.$url);
exit;
===Step 3: Create the Action===
We will call our action ''approve_news'' so we'll place it in the ''actions/approve_news.php'' file of our application:
getQuery();
$records =& df_get_selected_records($query);
$updated = 0; // Count the number of records we update
$errs = array(); // Log the errors we encounter
foreach ($records as $rec){
if ( !$rec->checkPermission('edit'), array('field'=>'approved')) ){
$errs[] = Dataface_Error::permissionDenied(
""You do not have permission to approve '"".
$rec->getTitle().
""' because you do not have the 'edit' permission."");
continue;
}
$rec->setValue('approved', 1);
$res = $rec->save(true /*secure*/);
if ( PEAR::isError($res) ) $errs[] = $res->getMessage();
else $updated++;
}
if ( $errs ){
// Errors occurred. Let's let the user know.
// The $_SESSION['--msg'] content will be displayed to the user as a message
// in the next page request.
$_SESSION['--msg'] = 'Errors Occurred:
'.implode('
', $errs);
} else {
$_SESSION['--msg'] = ""No errors occurred"";
}
$url = $app->url('-action=list'); // A default URL in case no redirect was supplied
if ( @$_POST['--redirect'] ) $url = base64_decode($_POST['--redirect']);
$url .= '&--msg='.urlencode($updated.' records were deleted.');
// Redirect back to the previous page
header('Location: '.$url);
exit;
}
}
===Step 4: Add the action to your actions.ini file===
The actions.ini file allows us to specify how and where this action is used, and by whom. We can specify permissions that are required to perform the action, conditions that are required to display the action, confirmation messages that are to be displayed to the user when they are about to perform the action, and more. Our [[actions.ini file]] entry looks like:
[approve_news]
label=""Approve""
description=""Approve selected records""
permission = edit
category=selected_result_actions
confirm=""Are you sure you want to approve the selected records?""
icon=""${dataface_site_url}/images/approve.gif""
condition=""$query['-table'] == 'news'""
This should be fairly straight forward. The only special items here are the ''category'' and ''confirm'' directives. The ''condition'' directive tells Xataface that this action should only be shown for the ''news'' table.
The ''confirm'' directive defines a confirmation message that should be displayed to the user when they attempt to approve records.
The ''icon'' directive allows you to specify the path to an icon to display for the action. In our case we have an icon located in the images directory of our application.
===Step 5: Trying it out===
Now when we go to the ''list'' tab of the ''news'' table there is an ''Approve'' button along the bottom where it says ""With Selected"". You we can click on this button to approve any of the selected rows.
",,en,0
no_access_text,59,no_access_text,"Whenever the NO_ACCESS permission is given for a field, normally the text NO ACCESS appears. But we might want to display another text. Here is an example of the text subscribe is used instead of NO ACCESS whenever the NO_ACCESS permissions is given.
function no_access_text(&$record){
return ""Subscribe"";
}
",,en,0
widget:type_textarea,60,widget:type_textarea,,,en,0
lookup,61,"The Lookup Widget","Return to [[widget:type]] page to see list of all widget types.
Back to [[fields.ini file]] to see other fields.ini directives.
[[toc]]
===Synopsis===
The lookup widget allows users to look a record from another table to insert into the field. It is like a select widget except that it doesn't use a vocabulary. Instead you just specify a table on which it should search using the widget:table directive. In order to use the lookup widget to edit a field, you should set the [[widget:type]] directive of the [[fields.ini file]] for the field to '''lookup''. I.e.
[fieldname]
widget:type=lookup
widget:table=mytable
'''Note that the lookup widget requires the [[widget:table]] directive to be set to the target table of the lookup or it will not work properly.'''
===Required Directives===
The following [[fields.ini file]] directives are required to accompany the field definition if a lookup widget is used:
{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| widget:table
| The name of the table in which the lookup widget should look up related records.
| 1.0
|}
===Optional Directives===
The following additional optional directives may be used to customize the behaviour of the lookup widget:
{| class=""listing listing2""
|-
! Name
! Description
! Version
|-
| widget:filters:-limit
| Sets the number of records that are shown by default in the lookup widget. Default is 30 if this is omitted. E.g.widget:filters:-limit=100 to show 100 records at a time.
| 1.0
|-
| widget:filters:-sort
| Specifies the columns to sort the results on. E.g. widget:filters:-sort=category_name asc, year desc
| 1.0
|-
| widget:filters:*
| Any valid Xataface directive can be used to filter the results by specifying widget:filters:param (where ""param"" is a valid Xataface GET parameter, which could include a column name to filter results on, or other filter directives). widget:filters:country=Canada To only show results with Country=Canada.
| 1.0
|-
| widget:filters:*=$*
| Dynamic filters. Causes the options in the record browser to be filtered on the value of another field in the form. e.g. widget:filters:country_id=""$country_id"" would show only results with records having country_id matching the value of the 'country_id' field in the current form.
| 1.3.1
|}
See [[URL Conventions]] for an overview of the types of GET parameters Xataface can take. Any GET parameters that manipulate a query can be used with the widget:filters:* directive to modify the query results that are shown in the lookup widget.
===Example===
In this example we have a field named appointee that is supposed to reference the contacts table. So in the [[fields.ini file]] we would have:
[appointee]
widget:type=lookup
widget:table=contacts
Initially we just have a little find icon next to the field. If the user clicks it, a dialog pops up enabling them to search for the contact that they want:
[[Image:http://media.weblite.ca/files/photos/Picture%2023.png?max_width=640]]
===Additional Tips===
Although the lookup widget does not use a vocabulary as indicated in the Synopsis above, it is still useful to define a vocabulary in the fields.ini file for this field. The reason is because the lookup widget is only used with the edit action, where you are inserting or editing data into the field. However, it is not used to the display the data in the view or list actions. Therefore, you must still have a vocabulary defined to properly display these values.
In order to customize the display of the lookup widget's select list, you must edit the delegate class for the table which is referenced by the widget:table directive. There are two important points to note:
# The items in the selection list are formatted based on the getTitle(&$record) delegate class function if it is defined. However, ...
# The Search box will search on text in VARCHAR and TEXT fields. If you need to search for data in numeric fields, you can create a grafted field using a function such as CONCAT() to display numbers as text.
Links:
* [http://xataface.com/forum/viewtopic.php?f=4&t=6723 Lookup widget on view with compound primary key]","lookup widget, widget:filters, widget:-filters:limit, widget:table",en,0
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 :
class tables_journal_interventions {
function css__tableRowClass(&$record){
if ( !$record->val('fermeture')){
return 'intervention_close';
}
else return '';
}
}
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.
td.intervention_close {
background-color: #FFE6E6 !important;
}
This is a class for each cell, the 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 tag, so it is probably better to write:
tr.intervention_close td {
background-color: #FFE6E6;
}
i.e. to apply the background color to the individual cells. ",,en,0
How_to_granulate_permissions_on_each_field,63,How_to_granulate_permissions_on_each_field,"==How to granulate permissions on each field==
To reach this aim, there is the method fieldname__permissions to place into the delegate class of the table.
===Getting the role===
First it is necessary to know the user's role. For this, the method getUser() is added in the class :
function getUser(&$record){
$auth =& Dataface_AuthenticationTool::getInstance();
$user =& $auth->getLoggedInUser();
return $user;
}
===Setting up the permissions for each field===
Next, the permissions are built for each column or field where they are needed, like in this example where the method name is formed with the field name, followed by 2 underscores then by ''permissions'' :
function fieldname__permissions(&$record){
$the_user =$this->getUser($record);
$user=$the_user->val('identifiant');
if ( !$user) return Dataface_PermissionsTool::NO_ACCESS();
if ( $user=='demande' ){
return Dataface_PermissionsTool::ALL();
} elseif ($user=='admin'){
return Dataface_PermissionsTool::ALL();
}
else {
return Dataface_PermissionsTool::READ_ONLY();
}
}
=== Also See ===
* [[viewable_editable_fields]] - How to make a field editable for some users and only viewable for some other users
* [[no_access_text]] - Replace the default NO ACCESS permission text with another text.
* [[__field__permissions]] - Returns the default permissions for a field of a given record.
* [[Delegate_class_methods#toc5|Permissions]] - other Delegate class methods",,en,0
LDAP_or_Active_Directory,65,"How to authenticate users with LDAP or Active Directory","[[toc]]
It is often easier to use the existing LDAP or Active Directory to authenticate users in Xataface than to create a new password for every user in the table users.
===In the conf.ini===
In the conf.ini file, in the [auth] part, you need to add your LDAP or AD configuration data :
[_auth]
auth_type=ldap
users_table = xata_users
username_column = id
ldap_host = ""xxx.xxx.xxx.xxx""
ldap_port = ""389""
ldap_base = ""OU=blabla,DC=blablabla""
Here in the table users, you need the login but the password can be just ''PASS'', because the password will be fetched into the LDAP base.
You need to add the [http://weblite.ca/svn/dataface/modules/Auth/ldap/trunk/ auth module] in the conf/modules directory.
===See Also===
* [[authentication]] - Overview of Authenthentication features in Xataface","LDAP,Active Directory,Authentication",en,0
How_to_authenticate_users_with_LDAP_or_Active_Directory,64,How_to_authenticate_users_with_LDAP_or_Active_Directory,"==How to authenticate users with LDAP or Active Directory==
",,en,0
table,66,table,"When using widget:type table, it will store the data as XML.
So the field type must be TEXT (or varchar... but text is better). You can decide which columns you want in the table by creating sub-fields in your fields.ini file as follows:
Suppose you want a column called 'name' and a column called 'url'
[myfield]
widget:type=table
[myfield:name]
[myfield:url]
Now when you access the stored value using the Dataface API, the value of myfield will be stored as an array of associative arrays. e.g.
foreach ( $record->val('myfield') as $vals){ echo $vals['name'].' -- '.$vals['url']; }
",,en,0
grid,67,grid,"==widget:type = grid==
Suppose we have two tables, tbl_organisation and tbl_individuals, in the edit view for a record in the organisations table (tbl_organisations) we also want to be able to view and edit the individuals within this organisation we can use widget:type=grid
In the /tables/tbl_organisation/fields.ini we create a transient field by adding:
[Individuals]
widget:label = ""Individuals""
transient=1
relationship=individuals
widget:type=grid
widget:columns=""ind_firstname,ind_lastname,ind_tel""
The above assumes we have a relationship entry in our /tables/tbl_organisation/relationships.ini that looks like this:
[individuals]
__sql__ = ""SELECT * FROM tbl_individual WHERE org_id='$org_id'""
The fields.ini will show the three columns shown in widget:columns from the table tbl_individual
Correct permissions need to be set to enable editing and deletion etc of these records.",,en,0
relationship,68,"The relationship fields.ini directive","[[fields.ini file|Return to fields.ini file directives]]
[[toc]]
===Synopsis===
Certain types of widgets (e.g. grid (v1.0) and checkbox (v1.2)) support the relationship directive which allows them to effectively add/remove records from a specified relationship. This directive only works with transient fields.
===Example 1: Checkboxes to add/remove categories===
(Note: This example requires Xataface 1.2 or higher to work)
Suppose we have a database that keeps track of courses and the branch of research that they belong to. A course can be part of multiple branches. We want to be able to select the branches that a particular course belongs to on the edit form for that course using checkboxes.
Table Structure:
courses:
course_id : int (primary key)
course_title : varchar
branches:
branch_id : int (primary key)
branch_name : varchar
branch_description: text
course_branches:
course_id : int
branch_id : int
Relationship definition: (from the tables/courses/[[relationships.ini file]]):
[branches]
course_branches.course_id=""$course_id""
course_branches.branch_id=branches.branch_id
Field definitions: (from tables/courses/[[fields.ini file]]):
[branches]
transient=1
relationship=branches
widget:type=checkbox
Things to notice:
# This is a many-to-many relationship (hence the need for the course_branches join table.
# The [branches] field is a transient field.
# The relationship directive from the [[fields.ini file]] references our branches relationship that was defined in the [[relationships.ini file]].
# You can call the field anything that you like. There is no need for it to have the same name as the relationship. It just turned out that way in this example.
===Example 2: Using a grid widget===
Let's modify example 1 slightly to use a grid widget instead of checkboxes. The grid widget will allow us edit the records in a relationship using dynamic table. It automatically uses the correct widget for each column of the table according to the definition in the target table's [[fields.ini file]]. Most of the definition can remain the same. We only change the [[fields.ini file]] directive:
[branches]
transient=1
relationship=branches
widget:type=grid
widget:columns=""branch_name,branch_description""
In this case we are able to edit the branch name and description in each row of the grid.
===See Also===
* [[grid|The grid widget]]
* [[checkbox|The checkbox widget]]
* [[relationships.ini file|The relationships.ini file]]
* [[fields.ini file|The fields.ini file]]","grid widget, relationship, checkbox",en,0
checkbox,69,checkbox,"==The checkbox widget==
In the [[fields.ini file]] you can specify a field to be edited using a checkbox widget by setting [[widget:type]] to [[checkbox]]. A checkbox widget can function in 2 different ways depending on the parameters that you assign to the field.
[[toc]]
===Example 1: A TinyInt (boolean) field===
Suppose our table has a tinyint field named ""Active"" which specifies whether the record is currently in use. This field will store a value of either 0 or 1. So we configure this field in our [[fields.ini]] file to use a checkbox widget as follows:
[Active]
widget:type=checkbox
Results:
[[Image:http://media.weblite.ca/files/photos/Picture%2024.png?max_width=640]]
===Example 2: A repeating field (multiple checkboxes for one field===
Checkboxes can store multiple values in a single field by setting the [[vocabulary]] directive and applying it to a varchar or text field. In this case there will be one value saved per line.
In this example, suppose we have a varchar field named '''categories''' which uses the '''categories''' [[valuelist]] to specify the different categories that can be checked at any given time. Our [[valuelists.ini file]] might look like:
[categories]
__sql__ = ""select id,name from categories""
And our [[fields.ini file]] looks like:
[categories]
widget:type=checkbox
vocabulary=categories
* Note that you don't need to name the field the same as the valuelist. It just worked out this way.
Now if we save a record with categories 1, 3, and 5 checked, then the categories column of our row in the database will store something like:
1
3
5
i.e. one category id per line. Note that using this method, your database will not be normalized because you are storing multiple values in a single field. However in many applications this is sufficient.
Results:
[[Image:http://media.weblite.ca/files/photos/Picture%2025.png?max_width=640]]
===Example 3: Using a ""Categories"" relationship===
""""""(Note: This example requires Xataface version 1.2 or higher)""""""
Example 2 above shows how we can easily add and remove a record from multiple categories using checkboxes. However it required multiple pieces of information to be stored in a single database field which may or may not be advantageous for your database design. If you're looking for a more normalized database schema you would probably design your database as follows for this case:
# Books table - Stores all of the books.
# Categories table - Stores all of the categories
# Book_Categories table - Stores mapping of books to categories.
With out table structure we will first want to define a relationship from Books to Categories to reflect the connection between books and categories. The [[relationships.ini file]] for this might look like:
[categories]
Books.Book_ID=""$Book_ID""
Book_Categories.Category_ID=Categories.Category_ID
And our [[fields.ini file]] for the Books table might look like:
[categories]
widget:type=checkbox
transient=1
relationship=categories
* Note that there is no need for our field to be named the same as our relationship. It just turned out this way. Also note that we used the transient=1 flag here because the Books table no longer has a categories field in the database. This field is defined purely for the benefit of the edit form so that we will get a checkbox group to select the book's categories.
Results:
[[Image:http://media.weblite.ca/files/photos/Picture%2025.png?max_width=640]]
==Related Parameters==
# [[vocabulary]] - Assigns a valuelist to be used as the options for this checkbox group.
# [[repeat]] - A boolean value indicating whether this field should be treated as a 'repeating field'. A repeating field is one with multiple checkboxes. By default the checkbox widget operates as a single checkbox that controls a boolean value.
# [[relationship]] - (Only applicable to [[transient]] fields). If the [[relationship]] directive is set then this field can be used to add/remove records from a relationship.",,en,0