How to embed Cards

Digital Assistant cards can be embedded in websites outside of Digital Assistant. In this guide we're going to cover the process of embedding an 'Annual Leave Status' card onto an external website. Let's get started!

1. Add the script

Add the following HTML code inside the <body> or <head> tag of your web page:

<script src="https://<Your-server-address>/components/at-app/at-app-context.js" async></script>

This script does two things:

  • It ensures that the user is logged in to Digital Assistant and will redirect to the login screen otherwise.
  • It defines custom HTML elements that we're going to use in the next steps.

Make sure to replace <Your-server-address> with the IP or domain name as configured in your IIS. If your server is not publicly reachable, you may want to use a tunnel.

2. Choosing the Card to embed

To embed a card we need to know its unique name in our Workplace Manager. To find it, we will navigate to Content Manager → Assistant Cards using the top left navigation inside Workplace Manager. This should bring the list of cards available to us. Here we'll find and click on the 'Annual Leave Status' card which we want to embed:

Finding the card in the list of available cards

This will show the card details such as the title, template used, etc. What we're interested in is the Name attribute:

Name attribute of the card

We will use 'atm-pto-status' as the name of the card we want to embed later on.

3. Embedding the Card

Generally, Digital Assistant cards can be embedded in two ways: statically or dynamically. Bellow we're going to discuss both approaches.

A. Static embedding

Static embedding refers to having our cards defined at compile-time. This means that we specify all the cards we want to embed in our markup in advance.

To add the card we're going to use a custom HTML tag <include-card>. Copy paste the following inside the <body> tag:

<div class="card-container">
<include-card name="atm-pto-status"></include-card>

B. Dynamic embedding

Dynamic embedding can be useful in cases when it is not known which cards should be embedded in advance: e.g. user input is required. In that case we can embed Digital Assistant cards at run-time.

To demonstrate let's remove the <include-card> tag from our markup and for simplicity use 'card-container' as an Id:

<div id="card-container"></div>

Now we're going to embed 'Annual Leave Status' card dynamically on page load using a script:

<script type="text/javascript">
window.onload = function() {
var card = document.createElement('include-card');
card.setAttribute('name', 'atm-pto-status');
var container = document.getElementById('card-container');

This should have the same result as static embedding and would embed the card once the page is loaded.

4. Add styling

To allow full design flexibility Digital Assistant cards fill their container width and by default come without container styles (e.g. borders). We've put the card inside a <div> with class name 'card-container', and that's the class we want to style next.

.card-container {
position: relative;
width: 33%;
box-shadow: rgba(0, 0, 0, 0.098) 0px 2px 4px, rgba(0, 0, 0, 0.1) 0px 0px 3px;
border-radius: 4px;
margin: 25px 25px;

Place this either in your <head> or <body> tag on the page.

5. Toggling a more compact layout

If you want a card to show with a more compact mobile layout you can enable this for your each Card.

A. For static embed

Add the attribute layout="mobile" to the include-card tag, for example:

<include-card name="atm-pto-status" layout="mobile"></include-card>

B. For dynamic embed

If you want a card to show with a more compact mobile layout toggled on, you can add another line card.setAttribute('layout', 'mobile'); to your script.

6. Set the CORS authorization

In order to embed a card to an external website, it is necessary to put our external website into the list of authorized websites to comply with CORS regulations. Luckily, it is a straightforward process.

Inside the Workplace Manager on the top left navigation menu let's navigate to GateKeeper → CORS Authorizations. Here we can 'Add new record':

Add new record

In the popup window enter the name and Url of the webpage you wish to authorize:

Enter details of the webpage you wish to authorize

Click 'Save' and your website should be ready to display your card.

Final result

Assuming we're already logged in, if we navigate to our external webpage we should see our card. The result should be the same, whether we've used static or dynamic embedding:

Our card is on the external webpage