Inicio
NexoPOS

Declaración de widgets

Un widget es una nueva función agregada en NexoPOS 5x que permite la creación de partes aisladas de funciones a las que se puede acceder desde el panel de control.

Anteriormente, teníamos muchos paneles por rol. A partir de esta versión, el panel será el mismo para todos, pero la única diferencia es que los widgets están sujetos a permisos.

Cuando decimos que los widgets están sujetos a permisos, queremos decir que algunos widgets podrían requerir permisos para ser visibles, cuando así se declara claramente.

Esta guía repasará la creación completa de un widget en NexoPOS v5.x.

Declarando el widget

Todos los widgets se declaran en la carpeta "app/Widgets". Cada clase de un widget debe extender "WidgetService". Una declaración típica de un widget es la siguiente:

<?php
namespace App\Widgets;

use App\Services\WidgetService;

class ProfileWidget extends WidgetService
{
    public function __construct()
    {
        // ...
    }
}

Después de haber definido el widget, necesitas definir algunas propiedades útiles, que son:

  • name: Esto define cómo identificar y nombrar el widget.
  • vueComponent: La mayoría de los widgets dependen de un componente de Vue. El nombre del objeto declarado globalmente en el objeto «window» debe definirse aquí.
  • Descripción: Para describir lo que hace el widget.
  • Permiso: Habilitará el widget si el usuario registrado tiene el permiso proporcionado.

Tenga en cuenta que al definir el permiso en una clase de widget, ese permiso no se crea automáticamente ni se asigna a los usuarios. Debe crear y asignar manualmente ese permiso usando un archivo de migración dedicado.

Aquí hay un ejemplo completo de un widget declarado:

<?php
namespace App\Widgets;

use App\Services\WidgetService;

class ProfileWidget extends WidgetService
{
    protected $vueComponent     =   'nsProfileWidget';

    public function __construct()
    {
        $this->name     =   __( 'Profile' );
        $this->description  =   __( 'Will display a profile widget with user stats.' );
        $this->permission   =   'nexopos.see.profile-widget';
    }
}

Ahora que se ha declarado un widget, necesitamos registrarlo usando un proveedor de servicios.

Registrar widget declarado

Un widget que no esté registrado no será reconocido por NexoPOS. Este es un paso obligatorio para que el widget sea accesible para todos los usuarios. En primer lugar, resolveremos la clase WidgetService en un método de arranque de nuestro proveedor de servicios.

<?php
namespace App\Providers;

use App\Services\WidgetService;
use App\Widgets\ProfileWidget;
use Illuminate\Support\ServiceProvider;

class WidgetsServiceProvider extends ServiceProvider
{
    public function boot()
    {
        /**
         * @var WidgetService $widgetService
         */
        $widgetService  = app()->make( WidgetService::class );

        $widgetService->registerWidgets([
            ProfileWidget::class,
        ]);
    }
}

Una vez que el widget está registrado, ahora puede ser administrado por cualquier usuario que tenga permiso para verlo. Si un widget no proporciona ningún permiso, será visible para cualquiera.

Declarando el componente de Vue

En este momento, nuestro widget no tiene ninguna persona ni componentes de Vue. Como se dijo anteriormente, necesitamos declarar en el objeto «window» (o en el contexto) nuestro componente de Vue 3.

Para poder continuar, registraremos nuestro componente de la siguiente manera:

import { defineAsyncComponent } from 'vue';

window[ 'nsProfileWidget' ]                 =   defineAsyncComponent( () => import( './widgets/ns-profile-widget.vue' ) );

Tenga en cuenta que "nsProfileWidget" coincide con el valor de la propiedad "vueComponent" definida en la clase ProfileWidget. En su caso, debe coincidir con el valor que ha definido en la propiedad "vueComponent".

Usar «nsProfileWidget» debe tener como valor un objeto que resuelva componentes de forma asíncrona. Si bien los comportamientos del widget pertenecen al desarrollador, por lo tanto se recomienda encarecidamente que cada widget incluya un botón de cierre. El botón de cierre permitirá que el usuario pueda eliminar un widget.

Botón de cerrar

Cada botón de cierre debe emitir un evento único que sea escuchado por el área del widget. Aquí hay un ejemplo:

<template>
    <div id="ns-best-cashiers" class="flex flex-auto flex-col shadow rounded-lg overflow-hidden">
        <div class="flex-auto">
            <div class="head text-center border-b w-full flex justify-between items-center p-2">
                <h5>Profile</h5>
                <div class="flex -mx-1">
                    <div class="px-1">
                        <ns-close-button @click="$emit( 'onRemove' )"></ns-close-button>
                    </div>
                </div>
            </div>
            <div class="body">
                <!-- put the body here -->
            </div>
        </div>
    </div>
</template>

Necesitamos hacer clic en «ns-close-button» para emitir el evento «onRemove». Esto garantizará que el widget pueda retirarse de forma segura por parte del usuario.

Botón de control

Este botón se utiliza para arrastrar el widget por la zona de colocación. Para lograrlo, debemos incluir la clase «widget-handle» dentro de un elemento que queramos usar para arrastrar el widget. Debes evitar aplicar esta clase a todo el widget, especialmente si tu widget incluye controles.

<template>
    <div id="ns-best-cashiers" class="flex flex-auto flex-col shadow rounded-lg overflow-hidden">
        <div class="flex-auto">
            <div class="head text-center border-b w-full flex justify-between items-center p-2">
                <h5>Profile</h5>
                <div class="flex -mx-1">
                    <div class="px-1">
                        <ns-close-button @click="$emit( 'onRemove' )"></ns-close-button>
                    </div>
                    <!-- Start Widget Handle -->
                    <div class="px-1">
                        <ns-icon-button class="widget-handle" className="la-expand-arrows-alt"></ns-icon-button>
                    </div>
                    <!-- End Widget Handle -->
                </div>
            </div>
            <div class="body">
                <!-- put the body here -->
            </div>
        </div>
    </div>
</template>