diff --git a/const-PARAMETERS.md b/const-PARAMETERS.md new file mode 100644 index 0000000..ee4b1bf --- /dev/null +++ b/const-PARAMETERS.md @@ -0,0 +1,88 @@ +Parameters are defined in an array, which is used to generate an HTML `
` by **RSS-Bridge**. + +The `const PARAMETERS` array is not mandatory if your bridge doesn't take any parameter. + +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 : + +```PHP +const PARAMETERS = array(array(...), array(...)); +const PARAMETERS = array('First usage' => array(...), 'Second usage' => array(...)); +``` + +It is worth mentioning that you can also define a set of parameters that will be applied to every possible utilization of your bridge. To do this, just create a parameter array with the `global` key : + +```PHP +const PARAMETERS = array('global' => array(...)); +``` + +### Format specifications + +`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. + +Following elements are supported : + +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 + +#### List values + +List values are defined in an associative array where keys are the string displayed in the combo list of the **RSS-Bridge** web interface, and values are the content of the \ HTML tag value attribute. + +```PHP +... + 'type' => 'list', + 'values' => array( + 'Item A' => 'itemA' + 'Item B' => 'itemB' + ) +... +``` + +If a more complex organization is required to display the values, the above key/value can be used to set a title as a key and another array as a value: +```PHP +... + 'type' => 'list', + 'values' => array( + 'Item A' => 'itemA', + 'List 1' => array( + 'Item C' => 'itemC', + 'Item D' => 'itemD' + ), + 'List 2' => array( + 'Item E' => 'itemE', + 'Item F' => 'itemF' + ), + 'Item B' => 'itemB' + ) +... +``` \ No newline at end of file