Dataface_Table Class Reference

A class that represents the table of a table in a database. More...

Public Member Functions
Internationalization
Methods for translation and internationalization
&	getTranslations ()
	Returns associative array of translations where the key is the 2-digit language code and the value is an array of column names in the translation.
&	getTranslation ($name)
	Returns an array of column names that are available in a given language.
	getTranslationStates ()
	Gets array of translation states available.
Tabs
Methods for working with tabbed sections of the edit form.
	getTabs ()
	Returns an array of strings that are the names of the tabs for this table. Fields can be grouped into tabs by specifying a 'tab' attribute in the fields.ini file. This is just a list of the tabs that are specified.
&	tabs ($record=null)
	Returns an associative array of tab definitions of the form: [tabname] -> [tab_properties].
&	getTab ($tabname, $record=null)
	Returns specified tab's properties.
	__join__ (&$record)
	Returns an array of tables for a particular record that can be treated as join tables.
	hasJoinTable ($tablename, &$record)
	Indicates whether or not this table has a join table.
Field Groups
Methods for working with field groups.
&	getFieldgroup ($fieldgroupname)
	Returns an associative array describing a field group.
&	getFieldgroups ()
	Returns associative array of all of the field group definitions (keys are the fieldgroup names).
Imports
Methods for working with import filters and importing records.
&	getImportFilters ()
	Import filters facilitate the importing of data into the table.
	registerImportFilter (&$filter)
	getImportTables ()
	Gets the tables from the database that are explicitly for importing data. They are tables of the form Tablename__import__<timestamp> where <timestamp> is the unix timestamp of when the import table was created.
	createImportTable ()
	Creates an import table for this table. An import table is an empty clone of this table. It serves as an intermediate step towards importing data into the main table.
	cleanImportTables ()
	Cleans up old import tables. Any import tables older (in seconds) than the garbage collector threshold (as defined in $app->_conf['garbage_collector_threshold']) will be dropped.
	isImportTable ($tablename)
	Checks if a given table is an import table as created with createImportTable().
	parseImportData ($data, $importFilter=null, $defaultValues=array())
	Prepares data to be imported into the table. It takes raw data and produces an array of Dataface_Record objects that can be imported into the table.
Field Type Information
Methods for checking the type information of fields.
	getType ($fieldname)
	Returns the type of a field , eg: int, float, varchar, blob, etc...
	isDate ($fieldname)
	Checks a field to see if it is a date type (date, datetime, time, or timestamp).
	isBlob ($fieldname)
	Checks a field to see if it is a blob type.
	isContainer ($fieldname)
	Indicates if a field is a container field. A container field is a varchar or char field but it contains the path to a file rather than data itself.
	isPassword ($fieldname)
	Checks to see if the field is a password field. Any field with widget:type=password is regarded as a password field.
	isText ($fieldname)
	Checks to see if the field is a text field (e.g. text, longtext, tinytext, or mediumtext).
	isXML ($fieldname)
	Checks to see if the field is stored in XML format. Only the 'table' and 'group' widgets cause the data to be stored as XML.
	isChar ($fieldname)
	Checks to see if the field is a character field (i.e. varchar or char).
	isInt ($fieldname)
	Checks to see if the field is an INT field.
	isFloat ($fieldname)
	Checks to see if the field is a floating point field (i.e. float, double, tinyfloat, etc..)
Templates
Methods for working with the user interface and templates.
	displayBlock ($blockName, $params=array())
	Displays a block from the delegate class. Blocks are defined in the delegate class by defining methods with names starting with 'block__'. Eg: block__header()
	getBlockContent ($blockName, $params=array())
	Returns the content of a given block as a string.
Factory Methods
Methods for loading and creating Dataface_Record objects on the current table.
	newRecord ($vals=null)
	Returns a new blank Dataface_Record object for this table.
&	getRecord ($query=null)
	Gets a record from the database that matches the given query.
Actions
Methods for dealing with table actions.
	getActions (&$params, $noreturn=false)
	Returns the actions for this table.

Data Fields
	$tablename
	The name of the table that this table represents. string.
	$db
	DB connection handle. resource handle.
	$errors = array()
	Store errors that occur in methods of this class.
	$versionField = -1

Initialization
Methods for obtaining Dataface_Table objects.
static &	loadTable ($name, $db=null, $getAll=false, $quiet=false)
	Loads the table object for a database table.

Fields
Methods for getting field information for this table.
static &	getTableField ($address, $db='')
	Returns field information given its address. Note: To prevent deadlocks, this method should never be called inside the Dataface_Table constructor.
static	fieldExists ($address, $db='')
	Checks if a field exists. Note: To prevent deadlocks, this method should never be called inside the Dataface_Table constructor.
static	tableExists ($tablename, $usecache=true)
	Checks if the given table exists. This caches the results so that you won't have to check the existence of the same table twice.
static	absoluteFieldName ($field, $tablenames, $db='', $columnList=null)
	Returns the absolute field name of a field as it appears in one of the given tables. This is kind of like a search to find out which of the given tables, the column belongs to. The absolute field name is a string of the form table_name.field_name (ie table name and field name separated by a dot). This method may be called statically.
static &	getGlobalFieldsConfig ()
	exists ($fieldname, $checkParent=true)
	Checks if a field exists in this table by the given name.
	hasField ($fieldname, $checkParent=true)
	Checks if a field exists in this table by the given name. Alias of hasField()
	relativeFieldName ($fieldname)
	Returns the relative field name given either a relative name or an absolute name.
	guessField ($types, $patterns, $forcePattern=false)
	Tries to find a field that best matches the criteria we provide. This is useful for finding e.g. description, last modified, and title fields.
	getDescriptionField ()
	Makes a best guess at which field in this table stores the record description. The record description is displayed in various logical places throughout the UI.
	getCreatedField ()
	Makes a best guess at which field stores the creation date of the record.
	getCreatorField ()
	Makes a best guess at which field stores the username of the person who created the record.
	getVersionField ()
	Gets the field that is used to track the version of this record, if one is set. The version field is set by setting the "version" directive for a field in the fields.ini file.
	setVersionField ($field)
	Sets the name of the field that should be used to version records of this table.
	isVersioned ()
	getLastUpdatedField ()
	Makes a best guess at which field stores the last modified date of the record.
	getBodyField ()
	Makes a best guess at which field stores the "body" of the record. The body is used in things like the RSS feed to show the "content" of the record.
&	getIndexes ()
	Returns an associative array of indexes in this table.
	getFullTextIndexedFields ()
	Returns an array of field names that have full text indexes.
	getCharFields ($includeGraftedFields=false, $excludeUnsearchable=false)
	Returns array of names of char, varchar, and text fields. These are the fields that can be searched using full text searches.
	isSearchable ($field)
	Checks if a field is searchable. Fields can be made unsearchable by setting the not_searchable directive in the fields.ini file.
	isMetaField ($fieldname)
	Indicates if the given field acts as a meta field that describes an aspect of another field. For example, some fields simply contain the mimetype of a blob field. Such a field is a meta field.
	getMetadataColumns ()
	Returns an array of names of columns in the metadata table for this table. The metadata table contains metadata such as state and translation state for the corresponding records of this table. Fields of this table that are considered to be metadata must begin with two underscores to signify that they are metadata.
