Download the PHP package iohttp/laravel-widgets without Composer
On this page you can find all versions of the php package iohttp/laravel-widgets. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download iohttp/laravel-widgets
More information about iohttp/laravel-widgets
Files in iohttp/laravel-widgets
Package laravel-widgets
Short Description A powerful alternative to view composers. Asynchronous widgets, reloadable widgets, console generator, caching - everything you can think of.
License MIT
Homepage https://github.com/arrilot/laravel-widgets
Informations about the package laravel-widgets
Widgets for Laravel
A powerful alternative to view composers. Asynchronous widgets, reloadable widgets, console generator, caching - everything that you can imagine.
Installation
Run
Laravel >=5.5 uses Package Auto-Discovery, so you don't need to manually add the ServiceProvider and Facades
Usage
Let's consider that we want to make a list of recent news and reuse it in several views.
First of all we can create a Widget class using the artisan command provided by the package.
This command generates two files:
1) resources/views/widgets/recent_news.blade.php
is an empty view.
Add "--plain" option if you do not need a view.
2) app/Widgets/RecentNews
is a widget class.
Note: You can use your own stubs if you need. Publish config file to change paths.
The last step is to call the widget. There are several ways to do so.
or
or even
There is no real difference between these. The choice is up to you.
Passing variables to widget
Via config array
Let's carry on with the "recent news" example.
Imagine that we usually need to show five news, but in some views we need to show ten. This can be easily achieved by:
['count' => 10]
is a config array that can be accessed by $this->config.
Config array is available in every widget method so you can use it to configure placeholder and container too (see below)
Note: Config fields that are not specified when you call a widget aren't overridden:
Note 2: You may want (but you probably don't) to create your own BaseWidget and inherit from it. That's fine. The only edge case is merging config defaults from a parent and a child. In this case do the following:
1) Do not add protected $config = [...]
line to a child.
2) Instead add defaults like this:
Directly (works only for Laravel versions below 7)
You can also choose to pass additional parameters to run()
method directly.
run()
method is resolved via Service Container, so method injection is also available here.
Namespaces
By default the package tries to find your widget in the namespace.
You can override this by publishing package config () and setting default_namespace
property.
Although using the default namespace is very convenient, in some cases you may wish to have more flexibility. For example, if you've got dozens of widgets it makes sense to group them in namespaced folders.
No problem, there are several ways to call those widgets:
1) Pass a full widget name from the default_namespace
(basically App\Widgets
) to the run
method.
2) Use dot notation.
3) FQCN is also an option.
Asynchronous widgets
In some situations it can be very beneficial to load widget content with AJAX.
Fortunately, this can be achieved very easily!
All you need to do is to change facade or blade directive - Widget::
=> AsyncWidget::
, @widget
=> @asyncWidget
Widget params are encrypted (by default) and sent via ajax call under the hood. So expect them to be json_encoded()
and json_decoded()
afterwards.
Note: You can turn encryption off for a given widget by setting
public $encryptParams = false;
on it. However, this action will make widget params publicly accessible, so please make sure to not leave any vulnerabilities. For example, if you pass something like user_id through widget params and turn encryption off, you do need to add one more access check inside the widget.Note: You can set
use_jquery_for_ajax_calls
totrue
in the config file to use it for ajax calls if you want to, but you need to manually add jquery to your page in this case.
By default nothing is shown until ajax call is finished.
This can be customized by adding a placeholder()
method to the widget class.
Side note: If you need to do something with the routes package used to load async widgets (e.g. you run app in a subfolder http://site.com/app/) you need to copy Arrilot\Widgets\ServiceProvider to your app, modify it according to your needs and register it in Laravel instead of the former one.
Reloadable widgets
You can go even further and automatically reload widget every N seconds.
Just set the $reloadTimeout
property of the widget class and it is done.
Both sync and async widgets can become reloadable.
You should use this feature with care, because it can easily spam your app with ajax calls if timeouts are too low. Consider using web sockets too but they are way harder to set up.
Container
Async and Reloadable widgets both require some DOM interaction so they wrap all widget output in a html container.
This container is defined by AbstractWidget::container()
method and can be customized too.
Note: Nested async or reloadable widgets are not supported.
Caching
There is also a simple built-in way to cache entire widget output. Just set $cacheTime property in your widget class and you are done.
No caching is turned on by default. A cache key depends on a widget name and each widget parameter. Override method if you need to adjust it.
Cache tagging
When tagging is supported (see the Laravel cache documentation) and to
simplify cache flushing, a tag widgets
is assigned by default to all widgets.
You can define one or more additional tags to your widgets by setting the values
in the $cacheTags
property in your widget class. Example :
For this example, if you need to flush :
Widget groups (extra)
In most cases Blade is a perfect tool for setting the position and order of widgets. However, sometimes you may find useful the following approach:
position()
can be omitted from the chain.
Widget::group('sidebar')->addWidget('files');
equals
Widget::group('sidebar')->position(100)->addWidget('files');
You can set a separator that will be display between widgets in a group.
Widget::group('sidebar')->setSeparator('<hr>')->...;
You can also wrap each widget in a group using wrap
method like that.
Removing widgets from a group
There is a couple of ways to remove widget/widgets from a group after they've been already added.
1) Remove one widget by its unique id
2) Remove all widgets with specific name
3) Remove all widgets that are placed on a specific position.
4) Remove all widgets at once.
Checking the state of a group
Widget::group('sidebar')->isEmpty(); // bool
Widget::group('sidebar')->any(); // bool
Widget::group('sidebar')->count(); // int
Namespaces for third party packages (extra)
In some cases, it may be useful to deliver widgets with your own packages. For example, if your package allows you to manage news, it would be convenient to have immediately configurable widgets, ready for display, directly delivered with your package.
To avoid having to use the fqcn each time, you can set a widget namespace into your package provider. This way the widgets from your package can be more easily identified, and especially the syntax will be shorter.
To do that, all you have to do is to register the namespace in your package service provider :
After that you can use the namespace in your views :
All versions of laravel-widgets with dependencies
illuminate/support Version >=5.5
illuminate/contracts Version >=5.5
illuminate/view Version >=5.5
illuminate/container Version >=5.5
illuminate/console Version >=5.5
illuminate/cache Version >=5.5