Coppermine Photo Gallery v1.5.x: Documentation et manuel

Table des Matières

Ajout d'options de configuration

Cette page est sensée expliquer comment ajouter (ou modifier) une option de configuration.

Cible de cette page

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.

Historique

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.

Nouvelles fonctions

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.

Pas à pas

Appliquez les étapes suivantes pour ajouter une option de configuration lors de la période de développement:

Basic.sql

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.

Si votre nouvelle option de configuration est nommées "enable_coffee_making" trouvez INSERT INTO CPG_config VALUES ('enable_plugins', '1'); et ajoutez votre nouvelle ligne juste avant.

Update.sql

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

Admin.inc.php

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.

If you want your new config option to be displayed beneath the "Enable plugins" entry, find
    '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

Language file

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.

Documentation

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.

To Do

There are some additional features for the config page that should be implemented in the near future