Secciones

El backoffice se compone de Secciones, que consisten en funcionalidad agrupada en una o varias vistas.

El tipo de sección por defecto más usual es de tipo CRUD, que consiste en una vista de Tabla de datos, con un listado, filtros y acciones de item, y otra vista de tipo Detalle que consiste en un formulario donde se presentan los campos para insertar / actualizar un item.

Alternativamente existe un tipo de sección "custom", que deja libertad para mostrar los elementos que se desee.
Éste tipo de de secciones se verán en la sección Secciones Custom.

• Crear sección
• Configuración
  • Definir modelo
  • Definir campos a mostrar
• Definir filtros
• Acciones
  • Acciones de sección
  • Acciones para elementos en listado de datos
• Acciones disponibles
• Vista de listado de datos
  • Definir título
  • Número de elementos por página
  • Query personalizada
  • Enlace a editar desde campo
• Vista de creación / edición
  • Definir título
• Elementos extra
  • Elementos relacionados con un registro
• Acciones antes / después de guardar
  • Antes de guardar
  • Después de guardar

Crear sección

La forma más sencilla de crear una nueva sección es mediante el comando preparado para ello:

php artisan backoffice:section Nombre

Donde Nombre será un identificador, en CamelCase con el cual se generará el archivo de configuración correspondiente en la carpeta Sections.

Nombre de clase y URLs

El sistema está preparado para crear una URL a partir del nombre de la clase de configuración de sección.
Por ejemplo, para una sección Sections/Users.php, el sistema creará la URL /users.
En clases con nombre compuesto como DigitalGoals.php, el sistema creará la URL digital-goals.

Sidebar

Para que la sección aparezca en el sidebar, debe añadirse en el archivo de configuración.
Ésto es cubierto en la sección Sidebar.

Configuración

Una vez creada la sección, su contenido inicial sería el siguiente:

<?php

namespace App\Backoffice\Sections;

use Zeus\Backoffice\Actions\BackToIndexAction;
use Zeus\Backoffice\Actions\CreateAction;
use Zeus\Backoffice\Actions\DeleteItemAction;
use Zeus\Backoffice\Actions\EditItemAction;
use Zeus\Backoffice\Filters\SearchFilter;
use Zeus\Backoffice\Sections\BackofficeResourceSection;

class Brands extends BackofficeResourceSection
{
    protected $titleForIndex = 'Listado';
    protected $titleForCreate = 'Nuevo';
    protected $titleForEdit = 'Modificar';
    protected $model = null;

    protected function fields(): array
    {
        return [];
    }

    protected function filters(): array
    {
        return [
            SearchFilter::make(['name']),
        ];
    }

    protected function actions(): array
    {
        return [
            CreateAction::make('Crear')->hideOnForm(),
            BackToIndexAction::make()->hideOnList()
        ];
    }

    protected function itemActions(): array
    {
        return [
            EditItemAction::make(),
            DeleteItemAction::make()
        ];
    }

    protected function extraElements(): array
    {
        return [];
    }

    protected function customQuery(Builder $query): Builder
    {
        return $query;
    }
}

Definir modelo

Al ser una sección de tipo CRUD, se opera sobre un modelo Eloquent, con las acciones típicas de Listar / Crear / Editar / Eliminar.
El modelo a usar se define mediante la variable $model, por ejemplo:

protected $model = Country::class;

Modelo no definido

Por defecto, al crear una sección mediante el comando, el valor de la variable $model será null, lo cual provocará una excepción de tipo ModelNotDefinedException indicando que el modelo no ha sido definido.

Definir campos a mostrar

Los campos a mostrar, tanto en la vista de listado como en la vista de formulario, se definen en la función fields():

protected function fields(): array
{
    return [
        TextField::make('Nombre', 'name')
    ];
}

Más información

Puedes encontrar más información sobre los campos disponibles y su documentación en la sección Campos.

Definir filtros

Para la vista de listado, puedes añadir filtros como por ejemplo un campo de búsqueda o selector de opciones:

Más información

Puedes encontrar más información sobre los filtros en la sección Filtros

Acciones

Acciones de sección

Pueden definirse botones de acción para realizar ciertas acciones como crear un nuevo registro, volver al listado de datos, etc.

Se definen en la función actions():

protected function actions(): array
{
    return [
        CreateAction::make('Crear')->hideOnForm(),
        BackToIndexAction::make()->hideOnList()
    ];
}

Acciones para elementos en listado de datos

Se definen en la función itemActions().
Normalmente suelen contener los botones para editar y eliminar un registro.

protected function itemActions(): array
{
    return [
        EditItemAction::make(),
        DeleteItemAction::make()
    ];
}

Acciones disponibles

Listado de acciones

El listado de accciones predefinidas y cómo crear acciones personalizadas puede encontrarse en la sección Acciones

Vista de listado de datos

Ésta vista muestra un listado con los registros del modelo especificado, aplicando los filtros especificados.
Consta de un título, un conjunto opcional de filtros, una tabla con filas y columnas con los campos especificados (a menos que tengan la opción hideInList()) y un paginador en la parte inferior:

Definir título

El título a mostrar se define mediante la variable $titleForIndex.

protected $titleForIndex = 'Listado de paises';

Número de elementos por página

Por defecto el listado tiene un número máximo de 15 elementos por página.
Ésto puede ser modificado mediante la variable $itemsPerPage:

protected $itemsPerPage = 10;

Query personalizada

Hay ocasiones que necesitamos aplicar algún tipo de condiciones a la query que mostrará el listado de datos, independientemente de los filtros que se apliquen.
Lo podemos hacer mediante la función customQuery() la cual devuelve un objeto de tipo Builder.

Por ejemplo, si estamos mostrando un listado de usuarios solamente de tipo customer:

protected function customQuery(Builder $query): Builder
{
    return $query->where('type', 'customer');
}

También podemos usarlo por ejemplo para establecer un orden personalizado:

protected function customQuery(Builder $query): Builder
{
    return $query->orderByDesc('name');
}

Enlace a editar desde campo

Además del botón de editar el registro ubicado en la parte derecha de cada fila, es posible asignar que uno o más campos (normalmente de tipo TextField o EmailField) sirva de enlace para ir a la sección de edición.
Se puede realizar aplicando el modificador editLink() al campo:

protected function fields(): array
{
   return [
       TextField::make('Nombre', 'name')->required()->editLink(),
       EmailField::make('Email', 'email')->required()
   ]
}

Vista de creación / edición

Consiste en un formulario para crear / editar un registro.
Los campos definidos serán los que se muestren (a menos que tengan la opción hideInForm() / hideOnCreate() ó hideOnEdit()).

Definir título

Se pueden definir título independientes para la vista de creación y edición.
El título a mostrar en la vista de creación se define mediante la variable $titleForCreate:

protected $titleForCreate = 'Nuevo pais';

El título a mostrar en la vista de edición se define mediante la variable $titleForEdit:

protected $titleForEdit = 'Modificar pais';

Elementos extra

En las vistas de listado / creación / edición, en ocasiones se necesita mostrar información extra o realizar acciones, al margen del listado de datos o el formulario de creación / edición.

Para ello tenemos un array en la función extraElements() donde se pueden añadir elementos que aparecerán en el orden definido por debajo o por arriba del listado de datos o del formulario principal de creación / edición.
Por defecto se sitúa debajo, pero puede ser establecido mediantes los modificadores onTop() y onBottom().

Puedes encontrar el listado completo de elementos que puedes usar en la sección Elementos.

Por ejemplo, si necesitamos un formulario adicional junto a la edición de un usuario, para el envio de un email con un código de vinculación, podemos hacer uso del elemento DataForm:

protected function extraElements(): array
{
    return [
        DataForm::make('Código de vinculación', [
            TextField::make('Código', 'code')->readOnly(),
            EmailField::make('Email', 'email')
        ])
            ->hideOnList()
            ->actionTitle('Enviar código')
            ->actionIcon('mail-send-line')
            ->onSubmit(function (Request $request) {
                Mail::to($request->input('email'))->send(new UserCodeMail($request->input('code')));
            })
    ];
}

Ocultar / Mostrar según vista

Podemos usar los mismos modificadores que usan los campos para mostrarse u ocultarse en ciertas vistas.
Disponemos de los siguientes modificadores:
hideOnList()
hideOnForm()
hideOnCreate()
hideOnEdit()

Seleccionar posición

Puedes elegir dónde quieres mostrar cada elemento, si por encima o por debajo del elemento principal (listado o formulario).
Lo puedes hacer mediante los modificadores:
onTop()
onBottom()

Elementos relacionados con un registro

Hay elementos que reciben los datos del registro actual si estás una vista de edición.

DataForm

En el caso del elemento DataForm en una vista de edición, el sistema aplicará los datos actuales a los campos mostrados, lo que hará que aparezcan rellenos.
También se recibirá el objeto de tipo Model en la función declarada en onSubmit, junto con los datos de la request:

protected function extraElements(): array
{
    return [
        DataForm::make('Código de vinculación', [
            TextField::make('Código', 'code')->readOnly()
        ])
            ->actionTitle('Enviar código')
            ->actionIcon('mail-send-line')
            ->onSubmit(function (Request $request, Model $user) {
                Mail::to($user->email)->send(new UserCodeMail($request->input('code')));
            })
    ];
}

Card

El elemento Card recibe, además del objeto Request, un objeto de tipo Model con los datos del registro actual.

protected function extraElements(): array
{
    return [
        Card::make('backoffice::users.detail', function (Request $request, Model $user) {
            return ['user' => $user];
        })
    ];
}

Acciones antes / después de guardar

A veces se necesita realizar acción como alterar el modelo antes de guardar o ejecutar alguna acción después de guardar.

Antes de guardar

Puedes ejecutar una acción justo antes de que los datos vayan a ser guardados, lo que da la posibilidad de, por ejemplo, alterar algún campo del modelo.

Para ello, en la clase que extiende de BackofficeResourceSection puedes añadir una función beforeSave(), que recibirá un objeto de tipo Model con los datos recogidos del formulario y un objeto de tipo Request con los datos de la request:

class Users extends BackofficeResourceSection
{
    ...

    public function beforeSave(Model $item, Request $request): Model
    {
        // Alteramos el modelo justo antes de guardar y lo retornamos modificado
        $item->slug = Str::slug($item->id . '-' . $item->name);

        return $item;
    }
}

Después de guardar

Puedes ejecutar una acción justo después de que se haya producido el guardado, por ejemplo, enviar una notificación o modificar otros modelos.

Para ello, en la clase que extiende de BackofficeResourceSection puedes añadir una función afterSave(), que recibirá un objeto de tipo Model con los datos del modelo recién guardado y un objeto de tipo Request con los datos originales de la request:

class Users extends BackofficeResourceSection
{
    ...

    public function afterSave(Model $item, Request $request): void
    {
        // Aquí podemos realizar una acción
    }
}