Custom fields

In our modern JMAP ORM, custom fields are commonly assigned to entities only, as properties are dependent on entities and cannot exist without entities. Our legacy ActiveRecord items do not have this condition.

Add custom fields to an entity

Consider the Note entity, that has custom fields by default. However, let us pretend that they have been added as an afterthought by the developer (which is not the case).

Install scripts

First, the custom fields table has to be created. In the install/install.sql table, the following queries should be added:

CREATE TABLE `notes_note_custom_fields` (
  `id` int(11) NOT NULL
) ENGINE=InnoDB;

ALTER TABLE `notes_note_custom_fields`
  ADD CONSTRAINT `notes_note_custom_fields_ibfk_1` FOREIGN KEY (`id`) REFERENCES `notes_note` (`id`) ON DELETE CASCADE;

Of course, the unintall.sql file should drop the custom field table too:

DROP TABLE IF EXISTS `notes_note_custom_fields`;

Edit the entity model

All you need to do in order for the entity to use the custom fields functions, is to include the CustomFieldsTrait trait:

<?php
namespace go\modules\community\notes\model;

use go\core\orm\CustomFieldsTrait;

class Note extends AclItemEntity
{

        /**
         * The Entity ID
         *
         * @var int
         */
        public $id;

        /*
         * Et cetera
         */
        use CustomFieldsTrait;

        /*
         * ... insert methods here
         */

The entity should now pop up in the System Settings > Custom Fields tab. Thu custom field mapping is automatically added, so you do not need to do this manually.

Getting / setting custom fields on the server side

By now, you should be able to add custom fields to your JMAP entity. If you haven’t already, please read the documentation on adding custom field sets and fields.

Building upon our earlier example: now that you have added custom fields to your note entity, let’s add a fieldset named ‘documentation’ and add a field ‘URI’ to it. Programmatically, you can add a note with the custom field somewhat like this:

<?php
$note = new Note();
// Add the normal fields
$note->customFields->URI = "/path/to/your/documentation/page";
$note->save();

The custom field is automatically mapped to the entity, so you can easily refer to the custom field by using the customFields relation.

Conversely, retrieving the value of a custom field is done in a similar way:

<?php
$note = Note::findById($id);
$documentationUri = $note->customFields->URI;

Although the older ActiveRecord model falls outside the scope of this document, please note that getting and setting custom field values works in the same way.