Adding custom columns

A custom column is a column that an administrator adds to a model from the configuration, without writing code. It is shown in the table and in the form like every other column.

Which models support them

Hubleto\Erp\Model::describeColumns() reads the custom columns of every model, so you can extend any model. Four community models declare that they are meant to be extended with the property isExtendableByCustomColumns: Customer, Contact, CashRegister and Receipt.

apps/Customers/Models/Customer.php (excerpt)

  public bool $isExtendableByCustomColumns = true;

NOTE Nothing in the current code reads isExtendableByCustomColumns. Treat it as a declaration of intent that you can set in your own models.

How the columns are loaded

The definitions are stored as JSON in the configuration, under models/<full class name of the model>/customColumns. The key is the name of the column and the value its definition:

src/Model.php (excerpt)

  public function describeColumns(): array
  {
    $columns = parent::describeColumns();
    $customColumns = $this->config()->forModel(get_class($this))->getAsJson('customColumns');

    foreach ($customColumns as $colName => $colDef) {
      if (!is_array($colDef)) continue;
      $colClass = 'Hubleto\\Framework\\Db\\Column\\' . ($colDef['class'] ?? '');
      if (class_exists($colClass)) {
        $columns[$colName] = new $colClass($this, $colDef['title'] ?? '')
          ->fromArray($colDef)
          ->setProperty('isCustom', true)
          ->setDefaultVisible()
        ;
      }
    }

    return $columns;
  }

The definition

{
  "customer_code": {
    "class": "Varchar",
    "title": "Customer code",
    "required": true,
    "placeholder": "e.g. C-0001",
    "cssClass": "w-48"
  },
  "vip": {
    "class": "Boolean",
    "title": "VIP customer"
  },
  "segment": {
    "class": "Integer",
    "title": "Segment",
    "enumValues": { "1": "Small", "2": "Medium", "3": "Large" }
  }
}

• class is the short name of a class from Hubleto\Framework\Db\Column (Varchar, Integer, Boolean, Date, ...), not the full name.
• Keys that are read: title, reactComponent, placeholder, readonly, required, visibility, unit, format, defaultValue, examples, enumValues, cssClass, tableCssClass, enumCssClasses, predefinedValues, lookupModel, decimals, step, icon, byteSize, endpoint, creatable.
• Custom columns are always visible in the table by default (setDefaultVisible()) and are marked with isCustom.

Create the column in the database

Defining the column does not create it in the table. At the time of writing, no tool of Hubleto does it for custom columns, so add it with SQL, using the type of the column class:

ALTER TABLE `customers` ADD COLUMN `customer_code` VARCHAR(255) NULL;
ALTER TABLE `customers` ADD COLUMN `vip` TINYINT(1) NOT NULL DEFAULT 0;

Until the column exists in the table, loading the table fails with an SQL error.

NOTE In the current framework Column::fromArray() reads some keys with a typo: yesText and noText are read as yestText and notText, and hint is only applied when description is present. These keys have no effect in custom columns. See Patch files.

When to use custom columns

• Use them for small, per-installation additions: a customer code, a segment, an external ID.
• Do not use them for a feature of your app. Create a model with proper columns and a migration instead.