Encapsulates a row in a relationship. This may contain fields that span across multiple tables. It implements many of the same methods as the Dataface_Record. More...

Public Member Functions
	Dataface_RelatedRecord ($record, $relationshipName, $values=null)
	Creates new blank related record whith the specified base record and relationship name.
Utility Methods
Miscellaneous housekeeping functions.
	clearCache ()
	Clears the cached values. This is used internally to clear calculated values when something is changed.
&	toRecord ($tablename=null)
	Produces a Dataface_Record object representing the portion of this related record that is stored in a particular table.
	toRecords ()
	Returns an array of Dataface_Record objects that represent collectively this related record.
&	getParent ()
	Gets reference to the parent record (base record).
	testCondition ($condition)
	Takes a boolean expression resembling an SQL where clause and evaluates it based on the values in this record.
	getActions ($params=array())
	Returns actions associated with this record.
Transactions
Methods to deal with transactions and change tracking (so that we know what has changed since we loaded the data from the db).
	clearFlags ()
	Clears the dirty flags to indicate the current state of the record is consistent with the database - or at least nothing needs to be saved.
	setFlag ($fieldname)
	Sets a flag on a field to indicate that it has changed and should be saved.
	clearFlag ($fieldname)
	Clears a flag on a field to indicate that it has no changes since loading.
	isDirty ($fieldname)
	Checks if a particular field has changed since we loaded it (i.e. it is dirty).
Accessing Field Data
Methods for getting and setting field/column values in the record.
	setMetaDataValue ($key, $value)
	Sets a meta data value for a field.
	getLength ($fieldname)
	Gets the length of a field's value (in bytes or characters).
	setValue ($fieldname, $value)
	Sets the value for a field of this related record.
	setValues ($values)
	Sets multiple values at once.
	getValue ($fieldname)
	Gets the value for a field.
	getValueAsString ($fieldname)
	Gets the string value of a given field.
	htmlValue ($fieldname)
	Gets a field value as HTML.
	getValuesAsStrings ($fields='')
	Gets the values stored in this table as an associative array. The values are all returned as strings.
	strvals ($fields='')
	strval ($fieldname, $index=0)
	stringValue ($fieldname)
&	getValues ($columns=null, $excludeNulls=false)
	Gets the values of this related record.
