Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Selectors

Selectors

Selectors are a hypermedia control that change a resource's state. Selectors provide a list of predefined options that a shopper can choose from. Once a choice is made through the selector, the resource's state updates accordingly. Selectors are generally rendered on the UI as radio button groups, combo boxes, or check boxes.

With selectors, you can discover:
  • The options available for a resource.
  • The options already selected for a resource.
  • The selection-rule that determines how many options can be selected at once.
  • The links to make the selection.
Cortex selectors follow this format:

  • A name property that identifies which options the selector handles.

  • A selection-rule property that identifies the number of options that can be selected at once.

  • A choice link for options that can be selected.

  • A chosen link for options that are already selected.

Cortex choice and chosen follow this format:

  • A description link that links to a description of the option.

  • A selectaction link that when followed selects the option. The link appears only on choice resources as chosen resources are already selected.

Selector Example: Selecting a Billing Address

The billingaddressinfo resource contains a selector that allows shoppers to select their billing address for an order. The selector provides a list of addresses shoppers have previously saved to their account from which the shopper can choose from. The selector's type is elasticpath.controls.selector, which indicates the resource is a selector control: 
{
  "rel": "selector",
  "rev": "billingaddressinfo",  
  "type": "elasticpath.controls.selector",
  "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector",
  "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector"
}
Retrieving the selector returns the selector resource. In this example, there are two choice links, indicating two possible billing addresses can be selected. The selection-rule property is set to 1, so only one billing address can be selected at a time: 
{
  "self": {
    "type": "elasticpath.controls.selector",
    "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector",
    "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector",
    "max-age": 0
  },
  "name": "billing-address-selector",
  "selection-rule": "1",
  "links": [
    {
      "rel": "choice",
      "rev": "selector",
      "type": "elasticpath.collections.links",
      "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3=",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3="
    },
    {
      "rel": "choice",
      "rev": "selector",
      "type": "elasticpath.collections.links",
      "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ha4=",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ha4="      
    },
    {
      "rel": "billingaddressinfo",
      "rev": "selector",
      "type": "elasticpath.controls.info",
      "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo"
    }
  ]
}}
A choice resource has a description link which can be used the retrieve the resource that is being selected. The selectaction link is used to select the option: 
{
  "self": {
    "type": "elasticpath.collections.links",
    "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3=",
    "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3=",
    "max-age": 0
  },
  "links": [
    {
      "rel": "description",
      "type": "elasticpath.addresses.address",
      "uri": "/commerce-legacy/profiles/mobee/grd=/addresses/ga3=",
      "href": "http://api.elasticpath.net/cortex/profiles/mobee/grd=/addresses/ga3="
    },
    {
      "rel": "selectaction",
      "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3=",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3="
    },
    {
      "rel": "selector",
      "type": "elasticpath.controls.selector",
      "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector"
    }
  ]
}
The client application should construct a POST request without a request body and send it to the URL described by the action link. If the action succeeds, Cortex returns status code 200 OK and a Location header with a reference to the updated selector resource: 
POST /orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3=
Content-Type: application/json
200 OK
Location: http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector
The updated selector resource now shows that a link called chosen has replaced the choice link. This indicates the resource has been selected: 
{
  "self": {
    "type": "elasticpath.controls.selector",
    "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector",
    "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector",
    "max-age": 0
  },
  "name": "billing-address-selector",
  "selection-rule": "1",
  "links": [
    {
      "rel": "choice",
      "rev": "selector",
      "type": "elasticpath.collections.links",
      "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ha4=",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ha4="      
    },
    {
      "rel": "chosen",
      "rev": "selector",
      "type": "elasticpath.collections.links",
      "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3=",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3="
    }
    {
      "rel": "billingaddressinfo",
      "rev": "selector",
      "type": "elasticpath.controls.info",
      "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo"
    }
  ]
}

The chosen resource does not have a selectaction link because it is already selected:

{
  "self": {
    "type": "elasticpath.collections.links",
    "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3=",
    "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector/profiles/mobee/grd=/addresses/ga3=",
    "max-age": 0
  },
  "links": [
    {
      "rel": "description",
      "type": "elasticpath.addresses.address",
      "uri": "/commerce-legacy/profiles/mobee/grd=/addresses/ga3=",
      "href": "http://api.elasticpath.net/cortex/profiles/mobee/grd=/addresses/ga3="
    }
    {
      "rel": "selector",
      "type": "elasticpath.controls.selector",
      "uri": "/commerce-legacy/orders/mobee/mu3=/billingaddressinfo/selector",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3=/billingaddressinfo/selector"
    }
  ]
}