Widget
Definition
A widget is an autonomous graphical element you can add to different pages of your application. In general widgets are placed on the Home Page, or in the Summary View of a record. But it is possible to place widgets on any page of the application.
Uccello use the Laravel Widgets library for managing widgets. For more information, please refer to its documentation.
Default Widgets
By default, Uccello offers 2 widgets you can use with your modules:
SummaryFields
RelatedListWidget
These widgets allow to display some information in the Summary View of a record.
SummaryFields
Thanks to this widget you can quickly view the summary of a record, displaying the value of the fields of your choice.

Here is an example for using this widget with a module:
<?php
use Uccello\Core\Models\Module;
use Uccello\Core\Models\Widget;
$module = Module::where('name', 'person')->first();
// Add summary field widget
$widget = Widget::where('label', 'widget.main_fields')->first();
$module->widgets()->attach($widget->id, ['data' => json_encode(['fields' => ['name', 'email', 'phone', 'opt_in', 'activated', 'image']]), 'sequence' => 0]);
RelatedListWidget
This widget allows to display a Related List in the Summary View of a record. It is useful to display several Related Lists in the same page.

Here is an example for using this widget with a module:
<?php
use Uccello\Core\Models\Module;
use Uccello\Core\Models\Widget;
$module = Module::where('name', 'person')->first();
// Add relatedlist widget
$widget = Widget::where('label', 'widget.relatedlist')->first();
$relatedlist = $module->relatedlists->where('label', 'relatedlist.contacts')->first();
$module->widgets()->attach($widget->id, ['data' => json_encode(['id' => $relatedlist->id]), 'sequence' => 1]);
Create widgets
Thanks to 2 tutorials we will learn to create new widgets.
Home Page widget
We will display on the home page a widget for displaying the number of Users total and only in the current domain.
Make the widget
You can easily create new widgets. To do this launch the following command:
php artisan make:widget DashboardUserWidget
This command create 2 files:
app/Widgets/DashboardUserWidget.php
: The widget's controllerresources/views/widgets/dashboard_user_widget.blade.php
: The widget's view
Override the Home Page view
First of all, we'll override the Home Page for displaying the widget:
Create a file located at resources/views/uccello/modules/home/index/main.blade.php
to override the view.
@extends('uccello::modules.home.index.main')
@section('content')
@widget('DashboardUserWidget', ['domain' => $domain])
@endsection
We pass the current domain object to the widget using the variable $domain
available in all pages of Uccello.
Configure the Widget's controller
Add the following code to the file located at app/Widgets/DashboardUserWidget.php
:
<?php
namespace App\Widgets;
use App\User;
use Arrilot\Widgets\AbstractWidget;
class DashboardUserWidget extends AbstractWidget
{
...
public function run()
{
$totalUsersCount = User::count();
$domainUsersCount = User::inDomain($this->config['domain'])->count();
return view('widgets.dashboard_user_widget', [
'config' => $this->config,
'totalUsersCount' => $totalUsersCount,
'domainUsersCount' => $domainUsersCount
]);
}
}
We can use $this->config['domain']
to get the domain object passed to the widget.
We use the inDomain()
scope for retrieving only the users created in the current domain.
Then we pass $totalUsersCount
and $domainUsersCount
variables to the widget's view.
Configure the Widget's view
Add the following code to the file located at resources/views/widgets/dashboard_user_widget.blade.php
:
<div class="row">
{{-- Total Users --}}
<div class="col s12 m6 l3">
<div class="card horizontal info-box">
<div class="icon primary">
<i class="material-icons">person</i>
</div>
<div class="card-stacked">
<div class="card-content">
<div class="text uppercase">Total</div>
<div class="number count-to" data-from="0" data-to="{{ $totalUsersCount }}" data-speed="1000" data-fresh-interval="20">{{ $totalUsersCount }}</div>
</div>
</div>
</div>
</div>
{{-- Domain Users --}}
<div class="col s12 m6 l3">
<div class="card horizontal info-box">
<div class="icon green">
<i class="material-icons">person</i>
</div>
<div class="card-stacked">
<div class="card-content">
<div class="text uppercase">Current domain</div>
<div class="number count-to" data-from="0" data-to="{{ $domainUsersCount }}" data-speed="1000" data-fresh-interval="20">{{ $domainUsersCount }}</div>
</div>
</div>
</div>
</div>
</div>
It is better to use translation for displaying "Total" and "Current domain" strings.
Our new dashboard widget is ready an it's displaying the number of users! Thanks to the jquery-countTo library, the numbers of users are animated.

Summary View widget
Although Summary View widgets can be created and used in the same way as Home Page widgets, Uccello provides a way to link a widget to a module and automatically add it to the module's Summary View.
We will create a widget that will be referenced in the database and that can be easily used with any module. The widget will display a list of all domains in which the user has a role.
Make the widget
You can easily create new widgets. To do this launch the following command:
php artisan make:widget UserRolesWidget
This command create 2 files:
app/Widgets/UserRolesWidget.php
: The widget's controllerresources/views/widgets/user_roles_widget.blade.php
: The widget's view
Configure the Widget's controller
Add the following code to the file located at app/Widgets/UserRolesWidget.php
:
<?php
namespace App\Widgets;
use App\User;
use Arrilot\Widgets\AbstractWidget;
use Uccello\Core\Models\Domain;
class UserRolesWidget extends AbstractWidget
{
...
public function run()
{
$user = User::find($this->config['record_id']);
$rolesOnDomains = collect();
foreach (Domain::all() as $domain) {
$rolesOnDomain = $user->rolesOnDomain($domain);
if (count($rolesOnDomain) > 0) {
$rolesOnDomains[$domain->name] = $rolesOnDomain;
}
}
return view('widgets.user_roles_widget', [
'config' => $this->config,
'domain' => ucdomain($this->config['domain']),
'module' => ucmodule($this->config['module']),
'data' => (object) $this->config['data'],
'record' => $user,
'label' => $this->config['data']->label ?? $this->config['labelForTranslation'],
'rolesOnDomains' => $rolesOnDomains
]);
}
}
Configure the widget's view
Add the following code to the file located at resources/views/widgets/user_roles_widget.blade.php
:
<div class="row">
<div class="col s12">
<div class="card">
<div class="card-content">
{{-- Title --}}
<span class="card-title">
{{-- Icon --}}
<i class="material-icons left primary-text">lock</i>
{{-- Label --}}
{{ trans($label) }}
</span>
<div class="row">
<ul class="collection with-header">
@forelse ($rolesOnDomains as $domainName => $roles)
{{-- Domain name --}}
<li class="collection-header"><b>{{ $domainName }}</b></li>
{{-- List of roles --}}
@foreach ($roles as $role)
<li class="collection-item">{{ $role->name }}</li>
@endforeach
@empty
{{-- No roles message --}}
<li class="collection-item red-text center-align">{{ uctrans('widget.user_roles.no_role') }}</li>
@endforelse
</ul>
</div>
</div>
</div>
</div>
</div>
Add the translations
Create a file located at resources/lang/en/widgets.php
and add it the following code:
<?php
return [
'widget' => [
'user_roles' => 'User\'s roles',
]
];
Add the widget into the database
First of all we will create a migration to reference the widget in the database and link it with the User module.
Launch the following command to create the migration:
php artisan make:migration add_user_roles_widget
Add this code into the migration file freshly created:
<?php
use Illuminate\Database\Migrations\Migration;
use Uccello\Core\Models\Module;
use Uccello\Core\Models\Widget;
class AddUserRolesWidget extends Migration
{
/**
* Run the migrations.
*
* @return void
*/
public function up()
{
// Add the widget into the list of widgets
$widget = Widget::create([
'label' => 'widget.user_roles',
'type' => 'summary',
'class' => 'App\Widgets\UserRolesWidget',
'data' => null
]);
// Link the widget to the User module
$module = Module::where('name', 'user')->first();
$module->widgets()->attach($widget->id, [ 'sequence' => 0]);
}
/**
* Reverse the migrations.
*
* @return void
*/
public function down()
{
Widget::where('label', 'widget.user_roles')
->where('type', 'summary')
->where('class', 'App\Widgets\UserRolesWidget')->delete();
}
}
Launch the migration with the following command:
php artisan migrate
Our new widget is ready an it's displaying the roles of a user in the Summary View of the record!

Properties
Attribute
Type
Description
Default
label
string
Widget's label. To translate it, create a localization file located at resources/lang/{lang_code}/widgets.php
and add your translations.
type
string
Type of widget. For the moment only the summary
option is available by default. It allows to display automatically the widget into a Summary View of a module.
class
string
Path to the widget's controller generated by the command php artisan make:widget WidgetName
.
data
array
Data to pass to the widget.
You can use
label
to override the way how the label is made. By default the full label generated is$this->languagePackage.'widgets.'.$this->label
.In case or you are developing an external package, you must use
package
to set the name of your external package in which the widget is located (e.g.acme/my-package
).This attribute is only useful for making sharable modules, installable with composer.
null
Last updated
Was this helpful?