variable.api.php 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213
  1. <?php
  2. /**
  3. * @file
  4. * Hooks provided by the Variable module.
  5. */
  6. /**
  7. * @defgroup variable_api_hooks Variable API Hooks
  8. * @{
  9. * Functions to define and modify information about variables.
  10. *
  11. * These hooks and all the related callbacks may be defined in a separate file
  12. * named module.variable.inc
  13. *
  14. * @}
  15. */
  16. /**
  17. * Define variables used by a module.
  18. *
  19. * Provides meta-information for each variable that includes at the very least some human readable title.
  20. * This information may be used by other modules to select variables from a list for translating, exporting, etc.
  21. *
  22. * Though not required we can also provide some more information to be able to handle the variable in an effective
  23. * way, like which type of data and form element it uses, default value, etc.. There are multiple predefined
  24. * variable types ('type' attribute) that will add a predefined set of properties. Some of them are:
  25. *
  26. * - "string": Simple plain string variable. The form element will be a text field and it will be localizable.
  27. * - "number": Simple numeric value. The form element will be a text field.
  28. * - "boolean": Simple TRUE/FALSE value. It will be a checkbox.
  29. * - "enable": Enabled / Disabled selector. It will display as two radio buttons.
  30. * - "select": Selectable list of options. Depending on the number of options, the element will be a list of
  31. * radios or a drop down.
  32. * - "options": List of options with multiple choices. It will be a list of checkboxes.
  33. * ...
  34. *
  35. * More variable types can be defined by modules using hook_variable_type_info().
  36. *
  37. * For the case of variable names that depend on some other parameter (like variables per content-type),
  38. * there's some special type of variables: Multiple variables. These can be defined like this:
  39. *
  40. * @code
  41. * $variables['node_options_[node_type]'] = array(
  42. * 'type' => 'multiple',
  43. * 'title' => t('Default options', array(), $options),
  44. * 'repeat' => array(
  45. * 'type' => 'options',
  46. * 'default' => array('status', 'promote'),
  47. * 'options callback' => 'node_variable_option_list',
  48. * ),
  49. * );
  50. * @endcode
  51. *
  52. * This multiple variable will spawn into one variable for each node type. Note the variable name that includes
  53. * the property [node_type]. Values for [node_type] will be defined on hook_variable_type_info().
  54. *
  55. * The 'repeat' property defines the properties of children variables. In this case the 'type' property is optional
  56. * and will default to 'multiple'.
  57. *
  58. * @param $options
  59. * Array of options to build variable properties. Since variable properties are cached per language
  60. * these options should be used at the very least for string translations, so titles and defaults are
  61. * localized. Possible options:
  62. * - "language" => Language object for which strings and defaults must be returned. This one will be always defined.
  63. *
  64. * @return
  65. * An array of information defining the module's variables. The array
  66. * contains a sub-array for each node variable, with the variable name
  67. * as the key. Possible attributes:
  68. * - "title": The human readable name of the variable, will be used in auto generated forms.
  69. * - "type": Variable type, should be one of the defined on hook_variable_type_info().
  70. * - "group": Group key, should be one of the defined on hook_variable_group_info().
  71. * - "description": Variable description, will be used in auto generated forms.
  72. * - "options": Array of selectable options, or option name as defined on hook_variable_option_info().
  73. * - "options callback": Function to invoke to get the list of options.
  74. * - "default": Default value.
  75. * - "default callback": Function to invoke to get the default value.
  76. * - "multiple": Array of multiple children variables to be created from this one.
  77. * - "multiple callback": Function to invoke to get children variables.
  78. * - "element": Form element properties to override the default ones for this variable type.
  79. * - "element callback": Function to invoke to get a form element for this variable.
  80. * - "module": Module to which this variable belongs. This property will be added automatically.
  81. * - "repeat": Array of variable properties for children variables.
  82. * - "localize": Boolean value, TRUE for variables that should be localized. This may be used by other modules.
  83. * - "validate callback": Callback to validate the variable value, it will be added to form element #validate.
  84. */
  85. function hook_variable_info($options) {
  86. $variables['site_name'] = array(
  87. 'type' => 'string',
  88. 'title' => t('Name', array(), $options),
  89. 'default' => 'Drupal',
  90. 'description' => t('The name of this website.', array(), $options),
  91. 'required' => TRUE,
  92. );
  93. $variables['site_403'] = array(
  94. 'type' => 'drupal_path',
  95. 'title' => t('Default 403 (access denied) page', array(), $options),
  96. 'default' => '',
  97. 'description' => t('This page is displayed when the requested document is denied to the current user. Leave blank to display a generic "access denied" page.', array(), $options),
  98. );
  99. return $variables;
  100. }
  101. /**
  102. * Define types of variables or list of values used by a module.
  103. *
  104. * These subtypes can be used to provide defaults for all properties of variables of this type
  105. * or to provide a list of options either for variable options (selectable values) or for children
  106. * variables in the case of multiple variables.
  107. *
  108. * Example, three usages of variable type:
  109. * @code
  110. * // Use variable type 'weekday' to provide a selector for a day of the week
  111. * $variables['date_first_day'] = array(
  112. * 'type' => 'weekday',
  113. * 'title' => t('First day of week'),
  114. * 'default' => 0,
  115. * );
  116. *
  117. * // Use 'options' with value 'weekday' for any other variable that needs to provide a selectable
  118. * // list of days of the week. In this example you can select one or more days.
  119. * $variables['working_days'] = array(
  120. * 'type' => 'options',
  121. * 'options' => 'weekday',
  122. * 'title' => t('Select working days from the list.'),
  123. * );
  124. *
  125. * // Use 'multiple' with value 'weekday' to create a subset of variables, one for each day of the week.
  126. * // In fact, using '[weekday]' in the variable name will set these properties ('type' and 'multiple') automatically.
  127. * $variables['daily_greeting_[weekday]'] = array(
  128. * 'type' => 'multiple',
  129. * 'multiple' => 'weekday',
  130. * 'repeat' => array('type' => 'string'),
  131. * 'title' => t('Greeting to display each day of the week'),
  132. * );
  133. * @endcode
  134. *
  135. * @return
  136. * An array of information defining variable types. The array contains
  137. * a sub-array for each variable type, with the variable type as the key.
  138. *
  139. * The possible attributes are the same as for hook_variable_info(), with the
  140. * type attributes being added on top of the variable attributes.
  141. *
  142. * A special attribute:
  143. * - "type": Variable subtype, the properties for the subtype will be added to these ones.
  144. */
  145. function hook_variable_type_info() {
  146. $type['mail_address'] = array(
  147. 'title' => t('E-mail address'),
  148. 'element' => array('#type' => 'textfield'),
  149. 'token' => TRUE,
  150. );
  151. $type['mail_text'] = array(
  152. 'title' => t('Mail text'),
  153. 'multiple' => array('subject' => t('Subject'), 'body' => t('Body')),
  154. 'build callback' => 'variable_build_mail_text',
  155. 'localize' => TRUE,
  156. 'type' => 'multiple',
  157. );
  158. return $type;
  159. }
  160. /**
  161. * Define groups of variables used by a module.
  162. *
  163. * Variable groups are used for presentation only, to display and edit the variables
  164. * on manageable groups. Groups can define a subset of a module's variables and can
  165. * be reused accross modules to group related variables.
  166. *
  167. * A form to edit all variables in a group can be generated with:
  168. *
  169. * drupal_get_form('variable_group_form', group_name);
  170. *
  171. * @return
  172. * An array of information defining variable types. The array contains
  173. * a sub-array for each variable group, with the group as the key.
  174. * Possible attributes:
  175. * - "title": The human readable name of the group. Must be localized.
  176. * - "description": The human readable description of the group. Must be localized.
  177. * - "access": Permission required to edit group's variables. Will default to 'administer site configuration'.
  178. * - "path": Array of administration paths where these variables can be accessed.
  179. */
  180. function hook_variable_group_info() {
  181. $groups['system_site_information'] = array(
  182. 'title' => t('Site information'),
  183. 'description' => t('Site information and maintenance mode'),
  184. 'access' => 'administer site configuration',
  185. 'path' => array('admin/config/system/site-information', 'admin/config/development/maintenance'),
  186. );
  187. $groups['system_feed_settings'] = array(
  188. 'title' => t('Feed settings'),
  189. 'description' => t('Feed settings'),
  190. 'access' => 'administer site configuration',
  191. );
  192. return $groups;
  193. }
  194. /**
  195. * Alter system settings forms.
  196. *
  197. * This is a special version of hook_form_alter() that is triggered only for
  198. * system settings forms, and only after any other module has added/removed
  199. * variables using hook_form_alter().
  200. *
  201. * It is used to mark / replace special realm variables that are contained in the form.
  202. *
  203. * @see hook_form_alter()
  204. * @see variable_module_implements_alter()
  205. */
  206. function hook_variable_settings_form_alter(&$form, &$form_state, $form_id) {
  207. }