Giter Site home page Giter Site logo

babel-plugin-jsx-adaptive-cards's Introduction

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://polarbearsinternational.org/</action>

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

<choices id="uniqueId">
  <choice value="1">Polar Bears International</choice>
  <choice value="2">Humane Society International</choice>
  ...
</choices>

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.

babel-plugin-jsx-adaptive-cards's People

Contributors

justinwilaby avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

babel-plugin-jsx-adaptive-cards's Issues

Error on require of .acx

I am unsure how to use the card that is produced by this plugin.

In my index.js file I first tried to use

const acx = require ('./BasicCard.acx')
similar to this example

However I get a syntax error saying it is an unexpected token.
If I remove that require statement and just print the output of babel.transform of the .acx file the card looks fine. This lead me to believe the .acx file is not getting transpiled on require.

I thought perhaps I needed to include the transpiled file so I changed the require to
const acx = require("./test/test.js");

However I get an error "can't find module "../schema".

I am very unfamiliar with babel, so it's likely I have something setup wrong, but I am not sure.

Any help would be appreciated.
https://github.com/aes421/AdaptiveCardTest

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.