cgmartin / cgmconfigadmin

ZF2 module for easy administration of application settings

CgmConfigAdmin

Version 1.2.1 Created by Christopher Martin

Introduction

Need to give clients access to website configuration settings?

CgmConfigAdmin is a ZF2 module for managing site-wide settings via a single web page.

Settings are exposed to the administration panel via a simple configuration format.

Module authors can also easily include their own specific configuration settings right from their module.config.php file.

UPDATES IN 1.2.1

Please see CHANGELOG.md.

Requirements

• Zend Framework 2
• ZfcBase
• A Database or Key/Value store

Installation

Composer / Packagist

% composer.phar require cgm/config-admin
Please provide a version constraint for the cgm/config-admin requirement: dev-master

Main Setup

1. Install the ZfcBase ZF2 module by cloning it into ./vendor/ and enabling ZfcBase in your application.config.php file.
2. Clone this project into your ./vendor/ directory and enable CgmConfigAdmin in your application.config.php file.
3. Copy ./vendor/CgmConfigAdmin/config/cgmconfigadmin.global.php.dist to ./config/autoload/cgmconfigadmin.global.php and change the values as desired.
4. Import the SQL schema located in ./vendor/CgmConfigAdmin/data/schema.sql.
5. Navigate to /config-admin and try it out.

Post-Install

Protect the /config-admin route with an authorization module, such as ZfcRbac or BjyAuthorize. The route can be changed in the ./config/autoload/cgmconfigadmin.global.php file.

Database Adapter Configuration

If you do not already have a valid Zend\Db\Adapter\Adapter in your service manager configuration, put the following in ./config/autoload/database.local.php:

<?php

$dbParams = array(
    'database'  => 'changeme',
    'username'  => 'changeme',
    'password'  => 'changeme',
    'hostname'  => 'changeme',
);

return array(
    'service_manager' => array(
        'factories' => array(
            'Zend\Db\Adapter\Adapter' => function ($sm) use ($dbParams) {
                return new Zend\Db\Adapter\Adapter(array(
                    'driver'    => 'pdo',
                    'dsn'       => 'mysql:dbname='.$dbParams['database'].';host='.$dbParams['hostname'],
                    'database'  => $dbParams['database'],
                    'username'  => $dbParams['username'],
                    'password'  => $dbParams['password'],
                    'hostname'  => $dbParams['hostname'],
                ));
            },
        ),
    ),
);

See the Zend\Db\Adapter documentation for more info on how to configure the adapter for your specific database.

Configuring custom settings

Example:

<?php
//
// Config Groupings
//
$configGroups = array(
    'group1' => array('label' => 'Simple Options',  'sort' => 1),
    'group2' => array('label' => 'Complex Options', 'sort' => 2),
    'group3' => array('label' => 'Multi Options',   'sort' => 3),
);

//
// Config Options
//
$configOptions = array(

    'group1' => array(
        //
        // Simple Options
        //
        // Key will be automatically converted to a label
        //
        'useCamelCase'    => true,
        'or-dashes'       => false,
        'or_underscores'  => true,
        'simpleText'      => 'Some text',
        'simpleNumber'    => '50',
        'simpleSelect'    => array('Foo', 'Bar', 'Dev', 'Null'),
    ),

    'group2' => array(
        //
        // Complex Options examples
        //
        'boolOption' => array(
            'input_type'    => 'radio',
            'label'         => 'Boolean Option',
            'value_options' => array('1' => 'True', '' => 'False'),
            'default_value' => false,
        ),

        'textOption' => array(
            'input_type'    => 'text',
            'label'         => 'Text Option',
            'default_value' => 'My Site',
            'required'      => true,        // options are not required by default
        ),

        'numberOption' => array(
            'input_type'    => 'number',
            'label'         => 'Number Option',
            'default_value' => '10',
        ),
    ),

    'group3' => array(
        //
        // Complex Multi-Options examples
        //
        'multiCheckboxOption' => array(
            'input_type'    => 'multicheckbox',
            'label'         => 'MultiCheckbox Option',
            'value_options' => array('Foo', 'Bar', 'Dev', 'Null'),
            'default_value' => array('Bar', 'Dev'),
        ),

        'radioOption' => array(
            'label'         => 'Radio Option',
            'input_type'    => 'radio',
            'value_options' => function ($configOption) {
                // Callbacks can be used to feed options
                return array('Foo', 'Bar', 'Dev', 'Null');
            },
            'default_value' => 'Bar',
        ),

        'selectOption' => array(
            'label'         => 'Select Option',
            'input_type'    => 'select',
            'value_options' => array('Spring', 'Summer', 'Fall', 'Winter'),
            'default_value' => 'Fall',
        ),
    ),
);

Adding Configuration Groups from other Modules

Simply add a new config group and options for your module and they will be included

