Settings

It’s generally better to reuse a module rather than creating a new one, since it leads to less code to maintain, fewer bugs and so less time spent developing! Therefore, rather than creating for example a file upload module, and a multiple file upload module, it’d be better if we could create a single file upload and give the user the choice of allowing multiple file uploads or not.

For this, we use settings. A module registers the settings it needs, then a user fills them out when creating a module instance. You can access the setting values in your controllers/blade templates.

Defining Settings

To define settings, you should create a 'settings' method in your service provider and return a form schema. To learn more about form schemas, see the FormSchema package.

public function settings(): Form
{
    return \FormSchema\Generator\Form::make()->withGroup(
        \FormSchema\Generator\Group::make('Page Settings')->withField(
            \FormSchema\Generator\Field::input('page_title')->inputType('text')->default('Title of the Page')
        )
    )->getSchema();
}

Custom Fields

Although the FormSchema package provides a number of fields, you may sometimes need to make your own. For example, you may need want a third party login button which redirects to an oauth URL, with a dropdown of recent logins. This can be created by creating a custom component as per the VueFormGenerator Vue Package.

Since your component will need to be used throughout the site, not just in your module, you need to globally register the javascript file that registers this component as a custom field. This should be in its own file. You can add the following to your service provider boot method to load a script on every page to be used for settings:

The components.js script should look something like

import CustomComponent from './components/CustomComponent';

Vue.component('field-modulealiasCustomComponent', CustomComponent);

Having added the script to your .mix file and compiled it, you can add the following to your service provider to load the script globally:

public function boot()
{
    parent::boot();
    $this->registerGlobalScript('modules/module-alias/js/components.js');
}

Accessing Setting Values

The SDK handles the assignment of the settings in a module. To access a settings value, use the settings() helper: settings($key, $default = null).

This will return the value of the setting, or the default if the setting is not given.

Setting listeners

If you want to respond to settings being changed, you can hook into the events fired when settings are created, saved, deleted etc.

Creating a Setting Listener

To create a settings listener, extend the \BristolSU\Support\ModuleInstance\Settings\SettingsListener class and add methods to handle different events. These events will correlate to the Eloquent events.

class NameSettingListener extends \BristolSU\Support\ModuleInstance\Settings\SettingListener
{
    protected $key = 'name'; // Key of the setting to trigger on

    public function onSaved(ModuleInstanceSetting $setting)
    {
        // Handle the setting change
    }
}

Register a Setting Listener

You should register a setting listener by including it in your $settingListeners array in the service provider.

protected $settingListeners = [
    \My\Namespace\NameSettingListener::class,
    ...
];

Module-wide settings

Some settings may need to be set module-wide as opposed to per module instance. The obvious example is a client ID for oauth, which should be set once for the whole application.

For these, put them in the config/config.php. You can use the env('ENV_NAME', default) method to load values from the .env file.