====== Configuration Manager Plugin ======

---- plugin ----
description: Manage your wiki's configuration settings (bundled with DokuWiki)
author     : Christopher Smith
email      : chris@jalakai.co.uk
type       : admin
lastupdate : 2014-03-18
compatible : (bundled)
screenshot_img: :plugin:configmanager.png
depends    : 
conflicts  : 
similar    : 
tags       : configuration, settings, options, !bundled
----

===== Description =====

{{ :plugin:configmanager.png?350|The Configuration Manager - Field colors: blue = default, white = local change, light red = protected setting}}
The Config Manager allows wiki [[config:superuser|administrators]] to easily alter the wiki [[:config|configuration]] settings online from the comfort of their favorite web browser. This plugin manages basic DokuWiki configurations as well as [[devel:configuration|other settings]] for installed [[:plugins]] and currently used [[:template]].

===== Usage =====

The Config Manager is accessible from the admin screen (Login as superuser, click "Admin" and choose "{{https://raw.githubusercontent.com/dokuwiki/dokuwiki/master/lib/plugins/config/admin.svg?14}} Configuration Settings").

Settings are shown with different backgrounds to highlight their current status. 
  * A blue background is used to show default values (''conf/dokuwiki.php''), eg. values that have not been modified by the user.  
  * A white background indicates local changes (''conf/local.php''). 
  * A light red background shows protected settings (''conf/local.protected.php'') which can not be modified.

Modify settings to your needs and save it by using the ''Save'' button at bottom of the page, by pressing 'Enter' in a textbox or by using the [[:accesskey]] of your browser: ''<accesskey> + S''

==== How is your config saved ====

On saving changed settings this plugin will copy the current local settings file (''conf/local.php'') to ''conf/local.php.bak'' and save the updated settings to ''conf/local.php''.  It will never make any changes to the default settings stored in ''conf/dokuwiki.php''.  However, any settings found in ''conf/local.php'' will override the default settings as explained in the [[:config|configuration options page]].

The plugin adds the following lines to the top of ''conf/local.php'' when it updates it:

<file php conf/local.php>
/*
 * DokuWiki's Main Configuration File - Local Settings 
 * Auto-generated by config plugin 
 * Run for user: <username>
 * Date: <current date/time, rfc 2822 format (day, dd MMM YYYY hh:mm:ss TZ)>
 */
</file>

==== Protecting Settings ====

You can protect certain settings by placing them in ''conf/local.protected.php'' (create the file if it doesn't exist).

By default DokuWiki loads its configuration files in the following order:

  - ''conf/dokuwiki.php''
  - ''conf/local.php''
  - ''conf/local.protected.php''

This way, it is ensured that any values previously set from ''conf/dokuwiki.php'' and ''conf/local.php'' will be overridden by protected values from ''conf/local.protected.php''. Any settings found in ''conf/local.protected.php'' will be displayed by the plugin surrounded in light-red to indicate their protected status. Editing of protected values is disabled.

The loading order of configuration files is controlled by the global ''[[devel:preload|$config_cascade]]'' variable.

=== Example ===

<code php conf/local.protected.php>
<?php
/**
 * Protected settings
 * Do override DokuWiki default settings and local settings from Config Manager
 */
$conf['useacl'] = 1;
</code>


==== File Permissions ====

To be able to save the configuration data, the file permissions of ''conf/local.php'' needs to be writable by the webserver, as well as the configuration directory itself. Refer to [[install:permissions]] on details how set file permissions on various systems.

When the plugin detects that the config file can not be written, it will show a message box at the top of the page that says

> "The settings file can not be updated, if this is unintentional, ensure the local settings file name and permissions are correct."

When this happens, the save button won't be shown.

==== Triangle, Exclamation and Padlock Mark ====

Some fields in the configuration page show:
  * A yellow warning sign ({{:config:warning.png?nolink|}}) , or
  * An exclamation mark in a red circle ({{:config:danger.png?nolink|}}), or
  * The drawing of a padlock ({{:config:security.png?nolink|}})

These are the meanings of these three symbols:\\
{{:config:warning.png?nolink|}} **Yellow Mark** ⇒ changing this option may result in undesirable behaviors.\\
{{:config:danger.png?nolink|}} **Red circle** ⇒ changing this option could make your wiki and the configuration menu inaccessible.\\
{{:config:security.png?nolink|}} **Padlock** ⇒ changing this option could present a security risk.\\

Please, keep attention when you change these fields.