This page is supposed to explain how to add (or edit) a config option.
This part of the documentation is not meant for end users of Coppermine, but only for developers. There is no support for this section, it comes as-is.
In versions prior to cpg1.5.x, the language file contained part of the logic how the config page looked and worked (section separation, help-icon links, input field type). This caused confusion for translators and kept the language fallback function from fully working as expected.
Additionally, every new config option that displayed a link to another page or that was supposed to offer different text for radio buttons required devs to come up with a separate function that made the code of the config file become more and more bloated.
In an effort to clean up the config screen and allow future enhancements, the config page (admin.php) has been re-coded.
The end user will see little changes on the new config screen - most changes happened "under the hood". Most obvious change is the regex check that is performed when the form is being submit: invalid entries are being caught and subsequently won't be written to the database. The end user will see a visualization what config setting needs review.
Apply the following steps when adding a config option during the development stage:
Add the needed sql queries to sql/basic.sql for fresh installs. The config entries should exist in alphabetical order.
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