Saltar al contenido
MovieMaster

Desarrolladores: plugins y themes

Páginas de administración para plugins

3 min de lectura 9 apartados

En esta página

Cómo darle a un plugin su propia sección en el panel de administración: la página, su entrada en el menú, el controlador, las vistas con el aspecto del panel, los permisos y los hooks del admin. Los ajustes simples no necesitan nada de esto: con $plugin->setting() el núcleo pinta el formulario por ti.

Registrar una página #

php
// plugin.php
$plugin->adminPage('panel', __('mi-plugin::menu'), [MiPlugin\AdminController::class, 'handle'], [
    'parent' => 'top',
    'icon'   => 'star',
    'cap'    => 'manage_content',
    'order'  => 60,
]);
ArgumentoQué es
$keyIdentificador de la página dentro del plugin. Forma la URL: /admin/p/<slug>/<key>.
$labelTexto del menú y título por defecto de la página. Pásalo traducido.
$handler[Clase::class, 'metodo'], un closure o cualquier callable. Se llama igual que un controlador de ruta.
$optionsOpciones de la tabla siguiente.
OpciónPor defectoEfecto
parentsystemGrupo del menú donde aparece: movies, series, content, import, player, appearance, system, o top para una entrada propia en el primer nivel.
icondotIcono del menú (lista abajo). En los submenús se suele dejar dot.
capmanage_settingsCapacidad necesaria para ver la entrada y abrir la página.
order50Posición dentro del grupo (menor = más arriba). Las entradas de primer nivel del núcleo van de 0 a 97.
methods['GET', 'POST']Métodos HTTP que acepta la URL.

Cada página tiene el nombre de ruta admin.plugin.<slug>.<key>, así que su URL se obtiene con route('admin.plugin.mi-plugin.panel'). Puedes registrar varias páginas con claves distintas; cada una es una entrada del menú.

Iconos del menú #

home, video, film, tv, folder, tag, star, image, file, palette, layout, plug, users, user, settings, refresh, cpu, server, dot, sliders, search, list, clock, inbox, globe, layers, play, filter, key, download, upload, check, alert, info, trash, edit, eye, plus, external.

Los mismos nombres sirven dentro de las vistas: @include('admin::partials/icon', ['name' => 'refresh']).

El controlador #

Hereda de MovieMaster\Admin\AdminController. Te da el layout del panel, los avisos y las redirecciones con mensaje:

MétodoQué hace
render(string $template, array $data = [], ?Request $request = null): ResponsePinta la vista con las variables del layout (usuario, menú, avisos, errores). Pasa page_title en $data para el título y la miga de pan. La respuesta sale con no-store.
redirect(string $to, ?string $success = null, ?string $error = null): ResponseRedirige y deja un aviso verde ($success) o rojo ($error) en la siguiente página.
back(Request $request, array $errors, ?string $to = null): ResponseVuelve al formulario con los errores por campo y lo que se había escrito.
json(mixed $data, int $status = 200): ResponseRespuesta JSON, para llamadas desde JavaScript.

Propiedades disponibles: $this->view, $this->session, $this->auth y $this->menu. Si necesitas más servicios, añádelos al constructor y llama al del padre:

php
<?php
declare(strict_types=1);

namespace MiPlugin;

use MovieMaster\Admin\AdminController as Base;
use MovieMaster\Admin\Menu;
use MovieMaster\Auth\Auth;
use MovieMaster\Auth\Session;
use MovieMaster\Http\Request;
use MovieMaster\Http\Response;
use MovieMaster\View\Engine;

final class AdminController extends Base
{
    public function __construct(Engine $view, Session $session, Auth $auth, Menu $menu, private Repository $repo)
    {
        parent::__construct($view, $session, $auth, $menu);
    }

    public function handle(Request $request): Response
    {
        $here = route('admin.plugin.mi-plugin.panel');

        if ($request->isPost()) {
            $nombre = trim($request->string('nombre'));
            if ($nombre === '') {
                return $this->back($request, ['nombre' => __('mi-plugin::nombre_obligatorio')]);
            }
            $this->repo->crear($nombre);
            return $this->redirect($here, __('mi-plugin::guardado'));
        }

        return $this->render('mi-plugin::admin', [
            'page_title' => __('mi-plugin::menu'),
            'items' => $this->repo->todos(),
            'here' => $here,
        ], $request);
    }
}

Una sola URL atiende el GET (pintar) y el POST (guardar). Si la página tiene varias acciones, distingue con un campo oculto (<input type="hidden" name="action" value="borrar">) y un switch. Para varias vistas en la misma página, usa un parámetro ?tab=.

Vistas con el aspecto del panel #

Las vistas del plugin extienden el layout del panel con @extends('admin::layout'):

html
{{-- views/admin.tpl --}}
@extends('admin::layout')

@section('actions')
  <a class="btn" href="{{ route('admin.settings', ['group' => 'plugin-mi-plugin']) }}">
    @include('admin::partials/icon', ['name' => 'settings']) {{ __('admin.menu.settings') }}
  </a>
@endsection

@section('help')
  <p>{{ __('mi-plugin::ayuda') }}</p>
@endsection

@section('content')
<div class="grid two">
  <section class="card">
    <div class="card-head"><h2>{{ __('mi-plugin::nuevo') }}</h2></div>
    <form method="post" action="{{ $here }}">
      @csrf
      <div class="field {{ isset($errors['nombre']) ? 'has-error' : '' }}">
        <label for="nombre">{{ __('mi-plugin::nombre') }}</label>
        <input id="nombre" name="nombre" value="{{ old('nombre') }}" required>
        @if(isset($errors['nombre']))<p class="error">{{ $errors['nombre'] }}</p>@endif
      </div>
      <div class="form-actions">
        <button class="btn primary" type="submit">{{ __('common.save') }}</button>
      </div>
    </form>
  </section>

  <section class="card">
    <div class="card-head"><h2>{{ __('mi-plugin::lista') }}</h2></div>
    @if($items)
    <div class="table-wrap">
      <table class="table">
        <thead><tr><th>{{ __('mi-plugin::nombre') }}</th><th></th></tr></thead>
        <tbody>
        @foreach($items as $it)
          <tr>
            <td>{{ $it['nombre'] }}</td>
            <td>
              <form method="post" action="{{ $here }}" class="inline" data-confirm="{{ __('mi-plugin::confirmar_borrar') }}">
                @csrf
                <input type="hidden" name="action" value="borrar">
                <input type="hidden" name="id" value="{{ $it['id'] }}">
                <button class="btn ghost small">@include('admin::partials/icon', ['name' => 'trash'])</button>
              </form>
            </td>
          </tr>
        @endforeach
        </tbody>
      </table>
    </div>
    @else
      <p class="empty muted">{{ __('mi-plugin::vacio') }}</p>
    @endif
  </section>
</div>
@endsection

Secciones del layout #

SecciónDónde sale
contentEl cuerpo de la página. Obligatoria.
actionsBotones a la derecha del título (.page-actions).
helpUn botón «?» junto al título que despliega este contenido.
page_headSustituye la cabecera entera (título, acciones y ayuda). Para cabeceras a medida.
headDentro del <head> del panel, solo en esta página: un <style> o un <script> propio.

El layout ya muestra el título (page_title), la miga de pan y los avisos de redirect().

Variables del layout #

Además de lo que pases en $data, la vista recibe: $user (el usuario del panel), $menu, $flash (success/error), $errors (los de back(), por campo) y $page_title. Para repoblar un formulario tras un error usa old('campo', $valorPorDefecto).

Clases y componentes #

El CSS del panel ya está cargado. Usa sus clases para que tu página se vea como el resto:

ClaseUso
.card, .card-head, .cardsTarjetas con cabecera.
.grid.twoDos columnas que pasan a una en móvil.
.field, .check, .rowCampo de formulario con su label; casilla; varios campos en una fila. Un campo con error lleva .field.has-error y el mensaje en <p class="error">.
.form-actions (.sticky)Barra de botones del formulario (fija al pie con .sticky).
.btn, .btn.primary, .btn.ghost, .smallBotones.
.table-wrap + .table (.compact)Tablas con scroll horizontal en móvil.
.badge, .tagEtiquetas pequeñas de estado.
.muted, .small, .empty, .inlineTexto secundario, pequeño, estado vacío, formulario en línea.
.kpi, .kpi-head, .kpi-valueCifras destacadas.

Para tus propios estilos, usa las variables del panel y así respetas el modo claro y el oscuro: --color-bg, --color-card, --color-card-2, --color-ink, --color-ink-2, --color-muted, --color-line, --color-line-2, --color-primary, --color-primary-soft, --color-on-primary, --color-ok, --color-ok-soft, --color-warn, --color-warn-soft, --color-bad, --color-bad-soft, --color-info, --color-info-soft, --radius-sm, --radius-md, --radius-lg. Prefija tus clases (.mp-…) para no chocar con las del panel.

Comportamientos con atributos #

admin.js añade comportamiento a cualquier marcado que lleve estos atributos, también en las páginas de un plugin:

AtributoEfecto
data-confirm="¿Seguro?"En un <form>, botón o enlace: pide confirmación en un diálogo antes de seguir.
[data-tabs] con botones [data-tab="x"] y paneles [data-panel="x"]Pestañas dentro de la página.
.field[data-hide-when="nombre"]Oculta el campo mientras la casilla nombre está marcada.
input[data-slug-from="#titulo"]Rellena un slug a partir de otro campo.
[data-media-picker] con un input oculto, [data-pick] y [data-clear]Selector de la biblioteca de medios.
label[data-dropzone] con input[type=file]Zona para arrastrar archivos.

Formularios y seguridad #

  • CSRF: todas las peticiones a /admin que no sean GET, HEAD u OPTIONS deben llevar el token. Pon @csrf en cada formulario; en JavaScript, envía la cabecera X-CSRF-Token. El layout del panel ya imprime el token en <meta name="csrf-token">. Sin token la respuesta es un error 419.
  • Permisos: el núcleo comprueba la cap de la página antes de llamar a tu controlador. Si dentro hay acciones más delicadas, compruébalas tú: if (!$this->auth->can('manage_settings')) { … }.
  • Escapa todo lo que venga de la base de datos con {{ }}. Usa {!! !!} solo con HTML que hayas generado tú.
  • Secretos: guarda claves de API con un ajuste de tipo secret (cifrado en la base de datos), nunca en un campo de texto normal.
js
// Llamada desde JavaScript a tu propia página del panel
await fetch(url, {
    method: 'POST',
    headers: { 'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]')?.content ?? '' },
    body: new FormData(form),
});

Capacidades y roles #

CapacidadQuién la tiene
access_adminTodos los usuarios del panel.
manage_content, upload_mediaadmin, editor y author.
manage_terms, manage_people, manage_pages, publish_content…admin y editor.
manage_settings, manage_usersSolo admin.

Una capacidad nueva (mi_plugin_moderar) solo la tiene admin hasta que se la des a otro rol con el filtro role_capabilities. La tabla completa está en la API PHP.

Rutas propias en el panel #

Si necesitas URLs que no son una entrada del menú (un endpoint JSON, una exportación, una acción de un botón), regístralas con la acción admin_routes. Quedan bajo /admin, con la sesión, la comprobación de login y el CSRF del panel:

php
add_action('admin_routes', function (\MovieMaster\Http\Router $r): void {
    $r->get('/mi-plugin/exportar.csv', [MiPlugin\Export::class, 'csv'], [
        'name' => 'mi-plugin.export',   // route('admin.mi-plugin.export')
        'cap'  => 'manage_content',
    ]);
    $r->post('/mi-plugin/api/ordenar', [MiPlugin\Api::class, 'ordenar'], ['cap' => 'manage_content']);
});

El nombre recibe el prefijo admin.. Sin cap, basta con access_admin. Usa siempre un prefijo con el slug de tu plugin para no chocar con rutas del núcleo.

Modificar el menú #

El filtro admin_menu recibe todas las entradas antes de filtrar por permisos. Cada entrada es un array con key, label, route (nombre de ruta o URL), icon, cap, order y children (las entradas del grupo, por clave):

php
add_filter('admin_menu', function (array $items): array {
    // Un enlace externo dentro del grupo Sistema
    $items['system']['children']['mi-plugin-docs'] = [
        'key' => 'mi-plugin-docs', 'label' => 'Ayuda de Mi Plugin',
        'route' => 'https://mi-plugin.com/docs', 'icon' => 'dot',
        'cap' => 'manage_settings', 'order' => 99, 'match' => null, 'children' => [],
    ];
    // Ocultar una entrada a quien no sea admin
    if (isset($items['import']['children']['queue'])) {
        $items['import']['children']['queue']['cap'] = 'manage_settings';
    }
    return $items;
});

Las claves de los grupos del núcleo son dashboard, movies, series, content, import, player, seo, appearance, settings y system. Para una página de tu plugin no hace falta este filtro: adminPage() ya crea la entrada.

Ajustes del plugin #

Los campos declarados con $plugin->setting() aparecen en Ajustes, en el grupo del plugin. Enlaza a ellos desde tu página:

php
route('admin.settings', ['group' => 'plugin-mi-plugin'])

Y léelos con $plugin->get('clave') o, desde una clase, con setting('plugin.mi-plugin.clave'). Los tipos de campo, la validación y hide_when están en crear plugins.

Hooks del panel #

HookTipoPara qué
admin_menufiltroCambiar las entradas del menú.
admin_routesacciónRegistrar rutas bajo /admin.
admin_headacciónImprimir en el <head> de todas las páginas del panel (CSS de tu plugin).
admin_footeracciónImprimir antes de </body> del panel (JavaScript).
admin_dashboard_widgetsfiltroAñadir tarjetas al escritorio.
admin_dashboard_status_cardsfiltroAñadir tarjetas al bloque de estado del escritorio.
admin_search_resultsfiltroAñadir resultados al buscador del panel.
admin_settings_fieldacciónHTML propio debajo de un campo de Ajustes.
admin_settings_links_forfiltroEnlaces junto a un campo de Ajustes.
admin_titles_index_top, admin_title_form_top, admin_title_actionsacciónHuecos en el listado y el editor de títulos.
admin_catalog_panelacciónBajo el formulario de Admin → Catálogo.
admin_onboarding_steps, admin_onboarding_itemsfiltroPasos de «Primeros pasos».

Argumentos y detalles de cada uno en la referencia de hooks.

Un widget en el escritorio #

php
add_filter('admin_dashboard_widgets', function (array $widgets): array {
    if (!app(\MovieMaster\Auth\Auth::class)->can('manage_content')) {
        return $widgets;
    }
    $n = (int) db()->table('mi_plugin_items')->count();
    $widgets[] = [
        'title' => __('mi-plugin::widget'),
        'html'  => '<p class="kpi-value">' . e((string) $n) . '</p>'
                 . '<a class="btn small" href="' . e(route('admin.plugin.mi-plugin.panel')) . '">' . e(__('mi-plugin::abrir')) . '</a>',
    ];
    return $widgets;
});

El html se imprime tal cual dentro de una .card: escapa tú los datos con e(). Las tarjetas se muestran a todos los usuarios del panel, así que comprueba la capacidad antes de añadir la tuya.

CSS y JavaScript en todo el panel #

php
add_action('admin_head', function () use ($plugin): void {
    echo '<link rel="stylesheet" href="' . e($plugin->asset('admin.css')) . '">';
});
add_action('admin_footer', function () use ($plugin): void {
    echo '<script src="' . e($plugin->asset('admin.js')) . '" defer></script>';
});

Si solo lo necesita tu página, ponlo en @section('head') de tu vista en lugar de cargarlo en todo el panel.

Buenas prácticas #

  • Una entrada de menú por plugin es casi siempre suficiente. Organiza el resto con pestañas (?tab=).
  • Elige la cap mínima que tenga sentido: manage_content para herramientas de contenido, manage_settings para configuración.
  • Traduce todas las etiquetas (__('mi-plugin::…')) y prueba la página en español y en inglés.
  • Prueba en móvil: el panel es responsive y tus tablas deben ir dentro de .table-wrap.
  • Las tareas largas (importar, recorrer el catálogo) no van en la petición: mételas en la cola de trabajos y muestra el progreso.
  • Si tu página cambia contenido público, purga la caché de páginas afectada. Ver caché de páginas.

¿Te quedó alguna duda?

Escríbenos y te ayudamos con tu caso.

Hablar con nosotros
¿Hablamos?