Helper class for ConfigurableModule

[owzim]

Hi folks,

I read some posts where people seem to struggle with setting up config values for their modules. Since I am currently working on some boilerplate code for modules I created a helper class that makes handling of config values a peace of cake.

on Github: https://github.com/owzim/PWModuleConfigHelper

from the README.md

Define a default array in your module:

protected static $defaultConfig = array(

    // example with just one option
    'prettySetting'  => array(

        // the label for the form
        'label' => 'Pretty Setting',

        // the default value
        'value' => 'I am pretty',

        // optional, defaults to 'InputfieldText'
        'inputfieldType' => 'InputfieldText'
    ),

    // example with multiple options
    'awesomeSetting' => array(

        // the label for the form
        'label' => 'Awesome Setting',

        // the default value
        'value' => 2,

        // optional, defaults to 'InputfieldRadios'
        'inputfieldType' => 'InputfieldRadios',

        // each key is for the input label, each value will be saved if selected
        'options' => array(
            'Option 1' => 1,
            'Option 2' => 2,
            'Option 3' => 3
        ),

        // set any additional attribute to the input field
        'attributes' => array(
            'optionColumns' => 1
        )
    )
);

Apply the defaults to your module:

public function __construct() {
    PWModuleConfigHelper::apply($this, self::$defaultConfig);
}

Render out the form:

public static function getPWModuleConfigInputfields(array $data) {
    return PWModuleConfigHelper::renderForm($data, self::$defaultConfig);
}

Result:

Access any of the config settings from your module:

$this->awesomeSetting;

Stuff to be aware of

If you're using this in your module and you don't want it to clash with other modules using this, you have the following options to include it:

1. use spl_autoload_register to autoload it, so it only gets loaded once
2. only include the class if it has not been loaded yet, via class_exists('PWModuleConfigHelper')
3. Option 1 and 2 require the class not to change (updates etc.) so the following options are more stable:
4. Namespace to class via renaming it, prefixing it with you module's name
5. Namespace it with PHP namespaces
6. I could make a module out of this but this might be overkill

Cheers!

[Nico Knoll]

Nicely done

[owzim]

When I skim through the existing modules I see some mundane tasks repeated over and over again. The implementation of tasks are quite different between the modules. Install pages, install templates, assign processes, making fields configurable, making modules configurable and so on ...

I just stumbled upon a need to abstract common tasks/methods when I tried to have two process modules share similar functionality, so I created a base class.

Then this module config thing came up and I created yet another class to abstract that stuff away from me and make it more flexible and easier to extend/update.

Both methods would require me to boilerplate code, for use in every module I will create in the future. I hate boilerplate. It can get pretty messy. If I update the boilerplate it's outdated in places it has been used in.

So a way better approach, I think, is to have the module helpers have in a separate module and my modules would depend on that.

My question to you people is, would you use a Module Helper Module in you Modules? It certainly adds another dependency which might not be desired, so you modules can only be installed if the helpers are installed first. Is that too much?

If not I would like to know what common tasks are out there when creating modules so we can create some kind of module helper suite. I am quite new do module dev, so I am only considering the stuff I stumbled upon already.

Please share your thoughts on that.

Cheers!

[netcarver]

Perhaps the core would be the best place for this - rather than having 3rd party modules depend on a helper class?

Regardless of location of the helper class (core or via a module) I'd love to see an option for defining this via yaml or json as an alternative to PHP. In particular yaml is a very terse way to describe options. If the 'inputfieldType' entry had shorter 'type' alias and if you prepend 'Inputfield' to the type, you could get to something like this...

prettySetting:
  label: Pretty Setting
  value: I am pretty
  type: Text

awesomeSetting:
  label: Awesome Setting
  value: 2
  type: Radios
  options:
    'Option 1': 1
    'Option 2': 2
    'Option 3': 3
  attributes:
    optionColumns: 1

 But yaml does have some drawbacks - it's whitespace sensitive and not supported in PHP by default.

[netcarver]

@owzim

Just opened an issue for this on github.

[owzim]

@netcarver sorry I did not get any email notification, because I disabled them while I was in deep deadline madness.

This class is obsolete anyway because Ryan implemented similar stuff in the core, see http://processwire.com/blog/posts/new-module-configuration-options/

Thanks Ryan for hearing us out (there was also a discussion about this somewhere, don't know where)!