Utils/RecordBrowser

Feature Overview


RecordBrowser allows quick and easy deployment of highly-customizable sets of records. It automatically covers browse, search, view and edit interface, favorites and recent records, full edits history and gives access to multiple types of fields. It also simplifies the use of Watchdog module.

You may be also interested in Objective RecordBrowser.

Glossary


  • RecordBrowser (RB) - the name of this CRUD engine

  • RecordSet - a set of records managed by RB

  • Field Name - name of the field as used in installation process - example: Company Name

  • Field Key - key of the field as used outside installation process; it's a lowercase variant of Field Name, with spaces replaced with underscores - example: company_name

  • Criteria (Crits) - set of rules for record subset retrieval

Development


New RecordSet

To make your own custom RecordSet it's highly recommended that you make a new module to manage that new RecordSet. It's not necessary to have separate module for each RecordSet, but for the purpose of this tutorial we suggest this solution.

Once you're past that stage, you need to create installation procedure of your RecordSet - you should place it in ModuleInstall.php install() method.

First step is to define fields for this new RecordSet. Fields' definitions are to be given as an array to the install_new_recordset() method from RBCommon. Each element in this array should be a definition of a field. Each definition should be an array, with format property_name=>value.

Two properties are obligatory - name and type. The use for the rest of properties depends on the type that was selected - for some types certain properties are unusable and there's no need to specify them. Lists of properties and types are available below.

Example:

$field1 = array('name'=>'Field 1', 'type'=>'text');
$field2 = array('name'=>'Field 2', 'type'=>'date');
$fields_definition = array($field1, $field2);
Utils_RecordBrowserCommon::install_new_recordset('my_recordset',$fields_definition);

Or shorter version:

Utils_RecordBrowserCommon::install_new_recordset('my_recordset',
 array(
  array('name'=>'Field 1', 'type'=>'text'),
  array('name'=>'Field 2', 'type'=>'date')
 ));

After you've created the RecordSet, you can now manipulate certain properties of this RecordSet:

  • Quickjump - enables GenericBrowser quickjump feature for a certain field

    Utils_RecordBrowserCommon::set_quickjump($recordset_name, $field);

  • Favorites - enables/disables ($bool=true/false) favorites for this RecordSet.

    Utils_RecordBrowserCommon::set_favorites($recordset_name, $bool);

  • Recent - enables/disables ($amount=integer/false) recent for this RecordSet. Please note that when enabling $amount should be set to the number of stored recent entries.

    Utils_RecordBrowserCommon::set_recent($recordset_name, $amount);

  • Caption - sets the ModuleIndicator caption for all windows (browse/view/edit/history). Please note that this caption will go through translation automatically, don't invoke Lang module here.

    Utils_RecordBrowserCommon::set_caption($recordset_name, $caption);

  • Access Callback - sets a callback that will be used to determine access to records in this RecordSet for different user groups. More details here.

Utils_RecordBrowserCommon::set_access_callback($recordset_name, $callback);

  • Processing Callback - registers a callback that enables pre/post-processing of records, on each view/edit/delete/restore. More details here.

    Utils_RecordBrowserCommon::register_processing_callback($recordset_name, $callback);

  • Watchdog - enables watchdog over this RecordSet. Callback defined should hold details regarding record display in Subscription applet. More details here.

    Utils_RecordBrowserCommon::enable_watchdog($recordset_name, $callback);

Field Properties

  • name - name of the field; this value will be also used as a label for the field

  • type - type of the field; it determines the HTML form element that will be used in add/edit form and the display format (please bear in mind there's a method of overriding these properties for each field separately - we will get on that later)

  • required - setting this to true will make RB call QuickForm error if user will try to submit form with empty value in that field. This property doesn't apply to checkbox, hidden and calculated data types. Value of this property can be changed by user with super administrator permissions. Also, please be aware that if you are going to disable a field with javascript in certain circumstances - marking that field as required will render user unable to submit the form

  • visible - enabling this property (set to true) will make this field display by default in table view, when browsing records. This property doesn't apply to hidden data type. The use of this property will change in near future - because of user-defined views
  • extra - by default this value is set to true. It controls the access user (super administrator) is given to the field properties. Non-extra fields are considered crucial to the system and it's impossible by admin to change their name, type and certain properties

  • filter - if set to true it will enable filter for this field while browsing param - additional parameter highly dependable on the field type. For instance, it holds the length for text fields. It may be also very useful property for fields that use QFfield_callback - since parameters given here will be available in this callback. Please refer to field types for details on param use

  • QFfield_callback - a callback to a method that will define the field for add/edit forms. This is the method to be used if you want to execute additional javascript code or add QuickForm rules. You can also freely modify HTML select options or define custom auto-complete field. Please be aware that if QFfield_callback was defined for a certain field, RB won't do any additional processing regarding that field - you need to manually set defaults for that field and define required rule. This property is never obligatory

  • display_callback - a callback method to define custom display method for a field. Every place where the value of the record is displayed by RB will go through this callback, if defined. This applies to view and browse interface. This property is required by calculated data type

Built-in Field Types

Name QF Type DB Type Description Param
text input type="text" C(param) Holds a string value. HTML entities are escaped. The length of the field must be defined. Defines the length of the field.
long text