weslal/nova-settings-tool

A Laravel Nova Tool to let users manage global settings created from code.

Downloads

2315

Stars

7

Version

v1.0.3

NovaSettingsTool

Latest Version on Packagist Latest Stable Version Latest Unstable Version Total Downloads License Monthly Downloads Daily Downloads composer.lock

A Laravel Nova Tool to let users manage global settings created from code. This package works only in combination with Laravel Nova.

NovaSettingsTool

Table of Contents

Installation

Install NovaSettingsTool by following the steps below.

Install Package

Install this package through composer using the following command:

composer require weslal/nova-settings-tool

Run Migrate

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

Publish Config & Translations

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"

Usage

Register Tool

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 Listener

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 Listener

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 Settings

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.'
                        ));
                });
        });
}

Object Methods

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.

Param string $key

The self-defined (or existing where to append to) key of the SettingGroup (normally snake cased).

Param 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.

Returns SettingRegister

The current SettingRegister object ($this).

getGroups()

Obtain a Collection of all registered SettingGroup objects from the SettingRegister object.

Returns \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.

Param string $key

The key of the SettingGroup.

Returns 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.

Param string $key

The self-defined key of the SettingGroup (normally snake cased).

Returns SettingGroup

The current SettingGroup object ($this).

name(string $name)

Set the name of the SettingGroup.

Param string $name

The displayed tab header of the SettingGroup.

Returns 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.

Param 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.

Returns 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.

Param int $priority

The priority of the SettingGroup.

Returns SettingGroup

The current SettingGroup object ($this).

item(string $key, Closure $callback = null)

Create a new SettingItem and add it to the SettingGroup.

Param string $key

The self-defined key of the SettingItem (normally snake cased).

Param 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.

Returns \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.

Param string $key

The key of the SettingItem.

Returns SettingGroup

The requested or newly created SettingItem.

getKey()

Get the key from the SettingGroup.

Returns string

The key of the SettingGroup.

getName()

Get the name from the SettingGroup.

Returns string

The key of the SettingGroup.

getIcon()

Get the icon from the SettingGroup.

Returns string

The key of the SettingGroup.

getPriority()

Get the priority from the SettingGroup.

Returns int

The key of the SettingGroup.

hasItems()

Check if the SettingGroup contains one or more SettingItem objects.

Returns 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.

Param string $key

The self-defined key of the SettingItem (normally snake cased).

Returns SettingItem

The current SettingItem object ($this).

name(string $name)

Set the name of the SettingItem.

Param string $name

The displayed title of the SettingItem.

Returns 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.

Param int $priority

The priority of the SettingItem.

Returns 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.

Param string $options

The Key => Value array containing the preferred options.

Returns 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.

Param string $type

The value of a SettingType constant.

Returns 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.

Param \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.

Param $value

The value for a SettingItem.

Returns SettingItem

The current SettingItem object ($this).

getKey()

Get the key from the SettingItem.

Returns string

The key of the SettingItem.

getName()

Get the name from the SettingItem.

Returns string

The key of the SettingItem.

getPriority()

Get the priority from the SettingItem.

Returns int

The key of the SettingItem.

getOptions()

Get the options from the SettingItem.

Returns array

The options of the SettingItem.

getType()

Get the type from the SettingItem.

Returns string

The type of the SettingItem.

getField()

Get the Field from the SettingItem.

Returns \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.

Returns mixed

The value of the SettingItem.

Helper Methods

settings()

Get the SettingRegister instance from the App Container. This method returns null if the SettingRegister is not initialized by the ServiceProvider.

Returns 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.

Param string $key

The key of the SettingItem.

Returns 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.

Param string $key

The key of the SettingItem.

Returns mixed

The value of the SettingItem instance request for or null if not found.

SettingType Representation

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

Config Options

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

Translation Options

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 options

Key Value Type Information
default mixed Set a default value for the SettingItem.

Tested Fields

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

Screenshots

NovaSettingsTool

NovaSettingsTool

NovaSettingsTool

License

The MIT License (MIT). Please see License File for more information.

weslal

Author

weslal

Collections containing this package

  • Created by Olivier Mourlevat