The API of available methods that can be defined in a table delegate class. More...

Initialization
	init (Dataface_Table $table)
	Called after a table is loaded for the first time each request.
	getDelegate ()
	Returns an alternate object to be used as the delegate. This is handy for module developers to allow application developers to override module-defined delegates with application-defined delegates.

Permissions
	getPermissions (Dataface_Record $record)
	Returns associative array of permissions that should be granted to the current user on this record.
	getRoles (Dataface_Record $record)
	Returns one or more roles that are to be granted to the current user for the specified record.
	__field__permissions (Dataface_Record $record)
	Returns default permissions for all fields of the given record to be granted to the current user.
	__field__roles (Dataface_Record $record)
	Returns the roles for all fields of the given record to be granted to the current user.
	fieldname__permissions (Dataface_Record $record)
	Returns the permissions for a particular field of the given record.
	fieldname__roles (Dataface_Record $record)
	Returns the roles for a particular field of the given record.
	rel_relationshipname__permissions (Dataface_Record $record)
	Returns the permissions for a particular relationship of the given record.
	rel_relationshipname__roles (Dataface_Record $record)
	Returns the roles for a particular relationship of the given record.
	no_access_link (Dataface_Record $record, $params=array())
	Returns the link that should be returned by Dataface_Record::getURL() if the user isn't granted the 'link' permission on the given record.
	no_access_text (Dataface_Record $record, $params=array())
	Returns the text that should be returned by Dataface_Record::display() if the user doesn't have 'view' permission for the record.

Record Metadata
	getTitle (Dataface_Record $record)
	Returns the record's title. This is used in Xataface to return the title of a record when the Dataface_Record has been loaded into memory already. It returns a string that can be used as the title of a record and takes a Dataface_Record object as a parameter - hence it can draw on any information in the record to form the effective title.
	titleColumn ()
	Returns an SQL expression (that is valid for a column in a select clause) denoting the column(s) that comprise the title of records in this table. This may return a single column name or it may make use of SQL functions like CONCAT() to compose a title from multiple columns.
	getURL (Dataface_Record $record, $params=array())
	Returns the URL of the given record.
	getLastModified (Dataface_Record $record)
	Returns the Unix timestamp representing the last modification time of the given record.
	getDescription (Dataface_Record $record)
	Returns a brief description of this record for use in lists, RSS feeds, and more.
	getCreator (Dataface_Record $record)
	Returns the name of the user who created this record (i.e. the record author).
	getPublicLink (Dataface_Record $record)
	Returns the publicly accessible URL for a given record.
	getBreadCrumbs (Dataface_Record $record)
	Returns the breadcrumbs to a given record.
	getChildren (Dataface_Record $record)
	Returns the records that are considered to be children of the given record.

Field Filters
	fieldname__display (Dataface_Record $record)
	Overrides the display of the specified field name for the given record.
	fieldname__format ($value)
	Formats the output value of a particular field. In constrast to fieldname__display() this does not take the Dataface_Record as a parameter. As such it can be used to format arbitrary values in a consistent way. If you don't need information from the record when formatting a value for display, it is preferred to use this method since it is more generic.
	fieldname__toString (Dataface_Record $record)
	Overrides the string value of specified field for a given record.
	fieldname__htmlValue (Dataface_Record $record)
	Overrides the HTML display value of a field for a given record.
	fieldname__parse ($value)
	Overrides the parsing behavior for normalizing a field value. This will dictate how values are transformed when being added to the record via setValue()
	fieldname__serialize ($value)
	Serializes a field value to prepare it for insertion into an SQL query.
	fieldname__default ()
	Returns the default value for a specified field when new records are inserted.
	fieldname__link (Dataface_Record $record)
	Provides a link to obtain more information about a field on the edit form.
	fieldname__pushValue (Dataface_Record $record, HTML_QuickForm_element $el)
	Retrieves the field value from a form widget in a format that can be inserted into a record using the Dataface_Record::setValue() method.
	fieldname__pullValue (Dataface_Record $record, HTML_QuickForm_element $el)
	Retrieves the value for a field from a record in a format that can be set in a form widget.

Calculated Fields
	field__fieldname (Dataface_Record $record)
	Defines a calculated field that can be used just like any other field in the table.

Record Triggers
	beforeSave (Dataface_Record $record)
	Trigger called before a record is saved.
	afterSave (Dataface_Record $record)
	Trigger called after a record is saved.
	beforeInsert (Dataface_Record $record)
	Trigger called before a record is inserted into the database for the first time.
	afterInsert (Dataface_Record $record)
	Trigger called after a record is inserted into the database for the first time.
	beforeUpdate (Dataface_Record $record)
	Trigger called before a record is updated.
	afterUpdate (Dataface_Record $record)
	Trigger called after a record is updated.
	beforeDelete (Dataface_Record $record)
	Trigger called before a record is deleted.
	afterDelete (Dataface_Record $record)
	Trigger called after a record is deleted.
	beforeAddExistingRelatedRecord (Dataface_RelatedRecord $record)
	Trigger called before an "existing" related record is added to a relationship.
	afterAddExistingRelatedRecord (Dataface_RelatedRecord $record)
	Trigger called after an "existing" related record is added to a relationship.
	beforeAddNewRelatedRecord (Dataface_RelatedRecord $record)
	Trigger called before a "new" related record is added to a relationship.
	afterAddNewRelatedRecord (Dataface_RelatedRecord $record)
	Trigger called after a "new" related record is added to a relationship.
	beforeAddRelatedRecord (Dataface_RelatedRecord $record)
	Trigger called before a related record is added to a relationship (either new or existing).
	afterAddRelatedRecord (Dataface_RelatedRecord $record)
	Trigger called after a related record is added to a relationship (either new or existing).
	beforeRemoveRelatedRecord (Dataface_RelatedRecord $record)
	Trigger called after a related record is removed from a relationship.
	afterRemoveRelatedRecord (Dataface_RelatedRecord $record)
	Trigger called after a related record is removed from a relationship.
	afterCopy (Dataface_Record $original, Dataface_Record $copy)
	Trigger called after a record is copied.

Action Triggers
	after_action_edit ($params=array())
	Trigger fired after the 'edit' action has completed successfully.
	after_action_new ($params=array())
	Trigger fired after the 'new' action has completed successfully.
	after_action_delete ()
	Trigger fired after the 'delete' action has completed successfully.

Template Customization
	block__blockname (array $params=array())
	Fills a block or slot in a template when operating in the context of the delegate class's table.
	getSearchTarget (array $action)
	Returns the name of an action that should be used as the target action of a search performed from the current context. In past releases searches would always go to the list action. This gives you the ability to override this behavior with your own custom action depending on the circumstances.

List Tab Cutomization
	css__tableHeaderCellClass ($colname)
	Returns a CSS class to be added to the table header cell (th tag) for a specified column of the table in list view.
	css__tableRowClass (Dataface_Record $record)
	Returns a CSS class to be added to the table row (tr tag) for the specified record in list view.
	fieldname__renderCell (Dataface_Record $record)
	Overrides the display of a table cell for a field in list view.
	renderRow (Dataface_Record $record)
	Overrides the display of a table row in list view.
	renderRowHeader (Dataface_Record $record)
	Overrides the headings row for the list view table.

