Model parameters

Every admin model is built from parameters that define how its components are generated in the administration. A freshly created model already contains the most common ones, which you can edit, remove or extend.

Any parameter that creates a database column, or changes an existing column or its properties, requires an automatic migration with php artisan admin:migrate. The command synchronises the whole relational database.

1. Fields

The $fields parameter defines every database column, every form input, the validation rules and the data shown in the record listing.

Static fields

protected $fields = [
    'name' => 'name:Name|placeholder:Enter the article name|type:string|required|max:90',
    'content' => 'name:Article content|type:editor|required',
    'image' => 'name:Author photo|type:file|image',
    'countries' => 'name:Country list|type:select|options:Slovak,Czech,English',
];

Dynamically generated fields

When fields are generated dynamically, you can change the rules for saving a record — the currently edited record is passed to the method.

The example below applies an exception to the unique e-mail rule for the record being edited.

public function fields($row)
{
    return [
        'username' => 'name:Full name|type:string|required',
        'email' => 'name:E-mail|email|required|unique:users,email,'.(isset($row) ? $row->getKey() : 'NULL'),
    ];
}

The complete field reference is in Fields.

2. Basic parameters

Creation date

$migration_date holds the date and time the model was created. The administration uses it to order the modules and build the structure in the right sequence.

protected $migration_date = '2017-11-05 10:00:00';

Required parameter, generated automatically. One date can belong to at most one admin model.

Module name

The name of the section in the administration.

protected $name = 'Articles';

Module name in the administration sidebar

Required parameter, generated automatically.

Module description

The optional description of the section in the administration.

protected $title = 'Edit the list of articles in the blog section.';

Module description under the section heading

Module group

An admin model can be assigned to a subgroup defined in the system configuration.

protected $group = 'settings';

Localization

Allows a unique translation of the content for every language version of the site.

protected $localization = true;

Each module gets unique records per language version, and a foreign key to the languages table is created automatically.

Translating records and texts is covered in Localization.

Relations between models

$belongsToModel defines the relationship between two or more admin models.

protected $belongsToModel = Article::class;

If a model is a child of several admin models at once, pass an array.

protected $belongsToModel = [Article::class, News::class, Blog::class];

Foreign keys between the tables are created automatically.

Relations and content branching are covered in Database relations.

Automatic URL generation

$sluggable generates URL addresses from the value of a column. Useful for content whose URL carries a formatted value that is then used to look the record up.

protected $sluggable = 'field-name';

A slug column is created in the table, holding the value of the chosen column without diacritics and in nice URL form.

Generating and resolving URL addresses is covered in Pretty URLs.

Change history

Enables the history of changes made to records.

protected $history = true;

Change history also has to be enabled in the administration configuration.

Disabling the module

When you need the database table without generating an administration interface, or you simply want to hide the module, set the value to false.

protected $active = true;

Skipping column removal during migrations

If your admin model is attached to an existing table shared with another project, which contains columns the admin model does not define, list those columns so they are ignored.

protected $skipDropping = ['column_x', 'column_y'];

3. Content restrictions

Each module needs its own content rules — the maximum or minimum number of records, whether records can be reordered by drag and drop, whether they can be published or deleted.

Creating records

Set to false to forbid creating new records in the section.

protected $insertable = true;

Editing records

Set to false to forbid editing existing records in the section.

protected $editable = true;

Deleting records

Set to false to forbid deleting existing records in the section.

protected $deletable = true;

Publishing records

Set to true to allow publishing and hiding records in the section.

protected $publishable = true;

A published_at column is created in the table, holding the publication state of the record.

Reordering records

Set to false to forbid moving records by drag and drop. Reordering is enabled on every admin model by default.

protected $sortable = true;

An _order column is created in the table, holding the position of the record. Records selected through the Eloquent model are ordered by it automatically.

Minimum number of records

Once the minimum number of records is reached, the administration hides the option to delete records.

protected $minimum = 0;

The value 0 means no limit.

Maximum number of records

Once the maximum number of records is reached, the administration hides the option to add new records.

protected $maximum = 0;

The value 0 means no limit.

Single record mode

$single switches the interface into single-record mode by setting $minimum and $maximum to 1. The record listing is hidden and the page contains only the form for editing one record.

protected $single = false;

In this mode $sortable and $publishable are set to false, which affects the database migration.

Useful for static pages such as About us or Contact, or for application settings that do not need more than one row.

4. Additional settings

Additional settings target specific behaviours of the admin model — form texts, table rules and similar options. They are defined in the $settings property or the settings() method.

protected $settings = [
    'columns.column_name' => [
        'name' => 'XYZ',
        'hidden' => true,
    ],
    'columns.other_column.name' => 'My column name',
];

Settings can be written as a nested array, or with keys where dots separate the nesting.

Form texts

protected $settings = [
    'title' => [
        'create' => 'New record',
        'update' => 'Editing record no. :id',
    ],
    'buttons' => [
        'insert' => 'Create a new record',
        'create' => 'Submit the new record',
        'update' => 'Update the record',
    ],
];

Column names and order

Use these parameters to hide a column, limit its text length or change its default name.

protected $settings = [
    'columns' => [
        'field1' => [
            'name' => 'Column name for field x',
            'limit' => 4,
        ],
        'field2.name' => 'Column name for field y',
        'field2.after' => 'field1',
        'field3' => [
            'before' => 'field1',
        ],
    ],
];

Adding new columns

You can add columns that carry no value from an existing database column and assign them any value, including HTML that will be rendered.

protected $settings = [
    'columns' => [
        'price_vat' => [
            'name' => 'Price with VAT',
            'after' => 'field1',
        ],
        'paid_status' => [
            'name' => 'Status',
            'encode' => false,
        ],
    ],
];

public function setAdminAttributes($attributes = [])
{
    $attributes['price_vat'] = ($this->price * 1.2) . ' €';
    $attributes['paid_status'] = $this->paid_at
        ? '<i class="fa fa-check green"></i>'
        : '<i class="fa fa-times unpaid"></i>';

    return $attributes;
}

Columns loaded by the query

setAdminAttributes runs for every row. When a column needs data from another table, a query inside it runs once per row. Load the value in the query of the table instead, with the scopeAdminRows scope.

app/Models/Package/Package.php

protected $settings = [
    'columns.last_version' => [
        'name' => 'Latest version',
        'after' => 'name',
    ],
];

public function scopeAdminRows($query)
{
    $query->addSelect([
        'last_version' => PackagesRelease::select('version')
            ->whereColumn('packages_releases.package_id', 'packages.id')
            ->orderByDesc('released_at')
            ->limit(1),
    ]);
}

public function setAdminRowsResponse()
{
    $this->makeVisible('last_version');
}

The table response contains only the fields of the admin model. A value added to the query is loaded, but it does not reach the response until you make it visible with makeVisible in setAdminRowsResponse.

Without setAdminRowsResponse, the column stays empty in the table, even though the query returns the value.

Visibility can be changed in three methods, which run before the attributes are rendered:

Method	Runs for
`setAdminResponse`	every response of the record
`setAdminRowResponse`	a single record, when it is opened in the form
`setAdminRowsResponse`	the rows of the table

Custom buttons in the side panel

The side panel of a record, which holds the delete and publish buttons, can be extended through $buttons.

protected $buttons = [
    App\Admin\Buttons\MyButton::class,
];

Configuring buttons is covered in Actions and buttons.

Custom layouts in the interface

The administration interface can be extended with layout snippets that build on the existing admin components.

protected $layouts = [
    App\Admin\Layouts\MyFormLayout::class,
];

Configuring layouts is covered in Layout snippets.

Getting started

Admin interface

Validation

Frontend

1. Fields

Static fields

Dynamically generated fields

2. Basic parameters

Creation date

Module name

Module description

Module group

Localization

Relations between models

Automatic URL generation

Change history

Disabling the module

Skipping column removal during migrations

3. Content restrictions

Creating records

Editing records

Deleting records

Publishing records

Reordering records

Minimum number of records

Maximum number of records

Single record mode

4. Additional settings

Form texts

Column names and order

Adding new columns

Columns loaded by the query

Custom buttons in the side panel

Custom layouts in the interface

​1. Fields

​Static fields

​Dynamically generated fields

​2. Basic parameters

​Creation date

​Module name

​Module description

​Module group

​Localization

​Relations between models

​Automatic URL generation

​Change history

​Disabling the module

​Skipping column removal during migrations

​3. Content restrictions

​Creating records

​Editing records

​Deleting records

​Publishing records

​Reordering records

​Minimum number of records

​Maximum number of records

​Single record mode

​4. Additional settings

​Form texts

​Column names and order

​Adding new columns

​Columns loaded by the query

​Custom buttons in the side panel

​Custom layouts in the interface

1. Fields

Static fields

Dynamically generated fields

2. Basic parameters

Creation date

Module name

Module description

Module group

Localization

Relations between models

Automatic URL generation

Change history

Disabling the module

Skipping column removal during migrations

3. Content restrictions

Creating records

Editing records

Deleting records

Publishing records

Reordering records

Minimum number of records

Maximum number of records

Single record mode

4. Additional settings

Form texts

Column names and order

Adding new columns

Columns loaded by the query

Custom buttons in the side panel

Custom layouts in the interface