:!: traduction en cours


====== Configuration ======

DokuWiki permet d'écrire des [[plugins|greffons]] et [[templates|thèmes]] très flexibles en les rendant hautement configurables.

===== Paramètres par défaut =====

Pour rendre un greffon configurable, vous devez fournir un fichier ''lib/plugins/<plugin>/conf/default.php'' qui contiendra les paramètres par défaut et un fichier ''lib/plugins/<plugin>/conf/metadata.php'' qui contient la description [[#Méta-données_de_configuration]] qui est utilisée par le [[fr:plugin:config|Gestionnaire de configuration]] pour gérer/afficher les options((les thèmes sont analogues à ''lib/tpl/<template>/conf/default.php'' etc.)).

<code php>
$conf[<setting>] = <value>;
</code>

===== Méta-données de configuration =====
Pour chaque paramètre dans ''lib/plugins/<votre plugin>/conf/default.php'', il devrait y avoir une valeur ''%%$meta[<setting>]%%'' définie dans ''lib/plugins/<votre plugin>/conf/metadata.php''((Pour les thèmes, c'est tout à fait analogue : ''lib/tpl/<votre thème>/conf/default.php'' et ''lib/tpl/<votre thème>/conf/metadata.php'')) :


<code php>
$meta[<setting>] = array(<setting class>, <param name> => <param value>);
</code>

Si aucun paramètre n'est requis pour une classe de réglage (voir ci-dessous), c'est tout simplement :

<code php>
$meta[<setting>] = array(<setting class>);
</code>

Exemples:

<code php>
$meta['_basic']     = array('fieldset');
$meta['title']      = array('string');
$meta['lang']       = array('dirchoice','_dir' => DOKU_INC.'inc/lang/');
$meta['dmode']      = array('numeric','_pattern' => '/0[0-7]{3,4}/'); // n'accepte qu'une représentation octale
$meta['allowdebug'] = array('onoff');
$meta['passcrypt']  = array('multichoice','_choices' => array('smd5','md5','sha1','ssha','crypt','mysql','my411'));
</code>

==== Classes ====

^ ''%%''%%''               | Classe par défaut ('setting'), zone de texte (textarea), validation minimale des entrées, mise entre guillemets des sorties.                                                                                                                        |
^ ''%%'string'%%''         | Saisie de texte sur une seule ligne, validation minimale des entrées, mise entre guillemets des sorties.                                                                                                                                                        |
^ ''%%'numeric'%%''        | Saisie de texte, accepte les nombres et les opérateurs arithmétiques, définit la sortie sans les guillemets. Si on leur donne les paramètres ''_min'' et ''_max'', ils seront utilisés pour la validation.                                                                           |
^ ''%%'numericopt'%%''     | Comme ci-dessus, mais accepte des valeurs vides.                                                                                                                                                                                              |
^ ''%%'onoff'%%''          | Case à cocher en entrée, définissant la sortie ''0'' ou ''1'' (notez que les valeurs par défaut doivent être un de ces entiers, et non un booléen).                                                                                                                 |
^ ''%%'multichoice'%%''    | Sélectionner l'entrée (choix unique), régler la sortie avec des guillemets, paramètre ''_choices'' requis.                                                                                                                                        |
^ ''%%'email'%%''          | Saisie de texte, la saisie doit être conforme au format de l'adresse électronique, en mettant la sortie entre guillemets.                                                                                                                                                                                                                                    |
^ ''%%'password'%%''       | Saisie d'un mot de passe, validation minimale de la saisie, mise entre guillemets du texte de sortie en clair. Une fois défini, le mot de passe n'est plus affiché dans le gestionnaire de configuration. Peut être masqué dans la configuration par le paramètre ''_code''.                      |
^ ''%%'dirchoice'%%''      | En tant que ''multichoice'', choix de sélection basé sur les dossiers trouvés à l'endroit spécifié dans le paramètre ''_dir'' (obligatoire).                                                                                                                       |
^ ''%%'multicheckbox'%%''  | Une case à cocher pour chaque choix plus une "autre" chaîne de saisie, le paramétrage du fichier de configuration est une liste de choix cochés séparés par des virgules.                                                                                                         |
^ ''%%'fieldset'%%''       | Utilisé pour regrouper les paramètres de configuration, mais n'est pas lui-même un paramètre. Pour que cela soit clair dans les fichiers de langue, les clés de ce type doivent commencer par ''_''.                                                                          |
^ ''%%'authtype'%%''       | Crée une sélection de méthodes d'authentification disponibles, basées sur les noms de classe dans ''inc/auth'' qui correspondent au modèle ''authtype.class.php''.                                                                                           |
^ ''%%'array'%%''          | tableau simple (unidimensionnel) de valeurs de chaînes de caractères, présenté sous forme de liste séparée par des virgules dans le gestionnaire de configuration mais enregistré sous forme de array()  PHP. Les valeurs ne peuvent pas contenir de virgules en elles-mêmes. La correspondance ''_pattern'' sur les valeurs du tableau est prise en charge.            |
^ ''%%'regex'%%''          | Chaîne d'expression régulière, normalement sans délimiteurs ; comme pour ''string'', en plus testée pour voir si elle se compile et s'exécute comme une regex.  En plus de ''_pattern'', accepte également ''_delimiter'' (par défaut ''/'') et ''_pregflags'' (par défaut ''ui'').  |


==== Parameters ====

^ ''%%'_pattern'%%''    | String, a regular expression. Input is tested against this pattern before being accepted.\\ Optional all classes, except ''onoff'', ''multichoice'' and ''dirchoice'' which ignore it.                                                                                                                                                                                                                                      |
^ ''%%'_choices'%%''    | Array of choices. Used to populate a selection box. Choice will be replaced by a localised language string, indexed by ''<setting name>_o_<choice>'', if one exists.\\ Required by ''multichoice'' & ''multicheckbox'' classes, ignored by others.                                                                                                                                                                    |
^ ''%%'_dir'%%''        | Location of directory to be used to populate choice list.\\ Required by ''dirchoice'' class, ignored by other classes.                                                                                                                                                                                                                                                                                           |
^ ''%%'_code'%%''       | Sets the obfuscation option for password fields. May be ''plain'', ''base64'' or ''uuencode''. When using the latter two, you need to use [[phpxref>conf_decodeString()]] to access the plain value.                                                                                                                                                                                                               |
^ ''%%'_combine'%%''    | Complimentary output setting values which can be combined into a single display ''checkbox''.\\ Optional for ''multicheckbox'', ignored by other classes.                                                                                                                                                                                                                                                            |
^ ''%%'_code'%%''       | Encoding method to use, accepted values: ''base64'', ''uuencode'', ''plain''.  Defaults to plain.                                                                                                                                                                                                                                                                                                                    |
^ ''%%'_min'%%''        | Minimum numeric value.\\ Optional for ''numeric'' and ''numericopt'', ignored by others.                                                                                                                                                                                                                                                                                                                            |
^ ''%%'_max'%%''        | Maximum numeric value.\\ Optional for ''numeric'' and ''numericopt'', ignored by others.                                                                                                                                                                                                                                                                                                                            |
^ ''%%'_delimiter'%%''  | String, default ''/'', a single character used as a delimiter for testing regex input values.                                                                                                                                                                                                                                                                                                                   |
^ ''%%'_pregflags'%%''  | String, default ''ui'', valid preg pattern modifiers used when testing regex input values, for more information see [[http://uk1.php.net/manual/en/reference.pcre.pattern.modifiers.php]].                                                                                                                                                                                                                          |
^ ''%%'_multiple'%%''   | Bool, allow multiple comma separated email values.\\ Optional for ''email'', ignored by others.                                                                                                                                                                                                                                                                                                                   |
^ ''%%'_other'%%''      | How to handle other values (not listed in ''_choices''). Accepted values: ''always'', ''exists'', ''never''. Default value ''always''.\\ ''exists'' only shows 'other' input field when the setting contains value(s) not listed in choices (e.g. due to manual editing or update changing ''_choices'').  This is safer than ''never'' as it will not discard unknown/other values.\\ Optional for ''multicheckbox'', ignored by others.  |


==== Examples ====

=== ''multicheckbox'' with ''_other'' ===

Let's say initially a plugin uses the syntax:

<code php>$meta['multi'] = array('multicheckbox', '_choices' => array('a','b','c','d'));</code>

this means the multicheckbox will show four choices plus a string input.

Let's suppose also that the user inserts one or more extra values not in ''_choices''.

In the next release of the plugin the author's plugin decides to use the multicheckbox without the extra string, but, in order to be backwardly compatible, adopts:

<code php>$meta['multi'] = array('multicheckbox', '_other' => 'exists', '_choices' => array('a','b','c','d'));</code>

which means:
  * if the user has inserted comma separated values, they will be printed in the extra string;
  * otherwise the extra string won't show.

Note also that if the user inserts comma separated values which already exist (or some of them) in ''_choices'' but:
  * they are already ticked, then the extra string will be removed and nothing else;
  * they are not already ticked, then the extra string will be removed and the relative value will be ticked.

===== Accessing Settings =====
====Core Settings====
Inside [[xref>inc/init.php]] the configurations settings are read into a [[devel:environment|global array]] ''$conf[]''. When no settings were set, these are read from the default settings file.
You can access the core settings anywhere by using the ''$conf[]'' array.

<code php>
$startpage = $conf['start'];
</code>

====Plugin settings====
You can access settings in [[plugins]] by using the ''%%$this->%%[[xref>getConf|getConf('<setting>')]]'' method. 
In your plugin class you use:
<code php>
$keyvalue = $this->getConf('key');
</code>

==== Template settings====
In [[templates]] you can use ''[[xref>tpl_getConf|tpl_getConf('<setting>')]]''.
<code php>
$nicetoknow = tpl_getConf('special');
</code>


===== Labels in Configuration Manager =====
For every setting in ''lib/plugins/<your plugin>/conf/default.php'' there can be a ''%%$lang[<setting>]%%'' value defined in ''lib/plugins/<your plugin>/lang/en/settings.php''. This value will be displayed as the label of the setting in the configuration manager. If the label file is left out or doesn't contain a value for the setting, the configuration manager will display "''%%plugin <plugin name> <setting>%%''" as the label instead. 

You can also create a ''settings.php'' file for other languages. 

Again, this also applies to templates (see [[:localization]] for further details).