====== confmanager Plugin ======

---- plugin ----
description: Plugin to manage various .conf files
author     : Dominik Eckelmann, Julian Heise, Michael Große
email      : dokuwiki@cosmocode.de
type       : admin, action, remote
lastupdate : 2023-06-13
compatible : Greebo, Hogfather, Igor, Jack Jackrum
depends    : 
conflicts  : 
similar    : txtconf, advanced, acronymedit
tags       : admin, configuration

downloadurl: https://github.com/cosmocode/confmanager/zipball/master
bugtracker : https://github.com/cosmocode/confmanager/issues
sourcerepo : https://github.com/cosmocode/confmanager/
donationurl: 

screenshot_img: :plugin:confmanager:confmanager_small.png
----

===== Download and Installation =====

[[https://www.cosmocode.de/en/open-source/dokuwiki-plugins/|{{ https://www.cosmocode.de/static/img/dokuwiki/dwplugins.png?recache|A CosmoCode Plugin}}]]

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

==== Changes ====

{{rss>https://github.com/cosmocode/confmanager/commits/master.atom date}}

===== Usage =====

You can use this plugin to edit several ''[[:config#configuration_files|*.conf]]'' files from the ''conf/'' directory via the DokuWiki admin menu: {{https://raw.githubusercontent.com/cosmocode/confmanager/master/admin.svg?20&recache}} Configuration File Manager.

After selecting a configuration file in the dropdown menu, you can add your own lines, or overwrite or disable the default lines.

{{:plugin:confmanager:confmanager.png?500|}}

===== Plugins that support the confmanager =====

  * [[plugin:docsearch]]
  * [[plugin:tagalerts]]
  * [[plugin:uncmap]]
  * [[plugin:elasticsearch]]

===== Development notes: Use the conf manager for your plugin =====

You can use the ConfManager with your very own plugin. The ConfManager plugin supports different types of config files descripted below. To add the config you have to add an [[devel:action_plugins|action]] component that hooks the ''CONFMANAGER_CONFIGFILES_REGISTER'' event. You can add your config file to the ''$event->data'' array.

The following example shows the usage of the ''ConfigManagerTwoLine'' config type.
<code php>
<?php

class action_plugin_docsearch_confmanager extends DokuWiki_Action_Plugin {

    public function register(Doku_Event_Handler $controller) {
        $controller->register_hook('CONFMANAGER_CONFIGFILES_REGISTER', 'BEFORE',  $this, 'addConfigFile', array());
    }

    public function addConfigFile(Doku_Event $event, $params) {
        if (class_exists('ConfigManagerTwoLine')) {
            $config = new ConfigManagerTwoLine('My Config', 'Description of my plugin', DOKU_INC . 'path to my config');
            $event->data[] = $config;
        }
    }
}
</code>

==== Config cascade config types ====

The ConfManager provides support for some config formats used by DokuWiki. DokuWiki use the global $config_cascade array to get the path to the config file.

The following config types are available:
^ Class name ^ Description ^
| ConfigManagerSingleLineCoreConfig | Every line is a config option. The config values are basically an array. I.e. the [[:blacklist]] config. |
| ConfigManagerTwoLineCascadeConfig | Every line is a config option. The first word in the line is a config key . The config is a associative array. I.e. the [[:abbreviations]] config |
| ConfigManagerTwoLineLeftImageConfigCascade | Like ConfigManagerTwoLineCascadeConfig but with image support. An image can be assigned for every key. I.e. the [[:mime]] config |

The following code shows how to create an instance of each config type from the table above.
The following placeholder are used:
  * **<name>** Name of the config in the ''$config_cascade'' array.
  * **<image path>** Path starting from DOKU_INC to the image folder.
  * **<image extension>** Extension of the images to use. I.e. mime icons use png.
<code php>
$scheme = new ConfigManagerSingleLineCoreConfig('<name>');
$acronyms = new ConfigManagerTwoLineCascadeConfig('<name>');
$mime = new ConfigManagerTwoLineLeftImageConfigCascade('<name>', '<image path>', '<image extension>');
</code>

These three config types all have the following methods to provide additional information:
  * **setName** (string): The name of the config file. This is shown in the drop down box and as headline.
  * **setDescription** (string): A description text to explain the config file. DokuWiki markup is allowed.

==== ConfigManagerTwoLine config type ====

The ConfigManagerTwoLine config type stores an associative array like the [[:abbreviations]] config.

The following code shows how to create an instance of the ConfigManagerTwoLine config type.
The following placeholder are used:
  * **<Title>** (string): The name of the config file. This is shown in the drop down box and as headline.
  * **<Description>** (string): A description text to explain the config file. DokuWiki markup is allowed.
  * **<Config path>** (string): Absolute path to the config file. If the file is not present it will be created.
<code php>
$config = new ConfigManagerTwoLine('<Title>', '<Description>', '<Config path>');
</code>