Model setup

For more detailed model customization, you can pass additional parameters in the $model_display_params property in the model class. All options are valid for the admin panel and its create(), update(), and delete() methods.

An example list of all default settings in the ModelBase base class.

protected $display_params = [
    'visible_fields' => '*',
    'hidden_fields' => [],
    'editable_fields' => '*',
    'not_editable_fields' => [],
    'create_actions' => true,
    'update_actions' => true,
    'delete_actions' => true,
    'mass_actions' => true,
    'fields_groups' => [],
    'default_table_columns' => [],
    'default_filters' => [],
    'show_empty_default_filters' => false,
    'redirects_to_models' => [],
    'foreign_keys_admin_links' => false,
    'versions_limit' => 'config'
];

Editable and non-editable fields

editable_fileds - editable model fields, by default: '*' (all fields)

not_editable_fields - non-editable model fields in the administrative interface, by default: an empty array

Visible and hidden fields

visible_fields - visible model fields, by default: '*' (all fields)

hidden_fields - hidden model fields, not displayed in the administrative interface, by default: an empty array

Virtual fields

The ability to create virtual fields that do not participate in CRUD is described in the section text data type.

Operations of creation, editing and deletion

create_actions - the ability to create model records in the admin panel
update_actions - the ability to edit model records in the admin panel
delete_actions - the ability to delete model records in the admin panel
mass_actions - the ability to mass edit/delete model records in the admin panel

All four parameters are set to true by default.

Grouping fields by tabs

If there are many fields in the model, you can ungroup them by tabs when creating and editing records in the administrative interface.

'fields_groups' => [
    'Main parameters' => ['active', 'name', 'url'],
    'Texts and images' => ['content', 'images']
];

Default fields in the general table

default_table_columns - an array of fields that are displayed in the general table until the user sets their own field settings

'default_table_columns' => ['name', 'date', 'color', 'options']

Transition to other models

For some model records, the administrative panel can set the ability to transition to other models. Such a need arises, for example, in the 'Page Menu' model, when the 'News' item is present in the list of model records, but the news itself is located in the 'News' model. For the convenience of users, you can set the ability to click on the 'News' link not to go to the next level of the tree, but to the 'News' model itself.

redirects_to_models - an array of parameters for transition to other models based on the specified criteria ['id'=32, 'url'='news', 'name'='Gallery']. This option is used only in tree models with a field of the 'parent' type.

'redirects_to_models' => [
    'url' => ['news' => 'News'],
    'name' => ['Directory' => 'Catalogs'],
    'id' => ['8' => 'Faq']
]

Links to foreign keys

If this option is set, then in the general table of records in the admin panel, a link will be added to the field with the value of the foreign key for going to the page for editing the record of this value of the foreign key.

'foreign_keys_admin_links' => true

Limit on the number of versions

When updating records through the admin panel, the old version of the record is saved, and it is possible to roll back to the previous values of the fields. The limit on the number of stored versions of one record is set by the 'ModelVersionsLimit' option in the config/settings.php file and is 25 by default. For each model, this value can be changed or the ability to save versions can be completely disabled. When the version limit for a record is reached, versions are deleted, starting with the oldest.

'versions_limit' => 30
'versions_limit' => 0

Configuring model filters

default_filters - array of filters that are visible by default before filtering is started, if the option is not set, the first 7 filters of the model are displayed

show_empty_default_filters - if the option is enabled, default filters will be displayed in the column even if they are not running, while others are running

'default_filters' => ['price', 'name'],
'show_empty_default_filters' => true

Named field parameters

Used when the model does not have a field named 'name'. This is the record name field that is displayed in statistics, for example in the user transaction history. The $name_field parameter specifies which field in the model is considered a named field. You can also set an additional $name_field_extra parameter to append the value of another field to the record name.

Example, client model for registration on the site.

class Clients extends Model
{
    protected $name = 'Clients';

    protected $name_field = 'first_name';

    protected $name_field_extra = 'last_name';

    protected $model_elements = [
        ['Activation', 'bool', 'active'],
        ['Registration confirmation', 'bool', 'confirm'],
        ['Name', 'char', 'first_name', ['required' => true]],
        ['Last name', 'char', 'last_name', ['required' => true]],
        ['Individual key', 'char', 'token']
    ];

