The uc_addresses_address form element

Last updated on
9 May 2017

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.

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

Page status: No known problems

You can: