Home
NexoPOS

Dichiarazione del widget

Un widget è una nuova funzionalità aggiunta a NexoPOS 5x che consente di creare parti isolate di funzionalità accessibili dalla dashboard.

In precedenza avevamo molti dashboard per ruolo. Da questa release, il dashboard sarà uguale per tutti, ma l’unica differenza è che i widget sono soggetti alle autorizzazioni.

Quando diciamo che i widget sono soggetti alle autorizzazioni, intendiamo che alcuni widget potrebbero richiedere autorizzazioni per essere visibili, quando è chiaramente dichiarato.

Questa guida ti accompagnerà attraverso la creazione completa di un widget su NexoPOS v5.x.

Dichiarare il widget

Tutti i widget sono dichiarati nella cartella "app/Widgets". Ogni classe di un widget deve estendere "WidgetService". Una tipica dichiarazione di un widget è la seguente:

<?php
namespace App\Widgets;

use App\Services\WidgetService;

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

Dopo aver definito il widget, devi definire alcune proprietà utili, che sono:

  • nome: Questo definisce come identificare e denominare il widget.
  • vueComponent: La maggior parte dei widget si basa su un componente Vue. Il nome dell’oggetto dichiarato globalmente sull’oggetto "window" deve essere definito qui.
  • descrizione: Per descrivere cosa fa il widget.
  • Autorizzazione: renderà il widget disponibile se l’utente connesso dispone dell’autorizzazione fornita.

Nota che definendo l’autorizzazione su una classe di widget, tale autorizzazione non viene né creata automaticamente né assegnata agli utenti. Devi crearla e assegnarla manualmente utilizzando un file di migrazione dedicato.

Ecco un esempio completo di un widget dichiarato:

<?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';
    }
}

Ora che un widget è stato dichiarato, dobbiamo registrarlo utilizzando un Service Provider.

Registra widget dichiarato

Un widget non registrato non verrà riconosciuto da NexoPOS. Questo è un passaggio obbligatorio per rendere il widget accessibile a tutti gli utenti. Innanzitutto, risolveremo la classe WidgetService in un metodo di avvio (boot) del nostro service provider.

<?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 volta registrato il widget, può essere gestito da qualsiasi utente che abbia il permesso di visualizzarlo. Se un widget non fornisce alcun permesso, sarà visibile a chiunque.

Dichiarare il componente Vue

Al momento, il nostro widget non dispone di nessuno o di componenti Vue. Come detto in precedenza, dobbiamo dichiarare sul “window” (o contesto) il nostro componente Vue 3.

Per procedere, registreremo il nostro componente in questo modo:

import { defineAsyncComponent } from 'vue';

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

Nota che “nsProfileWidget” corrisponde al valore della proprietà “vueComponent” definita nella classe ProfileWidget. Nel tuo caso, dovrebbe corrispondere al valore che hai definito nella proprietà “vueComponent”.

L’uso di “nsProfileWidget” deve avere come valore un oggetto che risolve i componenti in modo asincrono. Sebbene i comportamenti del widget dipendano dallo sviluppatore, è quindi altamente consigliato che ogni widget includa un pulsante di chiusura. Il pulsante di chiusura consentirà all’utente di eliminare un widget.

Pulsante di chiusura

Ogni pulsante di chiusura deve emettere un evento univoco che viene ascoltato dall’area del widget. Ecco un esempio:

<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>

Dobbiamo fare clic su “ns-close-button” per emettere l’evento “onRemove”. In questo modo si garantisce che il widget possa essere rimosso in sicurezza dall’utente.

Pulsante di gestione

Questo pulsante viene utilizzato per trascinare il widget all’interno dell’area di rilascio. Per ottenere questo risultato, è necessario includere la classe "widget-handle" in un elemento che si desidera utilizzare per trascinare il widget. Dovresti evitare di applicare questa classe all’intero widget, soprattutto se il tuo widget include controlli.

<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>