View Tab Customization
	section__sectionname (Dataface_Record $record)
	Defines a new section on the view tab.

Full-text Search
	getSearchableText (Dataface_Record $record)
	Returns the indexable text to be used for the full-text site search feature.

RSS Feed Customization
	getFeedItem (Dataface_Record $record)
	Returns a data structure with the contents to be included in the RSS feed.
	getFeed (array $query)
	Returns data structure with settings for the RSS feed as a whole.
	getFeedSource (array $query)
	Returns the source URL for the RSS feed that is generated by the given query.
	getRelatedFeed (Dataface_Record $record, $relationship)
	Returns details about a feed of related records. This overrides the feed details for related feeds.
	getRSSDescription (Dataface_Record $record)
	Overrides the description or body of a record as it is displayed in an RSS feed.

XML Output Customization
	toXML (Dataface_Record $record)
	Overrides the XML output of a record as it would appear in Xataface's export_xml action.
	getXMLHead (Dataface_Record $record)
	Returns XML content to be included at the beginning of the XML representation of this record.
	xmlTail (Dataface_Record $record)
	Returns XML content to be included at the end of the XML representation of this record.

Valuelist Customization
	valuelist__valuelistname ()
	Defines a valuelist on the table.

Importing Records
	__import__filtername ($data, array $defaults)
	Defines an import filter that can be used to import records into the table.

Table Settings
	__sql__ ()
	Defines an SQL query that should be used for loading data from this table.

Form Validation
	fieldname__validate (Dataface_Record $record, $value, array &$params)
	Validates form input for a field.

Detailed Description

The API of available methods that can be defined in a table delegate class.

Since: 0.1

Author: Steve Hannah steve.nosp@m.@web.nosp@m.lite..nosp@m.ca

Function Documentation

__field__permissions ( Dataface_Record $record )

Returns default permissions for all fields of the given record to be granted to the current user.

Parameters

Dataface_Record $record The record that is subject of these permissions.

Returns: array Associative array of permissions granted. Keys are permission names as defined in the permissions.ini file and corresponding values are either 0 or 1 depending on whether the permission is granted or not.

Since: 1.0

Synopsis

Implementing the fieldpermissions() method in your delegate class allows you to define the default permissions that should be applied to each field of the table.

Setting field defaults can be important if you want, for example, only certain fields to be editable, but all other fields to be read only. In such a case you would need to set the record-level permissions to allow editing (in order for users to even access the 'edit' action), then set the default field permissions to read only using the fieldpermissions() method, then set the permissions of only the editable fields to be editable by implementing fieldname__permissions() methods for each of those fields.

Attention: Field level permissions, like those returned by this method are treated as permission masks that are overlaid over the record permissions. Therefore if roles returned by this method do not explicitly disallow a permission, then the record-level permissions will be used for that permission.

Flowchart

The following flowchart shows the flow of control Xataface uses to determine the field-level permissions for a field in a record.

Click here to enlarge

Examples

Consider the following table 'people':

