Cette page est sensée expliquer comment ajouter (ou modifier) une option de configuration.
Cette partie de la docuentation n'est pas destinée aux utiliateurs finaux de Coppermine, mais uniquement aux développeurs. Il n'y a pas d'aide pour cette section, elle est t'elle qu'elle.
Dans les versions précédant cpg1.5.x, le fichier langue contenait une partie de la manière dont la page de configuration s'affichait et fonctionnait (séparateurs de section, icones d'aide, type de champs de saisie). Celà posait des problèmes aux traducteurs et empêchait la fonction de language de remplacement de fonctionner comme prévu.
En plus, chaque nouvelle option de configuration qui affichait un lien vers une autre page ou qui était supposées offrir différents textes pour des boutons radios forçaient les développeurs à créer une fonction séparée qui faisait que le code du fichier de configuration devenait de plus en plus gros et difficile à maintenir.
Afin de nettoyer l'écran de configuration et de permettre des améliorations futures, la page de configuration (admin.php) a été enièrement recodée.
L'utilisateur final verra peu de changements sur la nouvelle page de configuration - la plupart des changements se passent "sous le capot". Le changement le plus évident est la vérification du regex qui est effectuée lors de la soumission d'un formulaire: les entrées non valides sont isolées et ensuite ne sont pas écrite à la base de données. L'utilisateur final verra quels paramètres de configuration doivent être revus.
Appliquez les étapes suivantes pour ajouter une option de configuration lors de la période de développement:
Ajoutez les requêtes sql nécessaires dans sql/basic.sql pour une nouvelle installation. Les entrées de configuration doivent exister dans l'ordre alphabétique.
To make sure your new config option is not only taken into account for fresh installs, but for updates as well, you will have to add your new query line that you already added to basic.sql to update.sql as well. The only difference is that you don't sort the entries as in basic.sql, but add them at the very bottom of update.sql
As suggested above, the logic of the config entry has been moved from the language file to a separate, language-independent include file. Edit include/admin.inc.php and add a new line to the array definition there are suggested below.
'enable_plugins' => array(
'type' => 'radio',
'help_link' => 'f=configuration.htm&as=admin_general_enable-plugins&ae=admin_general_enable-plugins_end',
'options' => array($lang_common['no'],
$lang_common['yes'].' ('.$lang_admin_php['manage_plugins'].')'
)
), and add your new array definition below it (into a new line).
Currently, the following array fields exist:
| array key | Description | Needed? | Possible content | Dependancies |
|---|---|---|---|---|
| type | Determines the type of input field | mandatory | textfield, checkbox, radio, hidden, password, select, select_multiple | |
| default_value | Allow users to reset individual input fields to the default value (instead of resetting the entire config screen) | optional | Any valid config table content (text, numerals) | |
| help_link | When the help icon display is enabled, the content of this field determines what the help pop-up will contain. Example content: f=foo.htm&as=bla&ae=bar |
mandatory | The f-parameter determines the file name (needs to reside within the docs folder), the as-parameter determines the starting anchor and the ae-parameter the ending anchor. | none |
| width | Determines the width of text input fields. | optional | Any width entry that is CSS-valid, e.g. 70% (width in percent) or 20 (width in pixels). Default (if no value is given) will be 100%. | Only applies for the types "textfield" and "password". Possible interaction with the size key |
| size | Number of characters for the width of the text input fields. | optional | Can contain any valid entry for the size parameter of HTML's <input type="text" />-field | Possible interaction with the width-key. |
| maxlength | Maximum number of characters allowed to enter into textfield | optional | Any valid entry for the maxlength attribute of HTML's <input type="text" />-field | Regex-field |
| regex | Regular expression that the value entered will be checked against (using PHP's preg_match) when the form is being submit. If the regular expression returns false, the config field change will be rejected | optional | maxlength-field | |
| regex_not | Regular expression that the value entered will be checked against (using PHP's preg_match) when the form is being submit (similar to the field "regex") with the difference/exception that the config value the user has entered will be rejected if the regular expression entered into "regex_not" does match the field. Use it to make sure the end user changes the content of a field once registered to something that makes sense (instead of keeping the default value). |
optional | none | |
| bridged | Determine entries that are disabled / not being taken into account when coppermine is bridged | optional | If the entry is set to "hide", the field will be greyed out and disabled. | |
| options | Sub-array determines the <option>-entries for a select field or the possible choices for radio buttons | mandatory for 'type' => 'select' and 'radio' | For radio buttons: Non-associative array, that contains the possible options, starting from the option that corresponds to 0 onwards. $lang_common['no'], $lang_common['yes'].': '.$lang_admin_php['debug_everyone'], $lang_common['yes'].': '.$lang_admin_php['debug_admin'] For select-fields: Either an associative array with the scheme ('option_value' => 'option_label') or a non-associative array ('foo', 'bar', 'whatever'). 'options' => array(5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25)
|
|
| additional_description | Specifies additional text to be displayed after the actual config option name (in the left column of the table). This should allow shorter config options names and alternative ways of describing a config setting for those who are too lazy to click the help icon. | optional | Both hardcoded text as well as a reference to a language string. | none |
| end_description | Specifies additional text to be displayed after the input field. Should be used for short strings or links to other pages. | optional | Both hardcoded text as well as a reference to a language string. | none |
| preserve_when_resetting | If set to '1', the setting will remain as-is even if the entire config is reset to factory defaults. Currently only used for the legacy feature "password encryption", as it is a one-way feature that can not be undone. | optional | 1 | none |
| only_display_if | Was used to make sure that the one-way setting "enable_encrypted_passwords" would be only displayed if the config value is zero. As the storage of unencrypted passwords has been dropped for cpg1.5.x, there is currently no use for this setting. | optional | Any valid content of the config field that it is checked against | none |
| only_display_if_not | Used to make sure that the one-way setting "thumb_pfx" will be only displayed if the config value differs from the given value, thus making sure that only upgraded galleries with different settings get displayed. If the value is default, it won't be displayed. | optional | Any valid content of the config field that it is checked against | none |
| linebreak | If set, the value of the entry will be added to the HTML output for all radio buttons after each option. Use it for option labels that need a lot of space to make the output better readable. | optional | <br /> | type = radio |
| warning | When set, a warning will be displayed that the config setting mustn't be changed when there are already pics in the database | optional | Any reference to the language file (or even hard-coded text) will do - it will be displayed in the JavaScript alert box and onmouseover. | none |
| min | If set, there will be spin buttons next to the field and the minimum value will be set to what you specify here. Additionally, the value will be checked when the form is submit. | optional | Numeric | type = textfield |
| max | If set, there will be spin buttons next to the field and the maximum value will be set to what you specify here. Additionally, the value will be checked when the form is submit. | optional | Numeric | type = textfield |
| step | If set, the step size of the spin buttons will differ (default is 1). | optional | Numeric | type = textfield, min or max set |
During the development stage, only lang/english.php needs to be kept up to date. Edit the needed language strings to the array $lang_admin_php in the language file.
Remember to tag your newly-added string with the comment that shows your line is new.
The goal is to have a help icon available for all config settings. Subsequently, you should at least come up with a short section for the config page of the documentation that explains what the config setting you introduce does, what the default values are etc.
Remember to add the anchors for the help icon to work properly.
This step is not mandatory in technical terms, but it will help both developers as well as end users to understand what your config option actually does. If your config options needs to be explained in more detail, consider creating a separate page within the documentation that covers details about the feature you added. Refer to the page Editing the documentation for details.
There are some additional features for the config page that should be implemented in the near future