    protected $model_display_params = [
        'editable_fields' => ['active', 'first_name', 'last_name'],
        'hidden_fields' => ['token'],
        'create_actions' => false,
        'delete_actions' => false,
        'fields_groups' => [
            'Basic parameters' => ['first_name','last_name'],
            'Registration completed' => ['active','confirm', 'token']
        ],
        'default_table_columns' => ['first_name', 'last_name', 'active'],
        'default_filters' => ['first_name', 'last_name']
    ];
}

Modifying the display of fields in a table

It is possible to change the display of a field in a common table by creating a special method for the model.

class Clients extends Model
{
    ...

    public function processAdminModelTableFields($field, $row)
    {
        if($field === 'last_name')
            return 'Last name: '.$row['last_name'];
    }
}

Event methods

When a record is created, edited or deleted in the administrative part, special methods can be called to perform additional operations on the data. In all methods, $id is the key of the current record, $fields is an associated array of record fields of the form ['name' => 'Maxim', 'age' => 27].

beforeCreate($fields) - the method is called before creating a record (id does not exist yet)
afterCreate($id, $fields) - the method is called after creating a record (id has already been received after the INSERT query)
beforeUpdate($id, $old_fields, $new_fields) - before editing a record (old and new field values)
afterUpdate($id, $new_fields) - after editing a record (new field values)
beforeDelete($id, $fields) - before deleting to the trash
afterDelete($id, $fields) - after deleting to the trash (the record no longer exists in the model table)
beforeRestore($id, $fields) - before restoring from the trash
afterRestore($id, $fields) - after restoring from the recycle bin
beforeFinalDelete($id, $fields) - before final deletion from the recycle bin
afterFinalDelete($id, $fields) - after final deletion from the recycle bin (the recycle bin table entry no longer exists)

The beforeCreate and beforeUpdate methods can return an array of changed fields that will be written to the database and change history. In this case, the returned array can only contain those fields that were changed within this method. The beforeUpdate method receives old and new values of the record fields for comparison. See examples below.

If beforeDelete() or beforeRestore() return false, the delete (restore) operation will not be performed.

class Products extends Model
{
    protected $name = 'Catalog Products';

    protected $model_elements = [ ... ];

    protected function beforeCreate($fields)
    {
        if(!$fields['price'])
            return ['active' => 0];
    }
 
    protected function beforeUpdate($id, $old_fields, $new_fields)
    {
        if(!$old_fields['active'] && $new_fields['active'])
            return ['status' => 'new', 'order' => 1];
    }
     
    protected function beforeDelete($id, $fields)
    {
        if($fields['type'] == 'special')
        {
            $this -> addError('The deletion was not performed because...');
            return false;
        }
    }
}

Inserting code into the administrative interface

If necessary, you can add your own HTML and PHP code fragments to the administrative panel. To do this, create files in the customs/models/ folder that will be automatically connected in pre-designated places. The file name should replace the word 'model' with the name of the model, for example, products-create.top.php.

For regular models

Model record list

model-index-top.php - before top navigation buttons
model-index-bottom.php - after pagination

Creating a new record

model-create-top.php - before form
model-create-form.php - before buttons before form closes
model-create-bottom.php - after form and buttons

Editing a record

model-update-top.php - before form
model-update-form.php - before buttons before form closes
model-update-bottom.php - after the form and buttons

Creating and editing a record

model-action-top.php - before the top navigation buttons
model-action-bottom.php - after the form and buttons

For simple models

Editing fields of a simple model

model-index-top.php - before the form
model-index-form.php - before the buttons before closing the form
model-index-bottom.php - after the form

An example of an included file, we will add a button to go to a special page in the administrative panel, which are described in the section Additions to the administrative panel. For the product model, we will create a file with a button that will be located under the table with model records. The file name for the Products model will be customs/models/products-index-bottom.php.

<?
//If the user has editing rights, we display the link, 
//if not, then a message about insufficient rights

if($system -> user -> checkModelRights($system -> model -> getModelClass(), 'update'))
    $update_path = 'location.href="'.Registry::get('AdminPanelPath').'custom/?view=upload"';
else
    $update_path = "dialogs.showAlertMessage('{no_rights}')";
?>

<button type='button' onclick='<? echo $update_path; ?>'>Update price list</button>

Previous section

Data types

Next section

Simple models