diff --git a/const-PARAMETERS.md b/const-PARAMETERS.md index ee4b1bf..ecf0476 100644 --- a/const-PARAMETERS.md +++ b/const-PARAMETERS.md @@ -1,58 +1,128 @@ -Parameters are defined in an array, which is used to generate an HTML `
` by **RSS-Bridge**. +You can specify additional parameters in order to customize the bridge (i.e. to specify how many items to return). This document explains how to specify those parameters and which options are available to you. -The `const PARAMETERS` array is not mandatory if your bridge doesn't take any parameter. +For information on how to read parameter values during execution, please refer to the [getInput](The-getInput-function) function. -The first level of this array describes every possible usage of a bridge. +*** -The array can be a key-based array, but it is not necessary. The following syntaxes are hereby correct : +# Adding parameters to a bridge + +Parameters are specified as part of the bridge class. An empty list of parameters is defined as `const PARAMETERS = array();` + +
Show example
```PHP -const PARAMETERS = array(array(...), array(...)); -const PARAMETERS = array('First usage' => array(...), 'Second usage' => array(...)); +

+ +Parameters are organized in two levels: + +[**Level 1**](#level-1---context) - Context +[**Level 2**](#level-2---parameter) - Parameter + +## Level 1 - Context + +A context is defined as a associative array of parameters. The name of a context is displayed by RSS-Bridge. + +
Show example
```PHP -const PARAMETERS = array('global' => array(...)); +const PARAMETERS = array( + 'My Context 1' => array(), + 'My Context 2' => array() +); ``` -### Format specifications +**Output** -`const PARAMETERS` element is an associative array whose key is the input field identifier, and the value is another array containing all input fields names and values. +[[bridge_context_named.png]] -Following elements are supported : +

+ +**Warning**: Multiple contexts with the same parameters are not allowed! + +**Notice**: The name of a context can be left empty if only one context is needed! + +
Show example
+ +```PHP +const PARAMETERS = array( + array() +); +``` + +

+ +You can also define a set of parameters that will be applied to every possible context of your bridge. To do this, specify a context named `global`. + +
Show example
+ +```PHP +const PARAMETERS = array( + 'global' => array() // Applies to all contexts! +); +``` + +
+ +## Level 2 - Parameter + +Parameters are placed inside a context. They are defined as associative array of parameter specifications. Each parameter is defined by it's internal input name, a definition in the form `'n' => array();`, where `n` is the name with which the bridge can access the parameter during execution. + +
Show example
+ +```PHP +const PARAMETERS = array( + 'My Context' => array( + 'n' => array() + ) +); +``` + +

+ +The parameter specification consists of various fields, listed in the table below. + +
Show example
+ +```PHP +const PARAMETERS = array( + 'My Context' => array( + 'n' => array( + 'name' => 'Limit', + 'type' => 'number', + 'required' => false, + 'title' => 'Maximum number of items to return', + 'defaultValue' => 10 + ) + ) +); +``` + +**Output** + +[[context_parameter_example.png]] + +
+ +*** Parameter Name | Required | Type | Supported values | Description ---------------|----------|------|------------------| ----------- `name` | **yes** | Text | | Input name as displayed to the user -`type` | no | Text | `text`, `number`, `list`, `checkbox` |Type of the input, default is text -`required` | no | Boolean | `true`, `false` | Set this if you want your attribute to be required -[`values`](#list-values) | no | associative array | | name/value pairs used by the HTML option tag, required with the '`list`' type -`title` | no | Text | | Will be shown as tool-tip when mouse-hovering over the input -`pattern` | no | Text | | Defines a pattern for an element of type `text`. The required pattern should be mentioned in the `title` attribute! -`exampleValue` | no | Text | | Defines an example value that is shown for elements of type `text` and `number` -[`defaultValue`](#defaultvalue) | no | | | Defines the default value. - -Hence, the most basic parameter definition is the following : - -```PHP -... - const PARAMETERS = array( - 'u' => array('name' => 'Username') - ); - -... -``` - -#### defaultValue - -This attribute defines the default value for your parameter. Its behavior depends on the `type`: - -- `text`: Allows any text -- `number`: Allows any number -- `list`: Must match either name or value of one element -- `checkbox`: Must be "checked" to activate the checkbox +`type` | no | Text | `text`, `number`, `list`, `checkbox` | Type of the input (default: `text`) +`required` | no | Boolean | `true`, `false` | Specifies if the parameter is required or not (default: `false`) +[`values`](#list-values) | no | associative array | | name/value pairs used by the HTML option tag, required for type '`list`' +`title` | no | Text | | Used as tool-tip when mouse-hovering over the input box +`pattern` | no | Text | | Defines a pattern for an element of type `text`. The pattern should be mentioned in the `title` attribute! +`exampleValue` | no | Text | | Defines an example value displayed for elements of type `text` and `number` when no data has been entered yet +[`defaultValue`](#defaultvalue) | no | | | Defines the default value if left blank by the user #### List values @@ -85,4 +155,15 @@ If a more complex organization is required to display the values, the above key/ 'Item B' => 'itemB' ) ... -``` \ No newline at end of file +``` + +#### defaultValue + +This attribute defines the default value for your parameter. Its behavior depends on the `type`: + +- `text`: Allows any text +- `number`: Allows any number +- `list`: Must match either name or value of one element +- `checkbox`: Must be "checked" to activate the checkbox + +***