Widgets: Principle & Declaration

A widget is a new feature added on NexoPOS 5x that allows the creation of isolated pieces of features accessible from the dashboard.

Previously, we had many dashboards per role. From this release, the dashboard will be the same for everyone, but the only difference is that widgets are subject to permissions.

When we mention that widgets are subject to permissions we mean that some widgets might require permissions to be visible, when it's clearly declared.

This guide will go through the complete creation of a widget on NexoPOS v5.x.

Declaring The Widget

All widgets are declared in the folder "app/Widgets". Each class of a widget must extend "WidgetService". A typical declaration of a widget is as follows:

After having defined the widget, you need to define some useful properties which are:

• name: This defines how to identify and name the widget.
• vueComponent: Most widgets rely on a Vue component. The name of the object declared globally on the "window" object must be defined here.
• description: To describe what the widget does.
• permission: Will make the widget available if the logged user has the provided permission.

Note that by defining the permission on a widget class, that permission is not either created automatically or assigned to users. You must manually create and assign that permission using a dedicated migration file.

Here is a full example of a declared widget:

Now that a widget is declared, we need to register it using a Service Provider.

Register Declared Widget

A widget that is not registered won't be recognized by NexoPOS. This is a required step to make the widget accessible to all users. First of all, we'll resolve the WidgetService class on a boot method of our service provider.

Once the widget is registered, it can now be managed by any user who has permission to see it. If a widget doesn't provide any permission, it will be visible to anyone.

Declaring The Vue Component

At the moment, our widget doesn't have anybody or Vue components. As said previously, we need to declare on the "window" object (or context) our Vue 3 component.

In order to proceed, we'll register our component like so:

Note that "nsProfileWidget" matches the value of the property "vueComponent" defined on the class ProfileWidget. In your case, it should match the value you've defined on "vueComponent" property.

Using "nsProfileWidget" should have as a value an object that resolves components asynchronously. While the behaviors of the widget belong to the developer, it's therefore highly advised that each widget include a closing button. The closing button will ensure a widget can be deleted by the user.

Every close button must emit a unique event that is listened by the widget area. Here is an example:

We need while clicking on "ns-close-button" to emit the event "onRemove". This will ensure the widget can safely be removed by the user.