CREATE TABLE `people` (
   `person_id` INT(11)  NOT NULL AUTO_INCREMENT PRIMARY KEY,
   `username` VARCHAR(32) NOT NULL,
   `full_name` VARCHAR(100),
   `email` VARCHAR(100),
   `bio` TEXT,
   `admin_comments' TEXT
)

And our application is using the following 'users' table to store our user accounts.

CREATE TABLE `users` (
    `username` VARCHAR(32) NOT NULL PRIMARY_KEY,
    `password` VARCHAR(32),
    `role` ENUM('USER','ADMIN') default 'USER'
)

And let's assume that we intend for the people.username field to represent the username of the user who "owns" the people record. (i.e. it has an implicit foreign key to users.username.

Now, suppose we want to implement the following permission structure:

Admin users have full access
Regular users can edit the bio field of their own people record, but can only view the other fields - Except they cannot view the admin_comments field.
Regular users cannot view any information in records they do not own.

Step 2: Default Field-level Permissions

In tables/people/people.php:

function getPermissions($record){
    $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
    if ( $user and $user->val('role') == 'ADMIN' ){
        // ADMIN users get full access
        return Dataface_PermissionsTool::ALL();
    } else if ( $record and $user and $user->val('username') == $record->val('username') ){
        // Regular users get edit permissions to their own people record.
        return Dataface_PermissionsTool::getRolePermissions('EDIT');
    } else {
        // All other users get no access to this record.
        return Dataface_PermissionsTool::NO_ACCESS();
    }
}

In this getPermissions() method we define 3 levels of users:

Administrative users who have full access
Non-administrative users who own the current record who have edit access.
All other users who have no access.

Things to notice here:

Before calling any methods on $record, we needed to verify that it was not null, because this getPermissions() method will be called with null passed as the context record by Xataface.
We make use of the Dataface_PermissionsTool::getRolePermissions() method to return the edit permissions for the owner users. This makes use of the permissions.ini file which defines a role called "EDIT" which includes all permissions relevant to editing records (it also includes all permissions necessary for viewing records).

Step 2: Default Field-level Permissions

If we only implemented the getPermissions() method as above, record "owners" would be able to view and edit all fields in their own people record. In fact we only want them to be able to edit the "bio" field, and we don't want them to be able to see the admin_comments field.

We implement the fieldpermissions() method to limit their access to these fields:

Also in the tables/people/people.php file:

function __field__permissions($record){
    $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
    if ( $user and $user->val('role') == 'ADMIN' ){
        // Defer to record-level permissions for ADMIN users ... we have nothing
        // to add here
        return null;
    } else if ( $user and $record and $user->val('username') == $record->val('username') ){
        // We want to make all fields read only - no editing
        return array('edit'=>0, 'new'=>0);
    } 
    // For all other situations just defer to the record level permissions
    return null;
}

In this fieldpermissions() method we first defer admin users to their normal record level permissions because we don't wish to modify their permissions in any way at the field level (they can already do everything and that's how we like it).

For users who own a record, we return permissions array that explicitly disallows only those permissions that we want to disallow. Notice that it wouldn't be sufficient here to return Dataface_PermissionsTool::READ_ONLY() because that would return only an array of the permissions that the user is explicitly allowed - and since the result of this method is simply overlaid on top of the record level permissions it wouldn't cause any permissions granted at that level to be overridden. Hence we need to explicitly disallow the permissions here.

Another way to do this might be to start with a base of Dataface_PermissionsTool::NO_ACCESS() and then simply set 'view' = 1. However this would disallow some other 'view-ish' permissions that you may have wanted.

Step 3: Make the BIO field editable for Record Owner

In tables/people/people.php:

function bio__permissions($record){
    $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
    if ( $user and $user->val('role') == 'ADMIN' ){
        // Defer to default field-level permissions for ADMIN users ... we have nothing
        // to add here
        return null;
    } else if ( $user and $record and $user->val('username') == $record->val('username') ){
        // We want to make the bio field editable
        return array('edit'=>1);
    } 
    // For all other situations just defer to the default field-level permissions
    return null;
}

This looks almost the same as our fieldpermissions() method except that we are allowing the edit permission on the field for record owners.

Step 4: Hide the admin_comments field from record owners

At this point we have almost everything the way we want it except that record owners can still see the admin comments field - but we want this to be private for administrators.

So we implement the admin_comments__permissions() method:

function admin_comments__permissions($record){
    $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
    if ( $user and $user->val('role') == 'ADMIN' ){
        // Defer to default field-level permissions for ADMIN users ... we have nothing
        // to add here
        return null;
    } else if ( $user and $record and $user->val('username') == $record->val('username') ){
        // Hide the field from record owners
        return Dataface_PermissionsTool::NO_ACCESS();
    } 
    // For all other situations just defer to the default field-level permissions
    return null;
}

See Also: getPermissions(); fieldroles(); fieldname__roles(); http://xataface.com/documentation/tutorial/getting_started/permissions; http://xataface.com/wiki/permissions.ini_file; ApplicationDelegateClass::fieldpermissions()

__field__roles ( Dataface_Record $record )

Returns the roles for all fields of the given record to be granted to the current user.

Parameters

Dataface_Record $record The record that is subject of this query.

Returns: mixed Either a string with a single role or an array of strings representing roles that are assigned to the current user on the fields of this record. May also return null to indicate that the results of this method should be ignored in favor of permissions returned higher up the chain.

Since: 1.0

Flowchart

The following flowchart shows the flow of control Xataface uses to determine the field-level permissions for a field in a record.

Click here to enlarge

See Also: fieldpermissions(); getPermissions(); getRoles(); fieldname__roles(); fieldname__permissions(); Dataface_PermissionTool; http://xataface.com/documentation/tutorial/getting_started/permissions; http://xataface.com/wiki/permissions.ini_file

__import__filtername	(		$data,
		array	$defaults
	)

Defines an import filter that can be used to import records into the table.

Parameters

string	$data	The input data that the user has uploaded. This may be in any format - you need to parse it.
array	$defaults	The default values that should be inserted into the fields of the newly inserted records if the import doesn't explicitly specify the values to insert.

Returns: array An array of Dataface_Record objects to be inserted.

Since: 0.6

See Also: http://xataface.com/documentation/how-to/import_filters; Dataface_IO::importData()

__sql__ ( )

Defines an SQL query that should be used for loading data from this table.

Returns: string The SQL query that should be used for loading data from this table.

Since: 0.8

See Also: http://www.xataface.com/wiki/sql_delegate_method

after_action_delete ( )

Trigger fired after the 'delete' action has completed successfully.

Parameters

array Associative array of context variables including 'record' which is the Dataface_Record that was just deleted.

Since: 1.0

See Also: dataface_actions_delete

after_action_edit ( $params = array() )

Trigger fired after the 'edit' action has completed successfully.

Parameters

array $params Some context parameters. This includes a the key 'record' which refers to the Dataface_Record object that was just successfully edited and saved.

Since: 0.8

See Also: dataface_actions_edit

after_action_new ( $params = array() )

Trigger fired after the 'new' action has completed successfully.

Parameters

array Associative array of context variables including 'record' which is the Dataface_Record that was just inserted.

Since: 0.8

See Also: dataface_actions_new

afterAddExistingRelatedRecord ( Dataface_RelatedRecord $record )

Trigger called after an "existing" related record is added to a relationship.

Parameters

Dataface_RelatedRecord $record The related record that was added.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.7

See Also: beforeAddExistingRelatedRecord(); afterAddNewRelatedRecord(); afterAddRelatedRecord(); Dataface_IO::addExistingRelatedRecord()

afterAddNewRelatedRecord ( Dataface_RelatedRecord $record )

Trigger called after a "new" related record is added to a relationship.

Parameters

Dataface_RelatedRecord $record The related record that was added.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.7

See Also: beforeAddNewRelatedRecord(); afterAddExistingRelatedRecord(); afterAddRelatedRecord(); Dataface_IO::addRelatedRecord()

afterAddRelatedRecord ( Dataface_RelatedRecord $record )

Trigger called after a related record is added to a relationship (either new or existing).

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.7

See Also: beforeAddRelatedRecord(); afterAddExistingRelatedRecord(); afterAddNewRelatedRecord(); Dataface_IO::addRelatedRecord(); Dataface_IO::addExistingRelatedRecord()

afterCopy	(	Dataface_Record	$original,
		Dataface_Record	$copy
	)

Trigger called after a record is copied.

Parameters

Dataface_Record	$original	The original record.
Dataface_Record	$copy	The copied record.

Since: 1.3

See Also: Dataface_IO::copy()

afterDelete ( Dataface_Record $record )

Trigger called after a record is deleted.

Parameters

Dataface_Record $record The record that was deleted.

Returns: mixed PEAR_Error object if there is a problem.

Since: 1.0

See Also: beforeDelete(); Dataface_IO::delete(); Dataface_Record::delete()

afterInsert ( Dataface_Record $record )

Trigger called after a record is inserted into the database for the first time.

Parameters

Dataface_Record $record The record that is being inserted.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.5

See Also: beforeInsert(); Dataface_IO::insert(); Dataface_Record::save()

afterRemoveRelatedRecord ( Dataface_RelatedRecord $record )

Trigger called after a related record is removed from a relationship.

Parameters

Dataface_RelatedRecord $record The related record that has been removed.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.7

See Also: beforeRemoveRelatedRecord(); Dataface_IO::removeRelatedRecord()

afterSave ( Dataface_Record $record )

Trigger called after a record is saved.

Parameters

Dataface_Record $record The record that was saved.

Returns: mixed PEAR_Error object If there is a problem.

Since: 0.5

See Also: Dataface_IO::write(); Dataface_Record::save(); beforeSave()

afterUpdate ( Dataface_Record $record )

Trigger called after a record is updated.

Parameters

Dataface_Record $record

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.5

See Also: beforeUpdate(); afterInsert(); afterSave(); Dataface_Record::save(); Dataface_IO::update()

beforeAddExistingRelatedRecord ( Dataface_RelatedRecord $record )

Trigger called before an "existing" related record is added to a relationship.

Parameters

Dataface_RelatedRecord $record The related record that is being added.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.7

See Also: afterAddExistingRelatedRecord(); beforeAddNewRelatedRecord(); beforeAddRelatedRecord(); Dataface_IO::addExistingRelatedRecord()

beforeAddNewRelatedRecord ( Dataface_RelatedRecord $record )

Trigger called before a "new" related record is added to a relationship.

Parameters

Dataface_RelatedRecord $record The related record that is being added to a relationship.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.7

See Also: afterAddNewRelatedRecord(); beforeAddExistingRelatedRecord(); beforeAddRelatedRecord(); Dataface_IO::addRelatedRecord()

beforeAddRelatedRecord ( Dataface_RelatedRecord $record )

Trigger called before a related record is added to a relationship (either new or existing).

Parameters

Dataface_RelatedRecord $record The record that is being added.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.8

See Also: afterAddRelatedRecord(); beforeAddNewRelatedRecord(); beforeAddExistingRelatedRecord(); Dataface_IO::addRelatedRecord(); Dataface_IO::addExistingRelatedRecord()

beforeDelete ( Dataface_Record $record )

Trigger called before a record is deleted.

Parameters

Dataface_Record $record The record that is being deleted.

Returns: mixed PEAR_Error object if there is a problem.

Since: 1.0

See Also: afterDelete(); Dataface_Record::delete(); Dataface_IO::delete()

beforeInsert ( Dataface_Record $record )

Trigger called before a record is inserted into the database for the first time.

Parameters

Dataface_Record $record The record that is being inserted.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.5

See Also: Dataface_IO::insert(); Dataface_Record::save(); afterInsert()

beforeRemoveRelatedRecord ( Dataface_RelatedRecord $record )

Trigger called after a related record is removed from a relationship.

Parameters

Dataface_RelatedRecord $record The related record that is being removed.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.7

See Also: afterRemoveRelatedRecord(); Dataface_IO::removeRelatedRecord()

beforeSave ( Dataface_Record $record )

Trigger called before a record is saved.

Parameters

Dataface_Record $record The record being saved.

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.5

See Also: Dataface_IO::write(); Dataface_Record::save(); afterSave()

beforeUpdate ( Dataface_Record $record )

Trigger called before a record is updated.

Parameters

Dataface_Record $record

Returns: mixed PEAR_Error object if there is a problem.

Since: 0.5

See Also: afterUpdate(); beforeInsert(); beforeSave(); Dataface_IO::update(); Dataface_Record::save()

block__blockname ( array $params = array() )

Fills a block or slot in a template when operating in the context of the delegate class's table.

Parameters

array $params Associative array of key-value pairs passed to the block containing context information.

Returns: void This method does not return anything. It should print or echo content to the output stream.

Since: 0.6

See Also: Dataface_SkinTool; df_display(); Dataface_SkinTool::block(); Dataface_SkinTool::display()

css__tableHeaderCellClass ( $colname )

Returns a CSS class to be added to the table header cell (th tag) for a specified column of the table in list view.

Parameters

string $colname The name of the table column.

Returns: string CSS classes (separated by spaces).

Since: 2.0alpha2

css__tableRowClass ( Dataface_Record $record )

Returns a CSS class to be added to the table row (tr tag) for the specified record in list view.

Parameters

Dataface_Record $record The subject record.

Returns: string CSS classes (separated by spaces).

Since: 1.2

field__fieldname ( Dataface_Record $record )

Defines a calculated field that can be used just like any other field in the table.

Parameters

Dataface_Record $record The subject record.

Returns: mixed The field value. This may be any data type, including a data structure.

See Also: Dataface_Record::getValue()

fieldname__default ( )

Returns the default value for a specified field when new records are inserted.

Returns: string The default value.

Since: 0.6

fieldname__display ( Dataface_Record $record )

Overrides the display of the specified field name for the given record.

Parameters

Dataface_Record $record The record whose data is to be displayed.

Returns: string The string field contents prepared for print.

Since: 0.5

Attention: Do not return HTML tags in this method, as they will be escaped by Xataface. If you wish to override the HTML output of a record, implement the fieldname__htmlValue() method instead.

Note: If your output doesn't depend on anything but the string value of fieldname then it is preferred to implement the fieldname__format() method.

See Also: Dataface_Record::display()

fieldname__format ( $value )

Formats the output value of a particular field. In constrast to fieldname__display() this does not take the Dataface_Record as a parameter. As such it can be used to format arbitrary values in a consistent way. If you don't need information from the record when formatting a value for display, it is preferred to use this method since it is more generic.

Parameters

string $value The value that is to be formatted.

Returns: string The formatted value.

Since: 1.4

See Also: Dataface_Table::format()

fieldname__htmlValue ( Dataface_Record $record )

Overrides the HTML display value of a field for a given record.

Parameters

Dataface_Record $record The subject record.

Returns: string The HTML representation of the specified field value.

See Also: Dataface_Record::htmlValue()

fieldname__link ( Dataface_Record $record )

Provides a link to obtain more information about a field on the edit form.

Parameters

Dataface_Record $record The subject record.

Returns: string The link

Since: 0.6

See Also: Dataface_Record::getLink()

fieldname__parse ( $value )

Overrides the parsing behavior for normalizing a field value. This will dictate how values are transformed when being added to the record via setValue()

Parameters

mixed $value The input value.

Returns: mixed The normalized value ready to store in the record (not in the database) but in the record. i.e. this can be a data strucure - it doesn't have to be a string.

Since: 0.5

Synopsis

When Dataface_Record::setValue() is called to set the value in a field, it first tries to parse and normalize the value. Xataface has built-in parsers that work according to the type of column. However you may wish to write your own parser by implementing this method.

Invariants

1: Idempotent

Any fieldname__parse() implementations must be idempotent. I.e. it must be the case that fieldname__parse(fieldname__parse($val)) == fieldname__parse($val)

This is because we need to be able to set values in fields without worrying about the value being modified by the simple act of setting the field value.

2: Inverse of fieldname__toString()

Since the fieldname__toString() method, if implemented, would be used to produce the value that is displayed in form widgets, the fieldname__parse() method must be able to handle the result of fieldname__toString() and be able to normalize it since it is effectively the inverse operation of fieldname__toString().

See Also: fieldname__toString(); Dataface_Record::setValue(); Dataface_Record::getValue()

fieldname__permissions ( Dataface_Record $record )

Returns the permissions for a particular field of the given record.

Parameters

Dataface_Record $record The record that is subject of this query.

Returns: mixed Either an associative array of permissions or null to defer permissions to the default field permissions or record-level permissions.

Since: 0.7

Synopsis

This method can be implemented to define fine-grained permissions on a particular field of the database. It can be helpful if you want to override the record-level permissions (getPermissions() or the default field permissions ( fieldpermissions() ) with specific permissions for this field. See the flowchart below for details of how field-level permissions are resolved in Xataface.

Attention: Field level permissions are treated as a mask that is laid over the record permissions for that field. Therefore, to disallow a permission on a field that is otherwise allowed at the record level, you must explicitly return a permission of 0 - i.e. you can't just omit the permission as you can at the record level.

Flowchart

The following flowchart shows the flow of control Xataface uses to determine the field-level permissions for a field in a record.

Click here to enlarge

Examples

Please see the documentation for fieldexamples() for a thorough example of how to define fine-grained field-level permissions using this method.

See Also: fieldpermissions(); getPermissions(); getRoles(); fieldname__roles(); fieldname__permissions(); Dataface_PermissionTool; http://xataface.com/documentation/tutorial/getting_started/permissions; http://xataface.com/wiki/permissions.ini_file

fieldname__pullValue	(	Dataface_Record	$record,
		HTML_QuickForm_element	$el
	)

Retrieves the value for a field from a record in a format that can be set in a form widget.

Parameters

Dataface_Record	$record	The record from which the field value is being pulled.
HTML_QuickForm_element	$el	The form element for which the form value should be formatted.

Returns: mixed The field value ready to be set as the value in $el.

Since: 0.6

See Also: HTML_QuickForm; fieldname__pushValue()

fieldname__pushValue	(	Dataface_Record	$record,
		HTML_QuickForm_element	$el
	)

Retrieves the field value from a form widget in a format that can be inserted into a record using the Dataface_Record::setValue() method.

Returns: mixed A value obtained from $el in a format that can be set in $record.

Synopsis

This method is the inverse of fieldname__pullValue().

Since: 0.6

See Also: HTML_QuickForm; fieldname__pullValue()

fieldname__renderCell ( Dataface_Record $record )

Overrides the display of a table cell for a field in list view.

Parameters

Dataface_Record $record The subject record.

Returns: string The string contents of the cell.

Since: 0.8

See Also: http://xataface.com/documentation/how-to/list_tab; renderRow()

fieldname__roles ( Dataface_Record $record )

Returns the roles for a particular field of the given record.

Parameters

Dataface_Record $record The record that is subject of this query.

Returns: mixed Either an array of string role names, a string with a single role name, or null.

Since: 1.0

Synopsis

This method is the analog of the fieldname__permissions() method except that it returns roles instead of permissions. The roles returned by this method are resolved to permissions and laid over the record-level permissions to obtain the effective field permissions.

It is rare to implement both the fieldname__roles() and the fieldname__permissions() method in the same delegate class. If this happens, though the fieldname__permissions() will take precedence.

Attention: This method will always be superceded by fieldname__permissions() if defined.; Field level roles are resolved to a permissions array which is treated as a mask that is laid over the record permissions in order to establish the effective permissions for a field. Therefore, to disallow a permission on a field you must explicitly set it to 0 (you cannot just omit it).

Flowchart

The following flowchart shows the flow of control Xataface uses to determine the field-level permissions for a field in a record.

Click here to enlarge

Examples

E.g. To define custom roles for a field named 'invoice_number':

function invoice_number__roles($record){
    return 'READ ONLY';
}

Or to apply multiple roles:

function invoice_number__roles($record){
    return array('ROLE 1', 'ROLE 2');
}

See Also: fieldroles(); getPermissions(); getRoles(); fieldname__roles(); fieldname__permissions(); Dataface_PermissionTool; http://xataface.com/documentation/tutorial/getting_started/permissions; http://xataface.com/wiki/permissions.ini_file

fieldname__serialize ( $value )

Serializes a field value to prepare it for insertion into an SQL query.

Parameters

mixed $value The field value that is to be serialized.

Returns: string The serialized value that is ready to be placed in an SQL query (though hasn't been escaped for quotes).

Since: 0.5

See Also: Dataface_Serializer::serialize()

fieldname__toString ( Dataface_Record $record )

Overrides the string value of specified field for a given record.

Parameters

Dataface_Record $record The subject record.

Returns: string The string field value

Since: 0.5

Attention: This method affects how the field value is loaded into form widgets in addition to viewable sections of the site, so take great care when implementing this method. If you only want to override how a field value is displayed in the site but don't want to affect edit forms, them you should use the fieldname__display() method instead.

See Also: Dataface_Record::getValueAsString()

fieldname__validate	(	Dataface_Record	$record,
			$value,
		array &	$params
	)

Validates form input for a field.

@param Dataface_Record $record The record encapsulating the record we are validating. Note that the values of this object correspond with the submitted values from the form, and not necessarily the actual values of the record in the database.
@param string $value The submitted value that is being validated.
@param array &$params An output array to pass meta-information out in case of failure. This allows only one possible key to be set: 'message'.

@return boolean True if validation succeeds (i.e. $value is a valid input).  False otherwise.

@section Examples

@code 
function myfield__validate(&$record, $value, &$params){
if ( $value != 'Steve' ){
    $params['message'] = 'Sorry you must enter "Steve"';
    return false;
}
return true;

}

Since: 0.6

See Also: http://xataface.com/wiki/fieldname__validate

getBreadCrumbs ( Dataface_Record $record )

Returns the breadcrumbs to a given record.

Parameters

Dataface_Record $record The record to which the breadcrumbs apply.

Returns: array Associative array of breadcrumbs with the keys being the breadcrumb title, and the value being the breadcrumb link.

Since: 0.8

See Also: Dataface_Record::getBreadCrumbs(); Dataface_SkinTool::bread_crumbs()

getChildren ( Dataface_Record $record )

Returns the records that are considered to be children of the given record.

Parameters

Dataface_Record $record The parent record for which children are being returned.

Returns: array An array of Dataface_Record objects that are children of $record.

Since: 0.8

See Also: Dataface_Record::getChildren()

getCreator ( Dataface_Record $record )

Returns the name of the user who created this record (i.e. the record author).

Parameters

Dataface_Record $record

Returns: string The Author's name.

Since: 0.8

See Also: Dataface_Record::getCreator()

getDelegate ( )

Returns an alternate object to be used as the delegate. This is handy for module developers to allow application developers to override module-defined delegates with application-defined delegates.

Returns: mixed Returns null to indicate to just use the default delegate class ($this). otherwise returns an object that should be used as the delegate class object for the table.

See Also: Allowing Application to Override Permissions For an example use of this method.

getDescription ( Dataface_Record $record )

Returns a brief description of this record for use in lists, RSS feeds, and more.

Parameters

Dataface_Record $record The record for which the description applies.

Returns: string The record description.

Since: 0.8

See Also: Dataface_Record::getDescription()

getFeed ( array $query )

Returns data structure with settings for the RSS feed as a whole.

Parameters

array $query The query parameters for the request.

Returns: array A data structure that is a subset of the following array format:
array(

title => <string> // The title of the RSS feed

description => <string> // Description of the RSS feed

link => <string> // The URL to the original feed content

syndicationURL => <string> // Link to source page of RSS feed (same as link)

)

Default Value

If elements are omitted from the data structure that is returned from this method, Xataface will use default values for each field. The following table describes the values that Xataface will use as defaults in this case:

Key	Default Value
title	title directive of the [_feed] section of the conf.ini file. An auto-generated title based on the current query.
description	description directive of the [_feed] section of the conf.ini file.
link	link directive of the [_feed] section of the conf.ini file. The URL to list view of the application with the same result set as the current feed.
syndicationURL	syndicationURL directive of the [_feed] section of the conf.ini file. The URL to list view of the application with the same result set as the current feed.

Since: 0.8

See Also: http://xataface.com/wiki/getFeed; http://xataface.com/wiki/Introduction_to_RSS_Feeds_in_Xataface

getFeedItem ( Dataface_Record $record )

Returns a data structure with the contents to be included in the RSS feed.

Parameters

Dataface_Record $record The subject record.

Returns: array A data structure with details in the following format:
array(

title => <string> // The title of the post

description => <string> // The body of the post

link => <string> // The link to the original post

date => <long> // Unix timestamp marking the date of the post

// This is generally the last modified date

author => <string> // The author of this post

source => <string> // The source URL where the feed originated.

)

Note that if keys are omitted from this array, default values will be used by Xataface when building the RSS feed. In fact you could even return an empty array from this method in which case Xataface would fill in all of the values itself.

Default Value

The following table shows where Xataface will pull default values if keys are omitted from the array that is returned from this method.

Key	Default Value
title	Dataface_Record::getTitle()
description	getRSSDescription() if defined. Otherwise it will display an HTML table showing all data in the record (subject to permissions).
link	Dataface_Record::getPublicLink()
date	Dataface_Record::getLastModified() Dataface_Record::getCreated()
author	Dataface_Record::getCreator() default_author of the [_feed] section of the conf.ini file.
source	getFeedSource() source of the [_feed] section of the conf.ini file.

Since: 0.8

See Also: getFeed(); http://xataface.com/wiki/getFeed; http://xataface.com/wiki/getFeedItem; http://xataface.com/wiki/Introduction_to_RSS_Feeds_in_Xataface; getRSSDescription()

getFeedSource ( array $query )

Returns the source URL for the RSS feed that is generated by the given query.

Parameters

array $query The query parameters that produced the feed.

Returns: string The URL to the source webpage for the RSS feed.

Synopsis

This method will override any information returned by the getFeed() method with respect to the source of the feed.

Since: 0.8

See Also: http://xataface.com/wiki/Introduction_to_RSS_Feeds_in_Xataface; http://xataface.com/wiki/getFeed; getFeed()

getLastModified ( Dataface_Record $record )

Returns the Unix timestamp representing the last modification time of the given record.

Parameters

Dataface_Record $record The $record whose lastModified time we are checking.

Returns: long The unix timestamp marking the last modification date of this record.

See Also: Dataface_Record::getLastModified()

getPermissions ( Dataface_Record $record )

Returns associative array of permissions that should be granted to the current user on this record.

Parameters

Dataface_Record $record The record on which we are granting permissions. Note that this parameter may be null if permissions are being checked on the table in general so you must be able to handle null inputs for this value.

Returns: array Associative array of permissions that are granted. The keys of this array are the names of permissions (defined in the permissions.ini file) and values are boolean (0 or 1) to indicate whether or not the permission is granted. This method may also return null to indicate that it has no opinion on the permissions to use - i.e. it will default to the permissions defined in the ApplicationDelegateClass.

Since: 0.5

Attention: Note that the results of this method will always supercede the results of getRoles() if defined.

Flowchart

The following flowchart shows the flow of control Xataface uses to determine the record-level permissions for a record. (click here to enlarge):

Examples

Example 1: All Fields

function getPermissions($record){
    return Dataface_PermissionsTool::ALL();
}

Example 2: Only Some Fields

function getPermissions($record){
    return Dataace_PermissionsTool::NO_ACCESS();
}

Read Only Permissions

function getPermissions($record){
    return Dataface_PermissionsTool::READ_ONLY();
}

2-Tiered Permissions

Allow logged in users full permissions, and everyone else no access.

function getPermissions($record){
    $auth = Dataface_AuthenticationTool::getInstance();
    if ( $auth->isLoggedIn() ){
        return Dataface_PermissionsTool::ALL();
    } else {
        return Dataface_PermissionsTool::NO_ACCESS();
    }
}

3-Tiered Permissions

In this example we assume that our 'users' table has a 'role' column to track a user's role. In our case if the 'role' is 'ADMIN', then the user is considered to be an admin. Otherwise they are just a regular user.

function getPermissions($record){
    $auth = Dataface_AuthenticationTool::getInstance();
    $user = $auth->getLoggedInUser();
    if ( $user and $user->val('role') == 'ADMIN' ){
        return Dataface_PermissionsTool::ALL();
    } else if ( $user ){
        // user is logged in but isn't an admin
        return Dataface_PermissionsTool::READ_ONLY();
    } else {
        return Dataface_PermissionsTool::NO_ACCESS();
    }
}

Best Practice

It is recommended to define a getPermissions() method in the application delegate class that is very restrictive (i.e. no access for anyone except super-administrators) and then explicitly open up access to individual tables as necessary for other users.

e.g. In conf/ApplicationDelegate.php

function getPermissions($record){
    $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
    if ( $user and $user->val('role') == 'ADMIN' ){
        return Dataface_PermissionsTool::ALL();
    } else {
        return Dataface_PermissionsTool::NO_ACCESS();
    }
}

Then suppose we want to open up the people table to allow logged in users to have read only access.

In tables/tables/people.php

function getPermissions($record){
    $user = Dataface_AuthenticationTool::getInstance()->getLoggedInUser();
    
    // If user is an admin defer to the application delegate class for 
    // permissions
    if ( $user and $user->val('role') == 'ADMIN' ){
        return null;
    }
    if ( $user ){
        // User is logged in
        return Dataface_PermissionsTool::READ_ONLY();
    }
    // Defer to the application delegate class for all other users
    return null;
}

See Also: http://xataface.com/documentation/tutorial/getting_started/permissions; ApplicationDelegateClass::getPermissions(); getRoles(); fieldpermissions(); fieldname__permissions(); rel_relationshipname__permissions(); Dataface_Record::getPermissions(); Dataface_Table::getPermissions(); Dataface_PermissionsTool; http://xataface.com/wiki/permissions.ini_file

getPublicLink ( Dataface_Record $record )

Returns the publicly accessible URL for a given record.

Parameters

Dataface_Record $record The record to which the URL refers.

Returns: string The URL for the public webpage of the given record.

Since: 0.5

See Also: getURL(); Dataface_Record::getPublicLink()

getRelatedFeed	(	Dataface_Record	$record,
			$relationship
	)

Returns details about a feed of related records. This overrides the feed details for related feeds.

Parameters

Dataface_Record	$record	The subject record (the parent of the related records).
string	$relationship	The name of the relationship.

Returns: array A data structure that is a subset of the following array format:
array(

title => <string> // The title of the RSS feed

description => <string> // Description of the RSS feed

link => <string> // The URL to the original feed content

syndicationURL => <string> // Link to source page of RSS feed (same as link)

)

Default Value

If elements are omitted from the data structure that is returned from this method, Xataface will use default values for each field. The following table describes the values that Xataface will use as defaults in this case:

Key	Default Value
title	An auto-generated title. Generally {relationship_name} of Dataface_Record::getTitle()
description	Auto-generated title. Something like: Related Records of Dataface_Record::getTitel()
link	The URL to the related list of this feed.
syndicationURL	The URL to the related list of this feed.

Since: 0.8

See Also: http://xataface.com/wiki/Introduction_to_RSS_Feeds_in_Xataface; getFeed()

getRoles ( Dataface_Record $record )

Returns one or more roles that are to be granted to the current user for the specified record.

@param Dataface_Record $record The record on which the roles are to be granted.
@return mixed Either a string with a single role or an array of strings representing
            roles that are assigned to the current user on the given record.
@since 1.0

@section Synopsis

 This method can be implemented as an alternative to getPermissions() for the purpose
 of defining record-level permissions.  A "role" is a set of permissions that are grouped
 together.  This allows us to group together related permissions into easy-to-use sets
 and refer to them by their 'role' name.

 Roles are defined in the <a href="http://www.xataface.com/wiki/permissions.ini_file">permissions.ini file</a>, and Xataface comes with several 
 pre-defined roles.  These built-in roles are listed in the table below:

<table>
    <tr>
            <th>Role Name</th>
            <th>Description</th>
            <th>Definition</th>
            <th>Since</th>
    </tr>
    <tr>
            <td>NO ACCESS</td>
            <td>A contains only the 'register' permission.
            @attention This is NOT the same as Dataface_PermissionsTool::NO_ACCESS().  Dataface_PermissionsTool::NO_ACCESS() explicitly denies all permissions in the system, whereas the 'NO ACCESS' role simply does not explicitly <em>grant</em> any permissions except register.  This is an important distinction when dealing with field-level permissions since field permissions are applied as a mask over record-level permissions.
            </td>
            <td>
@code 
[NO ACCESS]
    register=1
@endcode
     </td>
     <td>0.6</td>

 </tr>
 <tr>
     <td>READ ONLY</td>
        <td>Includes all view-ish permissions  - for viewing records.  This includes viewing records in list view, details view, XML export, RSS feeds, etc..</td>
     <td>
@code 
[READ ONLY]
  view in rss=1
  view = 1
  link = 1
  list = 1
  calendar = 1
  view xml = 1
  show all = 1
  find = 1
  navigate = 1
  ajax_load = 1
  find_list = 1
  find_multi_table = 1
  rss = 1
  export_csv = 1
  export_xml = 1
  export_json = 1
  view related records=1
  related records feed=1
  expandable=1
@endcode
            </td>
            <td>0.6</td>
    </tr>
 <tr>
            <td>EDIT</td>
     <td>Includes all permissions for viewing and editing records.</td>
     <td>
@code 
[EDIT extends READ ONLY]
    edit = 1
    add new related record = 1
    add existing related record = 1
    add new record = 1
    remove related record = 1
    reorder_related_records = 1
    import = 1
    translate = 1
    new = 1
    ajax_save = 1
    ajax_form = 1
    history = 1
    edit_history = 1
    copy = 1
    update_set = 1
    update_selected=1
    select_rows = 1

0.6

DELETE

Permission to view, edit, and delete records.

[DELETE extends EDIT]
      delete = 1
      delete found = 1
      delete selected = 1

0.6

MANAGER

Edit and delete permissions as well as permission to access the control panel and management functions of the application.

[MANAGER extends ADMIN]
  manage=1
  manage_output_cache=1
  manage_migrate=1
  manage_build_index=1
  install = 1

0.6

Since this method simply provides an alternate way to define permissions, you generally would not define both methods in the same delegate class, but if you did implement both the getRoles() method would take priority of over the getPermissions() method.

Attention: Note that the results of this method are always superceded by the results of getPermissions() if defined.

Flowchart

The following flowchart shows the flow of control Xataface uses to determine the record-level permissions for a record. (click here to enlarge):

Examples

getRoles() vs getPermissions()

Consider the getPermissions() method below:

function getPermissions($record){
    return Dataface_PermissionsTool::getRolePermissions('READ ONLY');
}

This is equivalent to the getRoles() method:

function getRoles($record){
    return 'READ ONLY';
}

The getRoles() version is much more succinct as it just allows us to return the name of the role that is granted, rather than having to resolve the permissions for that role.

Granting Multiple Roles

It is also possible to grant multiple roles, in which case the resulting permissions would be the union of the granted roles (where the last role listed takes precendent).

function getRoles($record){
    return array('MY FIRST ROLE', 'MY SECOND ROLE');
}

See Also: getPermissions(); Dataface_Record::getRoles(); http://xataface.com/documentation/tutorial/getting_started/permissions; Dataface_PermissionsTool; http://xataface.com/wiki/permissions.ini_file; ApplicationDelegateClass::getPermissions()

getRSSDescription ( Dataface_Record $record )

Overrides the description or body of a record as it is displayed in an RSS feed.

Parameters

Dataface_Record $record The subject record.

Returns: string The HTML content of the RSS feed post.

Synopsis

The default behavior of the Xataface RSS feed is to layout all permitted fields in an HTML table and include that table in the RSS feed. If you want to customize this behavior you can implement this method to return exactly what you want to appear in the body of the RSS feed item.

Since: 1.0

See Also: getFeedItem(); http://xataface.com/wiki/Introduction_to_RSS_Feeds_in_Xataface

getSearchableText ( Dataface_Record $record )

Returns the indexable text to be used for the full-text site search feature.

Parameters

Dataface_Record $record The subject record.

Returns: string The searchable text for the record.

Since: 1.0

getSearchTarget ( array $action )

Returns the name of an action that should be used as the target action of a search performed from the current context. In past releases searches would always go to the list action. This gives you the ability to override this behavior with your own custom action depending on the circumstances.

Parameters

array $action The action definition to check (this would be the source action).

Since: 2.0

See Also: Dataface_Application::getSearchTarget(); ApplicationDelegateClass:getSearchTarget()

getTitle ( Dataface_Record $record )

Returns the record's title. This is used in Xataface to return the title of a record when the Dataface_Record has been loaded into memory already. It returns a string that can be used as the title of a record and takes a Dataface_Record object as a parameter - hence it can draw on any information in the record to form the effective title.

Attention: For sets of records (e.g. on the Add Existing Records dropdown list) Xataface will likely use the titleColumn() method instead for getting the titles so that it doesn't need to load each record into memory just to get the record titles.

Parameters

Dataface_Record $record The record whose title we are returning.

Returns: string The title of the record which would override the value returned by Dataface_Record::getTitle()

Since: 0.5

See Also: Dataface_Record::getTitle(); titleColumn() for use when record titles are needed for sets of records.

getURL	(	Dataface_Record	$record,
			$params = `array()`
	)

Returns the URL of the given record.

Parameters

Dataface_Record	$record	The record whose URL we are returning.
array	$params	The query parameters to include in the generated URL.

Returns: string The URL to the record.

Since: 0.5

See Also: Dataface_Record::getURL(); Dataface_Record::getPublicLink(); getPublicLink()

getXMLHead ( Dataface_Record $record )

Returns XML content to be included at the beginning of the XML representation of this record.

Parameters

Dataface_Record $record The subject record.

Returns: string XML content to be included at the beginning of the XML representation of $record.

Since: 1.3

Attention: toXML() supercedes this method if both are implemented in the delegate class.

See Also: Dataface_XMLTool; Dataface_XMLTool_default; dataface_actions_export_xml

init ( Dataface_Table $table )

Called after a table is loaded for the first time each request.

If you want to adjust table-wide settings, this is a good place to do it. E.g. for security filters, and modification of the configuration.

Parameters

Dataface_Table $table The table object that was just loaded.

Returns: void

Since: 0.6

See Also: Dataface_Table::loadTable()

no_access_link	(	Dataface_Record	$record,
			$params = `array()`
	)

Returns the link that should be returned by Dataface_Record::getURL() if the user isn't granted the 'link' permission on the given record.

Parameters

Dataface_Record $record The record that is subject of this query.

Returns: string The link that should be returned by getURL() if the user doesn't have the 'link' permission.

Since: 1.0

See Also: Dataface_Record::getURL(); no_access_text(); http://xataface.com/wiki/permissions.ini_file

no_access_text	(	Dataface_Record	$record,
			$params = `array()`
	)

Returns the text that should be returned by Dataface_Record::display() if the user doesn't have 'view' permission for the record.

Parameters

Dataface_Record	$record	The record that is subject of this query.
array	$params	Associative array of extra parameters. One such parameter is the 'field' parameter which is the name of the field for which the text is to be displayed.

Returns: string The string to display if the user doesn't have 'view' permission.

Since: 1.0

See Also: no_access_link(); Dataface_Record::display(); Dataface_Record::secureDisplay; http://xataface.com/wiki/permissions.ini_file

rel_relationshipname__permissions ( Dataface_Record $record )

Returns the permissions for a particular relationship of the given record.

Parameters

Dataface_Record $record The record that is subject of this query.

Returns: array Associative array of permissions granted for this relationship.

Since: 1.0

Attention: Relationship permissions are treated as a mask that are overlaid over the record level permissions to produce the effective permissions for the given relationship. Therefore, in order to deny a permission for a relationship, you must explicitly set it to 0 - it is not sufficient to omit the permission like you do with record level permissions.

Synopsis

This method, if implemented, returns a permissions mask to apply to a particular relationship in the given record. For example if we want to specifically allow adding related records to one relationship but not other relationships.

There are only a few specific permissions that pertain to relationships and these are the only ones that have any effect when returned from this method.

These permissions include:

Permission Name	Description
add new related record	Permission to add new records to the relationship.
add existing related record	Permission to add existing records to the relationship.
related records feed	Permission to view the RSS feed for the related records.
remove related record	Permission to remove a record from the relationship. This is only applicable to many-to-many relationships as this doesn't include permission to delete the record from the database, only to sever the relationship.
delete related record	Permission to delete a related record (delete it from the database).
view related records	Permission to view the related records list. If this is denied, then the related records tab won't be present, and if users try to go to the URL for the tab directly, they'll receive a permission denied error.
reorder_related_records	Permission to reorder related records. This is only applicable to relationships that have a designated order column (via the metafields:order directive of the relationships.ini file ).

See Also: rel_relationshipname__roles(); getPermissions(); http://xataface.com/documentation/tutorial/getting_started/relationships; http://www.xataface.com/wiki/relationships.ini_file

rel_relationshipname__roles ( Dataface_Record $record )

Returns the roles for a particular relationship of the given record.

Parameters

Dataface_Record $record The record that is subject of this query.

Returns: mixed Either an array of string role names, a single string role name, or null.

Since: 1.0

See Also: rel_relationshipname__permissions()

renderRow ( Dataface_Record $record )

Overrides the display of a table row in list view.

Parameters

Dataface_Record $record The subject record.

Returns: string The string row output (i.e. the tr tag and contents).

Since: 0.8

See Also: http://xataface.com/documentation/how-to/list_tab

renderRowHeader ( Dataface_Record $record )

Overrides the headings row for the list view table.

Returns: string The string row header (i.e. the tr tag and contents).

Since: 0.8

See Also: http://xataface.com/documentation/how-to/list_tab

section__sectionname ( Dataface_Record $record )

Defines a new section on the view tab.

Parameters

Dataface_Record $record The subject record.

Returns: array Data structure containing details about the section. The data structure is:
array(

name => <string> // The name of the section

label => <string> // The label of the section

content => <string> // The section content

order => <number> // Integer order of the section

url => <string> // The URL to 'see all'

edit_url => <string> // URL to edit the content in this section

records => <array(Dataface_Record)> // List of records to display

display => <enum('expanded','collapsed')> // Whether it should be default collapsed or expanded

class => <enum('main', 'left')> // Whether do display in left column or main column.

fields => <array(string)> // List of field names to display

)

Since: 0.8

See Also: http://xataface.com/wiki/How_to_Add_Custom_Sections_to_View_Tab

titleColumn ( )

Returns an SQL expression (that is valid for a column in a select clause) denoting the column(s) that comprise the title of records in this table. This may return a single column name or it may make use of SQL functions like CONCAT() to compose a title from multiple columns.

Returns: string An SQL expression. Either the column name to use as title or an SQL expression that evaluates to a column name.

Example

Using the firstname field as the record title:

function titleColumn(){
    return 'firstname';
}

Example 2

Using first name and last name as record title.

function titleColumn(){
    return "concat(firstname,' ',lastname)";
}

See Also: getTitle() For a method to define a title for a single record.

toXML ( Dataface_Record $record )

Overrides the XML output of a record as it would appear in Xataface's export_xml action.

Parameters

Dataface_Record $record The subject record.

Returns: string XML representation of the record.

Since: 0.8

See Also: Dataface_XMLTool; Dataface_XMLTool_default; dataface_actions_export_xml

valuelist__valuelistname ( )

Defines a valuelist on the table.

Returns: array Associative array serving as a valuelist where the keys are the ids and the values are the values.

Since: 0.6

See Also: Dataface_ValuelistTool; Dataface_Table::getValuelist(); http://www.xataface.com/wiki/valuelists.ini_file; http://xataface.com/documentation/tutorial/getting_started/valuelists

xmlTail ( Dataface_Record $record )

Returns XML content to be included at the end of the XML representation of this record.

Parameters

Dataface_Record $record The subject record.

Returns: string XML content to be included at the end of the XML representation of $record.

Since: 1.3

Attention: toXML() supercedes this method if both are implemented in the delegate class.

See Also: Dataface_XMLTool; Dataface_XMLTool_default; dataface_actions_export_xml

Initialization

Permissions

Record Metadata

Field Filters

Calculated Fields

Record Triggers

Action Triggers

Template Customization

List Tab Cutomization

View Tab Customization

Full-text Search

RSS Feed Customization

XML Output Customization

Valuelist Customization

Importing Records

Table Settings

Form Validation

Detailed Description

Function Documentation

Synopsis

Flowchart

Examples

Step 2: Default Field-level Permissions

Step 2: Default Field-level Permissions

Step 3: Make the BIO field editable for Record Owner

Step 4: Hide the admin_comments field from record owners

Flowchart

Synopsis

Invariants

1: Idempotent

2: Inverse of fieldname__toString()

Synopsis

Flowchart

Examples

Synopsis

Synopsis

Flowchart

Examples

Default Value

Default Value

Synopsis

Flowchart

Examples

Example 1: All Fields

Example 2: Only Some Fields

Read Only Permissions

2-Tiered Permissions

3-Tiered Permissions

Best Practice

Default Value

Flowchart

Examples

getRoles() vs getPermissions()

Granting Multiple Roles

Synopsis

Synopsis

Example

Example 2