Plugin Development: Registering Settings

Previous Section: Views


SupportPal comes with a PluginSetting model that can be used to store any settings required for the plugin to operate.

Contents

Saving Settings

To save a single setting for the plugin, use the addSetting function.

$this->addSetting($key, $value);

Removing Settings

To remove a single setting with a known key for the plugin, use the removeSetting function.

$this->removeSetting($key);

To remove all settings for the plugin, for example when uninstalling the plugin, use the removeSettings function.

$this->removeSettings();

Checking if a Setting Exists

If you need to just check if a setting currently exists, you can use the hasSetting function, which returns a Boolean. A second parameter can be entered for the setting value if you want to check the setting has a specific value.


    $this->hasSetting($key);
    $this->hasSetting($key, 'value');

To check if the plugin has any settings registered currently, you can use the hasSettings function, which returns a Boolean.

$this->hasSettings();

Creating a Settings Page

You should now know what controllers, routes and views are, and we can piece this together to build a simple settings page for the plugin. First we need to set up the routes for the settings page, a GET route to display the page and a POST route to handle saving the updated settings. The routes should have a name defined and be set to use a specific action, which we'll add shortly.

Routes/plugin.php

    <?php

    Route::get('settings', [
        'as'   => 'plugin.helloworld.settings',
        'uses' => 'Addons\Plugins\HelloWorld\Controllers\HelloWorld@getSettingsPage'
    ]);

    Route::post('settings', [
        'as'   => 'plugin.helloworld.settings.update',
        'uses' => 'Addons\Plugins\HelloWorld\Controllers\HelloWorld@updateSettings'
    ]);

Next we need to create a view to show the settings page, which will contain a form that submits to the POST route. The form_* functions are made available thanks to the TwigBridge library, providing snake_cased versions of all the functions available from the Laravel Collective HTML package, but you can also use straight HTML if you prefer.

Views/view.twig

    {% extends 'operator.' ~ template ~ '.index' %}

    {% block title %}
        {{ Lang.get('Plugins#HelloWorld::lang.hello_world') }}
    {% endblock %}

    {% block content %}
        {{ form_model(fields, {'method': 'POST', 'route': 'plugin.helloworld.settings.update'}) }}

            <div class="form-container first">

                <div class="form-row">
                    {{ form_label('setting', Lang.get('Plugins#HelloWorld::lang.setting')) }}
                    <div class="input-container">
                        {{ form_input('text', 'setting') }}<br />
                        <span class="description">{{ Lang.get('Plugins#HelloWorld::lang.setting_desc') }}</span>
                    </div>
                </div>

            </div>

            <div class="form-button">
                {{ form_submit(Lang.get('general.save')) }}
            </div>

        {{ form_close() }}
    {% endblock %}

Breaking the template down, the form_model call will create the initial <form> tag and sets the action and method, and the first attribute 'fields' should be an array containing any data that is currently set for the fields in the form. The form_input adds an input field with the name 'setting' to the form. The form_submit adds a button allowing to submit the form and form_close is needed at the end to close the form.

Finally we add our two actions, for displaying the settings page and updating the settings:

Controllers/HelloWorld.php

    /**
     * Get the settings page.
     *
     * @return \Illuminate\View\View
     */
    public function getSettingsPage()
    {
        return \TemplateView::other('Plugins#HelloWorld::settings')
            ->with('fields', $this->getSettings());
    }

    /**
     * Update the settings.
     *
     * @return \Illuminate\Http\RedirectResponse
     */
    public function updateSettings()
    {
        // Get settings data
        $data = \Request::all(['setting']);

        // Work through each row of data.
        foreach ($data as $key => $value) {
            if (! empty($value) || $value == 0) {
                $this->addSetting($key, $value);
            }
        }

        // All done, return with a success message.
        \Session::flash('success', Lang::get('messages.success_settings'));

        return \Redirect::route('plugin.helloworld.settings');
    }

The TemplateView::other method lets us display plugin templates, and we can pass data to the view with the with() helper. We will also fetch our current settings by using the getSettings function and use it to show the existing values when displaying our settings page.

The Request facade gives us access to data in the request, we use the only method to limit what data we fetch from the request, in this case only the 'setting' field. We add our settings provided they're present and not an empty string. Finally we show a success or error message depending on the success of saving the settings, flash will mean it only shows for one request, and redirect back to displaying the settings page.

Settings Page

The settings page now works, but we want to make it easier for operator to manage the plugin, which we can achieve by making it show a settings link in the plugins grid. We do this by calling the registerSetting function in the controller constructor and setting it to the GET route we created.

Controllers/HelloWorld.php

    /**
     * Initialise the plugin.
     */
    public function __construct()
    {
        parent::__construct();

        $this->setIdentifier('HelloWorld');

        // Register the settings page.
        $this->registerSetting('plugin.helloworld.settings');
    }

Now you have a functioning plugin with a settings page, and you're ready to make it more useful.


Next Section: Permissions