 |
Xataface 2.0
Xataface Application Framework
|
|
Xataface 2.0
Xataface Application Framework
|
Represents a single record from a table. More...
Public Member Functions | |
| __destruct () | |
| 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. | |
| & | getParentRecord () |
| Obtains a reference to the Dataface_Record object that holds the parent of this record (in terms of table heirarchy). | |
| getLink ($fieldname) | |
| Sometimes a link is specified to be associated with a field. These links will be displayed on the forms next to the associated field. Links may be specified in the fields.ini file with a "link" attribute; or in the delegate with the $fieldname__link() method. | |
| toJS ($fields=null) | |
Initialization | |
| Dataface_Record ($tablename, $values=null) | |
Utility Methods | |
| callDelegateFunction ($function, $fallback=null) | |
| Calls a delegate class method with no parameters (if it exists) and returns the result. | |
| getActions ($params=array()) | |
| Returns actions associated with this record. | |
| & | table () |
| Returns a reference to the Dataface_Table object. | |
| clearCache () | |
| Clears all of the various caches in this record. | |
| parseString ($str) | |
| Parses the string to replace column name variables with the corresponding column value. | |
Property Change Events | |
| addPropertyChangeListener ($key, &$listener) | |
| Adds a listener to be notified when field values are changed. | |
| removePropertyChangeListener ($key, &$listener) | |
| Removes a listener from the list of objects to be notified when changes are made on a particular field. | |
| firePropertyChangeEvent ($key, $oldValue, $newValue) | |
| Fires a property change event to all listeners registered to be notifed of changes to the specified field. | |
| propertyChanged (&$source, $key, $oldValue, $newValue) | |
| This method is to implement the PropertyChangeListener interface. This method will be called whenever a change is made to the parent record's primary key, so that we can keep our keys in sync. | |
Tab Management | |
| getJoinRecord ($tablename, $nullIfNotFound=false) | |
| Returns a join record for the given table. | |
| getJoinKeys ($tablename) | |
| Gets the keys that are necessary to exist in a join record for the given table. | |
| tabs () | |
| Returns the list of tabs that are to be used in the edit form for this record. | |
Permissions | |
Methods that deal with the record permissions. | |
| getRoles ($params=array()) | |
| Returns an array of the roles assigned to the current user with respect to this record. | |
| getRolePermissions ($params=array()) | |
| Returns permissions as specified by the current users' roles. This differs from getPermissions() in that getPermissions() allows the possibility of defining custom permissions not associated with a user role. | |
| getPermissions ($params=array()) | |
| checkPermission ($perm, $params=array()) | |
| Checks to see is a particular permission is granted in this record. | |
transactions Transaction Support | |
| setSnapshot () | |
| Signifies that we are beginning a transaction. So a snapshot of the values can be saved and possibly be later reverted. | |
| snapshotExists () | |
| Indicates whether a snapshot of values exists. | |
| clearSnapshot () | |
| Clears a snapshot of values. Note that for an update to take place properly, a snapshot should be obtained before any changes are made to the Table schema. | |
| & | getSnapshot ($fields='') |
| Returns the snapshot values for this table. These are copies of the values as they appeared the last time a snapshot was taken. | |
| snapshotKeys () | |
| Returns snapshots of only the primary key fields in this record. | |
| valueChanged ($fieldname, $index=0, $checkParent=false) | |
| Indicates whether a value in the record has been updated since the flags have been cleared. | |
| recordChanged ($checkParent=false) | |
| Boolean indicator to see whether the record has been changed since its flags were last cleared. | |
| clearFlags () | |
| Clears all of the dirty flags to indicate that this record is up to date. | |
| clearFlag ($name) | |
| setFlag ($fieldname, $index=0) | |
| Sets a dirty flag on a field to indicate that it has been changed. | |
| isLoaded ($fieldname) | |
| Boolean value indicating if a particular field is loaded. | |
Field Metadata | |
| getMimetype ($fieldname, $index=0, $where=0, $sort=0) | |
| Gets the mimetime of a blob or container field. | |
| isImage ($fieldname, $index=0, $where=0, $sort=0) | |
| Checks to see if a container or blob field contains an image. | |
| getLength ($fieldname, $index=0, $where=0, $sort=0) | |
| Gets the length of the value in a particular field. This can be especially useful for blob and longtext fields that aren't loaded into memory. It allows you to see if there is indeed a value there. | |
IO Methods | |
Methods for reading and writing records to and from the database. | |
| save ($lang=null, $secure=false) | |
| Saves the current record to the database. | |
| delete ($secure=false) | |
| Deletes the record from the database. | |
Data Fields | |
| $secureDisplay = true | |
| $_table | |
| $_tablename | |
| $useMetaData = true | |
| Flag indicating if we are using meta data fields. Meta data fields (if this flag is set) are signalled by '__' preceeding the field name. | |
| $loadBlobs = false | |
| Indicator to say whether blob columns should be loaded. This is useful for the blob columns of related records. boolean. | |
| $pouch = array() | |
| This is a multi-purpose pouch that allows triggers to attach data to a record and retrieve it later. | |
| $lang = null | |
| The language code of this record. This is automatically set to the language of content that was loaded when the record was loaded. | |
Relationships | |
| getRelationshipRange ($relationshipName) | |
| Gets the range of records that should be loaded for related records. | |
| setRelationshipRange ($relationshipName, $lower, $upper) | |
| Sets the range that should be included for a given relationship. | |
| numRelatedRecords ($relname, $where=0) | |
| Returns the total number of related records for a given relationship. | |
| & | getRelatedRecords ($relname, $multipleRows=true, $start=null, $limit=null, $where=0, $sort=0) |
| Returns an array of all of the records returned by a specified relation. | |
| getChildren ($start=null, $limit=null) | |
| Returns the "children" of this record. | |
| getChild ($index) | |
| Gets a particular child at the specified index. | |
| & | getParent () |
| Returns the "parent" record of this record. | |
| getRelationshipIterator ($relationshipName, $start=null, $limit=null, $where=0, $sort=0) | |
| Obtains an iterator to iterate through the related records for a specified relationship. | |
| & | getRelatedRecordObjects ($relationshipName, $start=null, $end=null, $where=0, $sort=0) |
| Gets an array of Dataface_RelatedRecords. | |
| & | getRelatedRecord ($relationshipName, $index=0, $where=0, $sort=0) |
| Returns a single Dataface_RelatedRecord object from the relationship specified by $relationshipName . | |
| moveUp ($relationship, $index) | |
| Moves a related record up one in the list. | |
| moveDown ($relationship, $index) | |
| Moves a related record down one in the list. | |
| sortRelationship ($relationship, $start=null, $subset=null) | |
Field Values | |
| setValue ($key, $value, $index=0) | |
| Sets the value of a field. | |
| setValues ($values) | |
| Sets muliple values at once. | |
| & | getValue ($fieldname, $index=0, $where=0, $sort=0, $debug=false) |
| Gets the value of a field in this record. | |
| & | value ($fieldname, $index=0, $where=0, $sort=0) |
| Alias for getValue() | |
| & | val ($fieldname, $index=0, $where=0, $sort=0) |
| Alias for getValue() | |
| & | getValues ($fields=null, $index=0, $where=0, $sort=0) |
| Gets the values of this Record in an associative array. [Field names] -> [Field values]. | |
| & | values ($fields=null, $index=0, $where=0, $sort=0) |
| Alias for getValues() | |
| & | vals ($fields=null, $index=0, $where=0, $sort=0) |
| Alias for getValues() | |
| getValueAsString ($fieldname, $index=0, $where=0, $sort=0) | |
| Gets the values of a field as a string. | |
| getValuesAsStrings ($fields='', $index=0, $where=0, $sort=0) | |
| Gets the values stored in this table as an associative array. The values are all returned as strings. | |
| strvals ($fields='', $index=0, $where=0, $sort=0) | |
| Alias for getValuesAsStrings() | |
| strval ($fieldname, $index=0, $where=0, $sort=0) | |
| Alias for getValueAsString() | |
| stringValue ($fieldname, $index=0, $where=0, $sort=0) | |
| Alias for getValueAsString() | |
| getSerializedValue ($fieldname, $index=0, $where=0, $sort=0) | |
| Returns the value of a field except it is serialzed to be instered into a database. | |
| display ($fieldname, $index=0, $where=0, $sort=0, $urlencode=false) | |
| Returns a the value of a field in a meaningful state so that it can be displayed. | |
| htmlValue ($fieldname, $index=0, $where=0, $sort=0, $params=array()) | |
| Returns an HTML-friendly value of a field. | |
| preview ($fieldname, $index=0, $maxlength=255, $where=0, $sort=0) | |
| Returns a preview of a field. A preview is a shortened version of the text of a field with all html tags stripped out. | |
| printValue ($fieldname, $index=0, $where=0, $sort=0) | |
| Alias for display() | |
| printval ($fieldname, $index=0, $where=0, $sort=0) | |
| Alias of display() | |
| q ($fieldname, $index=0, $where=0, $sort=0) | |
| Alias of display() | |
| qq ($fieldname, $index=0, $where=0, $sort=0) | |
| Alias of htmlValue() | |
| hasValue ($fieldname) | |
| Indicates whether a field exists in the table. | |
| getAbsoluteValues () | |
| Returns associative array of the record's values where the keys are the absolute field paths including the table name (using dot notation). | |
| getContainerSource ($fieldname) | |
| Returns the full path to the file contained in a container field. | |
| setMetaDataValue ($key, $value) | |
| Sets the value of a metadata field. | |
| clearValues () | |
| Clears all fields in this record. | |
| clearValue ($field) | |
| Clears the value in a field. | |
Record Metadata | |
| getTitle ($dontGuess=false) | |
| Returns the title of this particular record. | |
| getDescription () | |
| Returns a brief description of the record for use in listings and summaries. | |
| getCreated () | |
| Returns a Unix timestamp representing the date/time that this record was created. | |
| getCreator () | |
| Returns the name of the person who created this record (i.e. the author). | |
| getLastModified () | |
| Returns the last modified time of the record. | |
| getBody () | |
| Returns the "body" of a record. | |
| getPublicLink ($params=null) | |
| Returns the "public" URL to the record. | |
| getBreadCrumbs () | |
| Returns an array of parts of the bread-crumbs leading to this record. | |
| getURL ($params=array()) | |
| Returns the URL to this record. | |
| getId () | |
Represents a single record from a table.
The Dataface_Record class a core class as it encapsulates a single row of a table. Most interactions with the database will go through this class in some shape or form. It provides access to configuration, triggers, delegate classes, permissions, and just about every other facet of the framework.
Generally this class is used to view and edit records in the database. It is frequently used delegate classes for responding to events.
Sample loading a record and reading some values:
$record = df_get_record('people', array('person_id'=>10)); if ( !$record ){ echo "No record found with person_id=10."; } else { echo sprintf("We have loaded a record with First Name: %s, Last Name: %s.", $record->val('first_name'), $record->val('last_name') ); }
Sample editing some values and saving them:
$record->setValue('first_name', 'Steve'); $res = $record->save(); if ( PEAR::isError($res) ){ echo "An error occurred: ".$res->getMessage(); } else { echo "Sucessfully saved record."; }
Sample creating a new record and saving it to the database.
$record = new Dataface_Record('people', array()); $record->setValues(array( 'first_name'=> 'Steve', 'last_name'=> 'Hannah' )); $res = $record->save(); if ( !PEAR::isError($res) ){ echo "Record saved successfully with person_id ".$record->val('person_id'); } else { echo "Error occurred trying to save record: ".$res->getMessage(); }
Definition at line 100 of file Record.php.
| __destruct | ( | ) |
This was necessary to fix a memory leak with records that have a parent record. Thanks to http://bugs.php.net/bug.php?id=33595 for the details of this workaround.
When looping through and discarding records, it is a good idea to explicitly call __destruct.
Definition at line 366 of file Record.php.
| addPropertyChangeListener | ( | $ | key, |
| &$ | listener | ||
| ) |
Adds a listener to be notified when field values are changed.
| string | $key | The name of the field to listen for changes on. |
| Object | &$listener | The listener to register to receive notifications. |
Any object implementing the informal PropertyChangeListener interface may be added as a listener to receive notifications of changes to field values. This this interface dictates only that a a method with the following signature is implemented:
function propertyChanged( Dataface_Record $source, string $field, mixed $oldValue, mixed $newValue );
Definition at line 2981 of file Record.php.
| callDelegateFunction | ( | $ | function, |
| $ | fallback = null |
||
| ) |
Calls a delegate class method with no parameters (if it exists) and returns the result.
| string | $function | The name of the method to try to call. |
| mixed | $fallback | The value to return if the method could not be found |
Definition at line 403 of file Record.php.
| checkPermission | ( | $ | perm, |
| $ | params = array() |
||
| ) |
Checks to see is a particular permission is granted in this record.
| $perm | The name of a permission. |
| $params | Associative array of parameters: field: The name of a field to check permissions on. relationship: The name of a relationship to check permissions on. |
Definition at line 3338 of file Record.php.
| clearCache | ( | ) |
Clears all of the various caches in this record.
This is called generally when values are changed.
Definition at line 465 of file Record.php.
| clearFlag | ( | $ | name | ) |
Clears the dirty flag on a particular field.
| string | $name | The name of the field whose dirty flag we are clearing. |
Definition at line 3652 of file Record.php.
| clearFlags | ( | ) |
Clears all of the dirty flags to indicate that this record is up to date.
Definition at line 3618 of file Record.php.
| clearSnapshot | ( | ) |
Clears a snapshot of values. Note that for an update to take place properly, a snapshot should be obtained before any changes are made to the Table schema.
Definition at line 3504 of file Record.php.
| clearValue | ( | $ | field | ) |
Clears the value in a field.
| string | $field | The name of the field whose value we are clearing. |
Definition at line 2929 of file Record.php.
| clearValues | ( | ) |
| Dataface_Record | ( | $ | tablename, |
| $ | values = null |
||
| ) |
| $tablename | The name of the table that owns this record. |
| $values | An associative array of values to populate the record. |
Definition at line 336 of file Record.php.
| delete | ( | $ | secure = false | ) |
Deletes the record from the database.
| boolean | $secure | Whether to check permissions before saving. |
Definition at line 4518 of file Record.php.
| display | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0, |
||
| $ | urlencode = false |
||
| ) |
Returns a the value of a field in a meaningful state so that it can be displayed.
| string | $fieldname | The name of the field to return. |
| int | $index | For related fields indicates the index within the related list of the record to retrieve. |
| string | $where | Optional where clause to filter related list when retrieving a related field. |
| string | $sort | Optional sort clause when retrieving a related field. Used to sort related list before selecting the related record from which the value is to be returned. |
| boolean | $urlencode | Optional parameter to urlencode the output. |
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.
// 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"
The display() method, unlike the getValueAsString() method, respects permissions which means that if the current user doesn't have view permission granted on the record, it will simply return 'NO ACCESS' (or some other configurable string to indicate that the user has no access to view this field.
For exmaple, consider the following delegate class for the people table.
tables/people/people.php
<?php class tables_people { function sin__permissions($record){ return array('view'=>0); } function name__permissions($record){ return array('view'=>1); } }
So that no users have permission to view the sin field, but everyone has permission to view the name field.
Then we could have:
// $record is a Dataface_Record object from the people table $record->setValue('sin', '123456789'); $record->setValue('name', 'tom'); // We have full permission to the 'name' field so we can always get the value echo $record->display('name'); // 'tom' // We don't have view permission for the 'sin' field so display() will return no access echo $record->display('sin'); // 'NO ACCESS' // getValueAsString() does NOT respect permissions so we can use that to get the value echo $record->getValueAsString('sin'); // '123456789' // We could also set the 'secureDisplay' flag to false to tell display() to // not respect permissions $record->secureDisplay = false; echo $record->display('sin'); // '123456789'
The above example shows how the display() method respects permissions whereas the getValueAsString() method does not. For more information about the different field rendering methods and their differences see the documentation for the getValue() method.
If you want to use the output of display() and don't want to be limited by the user's actual permissions to see the field content, you can turn secure display off on the record by setting the secureDisplay flag to false.
$record->secureDisplay = false;
If you want to change the display security on multiple records at a time, you can use the df_secure() function of the dataface-public-api.php file to secure or unsecure an entire array of Dataface_Record objects.
$records = array(
$record1, $record2, $record3
);
df_secure($records, false); // disregard security
$record1->secureDisplay; // false
$record2->secureDisplay; // false
$record3->secureDisplay; // false
df_secure($records, true); // re-enable security
$record1->secureDisplay; // true
$record2->secureDisplay; // true
$record3->secureDisplay; // true
If you call display() on a field for which the user does not have the 'view' permission it simply returns the string 'NO ACCESS'. You can, however, override this string by implementing the no_access_text() method in the table's delegate class.
e.g.
function no_access_text($record){
return 'SUBSCRIBE';
}
Since the display() method is used by Xataface for most field display in the Xataface application, it is often desirable to override its output on particular fields to improve usability of the application.
For example you may want to store prices as simple decimal numbers, want them to be displayed formatted in the local currency. In this case you can implement the fieldname__display() method in the table's delegate class.
e.g. tables/products/products.php
<?php class tables_products { function price__display($record){ return money_format($record->val('price')); } }
Then when you are using records of the products table you would have:
$record->setValue('price', 1.50); echo $record->getValue('price'); // 1.5 echo $record->getValueAsString('price'); // '1.50' echo $record->display('price'); // '$1.50 USD'
Definition at line 2459 of file Record.php.
| firePropertyChangeEvent | ( | $ | key, |
| $ | oldValue, | ||
| $ | newValue | ||
| ) |
Fires a property change event to all listeners registered to be notifed of changes to the specified field.
| string | $key | The name of the field that was changed. |
| mixed | $oldValue | The old value of the field. |
| mixed | $newValue | The new value of the field. |
Definition at line 3023 of file Record.php.
| getAbsoluteValues | ( | ) |
Returns associative array of the record's values where the keys are the absolute field paths including the table name (using dot notation).
This method is very similar to getValues() except that the array keys are the absolute field name (including the table name) instead of just the field name.
Eg.
// For a reord of the 'people' table $vals = $record->getValues(); echo $vals['name']; // 'Steve' echo $vals['age']; // 27 $absVals = $record->getAbsoluteValues(); echo $absVals['people.name']; // 'Steve' echo $absVals['people.age']; // 27 echo $absVals['name']; // null
Definition at line 2827 of file Record.php.
| getActions | ( | $ | params = array() | ) |
Returns actions associated with this record.
| array | $params | An associative array of parameters for the actions to be retrieved. Possible keys include: category => the name of the category for the actions. |
Definition at line 435 of file Record.php.
| getBody | ( | ) |
Returns the "body" of a record.
This method first attempts to call the getBody() method of the delegate class if one is defined. If not, it will guess at which field of the table contains the record body and returns that. Failing that, it will return an empty string.
This method was initially created for use with the RSS feed functionality but that functionality has since been changed to generate the body in a different way. Currently there are no parts of the core that rely on this method so it has been deprecated.
Definition at line 4116 of file Record.php.
| getBreadCrumbs | ( | ) |
Returns an array of parts of the bread-crumbs leading to this record.
Breadcrumbs are used to display the navigational heirarchy for a record. This method is used to build the breadcrumbs that are displayed in the UI on the top bar.
This method first attempts to call the getBreadCrumbs() method of the delegate class. If none is found, it will check its parent record (see getParent()) for breadcrumbs and append itself to the end of its breadcrumbs.
If no parent is found and no explicit breadcrumbs can be found this will return some default breadcrumbs involving only the table name and the 'browse' action.
Building breadcrumbs string:
$base = ''; foreach ( $record->getBreadCrumbs() as $label=>$url){ $base .= ' :: <a href="'.$url.'" id="bread-crumbs-' .str_replace(' ','_', $label).'">'.$label.'</a>'; } $base = substr($base, 4);
Definition at line 4227 of file Record.php.
| getChild | ( | $ | index | ) |
Gets a particular child at the specified index.
If only one child is needed, then this method is preferred to getChildren() because it avoids loading the unneeded records from the database.
| int | $index | The zero-based index of the child to retrieve. |
Definition at line 1066 of file Record.php.
| getChildren | ( | $ | start = null, |
| $ | limit = null |
||
| ) |
Returns the "children" of this record.
A record's children can be defined by two means:
//Getting sub pages of a webpage record. $subpages = $page->getChildren(); foreach ($subpages as $pg){ echo $pg->val('path'); }
Note that the above example relies on the fact that either the getChildren method has been defined in the delegate class or a relationship has the meta:class=children designator for this table.
| int | $start | (optional) The start index from which to return children. |
| int | $limit | (optional) The upper limit on the nubmer of records to be returned. |
Definition at line 1029 of file Record.php.
| getContainerSource | ( | $ | fieldname | ) |
Returns the full path to the file contained in a container field.
| string | $fieldname | The name of the field. |
Since container fields only store the filename of the stored file, and doesn't store the full path to the directory that contains the file, loading the file requires more than just a call to getValue(). This method bridges the gap by returning the full filesystem path to where the file is stored.
echo $record->getValue('uploaded_image'); // 'my_image.jpg' echo $record->getContainerSource('uploaded_image'); // 'tables/people/uploaded_image/my_image.jpg'
Definition at line 2861 of file Record.php.
| getCreated | ( | ) |
Returns a Unix timestamp representing the date/time that this record was created.
This method will first check to see if the delegate class defines a method named getCreated() and return its value. Failing that, it will try to guess which field holds the creation date based on various heuristics. These heuristics involve looking for date fields with appropriate names. The field guessing is actually handled by the Dataface_Table::getCreatedField() method.
This method is used throughout Xataface to display the creation times of records.
Definition at line 4005 of file Record.php.
| getCreator | ( | ) |
Returns the name of the person who created this record (i.e. the author).
This method will first check to see if the delegate class implements a method named getCreator() and return its result. Otherwise it will try to guess which field contains the creator/author information for this record based on heuristics (handled by the Dataface_Table::getCreatorField() method). If it cannot find any appropriate field, it will simply return ''.
This method is used throughout Xataface to display the author of various records.
Definition at line 4041 of file Record.php.
| getDescription | ( | ) |
Returns a brief description of the record for use in listings and summaries.
This method first checks to see if a getDescription() method has been explicitly defined in the delegate class and returns its result if found. If none is found it will try to guess which field is meant to be used as a description based on various heuristics. Usually it will just use the first TEXT field it finds and treat that as a description.
This method is used throughout Xataface, most notably at the top of the details view (just below the title) where it displays what is intended to be a record summary.
Definition at line 3972 of file Record.php.
| getId | ( | ) |
This returns a unique id to this record. It is in a format similar to a url: table?key1=value1&key2=value2
Definition at line 4358 of file Record.php.
| getJoinKeys | ( | $ | tablename | ) |
Gets the keys that are necessary to exist in a join record for the given table.
| string | $tablename | The name of the join table. |
// Table: Persons(PersonID, Name, SSN) PKEY (PersonID) // Table: Authors(AuthorID, AuthorCategory, Description) PKEY (AuthorID) // Suppose AuthorID is a foreign key for PersonID (1-to-1). // In the fields.ini file we have: // [__join__] // Authors=Author Details $person = df_get_record('Persons', array('PersonID'=>10)); $authorKeys = $person->getJoinKeys('Authors'); print_r($authorKeys); // array( 'AuthorID'=>10)
Definition at line 3162 of file Record.php.
| getJoinRecord | ( | $ | tablename, |
| $ | nullIfNotFound = false |
||
| ) |
Returns a join record for the given table.
| string | $tablename | The name of the table from which the join record should be drawn. |
| boolean | $nullIfNotFound | If set, then this will return null if no join record yet exists in the database. Added in Xataface 2.0 |
A join record is one that contains auxiliary data for the current record. It is specified by the [__join__] section of the fields.ini file or the __join__() method of the delegate class.
It is much like a one-to-one relationship. The key difference between a join record and a related record is that a join record is assumed to be one-to-one, and an extra tab is added to the edit form to edit a join record.
Definition at line 3117 of file Record.php.
| getLastModified | ( | ) |
Returns the last modified time of the record.
This method will first check to see if the delegate class implements a method named getLastModified() and return its result. If none can be found it will attempt to guess which field is used to store the last modified date (based on the Dataface_Table::getLastUpdatedField() method). Otherwise it will simply return 0.
This method is used throughout Xataface to mark the modification times of records.
Definition at line 4073 of file Record.php.
| getLength | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Gets the length of the value in a particular field. This can be especially useful for blob and longtext fields that aren't loaded into memory. It allows you to see if there is indeed a value there.
| string | $fieldname | The name of the field to check. |
| integer | $index | If this is a related field then this is the index offset. |
| string | $where | If this is a related field this is a where clause to filter the results. |
| string | $sort | If this is a related field then this is a sort clause to sort the results. |
Definition at line 4454 of file Record.php.
| getLink | ( | $ | fieldname | ) |
Sometimes a link is specified to be associated with a field. These links will be displayed on the forms next to the associated field. Links may be specified in the fields.ini file with a "link" attribute; or in the delegate with the $fieldname__link() method.
Definition at line 3738 of file Record.php.
| getMimetype | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Gets the mimetime of a blob or container field.
| string | $fieldname | The name of the field to check. |
| integer | $index | If this is a related field then this is the index offset. |
| string | $where | If this is a related field this is a where clause to filter the results. |
| string | $sort | If this is a related field then this is a sort clause to sort the results. |
Definition at line 4389 of file Record.php.
| & getParent | ( | ) |
Returns the "parent" record of this record.
A record's parent can be defined in two ways:
| Dataface_Record | The parent record of this record. |
Definition at line 1102 of file Record.php.
| & getParentRecord | ( | ) |
Obtains a reference to the Dataface_Record object that holds the parent of this record (in terms of table heirarchy).
Tables can extend other tables using the __isa__ property of the fields.ini file.
Definition at line 3438 of file Record.php.
| getPermissions | ( | $ | params = array() | ) |
Gets the permissions associated witha field. Permissions are returned as an associative array whose keys are the permissions names, where a permission is granted only if a key by its name exists and evaluates to true.
| array | $params | (Optional) Associative array with keys to target the method toward a particular field or relationship. The possible keys are as follows: array(
field => <string> // The name of a field to return permissions for.
relationship => <string> // The relationship name to return permissions for.
fieldmask => <array> // Permissions mask to apply to field permissions.
recordmask => <array> // Permissions mask to apply to record permissions.
)
|
array(
view => 1,
edit => 0,
delete => 0
)
Normally you would use the Dataface_PermissionsTool class to generate permissions masks for you based on roles. Dataface_PermissionsTool provides the following static convenience methods to generate commonly used permissions sets for you:
| Method | Description |
|---|---|
| Dataface_PermissionsTool::ALL() | Returns associative array with all permissions granted. |
| Dataface_PermissionsTool::NO_ACCESS() | Returns associative array with all permissions explicitly denied. |
| Dataface_PermissionsTool::READ_ONLY() | Returns associative array with only those permissions in the READ ONLY role granted. It does not explicitly deny access to other permissions so this method should not be used for field-level permissions for the purpose of denying access. |
| Dataface_PermissionsTool::getRolePermissions() | Returns associative array of permissions granted for the specified role. |
The following flowchart shows the flow of control Xataface uses to determine the record-level permissions for a record. (click here to enlarge):
The following flowchart shows the flow of control Xataface uses to determine the field-level permissions for a field in a record.
Definition at line 3324 of file Record.php.
| getPublicLink | ( | $ | params = null | ) |
Returns the "public" URL to the record.
| array | $params | Supplementary parameters that can be passed through to getURL(). |
It is often the case that a record may be the subject of a public facing page on a website and you want to be able to associate the record with this page. The getURL() method will generally return a URL to the record's details view in the back end. This method, by contrast, is meant to allow you to link to the public page that features the record.
This method will first attempt to call the getPublicLink() method defined in the delegate class. If one cannot be found, it will simply call getURL().
So, in essence, this method is just a wrapper around the getURL() method that allows you to override its output in the delegate class. Its relationship to getURL() is very similar to display()'s relationship to getValue().
Most of the Xataface interface uses the getURL() method directly for linking to records. However there are some parts, which are meant for public consumption, that use the getPublicLink() method by default. This includes the RSS feeds and the full-text site search.
echo $record->getURL(); // 'index.php?-table=people&-action=view&person_id=10' echo $record->getPublicLink(); // 'index.php?-table=people&-action=view&person_id=10'
But we can override getPublicLink() by implementing it in the delegate class.
tables/people/people.php
... function getPublicLink($record){ return 'http://www.example.com/people/'.rawurlencode($record->val('username')); } ...
Now our example becomes:
echo $record->getURL(); // 'index.php?-table=people&-action=view&person_id=10' echo $record->getPublicLink(); // 'http://www.example.com/people/foobar'
Definition at line 4182 of file Record.php.
| & getRelatedRecord | ( | $ | relationshipName, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Returns a single Dataface_RelatedRecord object from the relationship specified by $relationshipName .
| string | $relationshipName | The name of the relationship. |
| integer | $index | The position of the record in the relationship. |
| string | $where | A where clause to filter the base result set. Use 0 for default. |
| string | $sort | A comma-delimited list of columns to sort on. |
Definition at line 1210 of file Record.php.
| & getRelatedRecordObjects | ( | $ | relationshipName, |
| $ | start = null, |
||
| $ | end = null, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Gets an array of Dataface_RelatedRecords.
This is basically a wrapper around the getRelatedRecords method that returns an array of Dataface_RelatedRecord objects instead of just an array of associative arrays.
| string | $relationshipName | The name of the relationship. |
| int | $start | The start index (zero-based). Use null for default. |
| int | $end | The limit parameter. Use null for default. |
| string | $where | A where clause to limit the results. e.g. 'Name="Fred" and Size='large'". Use 0 for default. |
| string | $sort | A comma delimited list of columns to sort on. e.g. 'OrderField, LastName desc, FirstName asc' |
Definition at line 1181 of file Record.php.
| & getRelatedRecords | ( | $ | relname, |
| $ | multipleRows = true, |
||
| $ | start = null, |
||
| $ | limit = null, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Returns an array of all of the records returned by a specified relation.
Each record is an associative array where the values are in raw format as returned by the database.
$relatedRecords = $record->getRelatedRecords('books'); foreach ($relatedRecords as $book){ echo 'Name: '.$book['name'].' Subject: '.$book['subject']."\n"; }
$relatedRecords = $record->getRelatedRecords('books', 0, 5); foreach ($relatedRecords as $book){ echo 'Name: '.$book['name'].' Subject: '.$book['subject']."\n"; }
$relatedRecords = $record->getRelatedRecords('books', 0, 5, "name LIKE 'Tale of %'"); foreach ($relatedRecords as $book){ echo 'Name: '.$book['name'].' Subject: '.$book['subject']."\n"; }
The preceding example should return the first 5 books whose name starts with "Tale of "
The following example shows how to retrieve the first 5 related records when sorting on book name then author.
$relatedRecords = $record->getRelatedRecords('books', 0, 5, null, "name asc, author asc"); foreach ($relatedRecords as $book){ echo 'Name: '.$book['name'].' Subject: '.$book['subject']."\n"; }
| string | $relname | The name of the relationship whose records we are retrieveing. |
| boolean | $multipleRows | (optional) If true, this will return an array of records. If it is false it only returns the first record. |
| integer | $start | The start position from this relationship to return records from. |
| integer | $limit | The number of records to return |
| string | $where | A short where clause to filter the results. |
| string | $sort | A comma-delimited list of fields to sort on. e.g. 'Name asc, Weight desc'. |
Definition at line 859 of file Record.php.
| getRelationshipIterator | ( | $ | relationshipName, |
| $ | start = null, |
||
| $ | limit = null, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Obtains an iterator to iterate through the related records for a specified relationship.
| string | $relationshipName | The name of the relationship. |
| int | $start | The start index (zero based). Use null for default. |
| int | $limit | The number of records to return. Use null for default. |
| string | $where | A string where clause to limit the results. e.g. 'Name="Fred" and Size="large"'. Use 0 for default. |
| string | $sort | A comma-delimited list of columns to sort on with optional 'asc' or 'desc' indicators. e.g. 'FirstName, SortID desc, LastName asc'. |
Definition at line 1146 of file Record.php.
| getRelationshipRange | ( | $ | relationshipName | ) |
Gets the range of records that should be loaded for related records.
| string | $relationshipName | The name of the relationship |
Definition at line 554 of file Record.php.
| getRolePermissions | ( | $ | params = array() | ) |
Returns permissions as specified by the current users' roles. This differs from getPermissions() in that getPermissions() allows the possibility of defining custom permissions not associated with a user role.
| array | $params | See getPermissions() for possible values. |
Definition at line 3234 of file Record.php.
| getRoles | ( | $ | params = array() | ) |
Returns an array of the roles assigned to the current user with respect to this record.
| array | $params | Extra parameters. See getPermissions() for possible values. |
Definition at line 3223 of file Record.php.
| getSerializedValue | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Returns the value of a field except it is serialzed to be instered into a database.
| string | $fieldname | The name of the field whose value we are to retrieve. |
| int | $index | The index of the related record whose value we are retrieving (only if we are retrieving a related record). |
| string | $where | The where clause to filter related records (only if we are retrieving a related field). |
| string | $sorrt | The sort clause to use in sorting related records (only if we are retrieving a related field). |
Definition at line 2283 of file Record.php.
| & getSnapshot | ( | $ | fields = '' | ) |
Returns the snapshot values for this table. These are copies of the values as they appeared the last time a snapshot was taken.
| array | $fields | A list of field names for which the snapshot should be returned. If omitted this should return all fields. |
Definition at line 3522 of file Record.php.
| getTitle | ( | $ | dontGuess = false | ) |
Returns the title of this particular record.
| boolean | $dontGuess | If true then it will disable guessing so that it will only return the title if it has been explicitly defined by a delegate class's getTitle() method. |
This method is used throughout Xataface to show the title of a record. This includes the heading for the record in details view, identification of the record when shown in a list, and any other time the record needs to be identified in the user interface.
The output of this method can be overridden by implementing a getTitle() method in the table's delegate class. If no such method is defined, then getTitle() will attempt to guess which field represents the title of a record. Generally it will just take the first varchar field that it finds and use that as the title.
Given a table with SQL definition:
CREATE TABLE `people` ( person_id int(11) not null auto_increment primary key, first_name varchar(100), last_name varchar(100) )
If no title column has been explicitly assigned, the first_name field will be treated as the source of the title because it is the first varchar field.
e.g.
$record->setValues(array(
'first_name'=>'Steve',
'last_name'=> 'Hannah'
));
echo $record->getTitle(); // 'Steve'
// Without guessing
$title = $record->getTitle(); // null
echo isset($title) ? 'Yes':'No'; // 'No'
In the above example you can see that only the first name is used as the record title. It would be more appropriate, in this case, to use the full name (first and last). We can achieve this by implementing the getTitle() method in the table delegate class:
tables/people/people.php:
... function getTitle($record){ return $record->val('first_name').' '. $record->val('last_name'); } ...
Now the same code as above will yield different output:
$record->setValues(array(
'first_name'=>'Steve',
'last_name'=> 'Hannah'
));
echo $record->getTitle(); // 'Steve Hannah'
// Without guessing
$title = $record->getTitle(); // 'Steve Hannah'
echo isset($title) ? 'Yes':'No'; // 'Yes'
Definition at line 3898 of file Record.php.
| getURL | ( | $ | params = array() | ) |
Returns the URL to this record.
| mixed | $params | An array or urlencode string of parameters to use when building the url. e.g., array('-action'=>'edit') would cause the URL to be for editing this record. |
// default points to record's browse action echo $record->getURL(); // index.php?-table=people&-action=browse&person_id=10 // Custom parameters echo $record->getURL(array( '-action'=>'my_custom_action' )); // index.php?-table=people&-action=my_custom_action&person_id=10 // Using urlencoded string parameters instead echo $record->getURL('-action=my_custom_action'); // index.php?-table=people&-action=my_custom_action&person_id=10
If secureDisplay is set to true in this record and the 'link' permission is denied to the current user, this method will look for the delegate class's no_access_link() methood to override its output. If the method hasn't been defined, or the link permission is granted, or secureDisplay is set to false this method will simply return its normal result.
A delegate class which denies the 'link' permission and defines the no_access_link() method.
tables/people/people.php:
... function getPermissions($record){ $perms = Dataface_PermissionsTool::READ_ONLY(); $perms['link'] = 0; return $perms; } function no_access_link($record, $params=array()){ return 'no_access.html'; } ...
Some sample code working with records of our people table:
echo $record->getURL(); // 'no_access.html' $record->secureDisplay = false; echo $record->getURL(); // index.php?-table=people&-action=browse&person_id=10
Definition at line 4318 of file Record.php.
| & getValue | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0, |
||
| $ | debug = false |
||
| ) |
Gets the value of a field in this record.
| string | $fieldname | The name of the field whose value we wish to obtain. Could be simple name (eg: 'id') or related name (eg: 'addresses.city'). |
| int | $index | The index of the value. This is primarily used when retrieving the value of a related field that has more than one record. |
| string | $where | Optional where clause that can be used to filter related record if the fieldname refers to a related field. |
| string | $sort | Optional sort clause that can be used to sort results when obtaining a field from a related record. |
| boolean | $debug | Optional parameter to echo some debugging information to help diagnose problems. |
This method returns the raw data structure of the stored data which could be an array, an object, a string, or just about anything. For varchar fields this will generally be a string, but for other field types (e.g. dates) it may return an actual data structure.
Dates are stored as an associative array of key values with keys such as
Dataface_Record provides a number of methods for returning the value of a field and each is a little bit different. The difference between these methods is based on the amount of processing that is performed on the value before it is returned.
The following table summarizes the differences between these methods.
| Method | Output Type | Respects Permissions | Valuelist Replacement |
|---|---|---|---|
| getValue() | Mixed. (May be a string, number, or data structure). | No | No |
| getValueAsString() | String | No | No |
| display() | String | Yes | Yes |
| htmlValue() | String. This string is made HTML friendly by converting special characters to their corresponding HTML entities (except for htmlarea fields). | Yes | Yes |
The "Respects Permissions" column in the above table indicates whether the method will first check the current users' permissions before returning the field value. Notice that the display() method respects permissions while the getValueAsString() method does not. This means that if the current user doesn't have the view permission for the given field it will just return "NO ACCESS" (or some other pre-defined value to indicate that the user doesn't have access to view the field content.
The "Valuelist Replacement" column in the above table only pertains to fields with the vocabulary directive in the fields.ini file. Methods without Valuelist Replacement will return the field's value as it is stored in the database (more or less), while methods with valuelist replacement will return the field's corresponding value from the valuelist specified by the vocabulary directive.
For example, a table "books" might have an "author_id" field that stores the ID of an author record. The fields.ini file directives for this field might look something like:
[author_id]
widget:type=select
vocabulary=people
Then we can contrast the output of getValueAsString() to display() with the following example:
$record->getValueAsString('author_id'); // Would return something like "10" $record->display('author_id'); // Would return something like "Charles Dickens"
getValue() will simply return the name of the file that is stored in container fields. It doesn't actually load the value of the field.
The display() method will return the URL to the file in a container field.
The getContainerSource() method will return the path to the file in a container field.
See How to Handle File Uploads (Tutorial)
getValue() will return an empty string for blob fields as Xataface knows not to load blob fields into memory. The only exception to this rule is when you want to save data to a blob field and have previously performed a setValue() call on the blob field with the blob data.
The display() method will return the URL to download the file that is stored in a blob field.
getValue() will return a data structure for date, datetime, time, and timestamp fields. This can often be more difficult to deal with when performing PHP date and time operations, so you may want to use getValueAsString() instead when working with date fields. getValueAsString() will return a string representation of the date in MySQL format (e.g. YYYY-mm-dd HH:MM:SS)
// Get the value from the 'name' column $record->getValue('name'); // Get the title of the first book in the record's 'books' relationship. $record->getValue('books.title'); // Get the title of the second book in the record's 'books' relationship. $record->getValue('books.title',1); // Get the title of the first book in the record's 'books' relationship // that was published in 1988 $record->getValue('books.title', 0, "year=1988"); // Get the title of the first book in the record's 'books' relationship // when the books are sorted on 'year' $record->getValue('books.title', 0, 0, 'year asc');
Definition at line 1774 of file Record.php.
| getValueAsString | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Gets the values of a field as a string.
| string | $fieldname | The name of the field whose value we want to retrieve. |
| int | $index | For related fields, the index of the record within the related list whose field value we wish to retrieve. |
| string | $where | Where clause used to filter related list if retrieving a related field. |
| string | $sort | A sort clause used to sort the related list if retrieving a related field. |
This method is a wrapper for the getValue() method. It converts values to strings before returning them. This is helpful for fields that store structures (e.g. date fields.
$record->val('person_id'); // returns integer. $record->getValueAsString('person_id'); // returns string representation of integer $record->val('date_posted'); // returns something like // array('year'=>2010, 'month'=>10, 'day'=>2, 'hours'=>9, 'minutes'=>23, 'seconds'=>5); $record->getValueAsString('date_posted'); // returns something like 2010-10-2 09:23:05
Dataface_Record provides a sort of display stack with 4 main types of output. The stack looks like:
htmlValue() which wraps display() which wraps getValueAsString() which wraps getValue(). For a description of the differences between these methods, see getValue()
The output of the getValueAsString() method can be overridden by implementing the fieldname__toString() delegate class method. E.g.
<?php class tables_products { ... function price__toString($record){ return '$'.$record->val('price'); } ... }
The above delegate class method would cause the string representation to have a '$' prefixed to it.
Definition at line 2151 of file Record.php.
| & getValues | ( | $ | fields = null, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Gets the values of this Record in an associative array. [Field names] -> [Field values].
// Getting all of the field values including grafted fields // but excluding transient fields $vals = $record->getValues(); foreach ($vals as $key=>$val ){ echo "Field name: ".$key." : Field value: ".$val."\n"; }
Output would be something like:
Field name: name : Field value: Steve Field name: age : Field value: 27 Field name: weight: Field value: 154 ... etc...
You could yield the same results as the above code by first obtaining a list of the fields in the table and looping through the fields, calling the getValue() method on each field as follows:
foreach ( array_keys($record->_table->fields(false, true)) as $field){ echo "Field name: ".$field." : Field value: ".$record->getValue($field)."\n"; }
// Only retrieve the name and age fields. $vals = $record->getValues(array('name','age')); foreach ($vals as $key=>$val ){ echo "Field name: ".$key." : Field value: ".$val."\n"; }
Output would be something like:
| array | $fields | Array of column names that we wish to retrieve. If this parameter is omitted, all of the fields are returned. |
| int | $index | If we are returning related fields, then this is the index of the record whose values should be returned. |
| string | $where | For related fields, this is the where clause that can be used to filter the related record list. |
| string | $sort | For related fields, this is the sort clause that can be used to sort the related records. |
Definition at line 2035 of file Record.php.
| getValuesAsStrings | ( | $ | fields = '', |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Gets the values stored in this table as an associative array. The values are all returned as strings.
| array | $fields | An optional array of field names to retrieve. |
| int | $index | For related fields, the index of the source related record within the related records list. |
| string | $where | (optional) Where clause to filter related lists in case some related fields are being returned. |
| string | $sort | (optional) Sort clause to sort related lists in case related fields are being retrieved. |
This method is basically the same as the getValues() method except that the results are returned as strings. I.e. getValuesAsStrings() is to getValueAsString() as getValues() is to getValue()
If the $fields parameter is omitted or entered as the empty string (''), then all primary fields and grafted fields will be used as default. This DOES NOT include related fields, calculated fields, or transient fields.
Definition at line 2236 of file Record.php.
| hasValue | ( | $ | fieldname | ) |
Indicates whether a field exists in the table.
| string | $fieldname | The name of the field to check. |
Definition at line 2792 of file Record.php.
| htmlValue | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0, |
||
| $ | params = array() |
||
| ) |
Returns an HTML-friendly value of a field.
| string | $fieldname | The name of the field to return. |
| int | $index | For related fields indicates the index within the related list of the record to retrieve. |
| string | $where | Optional where clause to filter related list when retrieving a related field. |
| string | $sort | Optional sort clause when retrieving a related field. Used to sort related list before selecting the related record from which the value is to be returned. |
| array | $params | Optional additional parameters to customize the HTML output. This may be passed to include HTML attributes width and height to blob fields containing an image. |
This method sits above "display" on the output stack for a field. I.e. it wraps display() and adds some extra filtering to make the output directly appropriate to be displayed as HTML. In text fields this will convert newlines to breaks, and in blob fields, this will output either the full a-href tag or img tag depending on the type of content that is stored.
Definition at line 2640 of file Record.php.
| isImage | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Checks to see if a container or blob field contains an image.
| string | $fieldname | The name of the field to check. |
| integer | $index | If this is a related field then this is the index offset. |
| string | $where | If this is a related field this is a where clause to filter the results. |
| string | $sort | If this is a related field then this is a sort clause to sort the results. |
Definition at line 4434 of file Record.php.
| isLoaded | ( | $ | fieldname | ) |
Boolean value indicating if a particular field is loaded.
| string | $fieldname | The name of the field to check. |
Definition at line 3717 of file Record.php.
| moveDown | ( | $ | relationship, |
| $ | index | ||
| ) |
Moves a related record down one in the list.
This depends on the metafields:order directive of the relationships.ini file to set the column upon which the relationship should be ordered. If this is not set, then this method will return a PEAR_Error object.
| string | $relationship | The name of the relationship. |
| int | $index | The index of the record to move down. |
Definition at line 1312 of file Record.php.
| moveUp | ( | $ | relationship, |
| $ | index | ||
| ) |
Moves a related record up one in the list.
This depends on the metafields:order directive of the relationships.ini file to set the column upon which the relationship should be ordered. If this is not set, then this method will return a PEAR_Error object.
| string | $relationship | The name of the relationship. |
| int | $index | The index of the record to move up. |
Definition at line 1247 of file Record.php.
| numRelatedRecords | ( | $ | relname, |
| $ | where = 0 |
||
| ) |
Returns the total number of related records for a given relationship.
if ( $record->numRelatedRecords('books') > 0 ){ echo "There are ".$record->numRelatedRecords('books')." books."; } else { echo "There are no books."; }
The following example counts the number of books in the relationship that where published in 1986.
$numBooksIn1986 = $record->numRelatedRecords('books', "year='1986'");
| string | $relname | The relationship name. |
| mixed | $where | (optional) String where clause that can be used to filter the records. |
Definition at line 764 of file Record.php.
| parseString | ( | $ | str | ) |
Parses the string to replace column name variables with the corresponding column value.
| string | $str | The string to be parsed. |
Parses a string, resolving any variables to the values in this record. A variable is denoted by a dollar sign preceeding the name of a field in the table. This method replaces the variable with its corresponding value from this record.
Examples of variables include:
Related records can be parsed, but currently indexes are not supported. For example, if there are records in a relationship there is no way to specify the third record in a variable. Variables refering to related fields are automatically replaced with the value found in the first related record.
Definition at line 507 of file Record.php.
| preview | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | maxlength = 255, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Returns a preview of a field. A preview is a shortened version of the text of a field with all html tags stripped out.
| $fieldname | The name of the field for which the preview pertains. | |
| $index | The index of the field (for related field only). | |
| $maxlength | The number of characters for the preview. | |
| string | $where | Optional where clause to filter related list when retrieving a related field. |
| string | $sort | Optional sort clause when retrieving a related field. Used to sort related list before |
Definition at line 2729 of file Record.php.
| printval | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
| printValue | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
| propertyChanged | ( | &$ | source, |
| $ | key, | ||
| $ | oldValue, | ||
| $ | newValue | ||
| ) |
This method is to implement the PropertyChangeListener interface. This method will be called whenever a change is made to the parent record's primary key, so that we can keep our keys in sync.
| Object | &$source | The source of the property change. |
| string | $key | The name of the field that was changed. |
| mixed | $oldValue | The old value. |
| mixed | $newValue | The new value. |
Definition at line 3055 of file Record.php.
| q | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
| ( | $ | fieldname, | |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
| recordChanged | ( | $ | checkParent = false | ) |
Boolean indicator to see whether the record has been changed since its flags were last cleared.
| boolean | $checkParent | A boolean flag to tell whether we should check the parent record also. |
Definition at line 3593 of file Record.php.
| removePropertyChangeListener | ( | $ | key, |
| &$ | listener | ||
| ) |
Removes a listener from the list of objects to be notified when changes are made on a particular field.
| string | $key | The name of the field that was changed. |
| object | $listener |
Definition at line 2999 of file Record.php.
| save | ( | $ | lang = null, |
| $ | secure = false |
||
| ) |
Saves the current record to the database.
| string | $lang | The 2-digit language code of the language for which to save the record to. Defaults to the value Dataface_Application::_conf['lang'] |
| boolean | $secure | Whether to check permissions before saving. If it fails it will return a PEAR::Error object. |
Definition at line 4506 of file Record.php.
| setFlag | ( | $ | fieldname, |
| $ | index = 0 |
||
| ) |
Sets a dirty flag on a field to indicate that it has been changed.
| string | $fieldname | The name of the field to set the flag on. |
| int | $index | For related fields marks the index of the related record to set. |
Definition at line 3689 of file Record.php.
| setMetaDataValue | ( | $ | key, |
| $ | value | ||
| ) |
Sets the value of a metadata field.
| string | $key | The field key. |
| mixed | $value | The value to store |
Metadata fields are fields that store supplementary information for other fields. E.g. If you have a container field, you probably have other fields to store the mimetype of the file. This is also used to store the lengths of all field data that is loaded.
Definition at line 2888 of file Record.php.
| setRelationshipRange | ( | $ | relationshipName, |
| $ | lower, | ||
| $ | upper | ||
| ) |
Sets the range that should be included for a given relationship.
| string | $relationshipName | The name of the relationship. |
| int | $lower | The start index to be returned. |
| int | $upper | The upper index to be returned. |
Definition at line 574 of file Record.php.
| setSnapshot | ( | ) |
Signifies that we are beginning a transaction. So a snapshot of the values can be saved and possibly be later reverted.
Definition at line 3468 of file Record.php.
| setValue | ( | $ | key, |
| $ | value, | ||
| $ | index = 0 |
||
| ) |
Sets the value of a field.
| string | $key | The name of the field to set. This can be a simple name (eg: 'id') or a related name (eg: 'addresses.city'). |
| string | $value | The value to set the field to. |
| integer | $index | The index of the record to change (if this is a related record). |
This is meant to accept the value in a number of different formats as it will first try to parse and normalize the value before storing it. It normalizes it using the Dataface_Table::parse() method.
Calling this method will also cause the clearCache() method to be called
$record->setValue('name', 'Benjamin'); echo $record->val('name'); // Benjamin
You can set up a listener to be informed when field values are changed on a particular record using property change events. See addPropertyChangeListener() for more information.
Definition at line 1473 of file Record.php.
| setValues | ( | $ | values | ) |
Sets muliple values at once.
| array | $values | Associative array. [Field names] -> [Values] |
$record->setValues(array(
'name' => 'Benjamin',
'phone'=> '555-555-5555',
'date_added' => '2008-12-23 10:00:12'
));
echo $record->val('name'); // Benjamin
echo $record->strval('date_added'); // 2008-12-23 10:00:12
Definition at line 1579 of file Record.php.
| snapshotExists | ( | ) |
Indicates whether a snapshot of values exists.
Definition at line 3492 of file Record.php.
| snapshotKeys | ( | ) |
Returns snapshots of only the primary key fields in this record.
Definition at line 3545 of file Record.php.
| sortRelationship | ( | $ | relationship, |
| $ | start = null, |
||
| $ | subset = null |
||
| ) |
Sorts the records of this relationship (or just a subset of the relationship.
| string | $relationship | The name of the relationship to sort. |
| int | $start | The start position of the sorting (optional). |
| array | $subset | An array of Dataface_RelatedRecord objects representing the new sort order. |
Definition at line 1325 of file Record.php.
| stringValue | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Alias for getValueAsString()
Definition at line 2264 of file Record.php.
| strval | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Alias for getValueAsString()
Definition at line 2256 of file Record.php.
| strvals | ( | $ | fields = '', |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
Alias for getValuesAsStrings()
Definition at line 2248 of file Record.php.
| & table | ( | ) |
Returns a reference to the Dataface_Table object.
Definition at line 452 of file Record.php.
| tabs | ( | ) |
Returns the list of tabs that are to be used in the edit form for this record.
Definition at line 3189 of file Record.php.
| toJS | ( | $ | fields = null | ) |
Definition at line 4530 of file Record.php.
| & val | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
| 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.
| string | $fieldname | The name of the field that we are validating for. |
| mixed | $value | The value that we are checking. |
| array | &$param | An out parameter. Optionally allows the method to set an error message. If an error message is provided, it would be provided as the 'message' key of the out parameter. E.g. if ( !$record->validate('myfield', 'myvalue', $params){ echo "Message was ".$params['message']; } |
Definition at line 3374 of file Record.php.
| & vals | ( | $ | fields = null, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
| & value | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
| valueChanged | ( | $ | fieldname, |
| $ | index = 0, |
||
| $ | checkParent = false |
||
| ) |
Indicates whether a value in the record has been updated since the flags have been cleared.
| string | $fieldname | The name of the field we are checking |
| int | $index | Either the integer index of the record we are checking or an array query to match a record. |
| boolean | $checkParent | Flag to indicate whether we should also check the parent record. |
Definition at line 3560 of file Record.php.
| & values | ( | $ | fields = null, |
| $ | index = 0, |
||
| $ | where = 0, |
||
| $ | sort = 0 |
||
| ) |
| $_table |
Reference to the Dataface_Table object that owns this Record.
Definition at line 161 of file Record.php.
| $_tablename |
| $lang = null |
The language code of this record. This is automatically set to the language of content that was loaded when the record was loaded.
string
Definition at line 324 of file Record.php.
| $loadBlobs = false |
Indicator to say whether blob columns should be loaded. This is useful for the blob columns of related records. boolean.
Definition at line 269 of file Record.php.
| $pouch = array() |
This is a multi-purpose pouch that allows triggers to attach data to a record and retrieve it later.
Definition at line 315 of file Record.php.
| $secureDisplay = true |
Definition at line 109 of file Record.php.
| $useMetaData = true |
Flag indicating if we are using meta data fields. Meta data fields (if this flag is set) are signalled by '__' preceeding the field name.
Definition at line 235 of file Record.php.
1.7.4