Card Choices Component

SAIL Design System guidance available for Card Layout Reduce clutter and bring balance to your interface designs with cards. Learn how to use cards to organize content in a way that is easier for users to understand and navigate.

Function

a!cardChoiceField( label, labelPosition, instructions, helpTooltip, data, sort, cardTemplate, value, saveInto, maxSelections, align, showShadow, required, requiredMessage, disabled, validations, validationGroup, showWhen, accessibilityText, spacing, marginAbove, marginBelow )

Displays a set of cards from which the user may select one or many cards and saves a value based on the selected choice. The card choices component allows you to create a set of choices using data from records, entities, data subsets, a dictionary, a list of data, or a list of mappings.

There are three card choices templates for you to choose from:

• Tiles template
• Bars (justified text) template
• Bars (stacked text) template

See also: Cards Layout

Parameters

Usage considerations

Mobile support

The card choices component is supported on mobile versions starting with 22.1.

Displaying data and card choices

• Use the sort parameter to change the display order of your card choices.
  • If you're using a query or a data subset, any logic defined in the card choices's sort parameter will evaluate after the query or data subset sorting. Sorting for queries and data subsets happen when the data is initially retrieved.
• Card choices automatically arrange themselves to take up as many rows as needed to best fit the width of the screen. To control the number of cards in each row, put the card choices component in a columns layout with a specified width.

Using icons and text

• Neither icons, primary text, nor secondary text are required. Templates will reallocate the space of any missing value.
  • For a uniform interface, make sure that you have consistent values for the icon, primary text, and secondary text fields for all card choices on an interface. For example, all card choices should include primary text, or none of them should.
• If you're using data from records or entities as your source, you can add an icon field in your record type or CDT to easily display icons in your card choices.
• Both the primary and secondary texts will truncate after two lines each. The tooltip shows the full text.
  • Spacing and truncation look different in the bars (justified text) template. To ensure that all your text has enough space to show properly, keep your secondary text short when using this template.

Choosing your card choices component's data source

The card choices component provides four options to easily access your data:

• A record type
• An expression
• A rule
• A variable

These four options allow you to access your data wherever it is, using one of the following methods:

• A record type, accessing your data using type reference or a!recordData().
• A query, using a!queryEntity().
• A data subset.
• A list of map or dictionary.
• A list of data.

Data in a map, dictionary, data subset, or list of data

To access your data in a map, dictionary, or list of data, you can select either Expression, Variable, or Rule as the data source for your card choices component.

Using Expressions, you can create a map, dictionary, or list of data directly in the card choice field data parameter.

Using Variable, you can create a map, dictionary, or list of data in a local variable or rule input and call it into the card choices data parameter.

Using Rule, you can access a map, dictionary, data subset, or list of data that is stored in an expression rule and call the expression rule into the card choices data parameter.

Examples

Using record data as the card choices data source

Copy and paste an example into an Appian Expression Editor to experiment with it.

Record type object references are specific to each environment. If you copy and paste these examples into your interface, they will not evaluate. Use them as a reference only.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
a!localVariables(
  local!save,
  {
    a!sectionLayout(
      label: "Select your company's industry",
      labelSize: "LARGE",
      contents: {
        a!cardChoiceField(
          label: "Select your company's industry",
          labelPosition: "COLLAPSED",
          instructions: "Don't see your company's industry listed? Contact our team to add your industry to our community!",
          data: 'recordType!{41134583-1730-42d9-a32f-be722d9b47b9}Industries',
          sort: {
            a!sortInfo(
              field: 'recordType!{41134583-1730-42d9-a32f-be722d9b47b9}Industries.fields.{4edb6e00-5b39-469f-9527-a5c5019bc1a4}industrytype',
              ascending: true
            )
          },
          cardTemplate: a!cardTemplateBarTextStacked(
            id: fv!data['recordType!{41134583-1730-42d9-a32f-be722d9b47b9}Industries.fields.{3cae152b-3f67-4736-91ef-569469ac657c}id'],
            primaryText: fv!data['recordType!{41134583-1730-42d9-a32f-be722d9b47b9}Industries.fields.{4edb6e00-5b39-469f-9527-a5c5019bc1a4}industrytype'],
            secondaryText: fv!data['recordType!{41134583-1730-42d9-a32f-be722d9b47b9}Industries.fields.{e30ac296-a285-4490-aab4-890fc4346e89}description'],
            icon: fv!data['recordType!{41134583-1730-42d9-a32f-be722d9b47b9}Industries.fields.{0fcc2280-7bef-4205-8ed4-aee913b57b7a}icon'],
            iconAltText: fv!data['recordType!{41134583-1730-42d9-a32f-be722d9b47b9}Industries.fields.{70404539-ab39-42cf-b380-197bb1ae3b73}iconalttext']
          ),
          value: local!save,
          saveInto: local!save,
          maxSelections: 1,
          align: "START",
          showShadow: false,
          validations: {}
        )
      }
    )
  }
)