&	formFields ($byTab=false, $includeTransient=false)
	Returns the fields that should be included in forms for editing. This includes fields from parent tables.
&	fields ($byTab=false, $includeGrafted=false, $includeTransient=false)
	Returns reference to the fields array that contains field definitions.
&	graftedFields ($includeParent=true)
	Field definitions of fields that have been grafted onto this table.
&	transientFields ($includeParent=false)
	Returns the transient fields in this table. Transient fields are fields that do not get saved in the database (i.e. have no corresponding field in the database. They are useful for creating fields on the new/edit forms.
&	delegateFields ($includeParent=false)
	Returns calculated fields defined in the delegate class via the field__fieldname() method naming convention.
	sql ()
	Returns the SQL query used to fetch records of this table, if defined.
	getProxyView ()
	Returns the name of the VIEW to be used for reading records from the database. This feature is new in version 1.2 and is intended to improve performance by NOT using subqueries to implement support for sql parameters on tables. We'll see if this makes a big difference to mysql.
&	keys ()
	Returns reference to the keys array that contains field definitions for keys.
	hasKey ($name)
	Checks to see if the specified field is part of the primary key.
&	mandatoryFields ()
	A list of the keys that are NOT auto incremented.
	getDefaultValue ($fieldname)
	Returns the default value for a field.
	titleColumn ()
	A valid SQL select phrase for a single column. This will be used when extracting the titles of each row from the database.
&	getField ($fieldname)
	Returns a field structure with the given name. This can also be related field. Simply prepend the relationship name followed by a period. eg: relationship_name.field_name.
	getFieldProperty ($propertyName, $fieldname, $params=array())
	This method returns a property associated with a field, that is defined in the fields.ini file. This method also checks the delegate class to see if an equivalent property method has been defined. Delegate class method names will be of the form <field_name>__<property_name>(). Note that in the case where the property name contains illegal characters (e.g., ':'), the character will be replaced by an underscore ( i.e., '_').
	getAutoIncrementField ()
	Returns the name of the field that is auto incrementing (if it exists).

Permissions
Methods to calculate permissions on records, fields, and relationships of the table.
	setSecurityFilter ($filter=null)
	Sets a security filter on the table. A security filter is an array of key/value pairs that are automatically added to any query of this table to limit the results.
	getSecurityFilter ($filter=array())
	Returns the security filter for this table.
	getRelationshipPermissions ($relationshipName, $params=array())
	Gets the permissions for a particular relationship.
	getPermissions ($params=array())
	Obtains the permissions for a particular record or for this table. Parameters are passed in associative array as key value pairs.
	convertRolesToPermissions ($roles)
	Resolves the pemissions for a role or list of roles.
	loadPermissions ()
	Loads the permissions from the permissions.ini files.

Table Info
Methods to retrieve configuration and status information about the table.
static &	getBackupModificationTimes ($refresh=false)
	Neither INNODB tables nor views store the last updated time inside of MySQL. This wreaks havoc on caching, so we create our own backup table called dataface__mtimes as a fallback mechanism to track uptime times of tables. The down side is that it only updates the timestamp when a change is made via Xataface. Outside changes aren't tracked.
static &	getTableModificationTimes ($refresh=false)
	Returns an associative array mapping table names to their associated modification as a unix timestamp.
	getLabel ()
	Gets the label for this table. This is displayed in the navigation menu (table tabs).
	getSingularLabel ()
	Returns the label for this table as a singular. Often tables are named as plurals of the entities they contain. This will attempt to get the name of the singular entity for use in UI items where referring to the items of the table in singular is more appropriate e.g. New Person.
	tableInfo ()
	Print information about Table.
	databaseInfo ()
&	attributes ()
	Returns reference to the attributes array for this table.
&	getParent ()
	Gets the parent table of this table to help model inheritance. The parent table can be specified by the isa attribute of the fields.ini file.
	implementsOntology ($ontologyName)
	Indicates whether this table is declared as implementing the given ontology.
&	getStatus ()
	Returns the status of this table. Includes things like modification time, etc...
	getUpdateTime ()
	Returns the update time as an SQL DateTime string for this table.
	getCreateTime ()
	Returns the creation time of this table as an SQL DateTime string.

Valuelists
Methods for working with valuelists.
	isYesNoValuelist ($valuelist_name, &$yes, &$no)
	Checks if a valuelist is just a boolean valuelist. It will also return (via output parameters) what the corresponding yes/no values are.
	_loadValuelistsIniFile_old ()
	clearValuelistCache ()
	Clears the valuelist cache.
&	getValuelist ($name)
	Returns a named valuelist in this table.
&	valuelists ()
	Returns the valuelists in this table.
	getAvailableValuelistNames ()
	Returns a list of all valuelists that are available to this table.

Relationships
Methods for working with relationships.
	addRelationship ($name, $relationship)
	Adds a relationship to the table.
&	getParentRelationship ()
	Gets the relationship that should be used as the parent relationship. This is useful for representing heirarchical structures.
&	getChildrenRelationship ()
	Gets the relationship that should be used as the children relationship. This is useful for representing heirarchical structures.
	getRelationshipRange ($relationshipName)
	Gets the range of records that should be returned for a given relationship when records are returning their related records.
	setRelationshipRange ($relationshipName, $lower, $upper)
	Sets the range of related records that should be returned by records of this table when getting records in the given relationship.
	getDefaultRelationshipRange ()
	Gets the default relationship range for all relationships.
	setDefaultRelationshipRange ($lower, $upper)
	Sets the default relationship range to be used for all relationships.
&	getRelationship ($name)
	Gets a relationship by name.
	hasRelationship ($name)
	Checks if this table has a relationship with the specified name.
	getRelationshipsAsActions ($params=array(), $relationshipName=null, $passthru=false)
	Returns a list of the relationships for this table as actions.
&	relationships ()
	Returns reference to the relationships array for this table.
&	getTableTableForField ($fieldname)
	Returns the Table object that contains a specified field. The fieldname is given as a relationship path (as opposed to an absolute path. This method cannot be called statically.

Delegate Classes
Methods for working with table delegate classes.
&	getDelegate ()
	Returns a reference to the Table's delegate class.

Field Data Manipulation
Methods for parsing and manipulating field data.
	parse_datetime ($value)
	Parses a value intended to be placed into a date field and converts it to a normalized format.
	parse_date ($value)
	Alias of parse_datetype()
	parse_timestamp ($value)
	Parses a date, but also recognizes teh CURRENT_TIMESTAMP keyword string to return the current timestamp in normalized format.
	parse_time ($value)
	Alias of parse_datetype()
	normalize ($fieldname, $value)
	Takes a value a normalizes it to a string representation of the value as encoded for the specified field. This is useful for equality comparisons on values of fields.
	getValueAsString ($fieldname, $value)
	Gets the values of this record as strings. Some records like dates and times, are stored as data structures. getValue() returns these datastructures unchanged. This method will perform the necessary conversions to return the values as strings.
	format ($fieldname, $value)
	Formats a value for a particular field to prepare it for display. This will delegate to the DelegateClass::field__format() method if it is defined. Otherwise it will use rules defined in the fields.ini file such as date_format, money_format, and display_format .
	parse ($fieldname, $value, $parseRepeat=true)
	Parses a value so that it conforms with the value stored in the given field.
	parse_repeated ($fieldname, $value, $separator="\n")
	Parses a value for a repeated field.
	validate ($fieldname, $value, &$params)
	Validates against a field of this table. This checks if a value is valid for this a field of this table.

Utility Methods
Miscellaneous useful utility methods.
static	setBasePath ($table, $path)
static	getBasePath ($table)
	clearCache ()
	Clears the table's cache. This is generally handled automatically but if you want to ensure that values get recalculated then you can clear the cache here.
	getSerializer ()
	Gets the serializer object that is used to serialize data in this table.

Detailed Description

A class that represents the table of a table in a database.

This models (and loads) all information about a table and its columns (names, types, keys, etc..), but it also augments these definitions by adding relationships, value lists, and widget types to the fields so that the system knows how a user will interact with the fields.

Usage Example:

$table = Dataface_Table::loadTable('Profiles');

Getting Table Fields

One of the most common uses of the Dataface_Table class is to obtain a list of the fields in the table. The Dataface_Table::fields() method returns an associative array of field definitions in the table. The Dataface_Table::getField() method can be used to obtain a reference to the field definition for a single field.

$table = Dataface_Table::loadTable('Profiles');
$fields = $table->fields();
foreach ($fields as $fieldName=>$fieldDef){
    echo "\n$fieldName label is ".$fieldDef['widget']['label'];
}

See Also

Dataface_Table::fields()

Definition at line 116 of file Table.php.

Member Function Documentation

__join__

(

&

$record

)

Returns an array of tables for a particular record that can be treated as join tables.

Parameters

Dataface_Record

&$record

The record whose context we're considering.

Returns

array Array of tables that are joined to this one. Format:

array(
  tableName:String => tableLabel:String
)

See Also

Dataface_Record::getJoinRecord()

Dataface_Record::getJoinKeys()

Definition at line 4155 of file Table.php.

_loadValuelistsIniFile_old

(

)

Definition at line 3406 of file Table.php.

static absoluteFieldName (   $field,   $tablenames,   $db = '',   $columnList = null  )

static

Returns the absolute field name of a field as it appears in one of the given tables. This is kind of like a search to find out which of the given tables, the column belongs to. The absolute field name is a string of the form table_name.field_name (ie table name and field name separated by a dot). This method may be called statically.

Note: To prevent deadlocks, this method should never be called inside the Dataface_Table constructor.

Parameters

string	$field	The name of a field.
array	$tablenames	An array of table names.
resource	$db	A db resource to query the database.
array	$columnList	Optional array of column names from which to get the absolute name (in case there is more than one possible).

Exceptions

PEAR_Error

if none of the specified tables contain a field named $field, or if more than one table contains a field named $field.

Returns

string The absolute field name.

Definition at line 982 of file Table.php.

addRelationship	(		$name,
			$relationship
	)

Adds a relationship to the table.

Parameters

string	$name	The name of the relationship
array	$relationship	Associative array of options. Keys are the same as expected keys in the relationships.ini file.

Definition at line 3667 of file Table.php.

& attributes

(

)

Returns reference to the attributes array for this table.

Returns

array Associative array of key-value pairs.

Definition at line 3033 of file Table.php.

cleanImportTables

(

)

Cleans up old import tables. Any import tables older (in seconds) than the garbage collector threshold (as defined in $app->_conf['garbage_collector_threshold']) will be dropped.

Definition at line 4397 of file Table.php.

clearCache

(

)

Clears the table's cache. This is generally handled automatically but if you want to ensure that values get recalculated then you can clear the cache here.

Definition at line 5411 of file Table.php.

clearValuelistCache

(

)

Clears the valuelist cache.

Definition at line 3490 of file Table.php.

convertRolesToPermissions

(

$roles

)

Resolves the pemissions for a role or list of roles.

Parameters

mixed

$roles

Either a string role name or an array of role names.

Returns

array Associative array of permission names and their associated 0 or 1 value to indicate whether they are granted or not.

See Also

getPermissions()

Definition at line 2802 of file Table.php.

createImportTable

(

)

Creates an import table for this table. An import table is an empty clone of this table. It serves as an intermediate step towards importing data into the main table.

Returns

string The name of the created table.

See Also

getImportTables()

Definition at line 4370 of file Table.php.

databaseInfo

(

)

Deprecated:

Definition at line 3020 of file Table.php.

& delegateFields

(

$includeParent = false

)

Returns calculated fields defined in the delegate class via the field__fieldname() method naming convention.

Parameters

boolean

$includeParent

True to also include fields from the parent table (via the isa directive).

Returns

array(string=>array) Associative array of field definitions.

See Also

DelegateClass::field::fieldname()

Definition at line 1666 of file Table.php.

displayBlock	(		$blockName,
			$params = array()
	)

Displays a block from the delegate class. Blocks are defined in the delegate class by defining methods with names starting with 'block__'. Eg: block__header()

Parameters

string	$blockName	The name of the block.
array	$params	Associative array of key/value pairs to pass to the block.

Definition at line 5244 of file Table.php.

exists	(		$fieldname,
			$checkParent = true
	)

Checks if a field exists in this table by the given name.

Parameters

string	$fieldname	The name of the field to check.
boolean	$checkParent	Whether to check the parent table also (via the isa relationship).

Returns

boolean True if the table contains a field by that name.

See Also

hasField()

Definition at line 931 of file Table.php.

static fieldExists (   $address,   $db = ''  )

static

Checks if a field exists. Note: To prevent deadlocks, this method should never be called inside the Dataface_Table constructor.

Parameters

string	$address	The absolute path to a field (of the form table_name.field_name).
resource	$db	A db resource connection.

Returns

boolean true if field exists; false otherwise.

Definition at line 899 of file Table.php.

& fields	(		$byTab = false,
			$includeGrafted = false,
			$includeTransient = false
	)

Returns reference to the fields array that contains field definitions.

Parameters

boolean	$byTab	Whether to group fields by tab.
booelan	$includeGrafted	Whether to include grafted fields as well.
boolean	$includeTransiet	Whether to include transient fields also.

Returns

array Array of field definition data structures.

Example Iterating Through Fields

$table = Dataface_Table::loadTable('Profiles');
$fields = $table->fields();
foreach ($fields as $fieldName=>$fieldDef){
    echo "\nField $fieldName has label ".$fieldDef['widget']['label'];
}

Note that the above exmple doesn't include any of the grafted fields or transient fields, just the fields that actually reside in the table definition.

Example Iterating Through Fields (Including Grafted):

$table = Dataface_Table::loadTable('Profiles');
$fields = $table->fields(false, true);
foreach ($fields as $fieldName=>$fieldDef){
    echo "\nField $fieldName has label ".$fieldDef['widget']['label'];
}

Definition at line 1479 of file Table.php.

format	(		$fieldname,
			$value
	)

Formats a value for a particular field to prepare it for display. This will delegate to the DelegateClass::field__format() method if it is defined. Otherwise it will use rules defined in the fields.ini file such as date_format, money_format, and display_format .

This method will be applied to output of the Dataface_Record::display() method unless the DelegateClass::fieldname__display() method is implemented, which would override the behavior completely.

Parameters

string	$fieldname	The name of the field that is being formatted.
string	$value	The string field value.

Returns

string The formatted value of the field.

Exceptions

Exception

if the field does not exist.

Since

1.4

See Also

DelegateClass::fieldname__format()

Definition at line 4900 of file Table.php.

& formFields	(		$byTab = false,
			$includeTransient = false
	)

Returns the fields that should be included in forms for editing. This includes fields from parent tables.

Parameters

boolean	$byTab	Whether to group the fields by the tab that they are in.
boolean	$includeTransient	True to include transient fields also.

Returns

array Array of field definition data structures to be included in the form.

Definition at line 1433 of file Table.php.

getActions	(	&	$params,
			$noreturn = false
	)

Returns the actions for this table.

Parameters

array

$params

An associative array of options. Possible keys include: record => reference to a Dataface_Record or Dataface_RelatedRecord object relationship => The name of a relationship. category => A name of a category for the actions to be returned.

Returns

array An associative array of action data structures.

See Also

Dataface_ActionTool

Definition at line 5500 of file Table.php.

getAutoIncrementField

(

)

Returns the name of the field that is auto incrementing (if it exists).

Returns

string The name of the autoincrement field (or null if none exists).

Definition at line 2157 of file Table.php.

getAvailableValuelistNames

(

)

Returns a list of all valuelists that are available to this table.

Returns

array Array of strings.

Definition at line 3578 of file Table.php.

static& getBackupModificationTimes (   $refresh = false )

static

Neither INNODB tables nor views store the last updated time inside of MySQL. This wreaks havoc on caching, so we create our own backup table called dataface__mtimes as a fallback mechanism to track uptime times of tables. The down side is that it only updates the timestamp when a change is made via Xataface. Outside changes aren't tracked.

Parameters

boolean

$refresh

This outputs the value from cache if possible. Setting this parameter to true overrides this to check the database again.

Returns

array(string=>long) Array of all of the table modification times in the system. Format:

     array(
        'table1' => 123456789078668
        'table2' => 987654345678967
        ...
)

See Also

Dataface_IO::createModificationTimesTable()

Dataface_IO::touchTable($tablename)

Definition at line 3135 of file Table.php.

static getBasePath (   $table )

static

Definition at line 5362 of file Table.php.

getBlockContent	(		$blockName,
			$params = array()
	)

Returns the content of a given block as a string.

Parameters

string	$blockName	The name of the block.
array	$params	Associative array of parameters to pass to the block.

Returns

string The block content as a string.

Definition at line 5285 of file Table.php.

getBodyField

(

)

Makes a best guess at which field stores the "body" of the record. The body is used in things like the RSS feed to show the "content" of the record.

Returns

string The name of the field that stores the body content.

See Also

Dataface_Record::getBody()

Definition at line 1225 of file Table.php.

getCharFields	(		$includeGraftedFields = false,
			$excludeUnsearchable = false
	)

Returns array of names of char, varchar, and text fields. These are the fields that can be searched using full text searches.

Parameters

boolean	$includeGraftedFields	If true, then this will also return grafted fields.
boolean	$excludeUnsearchable	If true then this will exclude fields that are marked as unsearchable.

Returns

array(string) Names of fields.

Definition at line 1331 of file Table.php.

& getChildrenRelationship

(

)

Gets the relationship that should be used as the children relationship. This is useful for representing heirarchical structures.

Returns

Dataface_Relationship The relationship used as the children relationship.

Definition at line 3699 of file Table.php.

getCreatedField

(

)

Makes a best guess at which field stores the creation date of the record.

Returns

string The name of the best candidate column.

See Also

Dataface_Record::getCreated()

Definition at line 1129 of file Table.php.

getCreateTime

(

)

Returns the creation time of this table as an SQL DateTime string.

Returns

string

Definition at line 3228 of file Table.php.

getCreatorField

(

)

Makes a best guess at which field stores the username of the person who created the record.

Returns

string The name of the best candidate for the creator column.

See Also

Dataface_Record::getCreator()

Force a pattern match for field to be considered

Definition at line 1148 of file Table.php.

getDefaultRelationshipRange

(

)

Gets the default relationship range for all relationships.

Returns

array(int,int) 2 element array With lower and upper bounds of relationship.

See Also

setRelationshipRange()

getRelationshipRange()

Definition at line 3756 of file Table.php.

getDefaultValue

(

$fieldname

)

Returns the default value for a field.

Parameters

string

$fieldname

The name of the field.

Returns

string

Definition at line 1864 of file Table.php.

& getDelegate

(

)

Returns a reference to the Table's delegate class.

Returns

DelegateClass

Definition at line 3947 of file Table.php.

getDescriptionField

(

)

Makes a best guess at which field in this table stores the record description. The record description is displayed in various logical places throughout the UI.

Returns

string The name of the best candidate column to be the description.

See Also

Dataface_Record::getDescription()

Definition at line 1107 of file Table.php.

& getField

(

$fieldname

)

Returns a field structure with the given name. This can also be related field. Simply prepend the relationship name followed by a period. eg: relationship_name.field_name.

Parameters

string

$fieldname

The name of the field for which we with to retrieve the construct.

Returns

PEAR_Error if the field requested does not exist or there was a problem processing the relationship (if a relationship is specified).

array Associative array with all attributes of the specified field if the field exists.

See Also

fields()

Definition at line 2030 of file Table.php.

& getFieldgroup

(

$fieldgroupname

)

Returns an associative array describing a field group.

Parameters

string

$fieldgroupname

The name of the field group to obtain.

Returns

array Data structure of field group properties.

Sample group:

array(
"element-display" => "inline",                  // Elements displayed inline
                                                                                //  poss vals: ENUM("inline","block")
"element-label-visible" => true,                // Show labels for elements
"element-description-visible" => true,  // Show descriptions for elements
"label" => "My Group",                                  // Label for the entire group
"description" => "This is a group of elements");

See Also

getField()

Definition at line 4220 of file Table.php.

& getFieldgroups

(

)

Returns associative array of all of the field group definitions (keys are the fieldgroup names).

Returns

array Associative array of the form:

array(
      groupName:String => groupConfig:array
)

See Also

getFieldGroup()

Definition at line 4245 of file Table.php.

getFieldProperty	(		$propertyName,
			$fieldname,
			$params = array()
	)

This method returns a property associated with a field, that is defined in the fields.ini file. This method also checks the delegate class to see if an equivalent property method has been defined. Delegate class method names will be of the form <field_name>__<property_name>(). Note that in the case where the property name contains illegal characters (e.g., ':'), the character will be replaced by an underscore ( i.e., '_').

Parameters

string	$propertyName	The name of the property. (e.g., 'widget:label')
string	$fieldName	The name of the field
array	$params	Optional named parameters: record : A reference to a Dataface_Record object that can be used to provide context about which record is being edited.

Since

0.6

See Also

getField()

fields()

Definition at line 2103 of file Table.php.

getFullTextIndexedFields

(

)

Returns an array of field names that have full text indexes.

A full-text index allows MySQL full-text searches to be performed on the contents of those fields. In MySQL 4+ full text searches may be performed on fields without a fulltext index but this will be slow.

Returns

array(string) Names of fields with full text indexes.

Definition at line 1306 of file Table.php.

static& getGlobalFieldsConfig ( )

static

Definition at line 2167 of file Table.php.

& getImportFilters

(

)

Import filters facilitate the importing of data into the table.

Returns

array Array of Dataface_ImportFilter objects

See Also

DelegateClass::importfiltername()

Definition at line 4281 of file Table.php.

getImportTables

(

)

Gets the tables from the database that are explicitly for importing data. They are tables of the form Tablename__import__<timestamp> where <timestamp> is the unix timestamp of when the import table was created.

Returns

array Array of string table names.

See Also

createImportTable()

Definition at line 4347 of file Table.php.

& getIndexes

(

)

Returns an associative array of indexes in this table.

Returns

array(string=>array) Array of index data structures describing the indexes in this table. It should follow the format:

array(
                <IndexName: string> => array(
                name => <string>                // The name of the index
                unique => <boolean>     // whether it is a unique index.
                type => <string>                // The type of index e.g. b-tree, hash, etc...
                comment => <string>     // Any comments added when the index was created
                columns => array(string) // Array of column names in this index.
        )
        ...
)

Definition at line 1266 of file Table.php.

getLabel

(

)

Gets the label for this table. This is displayed in the navigation menu (table tabs).

Returns

string The table's label.

Definition at line 2975 of file Table.php.

getLastUpdatedField

(

)

Makes a best guess at which field stores the last modified date of the record.

Returns

string The name of the column that stores the last modified date.

See Also

Dataface_Record::getLastModified()

Definition at line 1207 of file Table.php.

getMetadataColumns

(

)

Returns an array of names of columns in the metadata table for this table. The metadata table contains metadata such as state and translation state for the corresponding records of this table. Fields of this table that are considered to be metadata must begin with two underscores to signify that they are metadata.

If no metadata table yet exists, it will be created.

Returns

array List of column names.

Definition at line 1400 of file Table.php.

& getParent

(

)

Gets the parent table of this table to help model inheritance. The parent table can be specified by the isa attribute of the fields.ini file.

Returns

Dataface_Table The parent table of this table.

Definition at line 3054 of file Table.php.

& getParentRelationship

(

)

Gets the relationship that should be used as the parent relationship. This is useful for representing heirarchical structures.

Returns

Dataface_Relationship The relationship to be used as the parent relationship.

Definition at line 3681 of file Table.php.

getPermissions

(

$params = array()

)

Obtains the permissions for a particular record or for this table. Parameters are passed in associative array as key value pairs.

Parameters

Dataface_Record	record The context record for which to check permissions (optional).
string	field The name of the field for which to check permissions (optional).
string	relationship The name of the relationship for which to check permissions (optional).
boolean	nobubble If this is true and field or relationship is set, it will only return the permissions applied to the particular field/relationship and not overlay those permissions on the the record permissions. The default behavior is to overlay these on the record. See DelegateClass::fieldname__permissions() for a flowchart of how permissions are evaluated. Setting 'nobubble' to true will circumvent this process to just produce the permissions defined for the particular field or relationship.
array	recordmask Optional permissions mask to be laid under the record permissions.
array	relationshipmask Optional permissions mask to lay under the relationship permissions.

Returns

array Associative array mapping permission names to boolean values indicating whether the user is granted or denied permission to each permission.

See Also

Dataface_Record::getPermissions()

Dataface_PermissionsTool

Definition at line 2687 of file Table.php.

getProxyView

(

)

Returns the name of the VIEW to be used for reading records from the database. This feature is new in version 1.2 and is intended to improve performance by NOT using subqueries to implement support for sql parameters on tables. We'll see if this makes a big difference to mysql.

This method will return the name of the view to be used. If no custom SQL has been defined this will return null. If mysql doesn't support views, this will return null.

Returns

string The name of the proxy view to use to fetch records of this table or null if none exists.

Definition at line 1744 of file Table.php.

& getRecord

(

$query = null

)

Gets a record from the database that matches the given query.

Parameters

array

$query

associative array of key/value search terms.

Returns

Dataface_Record The matching record in this table.

See Also

df_get_record()

Definition at line 5326 of file Table.php.

& getRelationship

(

$name

)

Gets a relationship by name.

Parameters

string

$name

The name of the relationship to retrieve.

Returns

Dataface_Relationship The relationship with the specified name on this table.

See Also

relationships()

Definition at line 3789 of file Table.php.

getRelationshipPermissions	(		$relationshipName,
			$params = array()
	)

Gets the permissions for a particular relationship.

This is a wrapper around getPermissions() that automatically specifies the relationship as a parameter. I.e. The following are equivalent:

$table->getRelationshipPermissions('foo')

and

$table->getPermissions(array('relationship'=>'foo'))

Parameters

string	$relationshipName	The name of the relationship to check.
array	$params	The other parameters (possible keys include 'field' and 'record'). See getPermissions() for full list of parameters.

Returns

array A bit mask of permissions. Format:

array(
     permissionName:String => allowed:int (either 0 or 1)
)

See Also

getPermissions()

Dataface_Record::getPermissions()

Definition at line 2658 of file Table.php.

getRelationshipRange

(

$relationshipName

)

Gets the range of records that should be returned for a given relationship when records are returning their related records.

Parameters

string

$relationshipName

Returns

array(int,int) Array with the lower and upper indices that should be returned.

See Also

Dataface_Record::getRelatedRecords()

Dataface_Record::getRelatedRecordObjects()

Definition at line 3723 of file Table.php.

getRelationshipsAsActions	(		$params = array(),
			$relationshipName = null,
			$passthru = false
	)

Returns a list of the relationships for this table as actions.

Relationships can carry any action attributes and indeed can be treated as actions themselves for purposes of displaying menus of the various relationships primarily.

Parameters

array	$params	Parameters that are passed to Dataface_ActionTool to filter the actions.
string	$relationshipName	The name of the relationship to retrieve as an action.
boolean	$passthru	Not used anymore.

Returns

array Associative array of action attributes.

See Also

Dataface_ActionTool::getActions()

Definition at line 3827 of file Table.php.

getSecurityFilter

(

$filter = array()

)

Returns the security filter for this table.

Parameters

array

$filter

An array of filters to overlay the current security filter with.

Returns

array The resulting query.

Definition at line 2623 of file Table.php.

getSerializer

(

)

Gets the serializer object that is used to serialize data in this table.

Returns

Dataface_Serializer The serializer object.

Definition at line 5439 of file Table.php.

getSingularLabel

(

)

Returns the label for this table as a singular. Often tables are named as plurals of the entities they contain. This will attempt to get the name of the singular entity for use in UI items where referring to the items of the table in singular is more appropriate e.g. New Person.

This will use the singular_label directive of the fields.ini file if it is defined. Otherwise it will try to determine the singular of the label on its own.

Returns

string

Definition at line 2991 of file Table.php.

& getStatus

(

)

Returns the status of this table. Includes things like modification time, etc...

Returns

array

Definition at line 3087 of file Table.php.

& getTab	(		$tabname,
			$record = null
	)

Returns specified tab's properties.

Parameters

string	$tabname	The name of the tab to retrieve.
Dataface_Record	$record	(Optional) The record that is being edited.

Returns

array Data structure of tab properties.

Definition at line 4133 of file Table.php.

static& getTableField (   $address,   $db = ''  )

static

Returns field information given its address. Note: To prevent deadlocks, this method should never be called inside the Dataface_Table constructor.

Parameters

string	$address	The address to a field. eg: Profile.fname is the address of the fname field in the Profile table.
resource	$db	A db resource id.

Exceptions

PEAR_Error

if Address is invalid or the table or field does not exist.

Returns

array The field definition array from the appropriate table.

Definition at line 869 of file Table.php.

static& getTableModificationTimes (   $refresh = false )

static

Returns an associative array mapping table names to their associated modification as a unix timestamp.

Note that these values may not be accurate for views and innodb tables. Not sure if this is a MySQL bug or a feature.

Parameters

boolean

$refresh

Whether to refresh the stats or use cached version. Generally leave this false as it updates once per request anyways.

Returns

array(string=>timestamp) Associative array of table names and their associated modification timestamps.

Definition at line 3172 of file Table.php.

& getTableTableForField

(

$fieldname

)

Returns the Table object that contains a specified field. The fieldname is given as a relationship path (as opposed to an absolute path. This method cannot be called statically.

Parameters

string

$fieldname

The name of the field.

Returns

Dataface_Table The table containing the specified field.

Definition at line 3901 of file Table.php.

getTabs

(

)

Returns an array of strings that are the names of the tabs for this table. Fields can be grouped into tabs by specifying a 'tab' attribute in the fields.ini file. This is just a list of the tabs that are specified.

Deprecated:

This method should no longer be used. Rather, you should use array_keys($this->tabs());

See Also

tabs()

Definition at line 4069 of file Table.php.

& getTranslation

(

$name

)

Returns an array of column names that are available in a given language.

Parameters

string

$name

The 2-digit language code for the translation.

Returns

array Array of column names - if translation exists. Null if translation does not exist.

Definition at line 2908 of file Table.php.

& getTranslations

(

)

Returns associative array of translations where the key is the 2-digit language code and the value is an array of column names in the translation.

Returns

array(string=>array(string))

Definition at line 2853 of file Table.php.

getTranslationStates

(

)

Gets array of translation states available.

Returns

array(string=>string)

Definition at line 2943 of file Table.php.

getType

(

$fieldname

)

Returns the type of a field , eg: int, float, varchar, blob, etc...

Parameters

string

$fieldname

The name of the field whose type we wish to have returned.

Returns

string The type of the field.

Definition at line 4609 of file Table.php.

getUpdateTime

(

)

Returns the update time as an SQL DateTime string for this table.

Returns

string The update time of this table as a MySQL DateTime string.

Definition at line 3217 of file Table.php.

getValueAsString	(		$fieldname,
			$value
	)

Gets the values of this record as strings. Some records like dates and times, are stored as data structures. getValue() returns these datastructures unchanged. This method will perform the necessary conversions to return the values as strings.

Parameters

string	$fieldname	The name of the field for which the value is being stringified.
mixed	$value	The value that is to be stringified.

Returns

string The stringified value.

See Also

DelegateClass:fieldname__toString()

Definition at line 4853 of file Table.php.

& getValuelist

(

$name

)

Returns a named valuelist in this table.

Parameters

string

$name

The name of the valuelist to retrieve.

Returns

array The valuelist values.

See Also

valuelists()

Definition at line 3503 of file Table.php.

getVersionField

(

)

Gets the field that is used to track the version of this record, if one is set. The version field is set by setting the "version" directive for a field in the fields.ini file.

If a table is versioned, then any attempt to update records where the version differs from the version in the database will fail.

Returns

String The name of the field used for versioning - or null if none.

Definition at line 1170 of file Table.php.

& graftedFields

(

$includeParent = true

)

Field definitions of fields that have been grafted onto this table.

It is possible to provide an 'sql' parameter to the fields.ini file that will provide a custom query to be performed. This is really only meant for grafting extra columns onto the table that weren't there before. These columns will appear in list and view mode, but you won't be able to edit them.

Parameters

boolean

$includeParent

Whether to include grafted fields from the parent table (via the isa directive).

Returns

array Array of field definitions of grafted fields. Each field def is of the form:

     array(
                'Field'=>fieldname, 
        'Type'=>varchar(32), 
        'widget'=>array(
                'label'=>.., 
                'description'=>..
        )
)

Definition at line 1560 of file Table.php.

guessField	(		$types,
			$patterns,
			$forcePattern = false
	)

Tries to find a field that best matches the criteria we provide. This is useful for finding e.g. description, last modified, and title fields.

Parameters

	array(string=>int)	$types Associative array of field types (e.g. varchar) and their corresponding value if matched.
	array(string=>int)	$patterns Associative array of regular expession patters and their corresponding score values.
boolean	$forcePattern	If true, then it will only return a value if the pattern matches. Otherwise it will produce the best/closest match.

Returns

string The name of the field that best matches the criteria.

Examples:

$this->descriptionField = $this->guessField(
         array('text'=>10, 'mediumtext'=>10, 'shorttext'=>10, 'longtext'=>2,
             'varchar'=>1, 'char'=>1),
         array('/description|summary|overview/'=>10, '/desc/'=>2)
);

Definition at line 1068 of file Table.php.

hasField	(		$fieldname,
			$checkParent = true
	)

Checks if a field exists in this table by the given name. Alias of hasField()

Parameters

string	$fieldname	The name of the field to check.
boolean	$checkParent	Whether to check the parent table also (via the isa relationship).

Returns

boolean True if the table contains a field by that name.

Definition at line 941 of file Table.php.

hasJoinTable	(		$tablename,
		&	$record
	)

Indicates whether or not this table has a join table.

Parameters

string	$tablename	The name of the table to check if it is joined.
Dataface_Record	&$record	The record context.

Returns

boolean True if the specified table is a join table of the current table.

See Also

join()

Dataface_Record::getJoinRecord()

Definition at line 4177 of file Table.php.

hasKey

(

$name

)

Checks to see if the specified field is part of the primary key.

Parameters

string

$name

The name of the field to check.

Returns

boolean True if the specified field is part of the primary key.

See Also

keys()

Definition at line 1821 of file Table.php.

hasRelationship

(

$name

)

Checks if this table has a relationship with the specified name.

Parameters

string

$name

The name of the relationship to check.

Returns

boolean True if the table has a relationship named $name.

See Also

getRelationship()

relationships()

Definition at line 3807 of file Table.php.

implementsOntology

(

$ontologyName

)

Indicates whether this table is declared as implementing the given ontology.

A table can be specified as implementing an ontology by adding the ontology to the implements section of the fields.ini file for the table.

Parameters

string

$ontologyName

The name of the ontology.

Returns

boolean True if the table implements the givcen ontology.

See Also

Dataface_Ontology

Definition at line 3075 of file Table.php.

isBlob

(

$fieldname

)

Checks a field to see if it is a blob type.

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field is a blob type.

Definition at line 4654 of file Table.php.

isChar

(

$fieldname

)

Checks to see if the field is a character field (i.e. varchar or char).

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field is a character field.

Definition at line 4711 of file Table.php.

isContainer

(

$fieldname

)

Indicates if a field is a container field. A container field is a varchar or char field but it contains the path to a file rather than data itself.

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field is a container field.

See Also

http://xataface.com/documentation/how-to/how-to-handle-file-uploads

Definition at line 4667 of file Table.php.

isDate

(

$fieldname

)

Checks a field to see if it is a date type (date, datetime, time, or timestamp).

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field is a date type.

Definition at line 4639 of file Table.php.

isFloat

(

$fieldname

)

Checks to see if the field is a floating point field (i.e. float, double, tinyfloat, etc..)

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field is a floating point field.

Definition at line 4730 of file Table.php.

isImportTable

(

$tablename

)

Checks if a given table is an import table as created with createImportTable().

Parameters

string

$tablename

The name of the table to check.

Returns

boolean True if $tablename is an import table.

See Also

createImportTables()

cleanImportTables()

getImportTables()

Definition at line 4424 of file Table.php.

isInt

(

$fieldname

)

Checks to see if the field is an INT field.

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field is a character field.

Definition at line 4720 of file Table.php.

isMetaField

(

$fieldname

)

Indicates if the given field acts as a meta field that describes an aspect of another field. For example, some fields simply contain the mimetype of a blob field. Such a field is a meta field.

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field specified is a meta field.

Definition at line 1367 of file Table.php.

isPassword

(

$fieldname

)

Checks to see if the field is a password field. Any field with widget:type=password is regarded as a password field.

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field is a password field.

Definition at line 4679 of file Table.php.

isSearchable

(

$field

)

Checks if a field is searchable. Fields can be made unsearchable by setting the not_searchable directive in the fields.ini file.

Parameters

string

$field

The name of the field to check.

Returns

boolean True if the field is searchable.

Definition at line 1353 of file Table.php.

isText

(

$fieldname

)

Checks to see if the field is a text field (e.g. text, longtext, tinytext, or mediumtext).

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field is a text field.

Definition at line 4690 of file Table.php.

isVersioned

(

)

Definition at line 1194 of file Table.php.

isXML

(

$fieldname

)

Checks to see if the field is stored in XML format. Only the 'table' and 'group' widgets cause the data to be stored as XML.

Parameters

string

$fieldname

The name of the field to check.

Returns

boolean True if the field is stored in XML format.

Definition at line 4701 of file Table.php.

isYesNoValuelist	(		$valuelist_name,
		&	$yes,
		&	$no
	)

Checks if a valuelist is just a boolean valuelist. It will also return (via output parameters) what the corresponding yes/no values are.

Parameters

string	$valuelist_name	The name of the valuelist to check.
mixed	&$yes	Output parameter to store the "yes" value of the valuelist.
mixed	&$no	Output parameter to store the "no" value of the valuelist.

Returns

boolean True if the valuelist is a yes/no valuelist.

Definition at line 3254 of file Table.php.

& keys

(

)

Returns reference to the keys array that contains field definitions for keys.

Returns

array Associative array of field definitions that are part of the primary key. Format:

array(
     fieldName:String => fieldData:array
)

See Also

fields()

Definition at line 1810 of file Table.php.

loadPermissions

(

)

Loads the permissions from the permissions.ini files.

Returns

void

Definition at line 2824 of file Table.php.

static& loadTable (   $name,   $db = null,   $getAll = false,   $quiet = false  )

static

Loads the table object for a database table.

This is the prefered way to create a new table. If the table already exists for the specified table, then a reference to that table is returned. If it does not exist, then the table is created, and a reference to it is returned.

Parameters

string	$name	The name of the table for which the table should be returned.
resource	$db	A db connection handle.
boolean	$getAll	If true then this will return an array of all of the tables loaded.
boolean	$quiet	Whether to show debugging information.

Returns

Dataface_Table The singleton object for the table.

Definition at line 474 of file Table.php.

& mandatoryFields

(

)

A list of the keys that are NOT auto incremented.

Returns

array Associative array of field definitions. Format:

array(
        fieldName:String => fieldData:array
)

See Also

fields()

Definition at line 1843 of file Table.php.

newRecord

(

$vals = null

)

Returns a new blank Dataface_Record object for this table.

Parameters

array

$vals

Associative array of values to initialize in this record.

Returns

Dataface_Record A new record for this table.

Definition at line 5316 of file Table.php.

normalize	(		$fieldname,
			$value
	)

Takes a value a normalizes it to a string representation of the value as encoded for the specified field. This is useful for equality comparisons on values of fields.

Parameters

string	$fieldname	The full path of the field on which we are normalizing.
mixed	$value	The value which we are normalizing.

Returns

string The normalized value with respect to the field name.

Definition at line 4836 of file Table.php.

parse	(		$fieldname,
			$value,
			$parseRepeat = true
	)

Parses a value so that it conforms with the value stored in the given field.

Parameters

string	$fieldname	The name of the field that where the value should be storable.
mixed	$value	The value we wish to parse.
boolean	$parseRepeat	If true, this indicates that if this is a repeating field, then all of it's repeats should also be parsed individually.

Returns

mixed The parsed value.

Definition at line 5020 of file Table.php.

parse_date

(

$value

)

Alias of parse_datetype()

See Also

parse_datetype()

Definition at line 4772 of file Table.php.

parse_datetime

(

$value

)

Parses a value intended to be placed into a date field and converts it to a normalized format.

Parameters

mixed

$value

The input value to be normalized.

Returns

array Datetime associative array standard format. E.g.

array('year'=>2010, 'month'=>10, 'day'=>2, 'hours'=>9, 'minutes'=>23, 'seconds'=>5);

See Also

parse_datetype()

Definition at line 4762 of file Table.php.

parse_repeated	(		$fieldname,
			$value,
			$separator = "\n"
	)

Parses a value for a repeated field.

Parameters

string	$fieldname	The name of the field for which the value is being parsed.
mixed	$value	The value that is to be parsed.
string	$separator	The separator to be placed between each of the values in this repeated field.

Returns

mixed The parsed value.

Definition at line 5091 of file Table.php.

parse_time

(

$value

)

Alias of parse_datetype()

See Also

parse_datetype()

Definition at line 4802 of file Table.php.

parse_timestamp

(

$value

)

Parses a date, but also recognizes teh CURRENT_TIMESTAMP keyword string to return the current timestamp in normalized format.

Parameters

mixed

$value

The input date in any number of formats including the string 'CURRENT_TIMESTAMP'.

Returns

array Datetime associative array standard format. E.g.

array('year'=>2010, 'month'=>10, 'day'=>2, 'hours'=>9, 'minutes'=>23, 'seconds'=>5);

See Also

parse_datetype()

Definition at line 4790 of file Table.php.

parseImportData	(		$data,
			$importFilter = null,
			$defaultValues = array()
	)

Prepares data to be imported into the table. It takes raw data and produces an array of Dataface_Record objects that can be imported into the table.

Parameters

mixed	$data	Raw data that is to be imported.
string	$importFilter	The name of the import filter that is used to import the data. If this is null then every import filter is attempted until one is found that works.
array	$defaultValues	The default values to add to imported records.

Returns

array An array of Dataface_Record objects encapsulating the imported data. These objects must be records of the current table.

Exceptions

PEAR_Error

if the importing fails for some reason.

Usage:

$data = '<phonelist>
                        <listentry>
                                <name>John Smith</name><number>555-555-5555</number>
                        </listentry>
                        <listentry>
                                <name>Susan Moore</name><number>444-444-4444</number>
                        </listentry>
                </phonelist>';

                // assume that we have an import filter called 'XML_Filter' that can import the above data.

$table =& Dataface_Table::loadTable('ListEntry');
$records = $table->parseImportData(     $data,                  // The raw data to import
                                                                        'XML_Filter'    // The name of the filter to handle the import
                                                                        );

echo get_class($records[0]);            // outputs 'Dataface_Record'
echo $records[0]->val('name');  //outputs 'John Smith'
echo $records[0]->val('number'); // outputs '555-555-5555'
echo $records[1]->val('name');  // outputs 'Susan Moore'
echo $records[1]->val('number');        // outputs '444-444-4444'

// Note that the records in the $records array are NOT persisted in the database.

See Also

Dataface_Table::loadTable()

Dataface_Table::getImportFilters()

Dataface_Record::val()

Definition at line 4482 of file Table.php.

registerImportFilter

(

&

$filter

)

Parameters

	Registers	an import filter for this table.
Dataface_ImportFilter	$filter	The import filter to register.

Returns

void

See Also

getImportFilters()

DelegateClass::importfiltername()

Definition at line 4327 of file Table.php.

& relationships

(

)

Returns reference to the relationships array for this table.

Returns

array Associative array of relationships in this table.

See Also

getRelationship()

Definition at line 3880 of file Table.php.

relativeFieldName

(

$fieldname

)

Returns the relative field name given either a relative name or an absolute name.

Parameters

string

$fieldname

The name of the field.

Returns

string The relative name of the field.

Definition at line 1024 of file Table.php.

static setBasePath (   $table,   $path  )

static

Definition at line 5359 of file Table.php.

setDefaultRelationshipRange	(		$lower,
			$upper
	)

Sets the default relationship range to be used for all relationships.

Parameters

int	$lower	The default lower bound for relationships of this table.
int	$upper	The default upper bound for relationships of this table.

Definition at line 3766 of file Table.php.

setRelationshipRange	(		$relationshipName,
			$lower,
			$upper
	)

Sets the range of related records that should be returned by records of this table when getting records in the given relationship.

Parameters

string	$relationshipName	The name of the relationship.
int	$lower	The lower index to be returned.
int	$upper	The upper index to be returned

Returns

void

See Also

Dataface_Record::getRelatedRecords()

Dataface_Record::getRelatedRecordObjects()

Definition at line 3743 of file Table.php.

setSecurityFilter

(

$filter = null

)

Sets a security filter on the table. A security filter is an array of key/value pairs that are automatically added to any query of this table to limit the results.

Parameters

array

$filter

The query that should be used for a filter. This value will overwrite any previous security filter that had been set.

Returns

void

Example, filtering so that only records with schoolID=10 will be returned.

$table->setSecurityFilter(array('schoolID'=>10));
        // Will only show results where schoolID is 10

A good place to set security filters is in the DelegateClass::init() method. e.g.:

function init($table){
    $table->setSecurityFilter(array('schoolID'=>10));
}

Definition at line 2584 of file Table.php.

setVersionField

(

$field

)

Sets the name of the field that should be used to version records of this table.

Parameters

String

$field

The name of the field that should be used for versioning.

Returns

void

Definition at line 1190 of file Table.php.

sql

(

)

Returns the SQL query used to fetch records of this table, if defined.

This is only applicable the fields.ini contains an sql directive or the delegate class implements the sql() method. Will return null otherwise.

Returns

mixed String SQL query if defined. Null otherwise.

See Also

DelegateClass::sql()

Definition at line 1717 of file Table.php.

static tableExists (   $tablename,   $usecache = true  )

static

Checks if the given table exists. This caches the results so that you won't have to check the existence of the same table twice.

Parameters

string	$tablename	The name of the table to check.
boolean	$usecache	Whether to use the cache or not.

Returns

boolean Whether the table exists or not.

Definition at line 913 of file Table.php.

tableInfo

(

)

Print information about Table.

Deprecated:

Definition at line 3003 of file Table.php.

& tabs

(

$record = null

)

Returns an associative array of tab definitions of the form: [tabname] -> [tab_properties].

This merges together any join tables that haven't been defined as a tab explicitly also.

Parameters

Dataface_Record

&$record

A record to provide context. This will allow us to return different tabs for different records via the tabs method of the delegate class.

Returns

array Associative array of tabs and their properties data structures. Format:

array(
        'tab1'=>array(
                'label'=>'The First Tab'
                'description' => 'The tab description'
                'order' => 4
                ... etc...
        ),
        'tab2'=>array( .... )
                ... etc...
);

Definition at line 4098 of file Table.php.

titleColumn

(

)

A valid SQL select phrase for a single column. This will be used when extracting the titles of each row from the database.

Returns

string The SQL select clause defining the title of a record in this table.

Example output:

fname

or

CONCAT(fname,' ',lname)

Output can be overridden in the delegate class.

See Also

DelegateClass::titleColumn()

titleColumn vs getTitle

The titleColumn method is used in places where we want to obtain a list of record titles from the database but don't want to have to load each full record into memory. The getTitle() method is used only if we already have the record loaded into memory.

If you override one of these methods, you should override the other also.

Default Value

If you don't explicitly set this value, Xataface will try to make a best guess at which column should be used as the title based on column type and possibly the column names. It favours varchar columns if it can find one.

See Also

getTitle()

Definition at line 1989 of file Table.php.

& transientFields

(

$includeParent = false

)

Returns the transient fields in this table. Transient fields are fields that do not get saved in the database (i.e. have no corresponding field in the database. They are useful for creating fields on the new/edit forms.

Parameters

boolean

$includeParent

Whether to include fields from the parent record.

Returns

array Associative array of field definition data structures.

Definition at line 1614 of file Table.php.

validate	(		$fieldname,
			$value,
		&	$params
	)

Validates against a field of this table. This checks if a value is valid for this a field of this table.

Parameters

string	$fieldname	The name of the field
mixed	$value	The value to validate for the field.
array	$params	Array of parameters. This may be used to pass parameters OUT of this function. For example. Setting the 'message' attribute of this array will pass out a message to be displayed to the user along with the error upon failed validation.

Returns

boolean True if it validates ok, false otherwise.

Definition at line 5142 of file Table.php.

& valuelists

(

)

Returns the valuelists in this table.

Returns

array Associative array of valuelists. Keys are the valuelist names, values are associative array of valuelist values.

Attention

This may not return all of the valuelists. ONly the ones that have already been loaded with getValuelist()

See Also

getValuelist()

Definition at line 3563 of file Table.php.

Field Documentation

$db

DB connection handle. resource handle.

Definition at line 128 of file Table.php.

$errors = array()

Store errors that occur in methods of this class.

Definition at line 310 of file Table.php.

$tablename

The name of the table that this table represents. string.

Definition at line 122 of file Table.php.

$versionField = -1

Definition at line 446 of file Table.php.

---

The documentation for this class was generated from the following file:

• Dataface/Table.php