The uc_addresses_address form element
Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites
The form element "uc_addresses_address" is used to construct an address form element. When the form element is processed, it will present a collection of address fields. An UcAddressesAddress instance will be associated with this form element and its values will be used to prefill the address fields.
Default values
This are the default values a form element of type "uc_addresses_address" will get if not set.
- #tree = TRUE (don't override this value)
- #uc_addresses_address = UcAddressesAddress::newAddress();
- #uc_addresses_context = 'default'
- #uc_addresses_required = TRUE
- #key_prefix = ''
Properties
#uc_addresses_address
Description: The UcAddressesAddress instance that is associated with the address form element. The address fields will be automatically prefilled with the values of this instance. If this property is not set, a new instance of UcAddressesAddress will be assigned. This will be an unowned address. When the form is validated, the address instance will get the form values assigned. If you intend to save the address to the address book, the only thing that needs to be done in the form submit function is saving the address.
Values: An instance of UcAddressesAddress.
Usage example:
// Example 1: create an edit form for address ID 2 from user 1.
$address = UcAddressesAddressBook::get(1)->getAddressById(2);
$form['address'] = array(
'#type' => 'uc_addresses_address',
'#uc_addresses_address' => $address,
);
// Example 2: create an edit form for a new address for user 1.
$address = UcAddressesAddressBook::get(1)->addAddress();
$form['address'] = array(
'#type' => 'uc_addresses_address',
'#uc_addresses_address' => $address,
);
// Example 3: create an edit form for a new address not intended
// to be saved to the address book or for a new user.
$address = UcAddressesAddress::newAddress();
$form['address'] = array(
'#type' => 'uc_addresses_address',
'#uc_addresses_address' => $address,
);
#uc_addresses_context
Description: The context in which the uc_addresses_address field is used. This value is generally used by address fields to determine if it should be displayed or not. In the display settings of a field definition is defined in which contexts the field should be shown. Fields that should not appear in a certain context are not even constructed. If you define a new context, you should alter the field definitions to have control over which address fields should be shown. This can be done with the hook hook_uc_addresses_address_field_alter()
.
Values: See Display settings: contexts.
Usage example:
// An address form on a order administration page.
// For example: /admin/store/orders/11/edit
$form['address'] = array(
'#type' => 'uc_addresses_address',
'#uc_addresses_context' => 'order_form',
);
#uc_addresses_required
Description: Overrides the #required setting of address fields at the first level. With this property you can set one or more address fields to required or non-required before they are constructed! The address fields are constructed when the uc_addresses_address form element is processed, so they aren't available in form alter functions. Only the #required setting of address fields at the first level can be overridden, fields that are nested deeper are left untouched (Ubercart Addresses does not define fields that are nested deeper, but they can be defined by other modules).
Values:
There are three possible values:
- TRUE (default): The #required setting of all address fields are left untouched.
- FALSE: All subfields (address fields) at the first level are forced to be non-required. Even when the field handler had set them to required. And even when a "manually" added subfield is set to required.
- An array of
field name => boolean
pairs. Overrides the #required setting of certain address fields.
Usage example:
// Example 1: make all address fields non-required.
$form['address'] = array(
'#type' => 'uc_addresses_address',
'#uc_addresses_required' => FALSE,
);
// Example 2: make the "company" field required, but make
// the fields "first_name" and "last_name" non-required.
// Don't override the #required setting of other address fields.
$form['address'] = array(
'#type' => 'uc_addresses_address',
'#uc_addresses_required' => array(
'company' => TRUE,
'first_name' => FALSE,
'last_name' => FALSE,
);
);
// Example 3: make all address fields non-required, even
// fields that were added "manually".
// This will make the manually added "subfield" be
// non-required, even if it is set to be required.
$form['address'] = array(
'#type' => 'uc_addresses_address',
'#uc_addresses_required' => FALSE,
'subfield' => array(
'#type' => 'textfield',
'#title' => t('Subject'),
'#required' => TRUE, // Will be overridden by #uc_addresses_required in this example.
);
);
#key_prefix
Description: Prefixes the name of an address field. For example, if set to "delivery", all address fields will be prefixed with "delivery_". So instead of "first_name", "last_name", "company", etc. you will get "delivery_first_name", "delivery_last_name", "delivery_company", etc. This is needed for integration with Ubercart, which expects to have the address field names prefixed at checkout.
Values: String. Most used are "delivery" and "billing".
Usage example:
// Prefix address fields with "delivery_".
$form['address'] = array(
'#type' => 'uc_addresses_address',
'#key_prefix' => 'delivery',
);
// After the uc_addresses_address form element is processed,
// it will look something like this:
$form['address'] = array(
'#type' => 'uc_addresses_address',
'#uc_addresses_address' => (...),
'#uc_addresses_context' => 'checkout_form',
'#key_prefix' => 'delivery',
(...),
'#uc_addresses_required' => TRUE,
'#name' => 'panes[delivery][delivery]',
'#id' => 'edit-panes-delivery-delivery',
'#value' => '',
'delivery_first_name' => array(...),
'delivery_last_name' => array(...),
'delivery_phone' => array(...),
'delivery_company' => array(...),
'delivery_street1' => array(...),
'delivery_street2' => array(...),
'delivery_city' => array(...),
'delivery_country' => array(...),
'delivery_zone' => array(...),
'delivery_postal_code' => array(...),
);
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion