Skip to main content

Customizing models and templates with Yii Behaviors

Customizing models and templates with Yii Behaviors

Developer page - Overview of Yii Behaviors in mDIS

Introduction

For a concise overview, see the developer README. This page provides deeper details and practical examples for customizing mDIS models with Yii Behaviors.

Yii Behaviors for models

Yii Behaviorsopen in new window are a mechanism for injecting reusable logic into models, controllers, and other Yii components. Behaviors can respond to events (e.g., before insert, after update) and add properties or methods to the target class. In mDIS, they are used to automate tasks like generating IDs, enforcing constraints, copying values, and more.

Behaviors are similar to database triggers, but operate at the application level and can be attached to any Yii component, not just models. You can create custom behaviors by extending yii\base\Behavior or use built-in ones like AttributeBehavior.

mDIS provides a set of custom behaviors, implemented in backend/behaviors/ and backend/behaviors/template/. These are attached to models via the behaviors() method and can be parameterized through the Template Manager GUI or directly in code.

Tips

See behaviors-catalog.md for a full list and descriptions of all available behaviors.

mDIS Custom Behaviors

There are 2 important types of behaviors:

mDIS makes use of Behaviors to create...

  • very specific combined keys (CombinedIdBehavior - Automatic)
  • IGSNs (IgsnBehavior - Automatic)
  • autoincremented values that are customizable (UniqueCombinationAutoIncrementBehavior - User-defined)
  • numeric constraints on some groupings inside a data table (ChildrenLimitBehavior - User-defined)
  • serialized JSON strings that can be converted back to JavaScript Objects (JsonFieldBehavior - User-defined)
  • numeric values that are carried over from a previous record to the next (bottom-depth n becomes top-depth of record n+1)

Besides, mDIS makes use of Behaviors to...

  • store JSON Arrays as Strings in database columns, and converting back, serializing multivalued entries. This happens in the Dashboard widgets.
  • manage Access Control for users in the cg Module. This is an internal task.

Automatic Behaviors

Some behaviors are automatically attached based on column names (e.g., combined_id, igsn, analyst). These use AttributeBehavior and require minimal configuration. For more advanced behaviors, parameters can be set in the Template Manager or directly in code.

CombinedIdBehavior

CombinedIdBehavior creates a human-readable ID hierarchy like it was used before, in the Legacy DIS. Strings such as "5063_1_A_3_1" are easier to work with for humans than tuples such as [5063, 1, "A", 3, 1]. Every time a record is inserted or updated, the value of the assigned column (combined_id) is being updated. This behavior does not have to be assigned manually; it is invoked automatically as soon as there exists a column named combined_id in the MySQL data table.

The combined_id model definition should have these characteristics when assigned in the table designer of the Template manager:

// JSON fragment
"combined_id": {
            "name": "combined_id",
            "importSource": "",
            "type": "string",
            "size": 16,  // use appropriate length
            "required": false,
            "primaryKey": false,
            "autoInc": false,
            "label": "Combined Id",
            "description": "Convenience column to print on labels etc. Filled out automatically",
            "validator": "",
            "validatorMessage": "",
            "unit": "",
            "selectListName": "",
            "calculate": "",
            "defaultValue": ""
        }

IgsnBehavior

IgsnBehavior assigns a unique IGSNopen in new window value to a newly inserted record. IgsnBehavior uses the algorithm described in the Wiki Article "How to generate igsns (int geo sample nr) in legacy dis"open in new window. Depending on the table type (Core, Section, ...), a different letter (= "Object Tag" in IGSN jargon) has to be used. The different Object Tags are described in an older mDIS Wiki Articleopen in new window, or in the PHP source code of the behavior (File backend/behaviors/IgsnBehavior.phpopen in new window).
The behavior requires an object tag (one character) in a parameter objectTag. This behavior does not have to be assigned manually: If a table has a column igsn (type string, size 15) and the defaultValue attribute for that column is a single letter (H, C, S, X, B, W, U, T, Y, Z, or F), then the behavior will be automatically applied, and this letter will be used as an appropriate object tag by the IGSN algorithm. You should set the default value in the table designer of the mDIS Template manager.

Table column igsn should have the following characteristics when assigned in the table designer of the Template manager:

//JSON fragment from backend/dis_templates/models/CoreCore.json
"igsn": {
    "name": "igsn",
    "importSource": "IGSN",
    "type": "string",
    "size": 15,
    "required": false,
    "primaryKey": false,
    "autoInc": false,
    "label": "IGSN",
    "description": "IGSN",
    "validator": "",
    "validatorMessage": "",
    "unit": "",
    "selectListName": "",
    "calculate": "",
    "defaultValue": "C" // C for core. Can be H, C, S, X, B, W, U, T, Y, Z, or F
},

Form Field igsn could be designed like this:

//JSON fragment from backend/dis_templates/forms/core.json
{
  "name": "igsn",
  "label": "IGSN",
  "description": "IGSN (autom. calculated)",
  "validators": [
    {
      "type": "string",
      "min": null,
      "max": 15
    }
  ],
  "formInput": {
    "type": "text",
    "disabled": false,
    "calculate": "",
    "jsCalculate": ""
  },
  "group": "Subgroup",
  "order": 3
}

Actual values of some fields (such as Label descriptions) are a matter of the form designer's personal taste and preferences.

Parameterizable Behaviors

Parameterizable behaviors allow for advanced logic, such as custom auto-increment, limiting child records, copying values, and more. See the behaviors-catalog.md for a full list, parameters, and usage examples.

Tutorial: Using a behavior

How to Attach a Behavior

To attach a behavior to a model, add it to the behaviors() method in your model class. For example:

use app\behaviors\ChildrenLimitBehavior;

public function behaviors()
{
  return array_merge(parent::behaviors(), [
    [
      'class' => ChildrenLimitBehavior::class,
      'parentRefColumn' => 'core_id',
      'limit' => function ($model) {
        return $model->core->last_section;
      }
    ]
  ]);
}

Behaviors can be parameterized as needed. For details on each behavior and its parameters, see behaviors-catalog.md.

Tips

  • Behaviors can be reused across models.
  • New behaviors can be created by extending yii\base\Behavior.
  • The Template Manager GUI supports basic parameterization, but advanced use may require editing PHP code directly.

Template Behaviors

The Template Manager GUI allows you to attach and configure behaviors for models and forms. For advanced scenarios, consult the source code and the catalog for available behaviors and their options.