Displays the following:

Using a query as the card choices data source

Copy and paste an example into an Appian Expression Editor to experiment with it.

This example references specific fields in a CDT that you need to replace with your own fields. If you copy and paste this example into your interface, the fields won't evaluate. Use the example as a reference only.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
a!localVariables(
  local!save,
  {
    a!sectionLayout(
      label: "Select your work location",
      labelSize: "LARGE",
      contents: {
        a!cardChoiceField(
          label: "Select your work location",
          labelPosition: "COLLAPSED",
          data: a!queryEntity(
            entity: cons!WORK_INFO_ENTITY,
            query: a!query(
              selection: a!querySelection(
                columns: {
                  a!queryColumn(field: "id"),
                  a!queryColumn(field: "workLocation"),
                  a!queryColumn(field: "workLocationDescription"),
                  a!queryColumn(field: "locationIcon"),
                  a!queryColumn(field: "locationIconAltText")
                }
              ),
              pagingInfo: a!pagingInfo(startIndex: 1, batchSize: - 1)
            ),
            fetchTotalCount: true
          ),
          cardTemplate: a!cardTemplateTile(
            id: fv!data.id,
            primaryText: fv!data.workLocation,
            secondaryText: fv!data.workLocationDescription,
            icon: fv!data.locationIcon,
            iconAltText: fv!data.locationIconAltText
          ),
          value: local!save,
          saveInto: local!save,
          maxSelections: 1,
          validations: {}
        )
      }
    )
  }
)

Displays the following:

Using a map as the card choices data source

Using a map directly in the data source

This example shows how to use a map of data directly in the data parameter of the card choices component.

You can achieve a similar result to the example above using either a local variable, rule input, or expression rule.

Use the interactive editor below to test out the example code.

If you copy and paste the above expression into an interface, you'll see on the Data tab that Expression is selected for the Data Source in the design mode component configuration pane.

Using a map with a local variable

To achieve a similar configuration as above with a local variable from design mode:

1. Drag and drop the card choices component onto your interface.
2. Create a local variable and add a map of your data in the local variable.
3. In the component configuration pane, go to the Data tab.
4. For Data Source, select Variable.
5. Select the local variable from the dropdown.
6. Configure the card choices parameters according to the fields present in your data.

Using a map with a rule input

To achieve a similar configuration as above with a rule input from design mode:

1. Drag and drop the card choices component onto your interface.
2. Add a rule input of type Map and click Array (multiple values).
3. In the interface header, click TEST.
4. For Value, add a map of your data.

5. Click TEST.

   Tip:  To save the value to reuse later, click SAVE AS NEW SCENARIO to save it as a test scenario.

6. In the component configuration pane, go to the Data tab.
7. For Data Source, select Variable.
8. Select your rule input from the dropdown.
9. Configure the card choices parameters according to the fields present in your data.

Using a map with an expression rule

To achieve a similar configuration as above with an expression rule from design mode:

1. Drag and drop the card choices component onto your interface.
2. In the component configuration pane, go to the Data tab.
3. For Data Source, select Rule.
4. Select an expression rule that contains a map of your data.
5. Configure the card choices parameters according to the fields present in your data.

Feature compatibility

Related recipes

The following recipes include usage of the Card Choices Component.

• Cards as Choices Pattern (Card Choices, Rich Text):

  Use this pattern to display sets of choices that are quick and easy to navigate.

Feedback