Visualizing App Data with Cards

Introduction

App Cards framework for Apps allows for rendering various UI layouts based on “templates” (which we will define shortly) and the data used to populate the templates. When rendered, the data is merged into the “template” and the end result of it is a fully rendered “App Card”.

What is an “App Card Template”?

At the heart of any App Card is the “template.” A Template is a markup that defines how the data is arranged on the rendered card. Visually, a template looks a lot like XML, but an App Card template is more strictly defined (more about that later).

Let's start with a very simple App Card template:

<Card title="Customer Info">
	<StringValue dataSource="customer.firstName" label="First Name" />
	<StringValue dataSource="customer.lastName" label="Last Name" />
</Card>

In this example, we use specialized markup elements (called “components”) to display data, text, and arrange other components the card. Each component has a set of parameters (sometimes referred to as “props”, short for “properties”) that modify the component look, feel and/or behavior. In most cases, the parameters are optional. For complete reference, see Card component reference.

You may notice that the template does not give instructions on the card size, shape, or look. This is because all those parameters are determined by the “host application” (i.e., the application displaying the card). The same template may produce different UI depending on the “host application” - for example, this is how the above template looks in Agent Desktop and Chat.

What are the “components”?

Components are the building blocks of a template. In the template, they look like XML elements (e.g., <StringValue ... />). Components have parameters (often called “attributes” or “props”) that may change the way the component looks and/or behaves. Most of the parameters are optional and are only needed if you’d like to customize the standard look and behavior. If you don’t specify any optional parameters, the resulting component will have Gladly's “default” native look and feel.

We build templates by combining different components and “connecting” them to the data if necessary. “Connecting” means that we specify what particular data attribute the component should work with. In the above example, we did it by selecting the component “data source”: <StringValue dataSource="customer.firstName"... />.

Not all components have to be “connected” to the data. Those that have to be “connected” are:

• Data value components

• Iterators

Connecting components with the data

Data Context and Scoping

Each component is rendered within some “data context” (aka “scope”) - this context always exists whether the component uses it or not. By default, the data context/scope is determined by its place in the component hierarchy:

• Components that are not nested in a list are scoped to the top-level data object (as received from the GraphQL query)

• Components that are children of a list iterator are scoped to the current element of the nearest enclosing iterator. They also have access to the index of that element in the list

Example of scoping:

<StringValue dataSource="..." />      <!-- this component is scoped to the top-level data object `__root` -->

<List dataSource="orders">            <!-- this list iterator is also scoped to the top-level `__root`    -->          
	<DateTime dataSource="..." />     <!-- this one is scoped to orders[x] and has access to `x` as `__index` -->
	<List dataSource="items">         <!-- and this list, too - it iterates over orders[x].items         -->
		<DateTime dataSource="..." /> <!-- this one is scoped to order[x].items[y] and has access to `y` -->
	</List>
</List>

Data-bound Components

“Data-bound” components are the components that are directly linked to a particular data attribute. Only the following components can be data-bound:

• Data Values

• List iterators

• Image

The following components may use the underlying data for display value interpolation (see 7. Appendix B. Data Interpolation syntax - abbreviated guide ), even though they are not directly “bound” to one data element:

• Text component may display a mix of static text and data

• Containers with headings may use the underlying data for interpolating the heading (title) - for example, “3 Returns”

• Formula component

Data Binding Expressions

Components can access the underlying data context by using “data binding expressions”. Data binding expression is a string that gets evaluated and resolves to a particular attribute within the data context.

Data binding expressions may be used in several places:

• When a component needs to specify or override its default data context explicitly. Example: A list iterator must always specify which array it iterates over.

• When the output value, text, or component heading uses interpolation

When referencing the data attributes, data binding expressions use “dot notation” for objects and “indexer notation” for arrays, for example:

/* 
	Given the data context: 

	{ 
		agent: { 
			name: 'Michelle Smith', 
			roles: ['agent', 'superuser'] 
		} 
	}
*/

agent.name => 'Michelle Smith'
agent.roles[0] => 'agent'

Each component also has access to these “special variables” that can be used in the interpolation expressions just like a regular data attribute:

