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