<?php
// module.config.php
return array(
    //...
    'cgmconfigadmin' => array(
        'config_groups' => array(
            'site' => array(
                'mymod' => array('label' => 'My Module Options',  'sort' => -100),
            ),
        ),

        'config_options' => array(
            'site' => array(
                'mymod' => array(
                    'someText'   => 'Some text',
                    'someNumber' => '50',
                    'someSelect' => array('Foo', 'Bar', 'Dev', 'Null'),
                ),
            ),
        ),
    ),
);

Usage

To retrieve a config value:

<?php
$settingValue = $sm->get('cgmconfigadmin')->getConfigValue('groupId', 'optionId');
// ..or..
$settingValue = $sm->get('cgmconfigadmin')->getConfigValue('groupId/optionId');

An instance of the CgmConfigAdmin\Service\ConfigAdmin service is registered in the Service Manager under the alias cgmconfigadmin.

Events

Events below are emitted from the CgmConfigAdmin\Service\ConfigAdmin service:

Previewing Config Values

previewConfigValues : Before preview values are saved in the session.

• Param configValues (ArrayObject) List of config values from form.

previewConfigValues.post : After preview values are saved in the session.

• Param configValues (ArrayObject) List of config values saved in session.

Resetting Config Values

resetConfigValues : Before the previewed config values are reset.

• Param configValues (ArrayObject) The current list config values in the session.

resetConfigValues.post : After the previewed config values are reset.

Saving Config Values

saveConfigValues : Before the changed list of config values are saved.

• Param configValues (ArrayObject) The changed list of config values to be saved.

saveConfigValues.post : After the config values have been saved.

• Param configValues (ArrayObject) The saved list of config values.

To attach event listeners:

public function onBootstrap($e)
{
    $events = $e->getApplication()->getEventManager()->getSharedManager();
    $events->attach('CgmConfigAdmin\Service\ConfigAdmin', 'previewConfigValues', function($e) {
        $configAdminService = $e->getTarget();
        $configValues = $e->getParam('configValues');
        // Do what you will...
    });
    $events->attach('CgmConfigAdmin\Service\ConfigAdmin','previewConfigValues.post', function($e) {
        $configAdminService = $e->getTarget();
        $configValues = $e->getParam('configValues');
        // Do what you will...
    });
}

cgmconfigadmin's Issues

multicheckbox label

How can we specify label for each value in a multicheckbox ?

Password type does not hold value

Problem with Password inputs and the default behavior of inputs. The value does not carry over, since the Password element resets it's value when prepared.

Need a way to hold on to the current value, and if the password input is filled out, overwrite it.

Tabbed settings

Enhancement request for a Tabbed settings view helper.

Is it possible to have config groups other than 'site'?

Is it possible to have other config groups besides 'site'. In the example we have:

    'cgmconfigadmin' => array(
        'config_groups' => array(
            'site' => array(
                'mymod' => array('label' => 'My Module Options',  'sort' => -100),
            ),
        ),

Is it possible to have something like

    'cgmconfigadmin' => array(
        'config_groups' => array(
            'site' => array(
                'mymod' => array('label' => 'My Module Options',  'sort' => -100),
            ),
            'frontend' => array(
                'group1' => array('label' => 'My Frontend Options',  'sort' => -100),
            ),
             'backend' => array(
                'group2' => array('label' => 'My Backend Options',  'sort' => -100),
            ),
        ),

This would be useful when we have way too many options to show in a single page.

how to use in Module.php or in Controller?

Hi, please write how to use this module in other Module.php files or in other Controllers ?

Tooltips on inputs

Feature request for allowing tooltips to be easily added to config inputs.

cgmconfigadmin module

hello, help pls for this error
A 404 error occurred Page not found.

The requested controller could not be mapped to an existing controller class.

Controller:
CgmConfigAdmin\Controller\ConfigOptions(resolves to invalid controller class or alias: CgmConfigAdmin\Controller\ConfigOptions)

Composer install error

Hi, this might be me, but it seemed fine last week. I already have zf-commons/zfc-user install via composer using "dev-master" version. When trying to add this module using "dev-master" I get the following error:

Problem 1
- Installation request for cgm/config-admin dev-master -> satisfiable by cgm/config-admin dev-master.
- cgm/config-admin dev-master requires zf-commons/zfc-base dev-master -> no matching package found.

Any thoughts? This is a great module and I'd love to continue using it.
Cheers,
Marc

Table of contents for long list of settings

Feature request for a table of contents view helper (with Scrollspy) for long listings.

Filters the subform?

look! zendframework/zendframework#2583
And integrate my app and your app is posivol

Doctrine ORM support

I've created a simple module which adds Doctrine ORM support to CgmConfigAdmin:

https://github.com/adamlundrigan/CgmConfigAdminDoctrineORM

Everything seems to work fine, but i'm just getting started with using your module in my Doctrine-based ZF2 project so any feedback is welcome.

If you want I can transfer the repository to you so both modules live in the same location.

Alert when in Preview Mode

Feature request for an alert overlay to signal when in "preview mode".