&	values ($fields=null)
&	vals ($fields=null)
	val ($fieldname)
	getAbsoluteValues ($excludeNulls=false, $includeAll=false)
	Gets the values of this related record except that the keys of the returned associative array are absolute column names rather than relative names as are returned in getValues().
	getForeignKeyValues ($sql=null)
	Returns 2-Dimensional associative array of the values in this related record and in any join table. The output of this method is used to add and remove related records.
	getUnconstrainedFields ($sql=null)
	Gets a list of fields that are unconstrained (i.e. can be edited. This is helpful when building forms for this record.
	getConstrainedFields ($sql=null)
	Returns a list of fields in this related record that are constrained (i.e. cannot be changed.
	getUnconstrainedTables ($sql=null)
	Gets a list of the tables in this related record that are unconstrained. Unconstrained tables are ones that contain fields that are unconstrained.
	display ($fieldname)
	Returns a the value of a field in a meaningful state so that it can be displayed.
	preview ($fieldname, $index=0, $maxlength=255)
	Shows a short preview of field contents. Useful for text fields when we just want to see the first bit of the field. This will also strip all html tags out of the content.
	printValue ($fieldname)
	printval ($fieldname)
	q ($fieldname)
	qq ($fieldname)
Metadata
Methods to get descriptive information about this record.
	getId ()
	Returns the Id of this related record object. The id is a string in a url format to uniquely identify this related record. The format is: tablename/relationshipname?parentkey1=val1&parentkey2=val2&relationshipname::key1=val2&relationshipname::key2=val3.
	getTitle ()
	Gets the record title. This wraps the domain record's getTitle() method.
Form Handling
	validate ($fieldname, $value, &$params)
	Validates a value against a field name. Returns true if the value is a valid value to be stored in the field.
Saving
	save ($lang=null, $secure=false)
Permissions
Methods for checking permissions for this record.
	getPermissions ($params=array(), $table=null)
	checkPermission ($perm, $params=array())
	Checks to see if the current user is granted the specified permission on this record.

Data Fields
	$secureDisplay = true
	Flag to indicate whether display methods like display() and htmlValue should be constrained by permissions. Default is true. boolean.
	$_record
	The base record of the relationship. Dataface_Record.
	$_relationshipName
	The name of the relationship. string.
	$_relationship
	Reference to the relationship. Dataface_Relationship.

Detailed Description

Encapsulates a row in a relationship. This may contain fields that span across multiple tables. It implements many of the same methods as the Dataface_Record.

File: Dataface/RelatedRecord.php Author: Steve Hannah shann.nosp@m.ah@s.nosp@m.fu.ca Created: October 2005

Description: Represents a record that is part of a relationship.

Synopsis

Related records will be most often encountered as the output of Dataface_Record::getRelatedRecordObjects() However you can construct your own objects and use the Dataface_IO::addRelatedRecord() or Dataface_IO::addExistingRelatedRecord() methods for adding your record to the relationship.

Example Usage

Getting related records from a Dataface_Record object.

$author = df_get_record('people', array('person_id'=>10));
$books = $author->getRelatedRecordObjects();
foreach ($books as $book){
    echo "Book Title: ".$book->val('title')."\n";
}

Getting the Dataface_Record object that encapsulates the domain table of this relationship:

$bookRec = $book->toRecord();

Definition at line 61 of file RelatedRecord.php.

Member Function Documentation

checkPermission	(	$perm,
		$params = `array()`
	)

Checks to see if the current user is granted the specified permission on this record.

This is essentially a wrapper for the domain record's checkPermission() method.

Parameters

string	$perm	The name of the permission to check.
array	$params	Optional parameters. See Dataface_Record::checkPermission() for details of what can be included in this parameter.

Returns: boolean True if the user is granted the permission.

See Also: Dataface_Record::checkPermission(); Dataface_Table::getPermissions(); Dataface_PermissionsTool::getPermissions()

Definition at line 1356 of file RelatedRecord.php.

clearCache ( )

Clears the cached values. This is used internally to clear calculated values when something is changed.

Returns: Dataface_RelatedRecord Self for chaining.

Definition at line 210 of file RelatedRecord.php.

clearFlag ( $fieldname )

Clears a flag on a field to indicate that it has no changes since loading.

Parameters

string $fieldname The name of the field to mark "clean".

Returns: Dataface_RelatedRecord Self for chaining.

Definition at line 399 of file RelatedRecord.php.

clearFlags ( )

Clears the dirty flags to indicate the current state of the record is consistent with the database - or at least nothing needs to be saved.

Returns: Dataface_RelatedRecord Self for chaining.

Definition at line 379 of file RelatedRecord.php.

Dataface_RelatedRecord	(	$record,
		$relationshipName,
		$values = `null`
	)

Creates new blank related record whith the specified base record and relationship name.

Parameters

Dataface_Record	$record	Reference to Dataface_Record object to which this record is related.
string	$relationshipName	The name of the relationship of which this related record is a member.
array	$values	Associative array of values for this related record.

Definition at line 146 of file RelatedRecord.php.

display ( $fieldname )

Returns a the value of a field in a meaningful state so that it can be displayed.

This method is similar to getValueAsString() except that this goes a step further and resolves references. For example, some fields may store an integer that represents the id for a related record in another table. If a vocabulary is assigned to that field that defines the meanings for the integers, then this method will return the resolved vocabulary rather than the integer itself.

Parameters

string $fieldname The name of the field whose value we wish to retrieve.

Returns: string The field value as a string.

// Column definitions:
// Table Unit_plans (id INT(11), name VARCHR(255) )
// Table Lessons ( unit_id INT(11) )
// Lessons.unit_id.vocabulary = "select id,name from Unit_plans"
$record = new Dataface_Record('Lessons', array('unit_id'=>3));
$record->getValueAsString('unit_id'); // returns 3
$record->display('unit_id'); // returns "Good Unit Plan"

See Also: Dataface_Record::display()

Definition at line 899 of file RelatedRecord.php.

getAbsoluteValues	(	$excludeNulls = `false`,
		$includeAll = `false`
	)

Gets the values of this related record except that the keys of the returned associative array are absolute column names rather than relative names as are returned in getValues().

Parameters

boolean $excludeNulls If true then 'null' values are not included in returned associative array.

Returns: array Associative array of key/value pairs.

Definition at line 742 of file RelatedRecord.php.

getActions ( $params = array() )

Returns actions associated with this record.

Parameters

array $params An associative array of parameters to filter the actions. Possible keys include: category => the name of a category of actions to return.

Returns: array Associative array of action definitions.

See Also: Dataface_ActionTool::getActions(); Dataface_Table::getActions()

Definition at line 353 of file RelatedRecord.php.

getConstrainedFields ( $sql = null )

Returns a list of fields in this related record that are constrained (i.e. cannot be changed.

Returns: array($fieldname:string)

Since: 2.0

Definition at line 848 of file RelatedRecord.php.

getForeignKeyValues ( $sql = null )

Returns 2-Dimensional associative array of the values in this related record and in any join table. The output of this method is used to add and remove related records.

Parameters

string $sql Optional SQL query that is used for getting the related records.

Returns: array 2-Dimensional array...

See Also: Dataface_Relationship::getForeignKeyValues(); Dataface_QueryBuilder::addRelatedRecord(); Dataface_QueryBuilder::addExistingRelatedRecord()

Definition at line 772 of file RelatedRecord.php.

getId ( )

Returns the Id of this related record object. The id is a string in a url format to uniquely identify this related record. The format is: tablename/relationshipname?parentkey1=val1&parentkey2=val2&relationshipname::key1=val2&relationshipname::key2=val3.

Returns: string

See Also: Dataface_Record::getId(); df_get_record_by_id(); Dataface_IO::getById()

Definition at line 1033 of file RelatedRecord.php.

getLength ( $fieldname )

Gets the length of a field's value (in bytes or characters).

This will work for Blob fields as well as regular fields, as it is calculated using the MySQL LENGTH() function.

Parameters

string $fieldname The name of the field whose length we want to check.

Returns: int The length of the field's value in bytes.

Definition at line 451 of file RelatedRecord.php.

& getParent ( )

Gets reference to the parent record (base record).

The difference between this method and the toRecord() method is that this returns the parent record (or the source record of the relationship) - a record that generally is not part of this related record. The toRecord() method returns a record that comprises a portion of this related record (or at least the columns in one of the tables that is spanned by this related record).

For example:

$person = df_get_record('people', array('person_id'=>10));
$books = $person->getRelatedRecordObjects('books');
$firstBook = $books[0];
$parent = $firstBook->getParent();
echo ($parent === $person)? "True":"False"; // outputs "True"
echo $parent->_table->tablename;  // 'people'
echo $books->toRecord()->_table->tablename;  // 'books'

Returns: Dataface_Record The parent/base record of the relationship.

Definition at line 316 of file RelatedRecord.php.

getPermissions	(	$params = `array()`,
		$table = `null`
	)

Definition at line 1185 of file RelatedRecord.php.

getTitle ( )

Gets the record title. This wraps the domain record's getTitle() method.

Returns: string The record's title.

See Also: Dataface_Record::getTitle()

Definition at line 1059 of file RelatedRecord.php.

getUnconstrainedFields ( $sql = null )

Gets a list of fields that are unconstrained (i.e. can be edited. This is helpful when building forms for this record.

Returns: array($fieldname:string)

Since: 2.0

Definition at line 794 of file RelatedRecord.php.

getUnconstrainedTables ( $sql = null )

Gets a list of the tables in this related record that are unconstrained. Unconstrained tables are ones that contain fields that are unconstrained.

Returns: array($tablename:string)

Since: 2.0

Definition at line 861 of file RelatedRecord.php.

getValue ( $fieldname )

Gets the value for a field.

Parameters

string $fieldname The name of the field whose value we are retrieving. This may be either a relative fieldname or an absolute column name.

Returns: mixed The field value.

See Also: Dataface_Record::getValue()

Definition at line 531 of file RelatedRecord.php.

getValueAsString ( $fieldname )

Gets the string value of a given field.

Parameters

string $fieldname The name of the field whose value we are retrieving.

Returns: string The field value as a string.

See Also: Dataface_Record::getValueAsString()

Definition at line 573 of file RelatedRecord.php.

& getValues	(	$columns = `null`,
		$excludeNulls = `false`
	)

Gets the values of this related record.

Parameters

	array(string)	$columns An optional array of columns to get.
boolean	$excludeNulls	If this is true, then columns with 'null' values will not be included. Defaults to 'false'

Returns: array Associative array of values.

See Also: Dataface_Record::getValues()

Definition at line 703 of file RelatedRecord.php.

getValuesAsStrings ( $fields = '' )

Gets the values stored in this table as an associative array. The values are all returned as strings.

Parameters

array fields An optional array of field names to retrieve.

Returns: array Associative array of field values where the keys are the field names and the values are their corresponding values.

See Also: Dataface_Record::getValuesAsStrings()

Definition at line 657 of file RelatedRecord.php.

htmlValue ( $fieldname )

Gets a field value as HTML.

Parameters

string $fieldname The name of the field whose value we wish to retrieve.

Returns: string The field's value as HTML.

See Also: Dataface_Record::htmlValue()

Definition at line 616 of file RelatedRecord.php.

isDirty ( $fieldname )

Checks if a particular field has changed since we loaded it (i.e. it is dirty).

Parameters

string $fieldname The name of the field that we want to know about.

Returns: boolean True if the field has changed.

Definition at line 409 of file RelatedRecord.php.

preview	(	$fieldname,
		$index = `0`,
		$maxlength = `255`
	)

Shows a short preview of field contents. Useful for text fields when we just want to see the first bit of the field. This will also strip all html tags out of the content.

Parameters

string	$fieldname	The name of the field to preview.
int	$index	In case of a related record which index in the relationship to get the record from.
int	$maxlength	The maximum length of the preview (in characters).

Returns: string The preview of the string version.

See Also: Dataface_Record::preview()

Definition at line 951 of file RelatedRecord.php.

printval ( $fieldname )

display()

Deprecated:

Definition at line 976 of file RelatedRecord.php.

printValue ( $fieldname )

display()

Deprecated:

Definition at line 968 of file RelatedRecord.php.

q ( $fieldname )

display()

Deprecated:

Definition at line 984 of file RelatedRecord.php.

qq ( $fieldname )

Displays field contents and converts html special characters to entities.

Parameters

string $fieldname The name of the field to display.

Returns: string

Definition at line 995 of file RelatedRecord.php.

save	(	$lang = `null`,
		$secure = `false`
	)

Definition at line 1162 of file RelatedRecord.php.

setFlag ( $fieldname )

Sets a flag on a field to indicate that it has changed and should be saved.

Parameters

string $fieldname The name of the field to mark "dirty".

Returns: Dataface_RelatedRecord Self for chaining.

Definition at line 389 of file RelatedRecord.php.

setMetaDataValue	(	$key,
		$value
	)

Sets a meta data value for a field.

Parameters

string	$key	The string metadata name.
mixed	$value	The value.

Returns: Dataface_RelatedRecord Self for chaining.

Definition at line 434 of file RelatedRecord.php.

setValue	(	$fieldname,
		$value
	)

Sets the value for a field of this related record.

Parameters

string	$fieldname	The name of the field to set. This may be a relative name or an absolute column name.
mixed	$value	The value to set this field to.

See Also: Dataface_Record::setValue()

Definition at line 472 of file RelatedRecord.php.

setValues ( $values )

Sets multiple values at once.

Parameters

array $values Associative array of values to set. array([Field name] -> [Field value])

See Also: Dataface_Record::setValues()

Definition at line 508 of file RelatedRecord.php.

stringValue ( $fieldname )

getValueAsString()

See Also: getValueAsString()

Definition at line 689 of file RelatedRecord.php.

strval	(	$fieldname,
		$index = `0`
	)

getValueAsString()

See Also: getValueAsString()

Definition at line 680 of file RelatedRecord.php.

strvals ( $fields = '' )

getValuesAsStrings()

See Also: getValuesAsStrings()

Definition at line 671 of file RelatedRecord.php.

testCondition ( $condition )

Takes a boolean expression resembling an SQL where clause and evaluates it based on the values in this record.

Example:

$record->setValue('first_name', 'Steve');
$record->setValue('last_name', 'Hannah');
$record->checkCondition('$first_name=="Steve"');  // true
$record->checkCondition('$last_name=="foo"');  // false

Parameters

string $condition A PHP expression that evaluates to a boolean.

Returns: boolean True if the condition evaluates to true.

Definition at line 337 of file RelatedRecord.php.

& toRecord ( $tablename = null )

Produces a Dataface_Record object representing the portion of this related record that is stored in a particular table.

Parameters

string $tablename The name of the table for which we wich to have a Dataface_Record object returned.

Returns: Dataface_Record A record covering the domain table of this related record. The domain table is generally the table that is the target of the relationship. (I.e. not the join table and not the source table).

Since: 0.6

Definition at line 224 of file RelatedRecord.php.

toRecords ( )

Returns an array of Dataface_Record objects that represent collectively this related record.

Returns: array(Dataface_Record) An array of dataface record objects comprising the values in this related record.

Definition at line 281 of file RelatedRecord.php.

val ( $fieldname )

Alias getValue()

See Also: getValue()

Definition at line 729 of file RelatedRecord.php.

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

Validates a value against a field name. Returns true if the value is a valid value to be stored in the field.

This method will always return true. The Delegate class can be used to override this method. Use <fieldname>__validate(&$record, $value, &$message) to override this functionality.

Parameters

string	$fieldname	The name of the field that we are validating for.
mixed	$value	The value that we are checking.
array	&$params	An out parameter to store the validation message.