• __data - current data context/scope. In the above example, agent.name and __data.agent.name are equivalent. This property comes in handy when the data element (to which component is bound) is an array or scalar value.

• __root - top-level data object (as received from GraphQL)

• __parent - “parent” scope of the list element. Available only when the component is a child of a list iterator.

• __index - available when the component is a child of a list iterator. Provides the current iterator index in the array.

Components breakdown and descriptions

All available components can be divided into the following groups:

• Data value components that display data (e.g. StringValue in the above example) or text.

• Containers that group and organize the data.

• Layout components that help with laying out data side-by-side or sequentially.

• Decorators (dividers, spacers, etc.) that enhance the look and feel of the card.

• Iterators that can loop through an array of data and render each element in a certain way.

Data Value components

Data Value components are the workhorse of the App Card framework. They are responsible for formatting and displaying the data in the card. The following Data Value components are supported:

• Value components of the following types:

  • StringValue

  • NumericValue

  • CurrencyValue

  • DateTimeValue

  • BooleanValue

• Formula - for displaying calculated values (it allows for simple math, basic string operations, etc.)

• Image - for displaying images. The image URL may come from the data, or it can be static/hardcoded.

• Link - for displaying links (e.g., “See return in Loop”)

• Text - for displaying blocks of static text that can be mixed with the data elements to produce a customizable dynamic output like “You have until [XYZ] to return the item”

Here’s an example of what data value components look like out of the box:

<Card>
  <StringValue dataSource="name" label="Dog name" />
  <DateTimeValue dataSource="date" label="Favorite date" />
  <CurrencyValue dataSource="price" label="Price" />
  <NumericValue dataSource="quantity" label="Quantity" />
  <Formula label="Grand total">{{ (price * quantity)| formatCurrency }}</Formula>
  <BooleanValue dataSource="active" label="Active client" />
  <Link dataSource="link_url" linkText="See shipment in OMS" label="Tracking link" />
  <Link dataSource="link_url" linkText="See shipment in OMS (without label)" />
  <Text>Lorem Ipsum is simply dummy text of the printing and typesetting industry.</Text>
  <Image dataSource="image_url" size="medium" mode="fill" />
</Card>

Container components

Container components (or “containers”) help organize components inside the card. The containers are:

• Block - the most basic type of container. For those familiar with HTML, it acts a lot like <div></div> element - it may have visual styling, like a border or padding, but does not have any functional load. It does not do anything except for providing a wrapper and a “frame” as needed.

• Section - used for grouping semantically related data. Sections may have a heading (aka “title”) and may optionally collapse/expand, which comes in handy when dealing with a lot of data. Just like Blocks, they also may have visual styling.

• Drawer - this is a combination of a “static” part (similar to a Block) and the “expandable” part. This is commonly used in Agent Desktop.

Drawer function requirement

In order for Drawer to function correctly, it must have both <Fixed> and <Expandable> parts, and both parts must contain some renderable data or text.

Here is an example of what Drawers and Section would look like:

<Card>
  <Drawer>
    <Fixed>
      <Text>This is a "closed" Drawer</Text>
    </Fixed>
    <Expandable>
      <StringValue dataSource="name" />
    </Expandable>
  </Drawer>
  <Drawer>
    <Fixed>
      <Text>This is an "open" Drawer</Text>
    </Fixed>
    <Expandable>
      <StringValue dataSource="name" label="Dog name" />
      <CurrencyValue dataSource="price" label="Item price" />
      <Section title="Details">
        <DateTimeValue dataSource="date" label="Favorite date" />
        <NumericValue dataSource="quantity" label="Quantity" />
      </Section>
    </Expandable>
  </Drawer>
</Card>

Iterators

Iterators loop through an array of data, rendering each array element similarly. Currently, the template language supports one “iterator” component:

• List - is used to iterate over an array of data objects and render each object according to a certain layout. A common iterator use case would be rendering a list of Customers or items within an order.

Here is an example of how List is used:

a. Source data

