magicapp-recommendation (widgets)

Modified on Wed, 1 Apr at 5:56 AM

Overview

The magicapp-recommendation component displays a complete clinical recommendation with all associated content including key information, rationale, evidence summaries, decision aids, and adaptation guidance. This component uses the same production code as the MAGICapp interface.

Installation

Add the script tag to your page's <head> section:

<script src="https://app.magicapp.org/widget/recommendationComponent.js" type="module"></script>

Basic Usage

HTML Markup

Add the component directly in your HTML:

<magicapp-recommendation 
  guideline="guideline-short-code" 
  recommendation="recommendation-id">
</magicapp-recommendation>

JavaScript

Create and append the component dynamically:

const recComponent = document.createElement('magicapp-recommendation');
recComponent.setAttribute('guideline', 'guideline-short-code');
recComponent.setAttribute('recommendation', 'recommendation-id');
document.getElementById('container').appendChild(recComponent);

Component Attributes

Attribute	Type	Required	Dynamic Updates	Description
`guideline`	string	Yes	No	Guideline short code or ID
`recommendation`	string	Yes	Yes	Recommendation ID or short code. Using short code loads the latest published version
`lang`	string	No	Yes	Force specific locale (e.g., `en`, `es`, `fr`). Overrides browser language settings
`link-back`	boolean	No	Yes	Set to `"true"` to display a link back to the full guideline
`meta`	boolean	No	Yes	Set to `"true"` to show guideline title, version, and section information
`org`	boolean	No	Yes	Set to `"true"` to display organization logo, name, and publish date
`tab`	string	No	Yes	Default tab to open on load. Options: `key`, `advice`, `rationale`, `sof`, `da`, `adaptation`
`env`	string	No	No	Environment setting. Use `"test"` for test environment, omit for production

Attribute Notes

Guideline & Recommendation IDs: Both must use the same identifier type (either both short codes or both IDs)
Dynamic Updates: Attributes marked "Yes" can be changed after the component loads and will trigger a re-render
Boolean Attributes: Use string "true" to enable (e.g., meta="true")

Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Recommendation Widget Example</title>
  <script src="https://app.magicapp.org/widget/recommendationComponent.js" type="module"></script>
</head>
<body>
  <h1>Clinical Recommendation</h1>
  
  <!-- Full-featured recommendation display -->
  <magicapp-recommendation 
    guideline="jW0XmL" 
    recommendation="Lwr3VG"
    lang="en"
    link-back="true"
    meta="true"
    org="true"
    tab="key">
  </magicapp-recommendation>
  
  <!-- Minimal recommendation display -->
  <magicapp-recommendation 
    guideline="jW0XmL" 
    recommendation="136004">
  </magicapp-recommendation>
</body>
</html>

Using with Authentication

For authenticated API access, nest the component inside magicapp-connect:

<script src="https://app.magicapp.org/widget/apiBuilder.js" type="module"></script>
<script src="https://app.magicapp.org/widget/connectServiceComponent.js" type="module"></script>
<script src="https://app.magicapp.org/widget/recommendationComponent.js" type="module"></script>

<magicapp-connect client-id="your-client-id">
  <!-- Automatically uses parent's authentication -->
  <magicapp-recommendation 
    guideline="jW0XmL" 
    recommendation="Lwr3VG"
    meta="true"
    org="true">
  </magicapp-recommendation>
</magicapp-connect>

Tab Options

The tab attribute controls which section is displayed when the component loads:

Tab Value	Description
`key`	Key information (default expanded view)
`advice`	Clinical advice and practical information
`rationale`	Rationale and explanation for the recommendation
`sof`	Summary of findings (evidence tables)
`da`	Decision aids
`adaptation`	Adaptation guidance (deprecated - merged into "More info")

Using as an iFrame

You can also embed recommendations using an iframe with URL parameters.

iFrame URL Format

https://app.magicapp.org/widget/recommendation/?gId={GUIDELINE_ID}&recId={REC_ID}&open=1&tab={TAB}&org=1&m=1&lb=1

URL Parameters

Parameter	Values	Description
`gId`	string	Guideline short code or ID
`recId`	string	Recommendation ID or short code
`open`	`1`	Show recommendation expanded with specified tab open
`tab`	`key`, `advice`, `rationale`, `sof`, `da`	Which tab to display
`org`	`1`	Show organization name, logo, and publish date
`m`	`1`	Show guideline metadata (title, version, section)
`lb`	`1`	Include link back to full guideline
`lang`	locale code	Force specific language (e.g., `en`, `es`)

iFrame Examples

The latest published version with a key info tab:

<iframe 
  src="https://app.magicapp.org/widget/recommendation/?gId=jW0XmL&recId=Lwr3VG&open=1&tab=key&org=1&m=1&lb=1"
  width="100%" 
  height="600" 
  frameborder="0">
</iframe>

Specific recommendation ID with rationale tab:

<iframe 
  src="https://app.magicapp.org/widget/recommendation/?gId=jW0XmL&recId=136004&open=1&tab=rationale&org=1&m=1&lb=1"
  width="100%" 
  height="600" 
  frameborder="0">
</iframe>

Minimal display (no metadata):

<iframe 
  src="https://app.magicapp.org/widget/recommendation/?gId=jW0XmL&recId=Lwr3VG"
  width="100%" 
  height="400" 
  frameborder="0">
</iframe>

Dynamic Updates

You can change certain attributes after the component has loaded to update the display:

const rec = document.querySelector('magicapp-recommendation');

// Switch to a different recommendation
rec.setAttribute('recommendation', 'new-rec-id');

// Change the active tab
rec.setAttribute('tab', 'rationale');

// Change language
rec.setAttribute('lang', 'es');

// Toggle metadata display
rec.setAttribute('meta', 'true');

Test Environment

To use the test environment, add the env attribute:

<magicapp-recommendation 
  guideline="test-guideline" 
  recommendation="test-rec-id"
  env="test">
</magicapp-recommendation>

Or for iFrame:

https://app-test.magicapp.org/widget/recommendation/?gId=testGuideline&recId=testRec

Browser Compatibility

Chrome/Edge 80+
Firefox 75+
Safari 13.1+
Opera 67+

Requires support for ES6 modules, Custom Elements, and Shadow DOM.

Troubleshooting

Component is not rendering

Verify the script is loaded with type="module"
Check that guideline and recommendation IDs are valid
Open the browser console for error messages

Wrong language displaying

Set explicit lang attribute to override browser settings
Ensure the locale code is supported by MAGICapp

Content not updating

Only attributes marked "Dynamic Updates: Yes" can be changed after load
Changing guideline requires page reload

Support

Email: api-support@magicapp.org
Documentation: https://docs.magicapp.org
Examples: https://magicevidence.org/widget-demo