Howto Plugin Settings

There are 2 ways to have plugin settings. I don't mean the single component settings within a plugin, but settings that are covering the complete plugin.

File settings

This is the most easy one. You create a file config.php in the folder config of your plugin. This file looks something like this:

<?php

return [
    /**
     * position of the button
     * allowed values: 'tr', 'tl', 'br', 'bl'
     */
    'position' => 'tr',

    /**
     * Show label
     * allowed values: false, true
     */
    'showLabel' => true,
    /**
     * Edit URL
     * {id} is substitutet with blog post id
     */
    'editUrl' => 'rainlab/blog/posts/update/{id}'
];

Access values in plugin or component

<?php
namespace Enovision\FrontendEdit\Components;

use Config;

class EditButton extends \Cms\Classes\ComponentBase {

    public $position;
    public $showLabel;
    public $editUrl;

    ...

    public function onRun() {
        ...
        // $x = Config::get(parameter, default); 
        $this->position  = Config::get( 'enovision.frontendedit::position', 'tr' );
        $this->showLabel = Config::get( 'enovision.frontendedit::showlabel', true );
        $this->editUrl   = Config::get( 'enovision.frontendedit::editUrl', true );
        ....
    }
}

Database settings

These settings are available at the backend settings (click settings in the settings menu) and could look like:

fields.yaml

The setting fields we describe in a file named fields.yaml in the folder models\settings of your plugin. If the folder models doesn't exist you have to create it first.

Sample of fields.yaml

# ===================================
#  Form Field Definitions
# ===================================

fields:
    plugin_enabled:
        label: Enabled
        disabled: false
        type: switch
        default: false
        span: auto
        comment: Plugin is enabled?
    position:
        label: Position
        disabled: false
        default: tr
        type: dropdown
        options:
            tr: Top Right
            tl: Top Left
            br: Bottom Right
            bl: Bottom Left
        span: auto
        comment: Position of the button on the display
    show_label:
        label: Show Label
        disabled: false
        type: switch
        default: true
        span: auto
        comment: Show the button label?
    show_icon:
        label: Show Icon
        disabled: false
        type: switch
        default: true
        span: auto
        comment: Show the icon on the button? When this and label are both false, label is used automatically
    button_label:
        label: Button Label
        type: text
        required: false
        default: Edit Post
        span: auto
        comment: Text to put on the label, default "Edit Post"
    edit_url:
        label: Edit Url (don't change this if you not must)
        type: text
        default: rainlab/blog/posts/update/{id}
        span: auto
        comment: This has to be always "rainlab/blog/posts/update/{id}"

The indentions are fixed 4 blanks!

The model

Now we have to create a model named Settings.php in the models folder.

Sample of the model:

<?php namespace Enovision\FrontendEdit\Models;

use October\Rain\Database\Model;

class Settings extends Model {

    public $implement = [
        'System.Behaviors.SettingsModel',
        '@RainLab.Translate.Behaviors.TranslatableModel',
    ];

    public $settingsCode = 'enovision_frontendedit_settings';
    public $settingsFields = 'fields.yaml';
}

See documentation here

Retrieving the values

<?php
namespace Enovision\FrontendEdit\Components;

use Enovision\FrontendEdit\Models\Settings;

class EditButton extends \Cms\Classes\ComponentBase {

    public $position;
    public $showLabel;
    public $editUrl;

    ...

    public function onRun() {
        ...
        // $x = Settings::get(parameter, default); 
        $this->position  = Settings::get( 'position', 'tr' );
        $this->showLabel = Settings::get( 'show_label', true );
        $this->editUrl   = Settings::get( 'edit_url', true );
        ....
    }
}
Last update: Tue, 13 Sep 2022 14:32:15