diff --git a/variable.api.php b/variable.api.php index 2dcad16..d390e2e 100644 --- a/variable.api.php +++ b/variable.api.php @@ -19,26 +19,33 @@ /** * Define variables used by a module. * - * Provides meta-information for each variable that includes at the very least some human readable title. - * This information may be used by other modules to select variables from a list for translating, exporting, etc. + * Provides meta-information for each variable that includes at the very least + * some human readable title. This information may be used by other modules to + * select variables from a list for translating, exporting, etc. * - * Though not required we can also provide some more information to be able to handle the variable in an effective - * way, like which type of data and form element it uses, default value, etc.. There are multiple predefined - * variable types ('type' attribute) that will add a predefined set of properties. Some of them are: + * Though not required we can also provide some more information to be able to + * handle the variable in an effective way, like which type of data and form + * element it uses, default value, etc.. There are multiple predefined variable + * types ('type' attribute) that will add a predefined set of properties. Some + * of them are: * - * - "string": Simple plain string variable. The form element will be a text field and it will be localizable. + * - "string": Simple plain string variable. The form element will be a text + * field and it will be localizable. * - "number": Simple numeric value. The form element will be a text field. * - "boolean": Simple TRUE/FALSE value. It will be a checkbox. * - "enable": Enabled / Disabled selector. It will display as two radio buttons. - * - "select": Selectable list of options. Depending on the number of options, the element will be a list of - * radios or a drop down. - * - "options": List of options with multiple choices. It will be a list of checkboxes. + * - "select": Selectable list of options. Depending on the number of options, + * the element will be a list of radios or a drop down. + * - "options": List of options with multiple choices. It will be a list of + * checkboxes. * ... * - * More variable types can be defined by modules using hook_variable_type_info(). + * More variable types can be defined by modules using + * hook_variable_type_info(). * - * For the case of variable names that depend on some other parameter (like variables per content-type), - * there's some special type of variables: Multiple variables. These can be defined like this: + * For the case of variable names that depend on some other parameter (like + * variables per content-type), there's some special type of variables: + * Multiple variables. These can be defined like this: * * @code * $variables['node_options_[node_type]'] = array( @@ -52,38 +59,52 @@ * ); * @endcode * - * This multiple variable will spawn into one variable for each node type. Note the variable name that includes - * the property [node_type]. Values for [node_type] will be defined on hook_variable_type_info(). + * This multiple variable will spawn into one variable for each node type. Note + * the variable name that includes the property [node_type]. Values for + * [node_type] will be defined on hook_variable_type_info(). * - * The 'repeat' property defines the properties of children variables. In this case the 'type' property is optional - * and will default to 'multiple'. + * The 'repeat' property defines the properties of children variables. In this + * case the 'type' property is optional and will default to 'multiple'. * * @param $options - * Array of options to build variable properties. Since variable properties are cached per language - * these options should be used at the very least for string translations, so titles and defaults are - * localized. Possible options: - * - "language" => Language object for which strings and defaults must be returned. This one will be always defined. + * Array of options to build variable properties. Since variable properties + * are cached per language these options should be used at the very least for + * string translations, so titles and defaults are localized. The possible + * options: + * - "language" => Language object for which strings and defaults must be + * returned. This one will be always defined. * * @return - * An array of information defining the module's variables. The array - * contains a sub-array for each node variable, with the variable name - * as the key. Possible attributes: - * - "title": The human readable name of the variable, will be used in auto generated forms. - * - "type": Variable type, should be one of the defined on hook_variable_type_info(). - * - "group": Group key, should be one of the defined on hook_variable_group_info(). - * - "description": Variable description, will be used in auto generated forms. - * - "options": Array of selectable options, or option name as defined on hook_variable_option_info(). + * An array of information defining the module's variables. The array contains + * a sub-array for each node variable, with the variable name as the key. + * Possible attributes: + * - "title": The human readable name of the variable, will be used in auto + * generated forms. + * - "type": Variable type, should be one of the defined on + * hook_variable_type_info(). + * - "group": Group key, should be one of the defined on + * hook_variable_group_info(). + * - "description": Variable description, will be used in auto generated + * forms. + * - "options": Array of selectable options, or option name as defined on + * hook_variable_option_info(). * - "options callback": Function to invoke to get the list of options. * - "default": Default value. * - "default callback": Function to invoke to get the default value. - * - "multiple": Array of multiple children variables to be created from this one. + * - "multiple": Array of multiple children variables to be created from this + * one. * - "multiple callback": Function to invoke to get children variables. - * - "element": Form element properties to override the default ones for this variable type. - * - "element callback": Function to invoke to get a form element for this variable. - * - "module": Module to which this variable belongs. This property will be added automatically. + * - "element": Form element properties to override the default ones for this + * variable type. + * - "element callback": Function to invoke to get a form element for this + * variable. + * - "module": Module to which this variable belongs. This property will be + * added automatically. * - "repeat": Array of variable properties for children variables. - * - "localize": Boolean value, TRUE for variables that should be localized. This may be used by other modules. - * - "validate callback": Callback to validate the variable value, it will be added to form element #validate. + * - "localize": Boolean value, TRUE for variables that should be localized. + * This may be used by other modules. + * - "validate callback": Callback to validate the variable value, it will be + * added to form element #validate. * * @see hook_variable_info_alter() */ @@ -107,8 +128,8 @@ function hook_variable_info($options) { /** * Alter the variable definitions. * - * @param $info - * The variable info array, keyed by variable name. + * @param array $info + * The variable info, keyed by variable name. * * @see hook_variable_info() */ @@ -118,9 +139,10 @@ function hook_variable_info_alter(&$info) { /** * Define types of variables or list of values used by a module. * - * These subtypes can be used to provide defaults for all properties of variables of this type - * or to provide a list of options either for variable options (selectable values) or for children - * variables in the case of multiple variables. + * These subtypes can be used to provide defaults for all properties of + * variables of this type or to provide a list of options either for variable + * options (selectable values) or for children variables in the case of multiple + * variables. * * Example, three usages of variable type: * @code @@ -131,16 +153,18 @@ function hook_variable_info_alter(&$info) { * 'default' => 0, * ); * - * // Use 'options' with value 'weekday' for any other variable that needs to provide a selectable - * // list of days of the week. In this example you can select one or more days. + * // Use 'options' with value 'weekday' for any other variable that needs to + * // provide a selectable list of days of the week. In this example you can + * // select one or more days. * $variables['working_days'] = array( * 'type' => 'options', * 'options' => 'weekday', * 'title' => t('Select working days from the list.'), * ); * - * // Use 'multiple' with value 'weekday' to create a subset of variables, one for each day of the week. - * // In fact, using '[weekday]' in the variable name will set these properties ('type' and 'multiple') automatically. + * // Use 'multiple' with value 'weekday' to create a subset of variables, one + * // for each day of the week. In fact, using '[weekday]' in the variable + * // name will set these properties ('type' and 'multiple') automatically. * $variables['daily_greeting_[weekday]'] = array( * 'type' => 'multiple', * 'multiple' => 'weekday', @@ -157,7 +181,8 @@ function hook_variable_info_alter(&$info) { * type attributes being added on top of the variable attributes. * * A special attribute: - * - "type": Variable subtype, the properties for the subtype will be added to these ones. + * - "type": Variable subtype, the properties for the subtype will be added to + * these ones. * * @see hook_variable_type_info_alter() */ @@ -191,9 +216,9 @@ function hook_variable_type_info_alter(&$info) { /** * Define groups of variables used by a module. * - * Variable groups are used for presentation only, to display and edit the variables - * on manageable groups. Groups can define a subset of a module's variables and can - * be reused accross modules to group related variables. + * Variable groups are used for presentation only, to display and edit the + * variables on manageable groups. Groups can define a subset of a module's + * variables and can be reused accross modules to group related variables. * * A form to edit all variables in a group can be generated with: * @@ -204,9 +229,12 @@ function hook_variable_type_info_alter(&$info) { * a sub-array for each variable group, with the group as the key. * Possible attributes: * - "title": The human readable name of the group. Must be localized. - * - "description": The human readable description of the group. Must be localized. - * - "access": Permission required to edit group's variables. Will default to 'administer site configuration'. - * - "path": Array of administration paths where these variables can be accessed. + * - "description": The human readable description of the group. Must be + * localized. + * - "access": Permission required to edit group's variables. Will default to + * 'administer site configuration'. + * - "path": Array of administration paths where these variables can be + * accessed. * * @see hook_variable_group_info_alter() */ @@ -243,7 +271,8 @@ function hook_variable_group_info_alter(&$info) { * system settings forms, and only after any other module has added/removed * variables using hook_form_alter(). * - * It is used to mark / replace special realm variables that are contained in the form. + * It is used to mark / replace special realm variables that are contained in + * the form. * * @see hook_form_alter() * @see variable_module_implements_alter()