Accueil
NexoPOS

Déclaration de widget

Un widget est une nouvelle fonctionnalité ajoutée à NexoPOS 5x qui permet de créer des éléments de fonctionnalités isolés, accessibles depuis le tableau de bord.

Auparavant, nous avions de nombreux tableaux de bord par rôle. À partir de cette version, le tableau de bord sera identique pour tout le monde, la seule différence étant que les widgets sont soumis aux autorisations.

Lorsque nous mentionnons que les widgets sont soumis à des autorisations, nous voulons dire que certains widgets peuvent nécessiter des autorisations pour être visibles, lorsqu’elles sont clairement indiquées.

Ce guide vous expliquera la création complète d’un widget sur NexoPOS v5.x.

Déclarer le widget

Tous les widgets sont déclarés dans le dossier « app/Widgets ». Chaque classe d’un widget doit étendre « WidgetService ». Une déclaration typique d’un widget est la suivante :

<?php
namespace App\Widgets;

use App\Services\WidgetService;

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

Après avoir défini le widget, vous devez définir certaines propriétés utiles, à savoir :

  • name : Cela définit comment identifier et nommer le widget.
  • vueComponent : La plupart des widgets reposent sur un composant Vue. Le nom de l’objet déclaré globalement sur l’objet « window » doit être défini ici.
  • description : Décrire ce que fait le widget.
  • Autorisation : Rendra le widget disponible si l’utilisateur connecté dispose de l’autorisation fournie.

Notez que, en définissant l’autorisation sur une classe de widget, cette autorisation n’est ni créée automatiquement ni attribuée aux utilisateurs. Vous devez la créer et l’attribuer manuellement à l’aide d’un fichier de migration dédié.

Voici un exemple complet d’un widget déclaré :

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

Maintenant qu’un widget est déclaré, nous devons l’enregistrer à l’aide d’un fournisseur de services.

Enregistrer le widget déclaré

Un widget non enregistré ne sera pas reconnu par NexoPOS. Cette étape est obligatoire pour rendre le widget accessible à tous les utilisateurs. Tout d’abord, nous allons résoudre la classe WidgetService dans une méthode de démarrage (boot) de notre fournisseur de services.

<?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,
        ]);
    }
}

Une fois le widget enregistré, il peut désormais être géré par tout utilisateur disposant des autorisations nécessaires pour le voir. Si un widget ne fournit aucune autorisation, il sera visible par tout le monde.

Déclarer le composant Vue

À l’heure actuelle, notre widget ne dispose d’aucune personne ni de composants Vue. Comme indiqué précédemment, nous devons déclarer sur l’objet « window » (ou le contexte) notre composant Vue 3.

Afin de procéder, nous allons enregistrer notre composant comme suit :

import { defineAsyncComponent } from 'vue';

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

Notez que « nsProfileWidget » correspond à la valeur de la propriété « vueComponent » définie sur la classe « ProfileWidget ». Dans votre cas, elle doit correspondre à la valeur que vous avez définie sur la propriété « vueComponent ».

L’utilisation de « nsProfileWidget » doit avoir pour valeur un objet qui résout des composants de manière asynchrone. Bien que les comportements du widget relèvent du développeur, il est donc fortement recommandé que chaque widget inclue un bouton de fermeture. Le bouton de fermeture permettra à l’utilisateur de supprimer un widget.

Bouton Fermer

Chaque bouton de fermeture doit émettre un événement unique, écouté par la zone du widget. Voici un exemple :

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

Nous devons cliquer sur « ns-close-button » pour émettre l’événement « onRemove ». Cela permettra de s’assurer que le widget peut être retiré en toute sécurité par l’utilisateur.

Bouton de gestion

Ce bouton sert à déplacer le widget dans la zone de dépôt. Pour ce faire, il faut inclure la classe « widget-handle » dans l’élément que vous souhaitez utiliser pour déplacer le widget. Vous devez éviter d’appliquer cette classe à l’ensemble du widget, surtout si votre widget inclut des contrôles.

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