{
	orders: [
		{
			id: '12345',
			date_created: '2024-10-03T22:34:11.266Z',
			total_amt: 123.45
		},
		{
			id: '54321',
			date_created: '2024-10-03T22:34:11.266Z',
			total_amt: 54.32
		}
	]
}

b. Template

<Card>
	<List dataSource="orders" separateItems="yes">
		<StringValue dataSource="id" label="Order ID" />
		<DateTimeValue dataSource="date_created" label="Placed on" />
		<CurrencyValue dataSource="total_amt" label="Total amount" />
	</List>
</Card>

c. Resulting card

Layout components

Layout components help with displaying content side-by-side. Supported layout components are:

• Column – Just like a column in the newspaper or in many popular text editors, it is a vertical block that takes a part of the total card width and can be filled with any content: text, images, data values, etc.

• ColumnGroup – Columns are organized in “groups”. Columns must be nested under the ColumnGroup that manages the column width and other internal parameters.

Here is an example of how columns are used (using the data from the previous example):

<Card>
  <ColumnGroup columnSpacing="medium">
    <Column width="18%" verticalAlignment="middle">
      <Image defaultUrl="<https://files.catbox.moe/ma5oz8.jpg>" size="auto" mode="fill" shape="circle" />
    </Column>
    <Column width="stretch">
      <StringValue dataSource="orders[0].id" label="Order ID" />
      <DateTimeValue dataSource="orders[0].date_created" label="Placed on" />
      <CurrencyValue dataSource="orders[0].total_amt" label="Total amount" />
    </Column>
  </ColumnGroup>
</Card>

How do I know which component to use?

There is no single right or wrong answer, but here are some guidelines that will help you keep your templates more readable and maintainable. Let’s start by going over what each component can and cannot do:

• Data Values (StringValue, NumericValue etc.) are great when you need to format the data and display it as-is. They support a variety of common number, date, and time formats.

  • Data Value components follow a strict layout: they take the width of the entire container (column, block or card) and can be displayed either side-by-side (label -> value) or stacked (label over value)

  • Data Values may have no label at all (just the value)

Use Data Values to display simple data

Use Data Values when you need to display simple data and “key → value” layout is OK.

• In contrast, Text is a free-flowing block of text that allows basics formatting (like bold, underline etc.) You can insert data into the text via interpolation. See Appendix B. Data Interpolation syntax - abbreviated guide for more details.

• Text is considered a “block”, which means:

  • Text component cannot be nested inside another Text.

  • Text blocks cannot be “concatenated” by placing one immediately after the other.

• Like Data Values, Text takes the entire width of the card unless placed inside a Column.

Please note that Text do not support links. Also, Data Value components can't be nested inside a Text block.

Use Text to display informational messages

Use Text for displaying all sorts of informational messages that are not required to follow a strict key → value layout. Text may or may not include data, and can include as many data source variables as you need. (e.g. “Your order number {{ order_id }} shipped on {{ order_date }} and is expected to arrive within {{ delivery_speed }} of days”)

Formula is used for displaying key → value data when the value needs to be calculated. It combines the flexibility of Text with strict layout of Data Values. Please note that Formula does not support text formatting like Text does (bold, italic etc.)

As a rule of thumb, try to use the simplest component first, before opting for something more complicated.

Let’s look at some examples:

• <Formula>{{ someValue }}</Formula> works almost exactly the same as <StringValue dataSource="someValue" /> but the StringValue component is more explicit and it has more features - for example, it can display multi-line values that Formula component cannot.

• <Formula>{{ price|format_currency }}</Formula> in most cases is the same as <CurrencyValue dataSource="price" /> but CurrencyValue component offers more formatting options and can handle things like currency code coming from the data, fallback currency code, locales etc. that will be difficult to do with Formula.

Survival Guide: What if I need to … ?

Can I display just the value (without label)?

Yes, you can. All you need to do is omit the label attribute:

<Card>
  <StringValue dataSource="value" label="Label" />
  <StringValue dataSource="value" />
</Card>

This will work for all Data Value components (except for Image and Text - they do not have labels)

What if I need to render something only when …?

Often, it is necessary to skip some parts of the template based on the underlying data. For example, it does not make sense to render “Shipping information” if the order has not shipped yet. The App Card framework allows you to render components “conditionally” — that is, based on the results of a “conditional expression.”

What is the “conditional expression”?

Every component (except for Card) has a special attribute when that allows you to specify an expression. If the expression evaluates to “true” (or “truthy” in JavaScript), then the component is rendered. Otherwise, it is skipped.

For example, you want to display a certain text only if the item price is below $5. You can do it with a conditional expression like this:

<Card>
	<Text when="price < 5.0">This is a real bargain!</Text>
</Card>

In the above example, “price < 5.0” is called a “conditional expression”. Conditional expressions have to follow certain syntax (see below), and they are evaluated based on the data available to the component.

Conditional expression cheat sheet

The following is a list of the commonly used conditional expressions.

Logical operators (”and”, “or”, “not”) are CASE SENSITIVE. That is, they MUST be typed in LOWER CASE

Expressions that only work on data variables:

Parens () are allowed and are evaluated according to the common rules (i.e., the expression in parens is evaluated first, etc.)

Can I just add some plain text?

No, you cannot just add plain text anywhere (like you would with HTML). All static text must be wrapped in <Text>...</Text>

Can I merge data with static text?

Yes, App Card templates allow you to interpolate (merge data with static text) in the following places:

• For components that have a title (Card, Section) - the title attribute allows for interpolation

• Text within the Text component can use interpolation

• Content of the Formula component can use interpolation

To insert a data value into some static text, you would usually wrap the value in {{ ... }} delimiters:. Below are sample data, template, and the output:

Sample data

{
	price: 12.95,
	variants: [
		{ color: 'red', sku: 12345 },
		{ color: 'yellow', sku: 54321 }
	]
}

Sample template

<Text>Price is {{ price }}</Text>
<Text>First color is {{ variants[0].color }}</Text>
<Text>First SKU is {{ variants[0].sku }}</Text>

Output

Price is 12.95
First color is red
First SKU is 12345

Interpolation syntax also allows for some basic math calculations and logic expressions (if-else). It also gives you access to some formatting and string manipulation functions. For more details, see Appendix B. Data Interpolation syntax - abbreviated guide.

How do I display the order total amount (or calculate something else)?

If you need to display a calculated value, you would use data interpolation and do the math (or whatever calculation you need) inside the interpolated fragment. Below are sample data, template, and the output:

Sample data

{
	order_id: 12345,
	subtotal: 123.45,
	tax: 11.95,
	shipping: 6.95
}

Sample template

<StringValue label="Order ID" dataSource="order_id" />
<Formula label="Order total">
	{{ subtotal + tax + shipping }}
</Formula>

Output

Order ID              12345
Order total           142.35

Avoid calculations in the template

It’s best to avoid doing calculations in the template. The data should have all necessary values already calculated.

More on the data interpolation is here: Appendix B. Data Interpolation syntax - abbreviated guide.

How do I align my values to the …?

Data Values can align the values to the left (default), to the right, or the center:

Sample data

{
	name: 'Tado'
}

Sample template

<StringValue dataSource="name" label="Default" />
<StringValue 
	dataSource="name" 
	label="Left" valueAlignment="left" />
<StringValue 
	dataSource="name" 
	label="Center" valueAlignment="center" />
<StringValue 
	dataSource="name" 
	label="Right" valueAlignment="right" />

Output

Default       Tado
Left          Tado
Center                Tado
Right                         Tado

The same approach works for other Data Value components (NumericValue, DateTimeValue, CurrencyValue, BooleanValue and Link)

How do I make my values bolder or lighter (font weight)?

All Data Value components have an attribute called valueFontWeight which can take the following values (in the order of increasing boldness):

• "light" - very light text, weight 300.

• "regular" - default text, weight 400. If you don’t specify the weight, this value will be used.

• "meduim" - slightly darker text, weight 500. Used to emphasize the text or data value.

• "semiBold" - dark and heavy text, typically used in headers. Weight 600.

• "bold" - heaviest weight, 700. Should be used sparingly.

Most of the time, the values that need to draw attention would use medium and “bold” values (like grand totals etc.) would use semiBold. It is uncommon to use bold for anything other than major headings.

Example of the different font weights:

<CurrencyValue dataSource="subtotal" label="Subtotal" valueForntWeight="medium"/>
<CurrencyValue dataSource="tax" label="Tax" valueForntWeight="medium"/>
<Formula label="Grand Total" valueForntWeight="semiBold">
	{{ (subtotal + tax) | format_currency }}
</Formula>

i. How do I format dates and times?

• Formatting codes for <DateTimeValue>

  In order to change the way <DateTimeValue> displays the date and time, you need to give it a formatting mask (using format attribute). Under the hood, we use day.js to format dates. Here is a list of the formatting codes:

List of all available date formats

<!-- This is an example of using a custom date format -->
<DateTimeValue dataSource="..." format="MMMM D, YYYY" />    =>  "February 3, 2024"

For more information, see https://day.js.org/docs/en/display/format.

• Formatting dates inside interpolation fragments {{ … }}

  If you need to format the date inside an interpolation fragment, you should use date filter and give it the format you want:

  <!-- Example of formatting the date inside interpolated fragment -->
  <Text>The order was placed on {{ order_date | date('F j, Y') }}</Text>  => "February 3, 2024" 
  

  See https://www.php.net/manual/en/datetime.format.php for the list of formatting codes (you may need to scroll down a bit).

How do I format currency (money)?

• Formatting currency (money) with <CurrencyValue>

  By default, <CurrencyValue> component displays money according to the US standard. If that is what you want, then you don’t need to do anything special - just use <CurrencyValue> component as-is.

  In some cases, you may want to display money in the “accounting” format (that is, negative amount is in parens - e.g. “$(12.95)” instead of “-$12.95”). To do that, set negativeValueStyle attribute to “accounting”.

  <!-- Default format -->
  <CurrencyValue dataSource="..." label="Order amount" />                                         => "Order amount    $12.95"
  
  <!-- Non-USD currency, the currency code comes in `order_currency` field -->
  <CurrencyValue dataSource="..." curencyCodeSource="order_currency" label="Order amount" />      => "Order amount    GBP 12.95"
  
  <!-- Non-USD currency, hardcoded currency code -->
  <CurrencyValue dataSource="..." defaultCodeSource="GBP" label="Order amount" />                 => "Order amount    GBP 12.95"
  

For the complete list of the component attributes, see Card component reference.

• Formatting currency inside interpolation fragments {{ … }}

  Use format_currency filter to format currency inside an interpolated fragment:

  <Text>Total amount is {{ (subtotal + tax) | format_currency }}</Text>
  

Appendix

• Appendix A. Component reference

• Appendix B. Data Interpolation syntax - abbreviate

• Template syntax limitations. How templates differ from the standard XML

{
	customer: {
		first_name: 'Arthur',
		last_name: 'Lula',
		children: [
			{ name: 'Maria' age: 8 }, 
			{ name: 'Zach', age: 13 }
		]
	},
	ltv: 1234.56,
	favorite_sports: ['Chess', 'Ice skating', 'Boxing']
}

{{ customer.last_name }}          =>  'Lula'
{{ customer.children[0].name }}   =>  'Maria'
{{ ltv }}                         =>  1234.56
{{ favorite_sports[2] }}          =>  'Boxing'

{
	subtotal: 1234.56,
	tax_rate: 9.98,
	shipping: 6.95,
}

{{ subtotal * (1 + tax_rate/100) + shipping }} => Total amount with tax,
                                                  the tax amount is
                                                  calculated based on 
                                                  rate and the subtotal

{{ <expression> ? <value if true> : <value if false> }}

OR the "shorthand version":

{{ <expression> ? <value if true> }}     => same as {{ <expression> ? <value if true> : '' }}

OR another "shorthand version":

{{ <expression> ?? <value if false> }}   => same as {{ <expression> ? <value of the expression> : <value if false> }}

{
	items: [...]
}

<Text>We have {{ items|length }} item{{ not (items|length == 1) ? 's': '' }}</Text>