Settings

Edit settings in the administration

Editor mode is a development tool of the separate crudadmin/admin-editor package. Install it as a development dependency, production installs without dev dependencies carry no editor code at all:

composer require --dev crudadmin/admin-editor

Enable Editor mode in its own dropdown beside the administration language switch. The dropdown also opens every setting of the model you are looking at. The switch is available only to a signed-in administrator with full access (hasAdminAccess()) with APP_DEBUG=true outside the production environment. The server applies the same restrictions to reads and writes. With roles enabled, full access requires permissions = true; with roles disabled, CrudAdmin administrators already have full access. Pencils beside form headings, table headers, buttons, filters and the column picker open a shared settings modal. Their tooltips show the setting keys. A button pencil opens all three button texts: opening a new form, submitting a new record and saving an existing record. The pencil beside the table heading opens all editable settings for that model. Every modal edits only the settings its pencil covers. Edits render in the administration immediately; closing the modal without saving restores the stored settings. The initial editable set is increments, filter.single, filter.max_buttons, title.create, title.update, buttons.create, buttons.insert, buttons.update, columns.*.name, columns.*.hidden, and the default column snapshot. Other settings remain in PHP. The editor uses a shared registry for field types, group titles and server validation; fields are grouped by their prefix into the same cards the administration uses for field groups, and an empty field shows the value the administration renders in its place as the placeholder. Changes are written to the models section of bootstrap/admin.php, keyed by the model class basename. Commit and deploy this file with your application. Moving a model to another namespace keeps its settings. The file contains the current configuration only, not a change history. Existing model settings and mutators remain supported; the file overrides their values. Restore original setting removes an override.

bootstrap/admin.php

<?php

return [
    'models' => [
        'Product' => [
            'buttons.create' => _('Add product'),
            'columns.price.name' => _('Price'),
            'filter.max_buttons' => 4,
            'title.create' => _('New product'),
            'title.update' => _('Editing :name'),
        ],
    ],
];

Every administration setting lives in this one file, each under its own section. Besides models it holds the navigation tree; sections a project does not declare are left out. The same dropdown opens Upraviť menu, a modal arranging the menu: see menu order and groups. Enter text in the source language. The editor reads source strings even when your current administration language is different. Translatable values are written using _('text'), and bootstrap/admin.php is included in administration gettext extraction. Placeholders such as :name and :id remain supported. The file is never executed, it is read as source, so _('text') marks a string for extraction without translating it there. The file is independent of bootstrap/cache/crudadmin.php: admin:cache never overwrites it, and settings are translated at runtime. Conflicting concurrent edits are rejected; reopen the editor to load the current file before saving again.

Default columns

In editor mode, arrange and toggle columns in the column dropdown, then choose Use as default. This saves both their order and visibility for the model, including nested tables. A snapshot can override hidden; it cannot expose password or inaccessible columns. Clear default removes the snapshot and restores the model defaults. Existing personal column preferences remain above the shared defaults. When the developer changes table settings, the open model previews the new defaults. Newly introduced columns are inserted after their nearest predecessor from the current model definition and use that definition’s visibility. Removed fields are ignored; migrated virtual columns are retained explicitly. Use snapshots to reorder columns of fields. Keep columns.*.before and columns.*.after for virtual columns: a column without a field is not part of the model definition, so the declaration is the only place its position can be stated. Existing before / after declarations on field columns can be converted by admin:upgrade:settings.

Defining settings

Settings control texts, the table, the grid, search and form behaviour of a module. Define them in the $settings property, or in the settings() method when values depend on runtime conditions.

app/Models/Order.php

protected $settings = [
    'title.update' => 'Order no. :number',
    'columns.client_id.name' => 'Customer',
    'grid.default' => 'full',
];

app/Models/Product.php

public function settings()
{
    return [
        'table.increments' => admin()?->isSuperAdmin() ?? false,
        'search.autosave' => true,
        'form.modal' => ['enabled' => true, 'width' => 900],
    ];
}

When the settings() method exists, the $settings property is ignored. The method is evaluated on every request of the administration, so it can read config, the logged administrator or the request. Settings can be written as nested arrays or with dot keys. Both forms produce the same result and can be mixed. When the same path is declared twice, the later value wins.

protected $settings = [
    'grid' => ['default' => 'full'],
    'grid.sizes' => ['half', 'full'],
];

To extend the settings of a model from a module or a parent class, use the setSettingsProperty mutator:

public function setSettingsProperty($settings)
{
    return array_merge($settings, [
        'form.actions' => true,
        'title.update' => ':number - :name',
    ]);
}

