function location_form in Location 5
Same name and namespace in other branches
- 5.3 location.module \location_form()
- 6.3 location.module \location_form()
- 7.5 location.module \location_form()
- 7.3 location.module \location_form()
- 7.4 location.module \location_form()
Generates a Drupal HTML form for collecting locationes.
Parameters
$fields: An array of values where each value is one of 'street', 'city', 'province', 'postal_code', or 'country'. The presence of values in this array determines which fields will be served in the location form generated by a call to this function. If this array is empty, all fields are generated.
$prefilled_values: An associative array where -> Each key is one of the location fields: 'street', 'additional', 'city', 'province', 'postal_code', 'country' -> Each value is a prefilled value for the given field. ..... ))
$required_fields: An array of values that are required. Each string can be one of 'street', 'city', 'postal_code', 'province', or 'country'. The presence of values in this array determines which fields will be marked as 'required'. Validation (i.e., making sure a required value is actually filled in is the responsibility of the caller)
$suppressed_values: An array of values that are to be automatically filled and hidden from user view. These will be indicated in this associative array with the following possibilities for keys: 'province' => The standard province value as defined keyed by the country specific file (e.g., for US states, its the capitalized two letter abbreviation. 'country' => The lower-case two letter ISO code for the country being assumed.
$description: A text description of specifically what location is being collected by the form to be served.
$form_name: An additional parameter to help prevent HTML input name collisions. If the caller is using this function to generate more than 1 location form on a page, then the generated name for each HTML input's "name" attribute will go by the value supplied for $form_name. This parameter is defaulted to 'location' For example, if $form_name == 'xyz' and there is a 'street' field in the form to be served, the "name" attribute for the HTML <input> will be "edit[xyz][street]"
$function: A string that tells location_form() which location API function will be using the location submitted via the generated form. For example, if $function == 'latlon_rough', then the returned location_form (if it includes a country field) will only generate a list of countries in the HTML select for which function location_latlon_rough() is supported. To figure out which countries these are, we check to see which of the configured countries have existing functions to support the call. In this case, we would check to see if there existed a function called "location_latlon_rough_us()" before listing the United States in the HTML SELECT for the generated location form. $function is defaulted to NULL. If $function is NULL, the HTML SELECT that is generated will list all countries.
Return value
An location form based on the parameters specified. If the $fields array is empty, then the function returns a form in which all possible fields are served as optional form items.
EXAMPLES:
-> The following call returns a form that only contains fields for a postal_code and country where the postal_code is required: --- $form = location_form(array('postal_code', 'country'), array(), array('postal_code', 'country'), 'Permanent location') --- The form returned by this call is generated with calls to Drupal's 'form_' functions:
$form = form_textfield('Postal Code', 'location][postal_code', '', 64, 64, NULL, NULL, TRUE); ------------------------------------------------------------------------------------------------- -> The following call returns a form that contains fields for a street, province, and postal_code, but the street, city, and province fields are optional while postal_code is required: --- $form = location_form(array('street', 'city', 'province', 'postal_code'), array(), array('postal_code')); --- -> The form returned by this call is generated with the following calls to Drupal's 'form_' functions:
$form = form_textfield('Street', 'location][street', '', 64, 64); $form .= form_textfield('Additional', 'location][additional', '', 64, 64); // The 'Additional' field is always and only generated when 'street' is specified as one of the fields. // The 'Additional' field is always optional whether or not 'Street' is required. $form .= form_textfield('City', 'location][city', '', 64, 64); $form .= _location_province_select_options(); // defined below $form .= form_textfield('Postal Code', 'location][postal_code', '', 64, 64, NULL, NULL, TRUE); ------------------------------------------------------------------------------------------------ For the following examples, assume we have the following two locationes: (1) $locationA = ('street' => '2010 Broadway St', 'city' => 'Redwood City', 'province' => 'CA', 'postal_code' => '94063', 'country' => 'us'); (2) $locationB = ('street' => '2010 Broadway St', 'city' => 'Redwood City', 'province' => 'us-CA', 'postal_code' => '94063', 'country' => 'us'); -> The following calls return the exact same form that contains fields for a street, province, postal_code, where prefilled values are submitted to the form.
$form = location_form(array('street', 'city', 'province', 'postal_code', 'country'), $locationB, array('street', 'city', 'province', 'postal_code', 'country'), '', 'home_location');
$form = location_form(array('street', 'city', 'province', 'postal_code', 'country'), location_api2form($locationA), array('street', 'city', 'province', 'postal_code', 'country'), '', 'home_location');
-> The form returned by these call is ultimately generated with the following calls to Drupal's 'form_' functions:
$form = textfield('Street', 'home_location][street', '2010 Broadway St.', 64, 64, NULL, NULL, TRUE); $form .= textfield('Additional', 'home_location][additional', 'Attn: Ankur Rishi', 64, 64, NULL, NULL, TRUE); $form .= textfield('City', 'home_location][city', 'Redwood City', 64, 64, NULL, NULL, TRUE); $form .= _location_province_select_options(TRUE, 'us-CA', 'home_location'); $form .= textfield('Postal Code', 'home_location][postal_code', '94063', 64, 64, NULL, NULL, TRUE); $form .= _location_country_select_options(TRUE, 'us', 'home_location');
Note that in both cases, the first and third argument can take the same array since all the fields are being required.
4 calls to location_form()
File
- ./
location.inc, line 230
Code
function location_form($fields = array(), $prefilled_values = array(), $required_fields = array(), $suppressed_values = array(), $description = '', $function = NULL) {
if (count($fields) == 0) {
$fields = array(
'name',
'street',
'city',
'province',
'postal_code',
'country',
);
}
$form = array();
$form['description'] = array(
'#type' => 'markup',
'#value' => $description,
);
if (in_array('name', $fields)) {
$form['name'] = array(
'#type' => 'textfield',
'#title' => t('Location name'),
'#default_value' => isset($prefilled_values['name']) ? $prefilled_values['name'] : '',
'#size' => 64,
'#maxlength' => 64,
'#description' => t('e.g. a place of business, venue, meeting point'),
'#attributes' => NULL,
'#required' => in_array('name', $required_fields),
);
}
if (in_array('street', $fields)) {
$form['street'] = array(
'#type' => 'textfield',
'#title' => t('Street'),
'#default_value' => isset($prefilled_values['street']) ? $prefilled_values['street'] : '',
'#size' => 64,
'#maxlength' => 64,
'#required' => in_array('street', $required_fields),
);
$form['additional'] = array(
'#type' => 'textfield',
'#title' => t('Additional'),
'#default_value' => isset($prefilled_values['additional']) ? $prefilled_values['additional'] : '',
'#size' => 64,
'#maxlength' => 64,
);
}
if (in_array('city', $fields)) {
$form['city'] = array(
'#type' => 'textfield',
'#title' => t('City'),
'#default_value' => isset($prefilled_values['city']) ? $prefilled_values['city'] : '',
'#size' => 64,
'#maxlength' => 64,
'#description' => NULL,
'#attributes' => NULL,
'#required' => in_array('city', $required_fields),
);
}
if (in_array('province', $fields)) {
if (in_array('province', array_keys($suppressed_values))) {
$form['province'] = array(
'#type' => 'hidden',
'#value' => $suppressed_values['province'],
);
}
else {
$form['province'] = _location_province_select_options(isset($prefilled_values['province']) ? $prefilled_values['province'] : '', in_array('province', $required_fields), in_array('country', array_keys($suppressed_values)) ? $suppressed_values['country'] : NULL);
}
}
if (in_array('postal_code', $fields)) {
$form['postal_code'] = array(
'#type' => 'textfield',
'#title' => t('Postal code'),
'#default_value' => isset($prefilled_values['postal_code']) ? $prefilled_values['postal_code'] : '',
'#size' => 16,
'#maxlength' => 16,
'#required' => in_array('postal_code', $required_fields),
);
}
if (in_array('country', $fields)) {
if (in_array('country', array_keys($suppressed_values))) {
$form['country'] = array(
'#type' => 'hidden',
'#value' => $suppressed_values['country'],
);
}
else {
$form['country'] = _location_country_select_options(isset($prefilled_values['country']) ? $prefilled_values['country'] : '', in_array('country', $required_fields), $function);
}
}
$form['#theme'] = 'location_form';
return $form;
}