JSX For Adaptive Cards (ACX)
The Babel plugin for JSX Adaptive Cards allows you to use the familiar JSX syntax for authoring
your cards while leveraging the entire JavaScript language for organizing and generating cards. Build time notifications
of schema errors are output to the console with a pointer to the exact line that caused the error.
Similar to React JSX, JSX for Adaptive Cards allows authoring of cards using declarative
elements, components and expressions. It is then transpiled in to pure JavaScript to render valid Adaptive Card JSON. This plugin is compatible
with nearly all React JSX features and can live along side of projects that build using React. If you are familiar with React, you
already know how to use JSX for Adaptive cards.
Getting Started
Install babel dependencies:
npm i --save-dev @babel/core @babel/plugin-syntax-jsx @babel/plugin-transform-runtime @babel/preset-env
Install the JSX for Adaptive Cards plugin
npm i --save-dev bable-plugin-jsx-adaptive-cards
Then add it to the plugins array in your .babelrc
:
{
...
"plugins": ["babel-plugin-jsx-adaptive-cards", "@babel/plugin-syntax-jsx"]
...
}
JSX for Adaptive Cards can be used in projects that utilize JSX or TSX for React, InfernoJS or other
React-like libraries. To ensure these other processors do not process the Adaptive Card JSX, Babel 7+ must be used
since it allows overrides for pattern matching. The .acx
file extension
is recommended to separate jsx/tsx from Adaptive Card jsx.
Basic Syntax
JSX for Adaptive cards transforms the Adaptive Card Schema
into a terse and declarative XML syntax that's organized, easy to read, easy to maintain and easy to
reuse. The basic syntax is the foundation for creating your Adaptive Card using JSX. From there, you can expand into
components, expressions, fragments and many other tools.
Below are links to the original schema and a brief example of the ACX equivalent:
This is the root of your Adaptive Card
<card>
<body></body>
<actions></actions>
</card>
The child text node maps to the text
property.
<text>Polar bears have a conservation status of "Vulnerable"</text>
No children are allowed.
<image url="http://url.to/image.png"/>
All child elements are pushed into the items
array.
<container>
<text>Male polar bears weigh between 350-700kg.</text>
<text>Female polar bears come in at almost half the weight of males.</text>
...
</container>
Children are pushed into the items
array and must be <column>
elements
<columns>
<column></column>
...
</columns>
Allowed only as a child to the <columns>
element. Children are pushed into the items
array.
<column>
<text>The Brown Bear or Kodiak Bear is the closest relative to the Polar Bear</text>
<image url="https://en.wikipedia.org/wiki/Brown_bear#/media/File:2010-kodiak-bear-1.jpg"/>
...
</column>
All child elements are pushed into the facts
array and must be <fact/>
elements.
<facts>
<fact title="Male Polar Bear Weight" value="300-700kg"/>
<fact title="Female Polar Bear Weight" value="150-300kg"/>
...
</facts>
Allowed only as a child of the <facts>
element
<fact title="Polar Bear activity period" value="Year round"/>
All child elements are pushed into the images
array and must be <image/>
elements
<images>
<image url="https://en.wikipedia.org/wiki/Polar_bear#/media/File:Polarbear_spitzbergen_1.jpg"/>
<image url="https://en.wikipedia.org/wiki/Polar_bear#/media/File:Ursus_maritimus_us_fish.jpg"/>
...
</images>
The child text node maps to the url
property
<action type="openUrl">https:
Any expression or JSX element is allowed as a child and will map to the data
property
<action type="submit">
{{donationAmount: '$100', conservationGroup: 'Polar Bears International'}}
</action>
There must be a single child which is the <card>
element to show
<action type="showCard">
<card>
<body></body>
<actions></actions>
</card>
</action>
<input type="text" id="uniqueId"/>
<input type="number" id="uniqueId" min={10} max={9999} />
<input type="date" id="uniquerId"/>
<input type="time" id="uniqueUd"/>
<input type="toggle" id="uniqueId" valueOff="one-time" valueOn="monthly" title="Monthly Donation"/>
Children map to the choices
property and must be <choice>
elements
<input type="choiceSet" id="uniqueId">
<choice value="1">Polar Bears International</choice>
<choice value="2">Humane Society International</choice>
...
</input>
The child text node maps to the title
property
<choice value="1">Polar Bears International</choice>
Components
Like React Components, Adaptive Cards components come in 2 flavors: Pure Components and Stateful Components.
Pure Components
Pure Components are merely functions that accept a props
object and are expected to return an adaptive card or a fragment when called.
Pure Components are stateless, short lived and the easiest to consume.
The basic syntax for a Pure Component is:
export const PureComponent = props => {
return (
<card>
<body>
<text>Choose contribution amount</text>
</body>
<actions>
{...props.children}
</actions>
</card>
)
};
In the example above, the Pure Component renders it's children inside a <card>
element. Once the component is created,
Consuming it then looks like this:
import {PureComponent} from './components/pureComponent';
const renderMyCard = () => {
return (
<PureComponent>
{getActions()}
</PureComponent>
)
}
function getActions() {
'$5.00 $10.00 $100.00'
.split(' ')
.map(amount => <action type="submit" title={`Donate ${amount}`}>{amount}</action>);
}
Stateful Components
Stateful Components are a good choice when the encapsulation of functionality is important or more complex rules
need to be applied before the card is rendered. A Stateful Component has just 2 requirements:
render()
must be a callable function that returns a JSX Fragment or an Adaptive Card element of any kindprops
must be a member property and optionally can also be the single argument passed to the constructor.
The basic syntax for a Stateful Component is:
class StatefulComponent {
constructor(props) {
this.props = props;
}
render() {
return (
<card>
<body>
<text>Choose contribution amount</text>
</body>
<actions>
{...this.props.children}
</actions>
</card>
);
}
}
Consuming it is exactly the same as above
JSX Expressions
As seen in some of the syntax examples above, JSX expressions
can be used to call functions, evaluate conditionals or
use variables to generate dynamic content. Although powerful, it's important to understand some nuances when using them.
- Since expressions are evaluated at runtime, Adaptive Card JSX cannot be fully validated at compile time when an expression
is encountered. This can lead to an invalid JSON output. Unit testing is recommended for validation in these cases.
- Attribute values enclosed in quotes are always strings. Elements that require numbers or booleans as attribute values must
use JSX Expressions. e.g.
<input type="text" isMultiline={true}/>
. Refer to Microsoft's Adaptive Card Schema
for more details on which types are expected as attribute values.