Record IDs and the db_record Class

Record ID Handling

On a page that is handling a given table record, as well as the URL parameter for the table there is a URL parameter identifying the individual record. This is of the form -recordid=<record id>. The record ID is an encoded form of the following (using the example of two fields):-

<field1>=<val1>/<field2>=<val2>/

All primary key fields must be included and the fields are ordered by field name. A record ID can be created by calling the built-in function encode_record_id. This takes an array as a parameter, for which each element has the field name as the key and the field value as the value. The array elements are automatically sorted by field name. Each individual field name or field value is URL encoded and then at the end the whole string is itself URL encoded. The resulting record ID is then provided as the return value.

The built-in function decode_record_id basically does the reverse of the above, taking the record ID as a parameter and returning an array of primary keys. Because a $_GET variable has by definition already been URL decoded, this function omits the URL decode on the overall string. There are however situations in which a record ID is obtained other than via a $_GET variable. For this purpose there is also a built-in function fully_decode_record_id which performs the URL decode on the overall string and then calls decode_record_id.

The db_record Class

This class defines a data structure for holding the details of a table record and the operation to which it is currently being subjected. Although it has been enhanced to contain more information, it is based on the concept of the record object that is passed to table class methods in Xataface, and was adopted in this form to facilitate easy conversion of old code. The db_record class holds the following data:-

• $action - This is a public variable specifying the current action.
• $table - This is a public variable specifying the table to which the record belongs.
• $fields - This is a private array used to hold all the record fields. For each element the key is the field name and the value is the field value. To store an item in this array, the method SetField is called. This takes two parameters for the field name and field value. The retrieve an item, the method FieldVal is called. This takes the field name as a parameter and returns the value.
• $old_primary_keys - This is a private array of a similar form to $fields. It is used to store the primary key values that existed when the record was first opened for editing (i.e. before any changes). To set up this array, the method SaveOldPKs is called. A copy of the array is supplied as a single parameter. To retrieve an item, the method OldPKVal is called. This takes the field name as a parameter and returns the value.
• $custom_vars - This is a private array used to store any custom variables that may be needed from time to time. For each element, the key is the variable name and the value the variable value. To store an item, the SaveCustomVar method is called. This takes two parameters for the variable name and the value. To retrieve an item, the CustomVarVal method is called. This takes the variable name as a parameter and returns the value.

Pre-set Fields

There are times when the editing screen for a new record needs to have one or more fields pre-set (in addition to the use of MySQL defaults). Take for example a calendar view in a diary application. If there is a link to create a new item within the box for each date, then clicking an individual link should ideally open up a new record screen with the date initialised accordingly. To facilitate this, a new record screen can take a URL parameter of the form -presets=<preset fields>, where <preset fields> is a string that has been encoded from the required fields using encode_record_id (see above).