Embeddable recommendation widget: magicapp-recommendation (technical documentation)

Modified on Tue, 17 Nov at 10:06 AM

About this article

This article is intended for technical teams responsible for website integrations and software development.


The magicapp-recommendation component displays a complete clinical recommendation, including associated content such as rationale, evidence summaries, and supporting information. This article describes how to configure and implement the recommendation widget within your website or application.


Looking for general information about sharing MAGICapp content?

See:


Looking for an overview of MAGICapp embeddable widgets?

See Embeddable widgets for website integration (technical documentation) for an overview of MAGICapp's web components and related widget documentation.


Looking for direct API integration guidance?

See API: Using the MAGICapp API (technical documentation) for information about API user accounts, authentication, permissions, and direct API integrations.


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 

AttributeTypeRequiredDynamic UpdatesDescription
guidelinestringYesNoGuideline short code or ID
recommendationstringYesYesRecommendation ID or short code. Using short code loads the latest published version
langstringNoYesForce specific locale (e.g., en, es, fr). Overrides browser language settings
link-backbooleanNoYesSet to "true" to display a link back to the full guideline
metabooleanNoYesSet to "true" to show guideline title, version, and section information
orgbooleanNoYesSet to "true" to display organization logo, name, and publish date
tabstringNoYesDefault tab to open on load. Options: key, advice, rationale, sof, da, adaptation
envstringNoNoEnvironment 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 ValueDescription
keyKey information (default expanded view)
adviceClinical advice and practical information
rationaleRationale and explanation for the recommendation
sofSummary of findings (evidence tables)
daDecision aids
adaptationAdaptation 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 

ParameterValuesDescription
gIdstringGuideline short code or ID
recIdstringRecommendation ID or short code
open1Show recommendation expanded with specified tab open
tabkey, advice, rationale, sof, daWhich tab to display
org1Show organization name, logo, and publish date
m1Show guideline metadata (title, version, section)
lb1Include link back to full guideline
langlocale codeForce 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 


Last updated: 17 November 2026

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article