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 )

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:

• Card Choices Tile Template
• Card Choices Bar Template
• Card Choices Bar (Text Stacked) Template

See also: Cards Layout

Parameters

Usage considerations

Unsupported capabilities

• The card choices component is not supported on mobile versions prior to 21.4.
• If using the card choices component in a portal, you cannot use a record type as the data source.

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 card choices bars 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().
  • Note: Unless you are designing a portal. You cannot use a record type for your data source in a portal.
• 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 references 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

Use the interactive editor below to test out your code:

More map configurations

The example above shows how to use a map of data in the card choices component data parameter. If you copy and paste the expression into an interface, you'll see that Expression is selected for the Data Source in Design Mode. If you're using Expression Mode, you can write your expression as you normally would without selecting a data source from Design Mode.

You can achieve a similar result to the example above using either of the Variable or Rule data source configurations.

If you want to use a map with a local variable:

1. Drag and drop the card choices component onto your interface.
2. From Expression Mode, create a local variable.
3. Add a map of your data in the local variable.
4. From Design Mode, go to Data Source and select Variable.
5. Select your local variable from the dropdown.
6. Configure the card choices parameters according to the fields present in your data.

Go ahead and try out using a map with local variables in the interactive expression editor above.

If you want to use a map with a rule input:

1. Drag and drop the card choices component onto your interface.
2. From Design Mode, add a rule input of type Map and click Array (multiple values).
3. Click Test.
4. In Expression, add a map of your data.
5. Click Set as default test values, then click TEST INTERFACE.
6. From Design Mode, go to Data Source and select Variable.
7. Select your rule input from the dropdown.
8. Configure the card choices parameters according to the fields present in your data.

If you want to use a map with an expression rule:

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

Feature compatibility

Related Patterns

The following patterns 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