Utils/RecordBrowser

Feature overview

RecordBrowser lets you deploy highly-customizable sets of records quickly. It automatically provides browse, search, view, and edit interfaces, favorites and recent records, full edit history, and a range of field types. It also simplifies working with the Watchdog module.

You may also be interested in Utils/RBO, an object-oriented wrapper around this same engine.

Glossary

• RecordBrowser (RB) — the name of this CRUD engine
• RecordSet — a set of records managed by RB
• Field Name — the name of a field as used during installation, e.g. Company Name
• Field Key — the key of a field as used outside installation: a lowercase version of the Field Name with spaces replaced by underscores, e.g. company_name
• Criteria (Crits) — a set of rules for retrieving a subset of records

Development

New recordset

To create a custom recordset, we recommend giving it its own module — it isn't strictly required, but this page assumes that setup.

Once your module exists, define the recordset's installation in your ModuleInstall.php's install() method.

First, define the recordset's fields. Pass them as an array to install_new_recordset() in Utils_RecordBrowserCommon. Each element is a field definition — an array of property_name => value pairs. Two properties are required: name and type. Which other properties apply depends on the type; see the field type tables 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 more compactly:

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

Once the recordset exists, you can configure it further:

• Quickjump — enables GenericBrowser's quickjump feature for a given field:

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

• Favorites — enables or disables favorites for this recordset:

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

• Recent — enables or disables the "recent" list. When enabling, $amount should be the number of entries to keep:

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

• Caption — sets the ModuleIndicator caption shown across browse/view/edit/history windows. This string goes through translation automatically — don't wrap it in a Lang call yourself:

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

• Access callback — determines record-level access per user group. See Access management below.

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

• Processing callback — registers pre/post-processing on view/edit/delete/restore. See Pre/post-processing below.

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

• Watchdog — enables Watchdog integration for this recordset. See Watchdog integration below.

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

Field properties

• name — the field's name; also used as its label
• type — the field's type. Determines both the HTML form element used in the add/edit form and how the value is displayed (this can be overridden per-field — more on that later)
• required — when true, RecordBrowser raises a QuickForm error if the user submits the form with this field empty. Doesn't apply to checkbox, hidden, or calculated types. A super administrator can change this later. Be careful combining this with JavaScript that conditionally hides the field — a required-but-hidden field can leave the user unable to submit the form at all.
• visible — when true, the field appears by default as a column in table (browse) view. Doesn't apply to hidden type. (Expect this to change with user-defined views.)
• extra — true by default. Controls whether a super administrator can change the field's name, type, and other properties through the UI. Non-extra fields are treated as core to the system and can't be edited that way.
• filter — when true, enables filtering by this field while browsing.
• param — an additional parameter whose meaning depends on the field type — for text fields, for example, it's the length. Also useful with QFfield_callback, since values set here are available inside that callback. See the field type tables below for details on each type's param.
• QFfield_callback — a callback that defines the field for the add/edit form. Use this when you need custom JavaScript, QuickForm rules, or a modified HTML <select>/autocomplete. If set, RecordBrowser does no additional processing for that field — you're responsible for setting defaults and the required rule yourself. Never required.
• display_callback — a callback that defines how the field's value is displayed, used everywhere RecordBrowser renders that value (view and browse). Required for the calculated type.

Built-in field types

Additional field types

RecordBrowser also supports custom data types. A custom type is really just a pre-processing function: it accepts a field definition and returns a modified one, adding a QFfield_callback, adjusting param, and mapping the type back to one RecordBrowser understands.

The CRM/Contacts module defines two such types, crm_contact and crm_company. Both can be either a select or multi-select field for choosing contacts. param should be an array with keys field_type ('select' or 'multiselect') and crits (a callback to a static method on the module's Common class).

crm_contact supports two more features. First, param can include a format key holding a callback to a static method, used to format the value in both edit and view mode. The two most common are:

'format' => array('CRM_ContactsCommon', 'contact_format_default')
// John Doe [Some Company]

and

'format' => array('CRM_ContactsCommon', 'contact_format_no_company')
// John Doe

Second, you can replace the multiselect element with an auto-multiselect (an autocomplete/multiselect combo). This is rougher around the edges: to enable it, your crits callback must return true when its first argument is false, and return the actual crits when the first argument is true. This interface is expected to change.

Select/multiselect parameter

Select and multiselect param values are more involved. To link to another recordset, param has three parts, separated by ;. The 2nd and 3rd parts are optional.

Part 1:

RecordSet name::Fields list with | as delimiter

Which recordset this field refers to. List multiple fields separated by spaces, in the order they should be used; these fields also determine which columns are searched when a user searches by this select/multiselect field.

Part 2:

ModuleCommon::crits_method

A callback that returns crits to limit which records can be selected. If omitted, all records are available.

Part 3:

ModuleCommon::advanced_properties_method

A callback that returns an array of additional properties for record selection. Recognized (all optional) keys are order, cols, and format_callback. This third part is optional — most fields won't need it.

Example param string for a select field linking to the premium_projects recordset:

'param' => 'premium_projects::Project Name;'.
           'Premium_Projects_TicketsCommon::projects_crits;'.
           'Premium_Projects_TicketsCommon::projects_advanced'

Adding fields after installation

Usually you define all of a recordset's fields in install_new_recordset(). Sometimes, though, you need to add a field to a recordset that's installed in a different module. Rather than editing that module's code directly, use new_record_field() from RBCommon.

Its first argument is the recordset name, its second a field definition — in almost the same format used by install_new_recordset() (which takes an array of field definitions, while new_record_field() takes just one).

The difference is that new_record_field() also accepts a position key. Give it an integer to place the field at that exact position, pushing later fields (and page splits) forward without breaking the layout. Give it a string — the name of an existing column — to place the new field right after that column.

Access management

Note: access management is due for a major overhaul. The input/output structure will change to make achieving specific field behaviors simpler.

RecordBrowser lets you set different access levels for every action performed on a record. You can restrict which groups may browse a recordset, limit which records a user sees, and control who can edit which record.

All of this goes through the access callback, defined in your module's installation procedure:

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

RecordBrowser calls this callback whenever it needs to check access, passing up to 3 arguments. The first is always the action being performed — add, browse, edit, delete, view, or fields. For the first 4, return true or false to grant or deny access. view expects an array of crits used to filter which records are shown. For edit and delete, the record itself is passed as the 2nd argument.

The fields action is more involved, and is due to be deprecated soon, so it isn't covered here.

Pre/post-processing (triggers)

RecordBrowser lets you run your own logic around every action it performs — modifying fields, or updating another recordset — through a processing callback. Register one in your module's install() method:

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

Each recordset can have any number of processing callbacks; all of them run, in order, on every action. A processing callback can do both pre- and post-processing. Each call passes your method 3 arguments:

• the data in question — usually the record being acted on, though for some events it's just the defaults for a new record (adding), or a pair of records (clone)
• the action being performed (full list below)
• implicitly, what the method is expected to return

The action determines both what you receive as the first argument and what a valid return value looks like. Be careful: if the action expects an updated record back and you return nothing (array(), false, null), RecordBrowser treats that as a valid update — which empties every field in the record. The table below covers every action:

Watchdog integration

RecordBrowser makes it easy to hook into the Watchdog module. First, enable it by supplying a callback that will process Watchdog requests, in your module's install() method:

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

This callback is usually fairly involved, since it needs to supply everything Watchdog needs. RecordBrowser's built-in helper handles most of it:

public static function watchdog_label($rid = null, $events = array(), $details = true) {
    return Utils_RecordBrowserCommon::watchdog_label(
        'task',
        Base_LangCommon::ts('CRM_Tasks', 'Tasks'),
        $rid,
        $events,
        'title',
        $details
    );
}

Arguments:

1. recordset name
2. label for the category
3. record ID, passed through from the arguments
4. events list, passed through from the arguments
5. name of the field to use as the record's label
6. $details, passed through from the 3rd argument

The 5th argument can also be a callback: it receives the record as its first argument and should return the label string to use. Example:

public static function watchdog_label($rid = null, $events = array(), $details = true) {
    return Utils_RecordBrowserCommon::watchdog_label(
        'premium_tickets',
        Base_LangCommon::ts('Premium_Projects_Tickets', 'Tickets'),
        $rid,
        $events,
        array('Premium_Projects_TicketsCommon', 'watchdog_label_format'),
        $details
    );
}
public static function watchdog_label_format($r) {
    return $r['ticket_id'] . ': ' . $r['title'];
}

Manipulating records

RecordBrowser exposes a handful of methods for creating and retrieving records without touching its underlying table structure directly.

new_record()

The most basic method:

Utils_RecordBrowserCommon::new_record($record_set, $values);

Creates a new record. The add and added processing actions still apply. Only fields defined through install_new_recordset() or new_record_field() are accepted — you can't set the ID or other record metadata directly. Returns the new record's ID.

update_record()

Utils_RecordBrowserCommon::update_record($record_set, $id, $values, $full_update = false, $date = null, $dont_notify = false);

The first three arguments are the recordset name, the record's ID, and an associative array of values to update. $full_update controls whether unspecified fields keep their old value (false) or get cleared (true). $date lets you override the "edited on" date. $dont_notify, when true, skips sending an event to the Watchdog module — useful for minor updates.

get_record()

Utils_RecordBrowserCommon::get_record($record_set, $id, $htmlspecialchars = true);

Retrieves a single record. Returns an array on success, null otherwise. The first argument is the recordset name, the second the record's ID. The optional third argument, when false, skips htmlspecialchars() escaping of the returned values. Note that this method doesn't check whether the record is active (i.e. not deleted) — it does, however, include an active key indicating its state.

get_records()

Utils_RecordBrowserCommon::get_records($record_set, $crits = array(), $cols = array(), $order = array(),
    $limit = array(), $admin = false);

The most involved of the four. $record_set tells RecordBrowser which recordset to query; by default, only active (non-deleted) records are returned.

$crits is the filter: an array where each key is a column key (optionally with modifiers) and each value is what the record must contain in that field. If a value is itself an array, it's treated as alternatives — the record matches if it has any of those values in that field.

Each key/value pair is one criterion, and by default criteria are joined with AND — a record must satisfy all of them. For example, in CRM/Contacts:

$crits = array('first_name' => array('John', 'Tom'), 'last_name' => 'Doe');

This selects every record where first_name is 'John' OR 'Tom', AND last_name is 'Doe'. John Doe matches; Jeremy Doe doesn't.

In that example, key order doesn't matter — but with modifiers, it can. Modifiers go at the start of the key string:

The ( and | modifiers are the least intuitive of the set, and order matters once they're involved. Say you want everyone whose first name is John or whose last name is Doe:

array('(last_name' => 'Doe', '|first_name' => 'John')

or equivalently:

array('(first_name' => 'John', '|last_name' => 'Doe')

Both give the same result. In each, ( opens the OR group and | extends it — every element in the chain satisfies the whole group if it matches. To add a third condition (say, anyone from New York), add another | element:

array('(first_name' => 'John', '|last_name' => 'Doe', '|city' => 'New York')

Why distinguish ( from | at all? Because sometimes you need (cond_1 OR cond_2) AND (cond_3 OR cond_4). Use ( to open a new group for cond_1 and cond_3 — RecordBrowser will recognize that cond_3 starts a second OR group.

Two things to keep in mind:

• Always open a new OR chain with (, even if you don't think anything else will be ANDed with it — you may not know about other criteria it'll end up combined with (crits from a view access callback, for instance).

• Any element without a | modifier breaks the current OR chain. So:

  array('(first_name' => 'a', 'city' => 'b', '|last_name' => 'c')

  doesn't contain a real OR chain at all — city breaks it, leaving two unrelated one-element groups. Swapping city and last_name would fix that.

Modifying browse view

Custom fields

Custom templates

These three sections are stubs with no content in the source page — flagged during the August 2026 documentation review.