A Laravel Nova Tool to let users manage global settings created from code. This package works only in combination with Laravel Nova.
- Installation
- Usage
- Object Methods
- Helper Methods
SettingType
Representation- Config Options
- Translation Options
SettingItem
Options- Tested Fields
- Screenshots
- License
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.'
));
});
});
}
Create a new SettingGroup
or call an existing SettingGroup
(with the same key) and add it to the SettingRegister
.
The self-defined (or existing where to append to) key of the SettingGroup
(normally snake cased).
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.
The current SettingRegister
object ($this
).
Obtain a Collection
of all registered SettingGroup
objects from the SettingRegister
object.
The collection of SettingGroup
objects registered with the SettingRegister
.
Obtain a SettingGroup
from the SettingRegister
by it's key. When the SettingGroup
is not found, it will be created automatically.
The key of the SettingGroup
.
The requested or newly created SettingGroup
.
Set the key of the SettingGroup
. This is optional because the group gets it's key from the group()
method in the SettingRegister
class.
The self-defined key of the SettingGroup
(normally snake cased).
The current SettingGroup
object ($this
).
Set the name of the SettingGroup
.
The displayed tab header of the SettingGroup
.
The current SettingGroup
object ($this
).
Set the icon of the SettingGroup
. Icons are only shown when show_icons
is set to true
in the config file.
The FontAwesome 5 icon class (for example: fa fa-cog
) of the icon that needs to be displayed in the SettingGroup
tab header.
The current SettingGroup
object ($this
).
Set the priority of the SettingGroup
. When not set, the SettingGroup
tabs will be sorted based on the creation order.
The priority of the SettingGroup
.
The current SettingGroup
object ($this
).
Create a new SettingItem and add it to the SettingGroup
.
The self-defined key of the SettingItem
(normally snake cased).
The method where the SettingItem
can be configured. The created SettingItem
will be passed as parameter. The default value is null.
Obtain a Collection
of all registered SettingItem
objects from the SettingGroup
object.
The collection of SettingItem
objects registered with the SettingGroup
.
Obtain a SettingItem
from the SettingGroup
by it's key. When the SettingItem
is not found, it will be created automatically.
The key of the SettingItem
.
The requested or newly created SettingItem
.
Get the key from the SettingGroup
.
The key of the SettingGroup
.
Get the name from the SettingGroup
.
The key of the SettingGroup
.
Get the icon from the SettingGroup
.
The key of the SettingGroup
.
Get the priority from the SettingGroup
.
The key of the SettingGroup
.
Check if the SettingGroup
contains one or more SettingItem
objects.
Indicated if the SettingGroup
has any SettingItem
objects.
Set the key of the SettingItem
. This is optional because the item gets it's key from the item()
method in the SettingGroup
class.
The self-defined key of the SettingItem
(normally snake cased).
The current SettingItem
object ($this
).
Set the name of the SettingItem
.
The displayed title of the SettingItem
.
The current SettingItem
object ($this
).
Set the priority of the SettingItem
. When not set, the SettingItem
rows will be sorted based on the creation order.
The priority of the SettingItem
.
The current SettingItem
object ($this
).
Set additional option to the SettingItem
. The options array needs to be a Key => Value
array. See the SettingItem
Options for supported options.
The Key => Value
array containing the preferred options.
The current SettingItem
object ($this
).
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.
The value of a SettingType
constant.
The current SettingItem
object ($this
).
Make a new Field
instance and add it to the SettingItem
. Check which Field
classes proved to be working in the Tested Fields section.
The Field
for the current SettingItem
.
Set a value programmatically. Normally this should be handled by the Tool based on user input.
The value for a SettingItem
.
The current SettingItem
object ($this
).
Get the key from the SettingItem
.
The key of the SettingItem
.
Get the name from the SettingItem
.
The key of the SettingItem
.
Get the priority from the SettingItem
.
The key of the SettingItem
.
Get the options from the SettingItem
.
The options of the SettingItem
.
Get the type from the SettingItem
.
The type of the SettingItem
.
Get the Field
from the SettingItem
.
The Field
of the SettingItem
.
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
.
The value of the SettingItem
.
Get the SettingRegister
instance from the App Container. This method returns null if the SettingRegister
is not initialized by the ServiceProvider.
The SettingRegister
instance from the App Container or null
when not initialized.
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.
The key of the SettingItem
.
The SettingItem
instance request for or null if not found.
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.
The key of the SettingItem
.
The value of the SettingItem
instance request for or null if not found.
SettingType 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! |
Key | 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.