How to setup card preferences that change the appearance

This article will walk you through the steps to add appearance preferences to a Card in Digital Assistant.

As a basis for this article, we will use the employee list card created in the endlessly scrolling card guide, so please follow that guide first and return here when you have the functioning card.

Create a settings modal

First create a file customize.form in the card folder (depending on the template which was used to create the card, customize.form may already exist).

Enter the Designer for customize.form, and add a toggle element from the elements tab. Set the Label to 'Show Avatars', Name to showAvatars, and value to true. Verify the configuration is correct by opening the Schema tab, and checking that it matches the following:

customize.form schema

Next, enable customization for the Card by entering the designer for default.card, selecting the title element and checking the Customizable option:

enable customization

Read the setting value from a Connector

Because this Card uses a separate item.card to render each item in the list, we need to add some code to the connector to read this setting value and provide it to each item, so that we can then read it from the returned item, within item.card.

Navigate to Development → Manage Spaces → Global → Connectors → employee-list-connector, Edit employee.js, and add the following line to the convert_item function:

item.showAvatar = activity.Context.ContentItemSettings.showAvatars;

We can access the values of our settings from customize.form at the key activity.Context.ContentItemSettings. The name of the key that contains the setting value for a certain element, will match the Name field of that element in the form.

So, in this case, we access showAvatars, which will contain a boolean true/false value matching the current setting from the Card.

The entire function should then look like this:

function convert_item(_item) {
    var item = {};

    let id = _item.picture.large;
    id = id.substring(id.lastIndexOf("/") + 1); // extract id from image name
    item.id = id.substring(0, id.indexOf("."));

    item.title = _item.name.first + " " + _item.name.last;
    item.description = _item.email;
    item.picture = _item.picture.large;

    item.showAvatar = activity.Context.ContentItemSettings.showAvatars;

    return item;
}

For a complete copy of the Connector source code, see the Employee list with settings Connector repo.

Use the setting value in the Card

The last step is then to add markup to item.card to read this value. Navigate to Development → Manage Spaces → Global → Components → new-hires, enter the Designer for item.card, and replace the view markup for the main element with the following:

<div class="layout-horizontal layout-center">
  {% if showAvatar %}
      <iron-image src="{{ picture }}" style="width:60px; height:60px; background-color: lightgray;" sizing="cover" preload></iron-image>
  {% endif %}
  <div class="m">
    {{ title }}
  </div>
</div>

For a complete copy of the Card source code, see the New Hires with settings Card repo.

Using the custom settings form

We should now be able to see the following option on the Card in Now workplace:

card customize menu

Upon selecting this option, the customization form we created should now appear:

card customize form

After switching the toggle off and pressing _Ok_, the Card should reload without avatars present.

card without avatars