Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

babel-plugin-jsx-adaptive-cards

Package Overview
Dependencies
Maintainers
1
Versions
13
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

babel-plugin-jsx-adaptive-cards

A Babel plugin to transpile JSX to Adaptive Cards

  • 0.2.6
  • latest
  • Source
  • npm
  • Socket score

Version published
Maintainers
1
Created
Source

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:

AdaptiveCard

This is the root of your Adaptive Card

<card>
  <body></body>
  <actions></actions>
</card>

TextBlock

The child text node maps to the text property.

<text>Polar bears have a conservation status of "Vulnerable"</text>

Image

No children are allowed.

<image url="http://url.to/image.png"/>

Container

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>

ColumnSet

Children are pushed into the items array and must be <column> elements

<columns>
  <column></column>
  ...
</columns>

Column

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>

FactSet

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>

Fact

Allowed only as a child of the <facts> element

<fact title="Polar Bear activity period" value="Year round"/>

ImageSet

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>

Action.OpenUrl

The child text node maps to the url property

<action type="openUrl">https://polarbearsinternational.org/</action>

Action.Submit

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>

Action.ShowCard

There must be a single child which is the <card> element to show

<action type="showCard">
  <card>
    <body></body>
    <actions></actions>
  </card>
</action>

Input.Text

<input type="text" id="uniqueId"/>

Input.Number

<input type="number" id="uniqueId" min={10} max={9999} />

input.Date

<input type="date" id="uniquerId"/>

Input.Time

<input type="time" id="uniqueUd"/>

Input.Toggle

<input type="toggle" id="uniqueId" valueOff="one-time" valueOn="monthly" title="Monthly Donation"/>

Input.ChoiceSet

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>

Input.Choice

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:

  1. render() must be a callable function that returns a JSX Fragment or an Adaptive Card element of any kind
  2. props 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.

  1. 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.
  2. 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.

FAQs

Package last updated on 20 Apr 2018

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc