marshmallow/nova-tool-settings

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

v1.3.0 2021-08-31 12:13 UTC

Requires

• php: ^7.1|^8.0

MIT

• Marshmallow

• configuration
• config
• manage
• nova
• laravel
• Settings
• global
• preferences
• preference
• setting

README

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

Table of Contents

• Installation
  • Install Package
  • Run Migrate
  • Publish Config & Translations
• Usage
  • Register Tool
  • Create Listener
  • Register Listener
  • Define Setting
• Object Methods
  • SettingRegister
  • SettingGroup
  • SettingItem
• Helper Methods
• SettingType Representation
• Config Options
• Translation Options
• SettingItem Options
• Tested Fields
• Screenshots
• License

Installation

Install NovaSettingsTool by following the steps below.

Install Package

Install this package through composer using the following command:

composer require marshmallow/nova-tool-settings

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 Marshmallow\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 Marshmallow\NovaSettingsTool\Enums\SettingType;
use Marshmallow\NovaSettingsTool\Events\SettingsRegistering;
use Marshmallow\NovaSettingsTool\ValueObjects\SettingGroup;
use Marshmallow\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 Marshmallow\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

Config Options

Translation Options

SettingItem options

Tested Fields

Screenshots

License

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