User Interface | Documentation

Once you defined the structure of application objects, Osm Admin provides the default user interface that allows you to manage them in the admin area.

You can customize the user interface by defining custom views, and by changing property editing or filtering behavior.

Status. This specification is a work in progress.

Contents:

Views

There maybe N configured ways to show an object, or a list of objects, and these "ways" are called views. Also, there are several places in the UI where objects are displayed, for example:

list - the object list page of the admin area
form - the object creation/editing page of the admin area

Define various views for every such place in the UI, by specifying the class name, and the place name as shown below:

namespace My\Base\Product;

use My\Base\Product;
use Osm\Admin\Ui\Grid as BaseGrid;
use Osm\Admin\Ui\Form as BaseForm;
...

// a view to be shown on the product list page of the admin area

#[Class_(Product::class), View('list')]
class Grid extends BaseGrid {
}

// a view to be shown on the product creation and editing pages 
// of the admin area

#[Class_(Product::class), View('form')]
class Form extends BaseForm {
}

// a view to be shown when selecting products to be added as order lines

#[Class_(OrderLine::class), Property('product'), View('select')]
class SelectOrderLine extends Grid {
}

Name

Each view has a name inferred from the class name: Grid view is called grid, Form view is called form.

Some place in the UI allow user to select the view. For example, you can select a list view. In this case, Osm Admin shows a view specified in the ?view=<name> URL parameter. If omitted, the default view, having a predefined name, is used. For example, the default view name for list is grid.

If needed, assign a custom view name using the #[Name] attribute:

#[Class_(Product::class), View('list'), Name('newest')]
class NewestGrid extends BaseGrid {
}

Auto-Generated Views

You may wonder why the admin area works without defining any views in the code base, and answer is, because Osm Admin automatically generates default views that are not defined manually.

The automatically generated list view is a grid with a single column, title. It's equivalent to:

#[Class_(Product::class), View('list')]
class Grid extends BaseGrid {
    public array $select = ['title'];
}

The automatically generated view used on creation and editing pages is a form showing all properties in a single fieldset:

#[Class_(Product::class), View('form')]
class Form extends BaseForm {
    protected function get_layout(): array {
        return [
            '' => [
                'sections' => [
                    '' => [
                        'fieldsets' => [
                            '' => [
                            ],
                        ],
                    ],
                ],
            ],
        ];
    }
}

Controls

A property of the same type, say int, maybe represented in the UI in a number of ways, for example, Input, Select or Hidden. The "way" a property is represented and behaves in the UI, is called control.

Specify a property control using the following attributes:

#[Input]
#[Select]
#[Switch]
#[Relation]
#[Date]
#[Markdown]
#[Hidden]

For example:

/**
 * @property string $name
 * @property int $qty
 * @property float $price
 * @property bool $enabled #[Select]
 * @property Carbon $created_at
 */
class Product extends Record
{
}

If you don't specify a control explicitly, a default one is used. Most properties are displayed as inputs, bool properties are displayed as switches, date properties are displayed as date pickers, and so on.

Filters

There are several ways a property filter can be rendered, for example, int property can be displayed as Checkboxes or Slider. Specify a property filter type using #[Filter\*] attributes:

#[Filter\Checkboxes]
#[Filter\Slider]
#[Filter\Input]

For example:

/**
 * @property string $name
 * @property int $qty
 * @property float $price #[Filter\Slider]
 * @property bool $enabled
 * @property Carbon $created_at
 */
class Product extends Record
{
}

If you don't specify a filter type explicitly, a default one is used. Most properties are displayed as a list of checkboxes.