How to create JSON widgets for the Hero

Share on print
Share on facebook
Share on linkedin
Share on whatsapp
Share on email
In the Hero blocks, we can configure a Custom Widget called JSON.

mceclip0 (31).png

This JSON refers to Adaptive Cards, a Microsoft card UI framework. This means that we cannot use any JSON, but we need to follow the Adaptive Card’s standard. Find more information about the format that our “Template JSON” have to follow, here: https://adaptivecards.io/explorer/

Static and dynamic widgets

The widgets created with Adaptive Cards can be static or dynamic:
  • They are static if both layout and data are specified in the “Template JSON”.
  • They are dynamic if the layout is specified in the “Template JSON” while the data is in a separate “Data JSON”. This separation allows populating the layout with changing data. For more information read the docs about Adaptive Cards templating here: https://docs.microsoft.com/en-us/adaptive-cards/templating/language

The JSON widget

To create a JSON widget, you need to be a Appspace Intranet Global/Local Admin, open the Manage Settings, Hero settings, click on the custom block where you want to show the Adaptive Card, select the block type Custom widget and check the JSON option.
Here you will find the following fields:
  • Source
  • Source data URL
  • Template JSON (mandatory)
  • HostConfig styling
  • CSS styling
  • Fallback background color
mceclip1 (18).png
mceclip2 (10).png
Let’s look at them one by one.

“Source field”

If you are creating a static card and you won’t add a Source data URL (next field), this field will be ignored.
If you are creating a dynamic card, here you need to specify if the Source data URL that you will provide in the next field, is internal (in your SharePoint domain) or external (in a different domain).

“Source data URL” field

Just leave this field empty in case you want a static card.
If you are creating a dynamic card, here you have to paste the URL that will provide the “Data JSON”.

“Template JSON” field

This is the only mandatory field and the most important one. Here we have to add our Adaptive Card JSON template.
You can find some samples here: https://adaptivecards.io/samples/
In the samples page, you will see this option checked by default.
mceclip4 (6).png
If you decide to add a static card, just uncheck the “Use Adaptive Card Templating”, copy the JSON and paste it in the Template JSON field.
mceclip6 (5).png
If you do want a dynamic card, then you need to check the “Use Adaptive Card Templating”. You will see two JSON:
  • copy/paste the Template JSON in the Template JSON field in the block.
  • copy the Data JSON, paste it in a .txt file, change the extension to .json, then you should upload it in SharePoint (internal) or an external provider, and paste the URL in the Source data URL field.

HostConfig & CSS styling JSON fields

Please read the guide: How to style Adaptive Cards (WIP) to learn more about these two fields.

Fallback background color

This is the color that will appear in your widget if you do not set any background color (neither in the HostConfig nor the CSS styling fields)
It is also the color of the widget loading state.
mceclip7 (2).png
Once you have filled every field you need, click the Save and Close button, and go to the Preview or directly click on Publish/Update the Hero and check it on the start page.

Examples

Simple static widget

mceclip8.png
  • Copy the JSON and paste it in the Template JSON field of your custom widget block (in Manage Settings => Hero)
  • Save and Close
  • Publish/Update Hero
  • Check the Hero in the start page
mceclip9 (1).png

Dynamic widget with HostConfig & CSS styling

mceclip10.png
  • Copy the Template JSON and paste it in the Template JSON field of your custom widget block (in Manage Settings => Hero).
  • Copy the Data JSON, paste it in a .txt file, change the extension to .json, upload it here: https://firebase-image.vercel.app/ and copy/paste the resulting URL in the Source data URL field in the block.
  • Set the Source field to “external”.
  • Copy the HostConfig sample here: https://github.com/microsoft/AdaptiveCards/blob/main/samples/HostConfig/webchat.json and paste it in the HostConfig field in the block.
  • Copy/Paste the following CSS to the CSS styling field in the block: html, body, .ac-adaptiveCard {   height: 100%; } body {   margin: 0;   overflow: hidden; }  .ac-adaptiveCard:focus { outline: 0; }
  • Save and Close
  • Publish/Update Hero
  • Check the Hero in the start page
mceclip11.png
Related Articles