Choice Table Element (choicetable)
choicetable element creates a structured, tabular format for presenting multiple option-action pairs in task topics. It's particularly suitable for documenting cases where, to complete a step, a reader must choose one option from several alternatives.
The choicetable element serves these primary purposes:
-
Organizing sets of mutually exclusive options in a clear, tabular format
Presenting structured option-action pairs for complex actions
Key characteristics of the choicetable element:
-
An optional element that must be added must appear within a
stepelement -
Must follow a command element (
cmd) that introduces the choices -
Requires at least one table row element (
chrow)
A choice table consists of these required and optional elements:
- Choice heading (
chhead) -
An optional container inside the
choicetableelement that provides specific heading text to override any default headings for thechoicetable, such as Option and Description. Choice heading contains two required elements:Choice option heading (
choptionhd) that provides a label for the options column, such as OptionChoice description heading (
chdeschd) that provides a label for the list of the descriptions column, such as Description
- Choice row (
chrow) -
A required container inside the
choicetableelement. Choice row contains a pair of required elements:-
Choice option (
choption) that describes an option a user could choose to accomplish a step. For example, the name of a check box or a specific condition starting with an If... clause. -
Choice description (
chdesc) that provides details about an option that a user chooses while performing a step. It may explain why the user would choose that option, provide actions to perform to complete the step, and contain the result of the choice when it is not immediately obvious.
-
Content within the choicetable element typically follows these output formatting rules:
-
Appears as a two-column table with the option column narrower than the description column
-
The option column often has emphasized text (bold) or background shading
-
Responsive design may stack columns vertically on narrow screens
Choice table best practices:
-
Use when any of the options triggers more than one action
-
Don't use when all of the options trigger only one action; use
choicesinstead -
Use instead of regular tables (
table) or unordered lists (ul) -
Use ordered list (
ol) or unordered list (ul) to document actions in the description column -
Don't use more than one
choicetablein a step
A choicetable element added to a task topic in the Heretto CCMS Content Editor. In this example, choice table headings are custom.
The DITA source of the choicetable element with the surrounding context of a task:
<task id="task-5043">
<title>Signing in to MobileView</title>
<shortdesc>Sign in to the MobileView application through the ClusterControl server.</shortdesc>
<prolog>
<author translate="no" type="creator">Heretto User <user@heretto.com></author>
</prolog>
<taskbody>
<context>
<p>MobileView requires authentication to ensure secure access to your ClusterControl server resources and project data. You can authenticate either through your MobileView-specific credentials or using your Windows account credentials through single sign-on.</p>
</context>
<steps>
<step>
<cmd>To open MobileView, click <menucascade><uicontrol>Start</uicontrol><uicontrol>All programs</uicontrol><uicontrol>Thunderbird MobileView</uicontrol></menucascade>.</cmd>
</step>
<step>
<cmd>Select your preferred authentication method:</cmd>
<choicetable>
<chhead>
<choptionhd>Authentication Method</choptionhd>
<chdeschd>Description and Requirements</chdeschd>
</chhead>
<chrow>
<choption>MobileView Credentials</choption>
<chdesc>
<ul>
<li>Enter your MobileView username and password in the respective fields</li>
<li>Requires a valid MobileView account created by your system administrator</li>
<li>Provides access based on your assigned MobileView permissions</li>
</ul>
</chdesc>
</chrow>
<chrow>
<choption><tm tmtype="reg">Windows</tm> Single Sign-On</choption>
<chdesc>
<ul>
<li>Click the <uicontrol>Windows</uicontrol> selection button</li>
<li>Requires active directory integration</li>
<li>Uses your current Windows login credentials</li>
<li>Ideal for enterprise environments with domain authentication</li>
</ul>
</chdesc>
</chrow>
</choicetable>
</step>
<step>
<cmd>In the directory field, enter the name or IP address of the main StormCluster ClusterControl server. Click <uicontrol>Sign In</uicontrol>.</cmd>
</step>
</steps>
</taskbody>
</task>