Texts in title.*, buttons.* and columns.*.name are translated with gettext, so write them in the source language of the administration.

Most settings only change the administration interface, they do not restrict the server. 'form.editable' => false makes the form read-only, but updates are still accepted. Use the $editable parameter to forbid them.

Form texts

app/Models/Client.php

protected $settings = [
    'title.rows' => 'Clients',
    'title.create' => 'New client',
    'title.update' => 'Editing client :name (no. :id)',
    'buttons.create' => 'Add client',
    'buttons.insert' => 'Create client',
    'buttons.update' => 'Save client',
    'buttons.show_history' => 'Changes',
];

Key	Where it is shown	Default
`title.rows`	heading above the table	model name
`title.create`	heading of the new record form	”Add new”
`title.update`	heading of an opened record	`name`, `title`, `username` or `number` of the record
`buttons.create`	add new record button above the table	”Add new”
`buttons.insert`	submit button of the new record form	”Send”
`buttons.update`	submit button of an opened record	”Save”
`buttons.show_history`	history button in the form header	”Show changes”

Every :column placeholder in title.update is replaced by the value of the opened record. Values of select and radio fields are replaced by the option label, translatable values by the first language. Set 'buttons.create' => false to hide the add button.

Well known table names get these texts automatically, the same way as the module icon. A table ending with clients gets “New client” and “Editing client no. :id” without any setting; a declared value always wins.

Columns

app/Models/Product.php

protected $settings = [
    'columns.name.name' => 'Product',
    'columns.name.clickable' => false,
    'columns.code.hidden' => true,
    'columns.description.limit' => 60,
    'columns.price.add_after' => ' €',
    'columns.price.after' => 'name',
    'columns.stock.before' => 'price',
    'columns.released_at.format' => 'd.m.Y',
];

Key	Effect
`name`	column header, also used in the table download
`hidden`	the column is turned off by default, the administrator can turn it on in the columns list
`limit`	maximum length of the text in the cell, `0` shows the whole text
`before` / `after`	places the column next to another column; keep it for virtual columns, which have no field to anchor them, and use a default column snapshot to reorder field columns
`add_before` / `add_after`	text added before or after a non-empty value, for example a unit
`clickable`	`false` does not open the record when the cell is clicked
`format`	date format of the value, also for columns added by `setAdminAttributes`
`type`	`integer` sorts the column numerically in the browser
`sort_by`	sorts the column by another column or by a value selected in `scopeAdminRows()`, in the database when the query has it; a list uses the first one the query has
`sortable`	`false` turns off sorting by the column
`editable`	`false` turns off switching the column to its field in the table, see `column_editable`

Use columns.*.name to customize column headers, for example columns.price.name.

Adding new columns

A column which is not a field adds a new column to the table. Its value is added by setAdminAttributes or loaded in scopeAdminRows.

protected $settings = [
    'columns.price_vat' => [
        'name' => 'Price with VAT',
        'after' => 'price',
    ],
    'columns.paid_status' => [
        'name' => 'Status',
        'encode' => false,
    ],
    'columns.progress' => [
        'name' => 'Progress',
        'component' => 'OrderProgressColumn',
    ],
];

before / after place the column next to an existing one. A virtual column is not part of the model definition, so a default column snapshot cannot position it; declare it here.
'encode' => false renders the value as HTML and disables the text limit.
component renders the cell with a Vue component from the component directories. The component receives the value, valueMutated, valueLimited, field, row and model props. Unknown component names are ignored.
'hidden' => true adds the column turned off, the administrator can still enable it in the columns list.

Table and grid

app/Models/StockMovement.php

protected $settings = [
    'table.increments' => false,
    'table.checkboxes' => false,
    'table.small' => true,
    'table.columns_picker' => false,
];

Key	Effect
`table.enabled`	`false` hides the table, table layouts stay visible
`table.small`	compact table
`table.dense`	`true` or `false` forces the dense table, which a page of 100 records and more switches to on its own: tighter rows, smaller type, no drag handle
`table.virtual`	a page with more records than this renders in full only the rows in view while scrolling, the rest as plain text placeholder rows; default `20`, `false` renders every row
`table.clickable`	`false` does not open records by clicking the row
`table.columns_picker`	`false` hides the columns list
`table.sortable`	`false` disables sorting by clicking column headers, drag and drop is controlled by `$sortable`
`layout.split_view`	`true` keeps the table and the form side by side also in the full grid
`table.checkboxes`	`false` hides the checkboxes for bulk actions
`table.increments`	`false` hides the id column and the id search option
`table.timestamps`	`true` shows created and updated dates in the row actions
`table.actions`	`false` hides the row action buttons
`form.editable`	`false` shows opened records read-only, see read-only forms
`default`	`true` opens this module after login
`recursivity.name`	tab name of a model nested in itself
`recursivity.max_depth`	maximum nesting of a model in itself, default `10`

Grid

The grid defines how the table and the form share the screen: small, big, half (alias medium) and full.

protected $settings = [
    'grid.default' => 'half',           // size used until the administrator picks one
    'grid.sizes' => ['half', 'full'],   // sizes the administrator can switch between
];

grid.sizes is the only way to restrict the sizes. The switcher hides itself when one size is left, so 'grid.sizes' => ['full'] locks the module to the full grid.

A form with 20 or more fields opens in the full grid. Declaring grid.default or grid.sizes turns that rule off and keeps your own sizes.

Search, filters and pagination

protected $settings = [
    'search.enabled' => true,          // always show the search bar, false hides it
    'search.column' => 'number',       // preselected search column
    'search.autosave' => true,         // remember searches of the administrator
    'pagination.limit' => 50,          // rows per page, 0 does not load rows at all
    'pagination.limits' => [25, 50, 100],
    'pagination.enabled' => false,     // load all rows at once
    'filter.single' => true,           // only one filter at once
    'filter.max_buttons' => 3,         // more filters are rendered as a dropdown
];

By default the search bar appears when the table has at least 3 rows. Filter buttons are defined by getFilterStates(), which fills filter.items automatically. 'filter.enabled' => false hides them.

Form behaviour

app/Models/Booking.php

protected $settings = [
    'form.modal' => ['enabled' => true, 'width' => 900],
    'form.actions' => true,
    'form.autoreset' => false,
    'table.refresh_interval' => 30000,
    'table.reload_on_update' => true,
];

Key	Effect
`form.enabled`	`false` hides the form, only the table is shown
`form.modal`	opens records in a modal in the full grid, `form.modal.width` sets its width
`form.actions`	shows the row action buttons in the header of an opened record
`form.header` / `form.footer`	`false` hides the form header or the footer with the submit button
`form.autocomplete`	`autocomplete` attribute of text inputs, default from the `model.settings.form.autocomplete` config
`layout.header`	`false` hides the module header with the grid switcher, search and add button
`tabs.enabled`	`false` does not render the form tabs
`tabs.default`	index of the tab opened by default
`tabs.autoload`	`false` loads child models of a tab only when the tab is opened
`tabs.name`	name of the first tab holding fields outside of tabs, default “General”
`form.autoreset`	`false` keeps the created record opened instead of resetting the form
`table.refresh_interval`	automatic refresh of rows in milliseconds, `false` refreshes once per hour, default 60–120 s
`table.reload_on_update`	reloads all rows after a record is saved

Read-only forms

'form.editable' => false renders an opened record without the save button. It changes the browser only, the server still accepts updates; use the $editable parameter to forbid them. The setting is meant to be switched at runtime, so a custom component can close the form for a record it decides about:

model.setSettings('form.editable', row.state === 'closed');

File fields in the form

protected $settings = [
    'fields.invoice.downloadable' => false,
    'fields.invoice.deletable' => false,
    'fields.brand_id.options' => ['createOption' => true, 'searchable' => true],
];

downloadable / deletable hide the download link and the remove button of an uploaded file.
options are passed as props to the select component of the field.

Primary key

The administration reads the primary key name from Eloquent’s getKeyName(). Use the standard model property instead of a separate setting:

protected $primaryKey = 'code';

The default is id. This property identifies the model’s actual database key; it is not an alternative display column. For a non-incrementing string key, also configure $incrementing = false and $keyType = 'string' on the model.

Getting started

Upgrade guide

Admin interface

Validation

Frontend

Website

Edit settings in the administration

Default columns

Defining settings

Form texts

Columns

Adding new columns

Table and grid

Grid

Form behaviour

Read-only forms

File fields in the form

Primary key

​Edit settings in the administration

​Default columns

​Defining settings

​Form texts

​Columns

​Adding new columns

​Table and grid

​Grid

​Search, filters and pagination

​Form behaviour

​Read-only forms

​File fields in the form

​Primary key

Edit settings in the administration

Default columns

Defining settings

Form texts

Columns

Adding new columns

Table and grid

Grid

Search, filters and pagination

Form behaviour

Read-only forms

File fields in the form

Primary key