Chooser Pattern

Chooser is a hypermedia control that presents one or more choices for clients to select. A Chooser has two types that determine how many selections are possible. The types are patterned after HTML’s selection <input> formats. The radio type accepts a single selection. The checks type can accept multiple choices.

A client examines the Description resource of each Choice and makes their selection by triggering the Choice action resource. The result of the POST to choice changes the state of the Choice. If the Choice’s checked property was false, it becomes true after the action. If the Choice’s checked property was true then it changes to false after the action.

The Choice’s state is changed on the action, as is the state of the Chooser overall. For a radio chooser, selecting a choice deselects a previously-selected choice. For a checks chooser, the overall chooser’s state may change, depending on the business rules the chooser is representing. For this reason, the Location response header from choice actions points to the Chooser resource so that the client can fetch the overall chooser state again.

Chooser Resource

Profile: <http://level3.rest/patterns/chooser#chooser-resource>

The Choice resource presents either the Info or Nexus profile. It has the following state:

Property Purpose
type radio for single selections, checks for 0 or more selections.

If the Chooser resource presents the Nexus profile, then it can be deleted with a DELETE operation. The Choice resources are deleted as well. The Description resources may not be part of the domain, and if they are not, then they are not deleted.

choice

rel="http://level3.rest/patterns/chooser#choice"

A Chooser resource has 0 or more choice links pointing to Choice resources in its list. The ordering of the links is intentional, meaning they should be considered the presentation order of the choices. The HTTP specifications require header order to be maintained so clients can expect consistent link order.

Choice Resource

Profile: <http://level3.rest/patterns/chooser#choice-resource>

The Choice resource presents the Action profile. It has the following state:

Property Purpose
checked Indicates the selected state of the choice with true or false.

choice-for

rel="http://level3.rest/patterns/chooser#choice-for"

This link points to the Chooser to which this Choice belongs.

description

rel="http://level3.rest/patterns/chooser#description"

This link points to a Description that describes this Choice. This relation is similar to the registered IANA relation “describedby.”

Description Resource

Describes the Choice. Its profile is undefined as it could point to any resource in any domain. As an example, if the Chooser selects addresses, this Description resource links to an entry in an address list. Because of this, the Description resource has no choice-specific links or profile. It is unaware that it participates in a Chooser pattern.

Specifications

HTML 5.2: Input Element

HTTP/1.1 Message Syntax and Routing: RFC 7230

Protocol for Web Description Resources: POWDER


Copyright © 2019 Matt Bishop
Creative Commons Licence
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.