Kevin Carwile

Creating And Using Custom Data Fields


Rules allows you to attach your own custom data fields to any content, content containers, or members in the system. Custom data fields can be set up for internal use only, or be configured to be edited by users via form input.

An added benefit of using custom data fields is that it allows you to create additional rules which are triggered when your custom data fields get updated (either through rules, through form input, or through custom code). Since custom data fields can be updated via rules, and rules can also be created in reaction to that data being updated, this brings in to play all new powerful capabilities such as relational or chained data updates.

Permissions

Data fields also have member group permission associations which allow you to restrict who can see and edit the data. In addition to permissions, you can also restrict custom data fields to specific content containers (forums, categories, etc).

Access Modes

Data fields can be configured for three different access modes:

  • Internal
    When a data field is configured for internal use, it will not be presented for editing on any form, regardless of the 'edit' permission set on the data field. It can only be updated via rules or custom php code, but is still fully available for rules conditions.
  • Public
    When a data field is configured for public use, it will be presented on the editing form for any member with the 'edit' permission on the data field and the item that it is attached to.
  • Administrative
    When a data field is configured for administrative use, it will only be presented for editing by members who have the 'edit' permission on the data field and also have moderator permissions to edit the object which it is attached to.

Data Access Methods

Rules provides multiple ways to access custom data associated with objects. There are three API methods to get and save rules data, as well as two shorthand ways to access rules data via object properties.

API Methods (for php):

The getRulesData() method can be used to retrieve data which has been saved to an object. This method will retrieve data regardless of the permissions of the logged in user.

$data = $object->getRulesData( 'data_key' );

The getRulesDataWithPermission() method can be used to retrieve data saved to an object according to permissions. If the logged in user does not have permission to 'view' the data, then no data will be returned by this method.

$data = $object->getRulesDataWithPermission( 'data_key' );

The setRulesData() method can be used to update the data which is associated with an object.
Note: The data must be the same data type that has been defined in the custom data field configuration, otherwise an \InvalidArgumentException will be thrown.

$object->setRulesData( 'data_key', $data );

Shorthand Methods (for php or template tags)

The shorthand methods for accessing rules data are very useful for a couple of different reasons. Firstly, it's shorter. But more importantly, it can be used safely to check for rules data even if rules is not installed on the site or has been disabled. This means when you use the shorthand data access method in template tags or php code, no errors will be produced if the rules application goes offline.

Data Key (with permissions)

Rules data can be accessed for an object simply by using the data_key for the data as an object property. This method of accessing the rules data will also respect permissions set on the data, so if the logged in user does not have permission to 'view' the data, then the property will be empty.

/* php code */
$data = $object->data_key;
<!-- template tags -->
{{if $object->data_key}}
  <strong>Data:</strong> {$object->data_key}
{{endif}}

Data Key (without permissions)

Data can be accessed for an object without a permission check by prefixing the data_key with "r_". Therefore, any custom data saved to the object will be available regardless of the permissions of the logged in user.

/* php code */
$data = $object->r_data_key;
<!-- template tags -->
{{if $object->r_data_key}}
  <strong>Data:</strong> {$object->r_data_key}
{{endif}}

 


  Report Article


User Feedback


There are no comments to display.