Downloads
Stars
Version
A Laravel Nova Tool to let users manage global settings created from code. This package works only in combination with Laravel Nova.
SettingType
Representation
SettingItem
Options
Install NovaSettingsTool
by following the steps below.
Install this package through composer using the following command:
composer require weslal/nova-settings-tool
This package uses a database table to store the setting values. Run the migrate command to create the table in the databasem, using the following command:
php artisan migrate
This packages comes with a config file with options and translations. In order to change them, publish these config and translation files using the following command:
php artisan vendor:publish --tag="settings"
Register the tool with Nova. Add the tool to the tools()
method of the App\NovaServiceProvider
, as shown below:
use WesLal\NovaSettingsTool\NovaSettingsTool;
// ...
public function tools()
{
return [
// ...
new NovaSettingsTool(),
// ...
];
}
Create a listener class where the settings tool will request for groups and items. A listener class can be placed in for example App/Handlers and can be named for example SettingsRegisteringListener.php. The handle()
method is used to define the setting groups and setting items, it can be used as shown below:
use WesLal\NovaSettingsTool\Enums\SettingType;
use WesLal\NovaSettingsTool\Events\SettingsRegistering;
use WesLal\NovaSettingsTool\ValueObjects\SettingGroup;
use WesLal\NovaSettingsTool\ValueObjects\SettingItem;
// ...
class SettingsRegisteringListener
{
// ...
public function handle(SettingsRegistering $event)
{
// ...
}
// ...
}
Register the listener with Nova. Add the SettingsRegistering
event containing the listener class(es) to the $listen
array of the App\EventServiceProvider
, as shown below:
use WesLal\NovaSettingsTool\Events\SettingsRegistering;
use App\Handlers\SettingsRegisteringListener;
// ...
protected $listen = [
// ...
SettingsRegistering::class => [
SettingsRegisteringListener::class
]
// ...
];
Define the settings in the handle()
method in the listener, or in that method in another listener that listens to the SettingsRegistering
event. Shown below is an example of how to define settings:
public function handle(SettingsRegistering $event)
{
$event->settingRegister
->group('general', function(SettingGroup $group) {
$group->name('General')
->icon('fa fa-cog')
->item('title', function (SettingItem $item) {
$item->name('Website Title');
})
->item('description', function (SettingItem $item) {
$item->type(SettingType::TEXTAREA);
});
})
->group('privacy', function(SettingGroup $group) {
$group
->name('Privacy')
->icon('fa fa-user-secret')
->item('log', function (SettingItem $item) {
$item->name('Log User Activity')
->field(Boolean::make('log')->help(
'When enabled, user activity will be logged.'
));
});
});
}
SettingRegister
group(string $key, Closure $callback = null)
Create a new SettingGroup
or call an existing SettingGroup
(with the same key) and add it to the SettingRegister
.
string $key
The self-defined (or existing where to append to) key of the SettingGroup
(normally snake cased).
Closure $callback
The method where the SettingGroup
can be configured and where items can be defined. The created SettingGroup
will be passed as parameter. The default value is null.
SettingRegister
The current SettingRegister
object ($this
).
getGroups()
Obtain a Collection
of all registered SettingGroup
objects from the SettingRegister
object.
\Illuminate\Support\Collection
The collection of SettingGroup
objects registered with the SettingRegister
.
getGroup(string $key)
Obtain a SettingGroup
from the SettingRegister
by it's key. When the SettingGroup
is not found, it will be created automatically.
string $key
SettingGroup
The requested or newly created SettingGroup
.
SettingGroup
key(string $key)
Set the key of the SettingGroup
. This is optional because the group gets it's key from the group()
method in the SettingRegister
class.
string $key
The self-defined key of the SettingGroup
(normally snake cased).
SettingGroup
The current SettingGroup
object ($this
).
name(string $name)
Set the name of the SettingGroup
.
string $name
The displayed tab header of the SettingGroup
.
SettingGroup
The current SettingGroup
object ($this
).
icon(string $icon)
Set the icon of the SettingGroup
. Icons are only shown when show_icons
is set to true
in the config file.
string $icon
The FontAwesome 5 icon class (for example: fa fa-cog
) of the icon that needs to be displayed in the SettingGroup
tab header.
SettingGroup
The current SettingGroup
object ($this
).
priority(int $priority)
Set the priority of the SettingGroup
. When not set, the SettingGroup
tabs will be sorted based on the creation order.
int $priority
The priority of the SettingGroup
.
SettingGroup
The current SettingGroup
object ($this
).
item(string $key, Closure $callback = null)
Create a new SettingItem and add it to the SettingGroup
.
string $key
The self-defined key of the SettingItem
(normally snake cased).
Closure $callback
The method where the SettingItem
can be configured. The created SettingItem
will be passed as parameter. The default value is null.
getItems()
Obtain a Collection
of all registered SettingItem
objects from the SettingGroup
object.
\Illuminate\Support\Collection
The collection of SettingItem
objects registered with the SettingGroup
.
getItem(string $key)
Obtain a SettingItem
from the SettingGroup
by it's key. When the SettingItem
is not found, it will be created automatically.
string $key
SettingGroup
The requested or newly created SettingItem
.
getKey()
Get the key from the SettingGroup
.
string
The key of the SettingGroup
.
getName()
Get the name from the SettingGroup
.
string
The key of the SettingGroup
.
getIcon()
Get the icon from the SettingGroup
.
string
The key of the SettingGroup
.
getPriority()
Get the priority from the SettingGroup
.
int
The key of the SettingGroup
.
hasItems()
Check if the SettingGroup
contains one or more SettingItem
objects.
bool
Indicated if the SettingGroup
has any SettingItem
objects.
SettingItem
key(string $key)
Set the key of the SettingItem
. This is optional because the item gets it's key from the item()
method in the SettingGroup
class.
string $key
The self-defined key of the SettingItem
(normally snake cased).
SettingItem
The current SettingItem
object ($this
).
name(string $name)
Set the name of the SettingItem
.
string $name
The displayed title of the SettingItem
.
SettingItem
The current SettingItem
object ($this
).
priority(int $priority)
Set the priority of the SettingItem
. When not set, the SettingItem
rows will be sorted based on the creation order.
int $priority
The priority of the SettingItem
.
SettingItem
The current SettingItem
object ($this
).
options(array $options)
Set additional option to the SettingItem
. The options array needs to be a Key => Value
array. See the SettingItem
Options for supported options.
string $options
The Key => Value
array containing the preferred options.
SettingItem
The current SettingItem
object ($this
).
type(string $type)
Set the SettingType
of the SettingItem
. Only values from the SettingType
enumeration are supported. This is optional when a Field
is set using the field()
method.
string $type
The value of a SettingType
constant.
SettingItem
The current SettingItem
object ($this
).
field(\Laravel\Nova\Fields\Field $field)
Make a new Field
instance and add it to the SettingItem
. Check which Field
classes proved to be working in the Tested Fields section.
\Laravel\Nova\Fields\Field $field
The Field
for the current SettingItem
.
value($value)
Set a value programmatically. Normally this should be handled by the Tool based on user input.
$value
SettingItem
The current SettingItem
object ($this
).
getKey()
Get the key from the SettingItem
.
string
The key of the SettingItem
.
getName()
Get the name from the SettingItem
.
string
The key of the SettingItem
.
getPriority()
Get the priority from the SettingItem
.
int
The key of the SettingItem
.
getOptions()
Get the options from the SettingItem
.
array
The options of the SettingItem
.
getType()
Get the type from the SettingItem
.
string
The type of the SettingItem
.
getField()
Get the Field
from the SettingItem
.
\Laravel\Nova\Fields\Field
The Field
of the SettingItem
.
getValue()
Get the value from the SettingItem
. It checks if the value is already obtained from the database, else it checks the database and when there is no value, it will return the default value (set through the options()
method). When then there is still no value, it will return null
.
mixed
The value of the SettingItem
.
settings()
Get the SettingRegister
instance from the App Container. This method returns null if the SettingRegister
is not initialized by the ServiceProvider.
SettingRegister|null
The SettingRegister
instance from the App Container or null
when not initialized.
setting(string $key)
Get a SettingItem
instance from the the SettingRegister in the App Container using the key of the SettingItem
. This method returns null if the SettingRegister
is not initialized by the ServiceProvider or the SettingItem
does not exist.
string $key
mixed
The SettingItem
instance request for or null if not found.
settingValue(string $key)
Get the value of a SettingItem
instance from the the SettingRegister in the App Container using the key of the SettingItem
. This method returns null if the SettingRegister is not initialized by the ServiceProvider, the SettingItem
does not exist or if there is no value set.
string $key
mixed
The value of the SettingItem
instance request for or null if not found.
SettingType
RepresentationSettingType constant |
Value | Represents Nova Field |
---|---|---|
TEXT |
text | \Laravel\Nova\Fields\Text |
BOOLEAN |
boolean | \Laravel\Nova\Fields\Boolean |
NUMBER |
number | \Laravel\Nova\Fields\Number |
TEXTAREA |
textarea | \Laravel\Nova\Fields\Textarea |
DATE |
date | \Laravel\Nova\Fields\Date |
DATETIME |
datetime | \Laravel\Nova\Fields\DateTime |
CODE |
code | \Laravel\Nova\Fields\Number |
PASSWORD |
password | \Laravel\Nova\Fields\Password |
Option | Information | Values |
---|---|---|
show_title |
Show the title of the module in the header of the settings tool page. | true title is shown false title is hidden |
show_suffix |
The suffix of the tab title on the settings tool page (space included automatically). The suffix can be set in the translation (the default suffix is Settings ). |
true suffix is shown false suffix is hidden |
show_icons |
Determines if the prefix of the tab title on the settings tool page can hold an icon. The icon can be set when a SettingGroup is created. |
true icons are shown false icons are hidden |
Key | Information | Default English Value |
---|---|---|
settings_title |
The title of the navigation item and the header of the tool page. | Settings |
save_settings |
The caption of the save button on the tool page. | Save Settings |
setting_tab_suffix |
The suffix of the tabs (groups) on the tool page (first space is included automatically). | Settings |
save_success |
The toaster message when saving the settings succeeded. | The settings are saved successfully! |
save_error |
The toaster message when saving the settings fails. | An error occurred while saving the settings! |
load_error |
The toaster message when loading the settings fails. | An error occurred while loading the settings! |
module_not_migrated |
The toaster message when the module is not migrated yet. | The settings module is not migrated! |
SettingItem
optionsKey | Value Type | Information |
---|---|---|
default | mixed |
Set a default value for the SettingItem . |
Field Class | Passed Test | Not Supported (Yet) | Not Tested Yet |
---|---|---|---|
\Laravel\Nova\Fields\Text |
x | ||
\Laravel\Nova\Fields\Boolean |
x | ||
\Laravel\Nova\Fields\Number |
x | ||
\Laravel\Nova\Fields\TextArea |
x | ||
\Laravel\Nova\Fields\Date |
x | ||
\Laravel\Nova\Fields\DateTime |
x | ||
\Laravel\Nova\Fields\Code |
x | ||
\Laravel\Nova\Fields\Password |
x | ||
\Laravel\Nova\Fields\Avatar |
x | ||
\Laravel\Nova\Fields\Country |
x | ||
\Laravel\Nova\Fields\Currency |
x | ||
\Laravel\Nova\Fields\File |
x | ||
\Laravel\Nova\Fields\Gravatar |
x | ||
\Laravel\Nova\Fields\ID |
x | ||
\Laravel\Nova\Fields\Image |
x | ||
\Laravel\Nova\Fields\Markdown |
x | ||
\Laravel\Nova\Fields\PasswordConfirmation |
x | ||
\Laravel\Nova\Fields\Place |
x | ||
\Laravel\Nova\Fields\Select |
x | ||
\Laravel\Nova\Fields\Status |
x | ||
\Laravel\Nova\Fields\Timezone |
x | ||
\Laravel\Nova\Fields\Trix |
x |
The MIT License (MIT). Please see License File for more information.