External Apps

When building a custom widget the javascript for that widget lives in a single function. This code must be maintained as part of the custom widget and updated within the Widget Builder only. This works great for most widgets; however, this can pose challenges for a widget that require a significant amount of javascript. This is where you can use an external app to manage the logic of your custom widget.

📘

This functionality is currently in BETA. Feel free to try it out and let us know any feedback you have.

renderExternalApp

The Widget Builder now offers an easy way to do that - by using a new API referenced at api.scripts.renderExternalApp. Here's how it is used within the Javascript section of your custom widget.

function(element, data, api) {
   api.scripts.renderExternalApp(<scriptSrc>, <container>, <props>, <options>)
}
ParameterDescription
scriptSrc *The src of the external script
container *The DOM element to render the external app into
propsProps that are passed into the external app
options.amdShould the external app be lazy loaded. Using require.js. Defaults to true
options.nameIf not using amd this should specific the global name of the app
options.keepSubtreeClean the subtree on every widget update. Defaults to false
options.additionalDataObject containing additional data passed to the external app on init

External App Code

The app should expose init and clean methods with the following signature:

export function init({ container, props, ...additionalData }) {
  // render you app into `container`, passing it `props` if needed
}

export function clean() {
  // cleanup for the app
}

Here's what this looks like in the Widget Builder

function(element, data, api) {

  // define the script src
  var scriptSrc = 'https://duda-widget-poc.s3.amazonaws.com/static/js/duda-widget.js';

  // render the app
  api.scripts.renderExternalApp(scriptSrc, element, {
      // the external app will get a `userName` prop
      // that mirrors the `accountName` field from the widget editor
      userName: data.config.accountName,
      // the external app will get a `type` prop
      // that mirrors the `mode` field from the widget editor
      type: data.config.mode,
  });
}

React/Angular/Vue apps

For code that is written in a framework, and built using an external build tool (for example, Webpack) - the usage in the widget builder is as follows:

function(element, data, api) {

  // define the script src
  var scriptSrc = 'https://duda-widget-poc.s3.amazonaws.com/static/js/duda-widget.js';

  // render the app
  api.scripts.renderExternalApp(scriptSrc, element, {
      bw: !!data.config.bw,
      userName: data.config.accountName,
      theme: data.config.theme,
      type: data.config.mode,
      backToList: data.config.backToList
  });
}

The app should be built as AMD

Example app code
Built code (minified)

Vanilla JS apps

For code that is written without a build system (or that is not built as amd), some additional properties should be passed (namely, amd and name):

function(element, data, api) {

  var vanillaScriptSrc = 'https://duda-widget-poc.s3.amazonaws.com/static-noamd/index.js';

  // render the app (safe to be called multiple times)
  api.scripts.renderExternalApp(vanillaScriptSrc, element, {
      areaFill: data.config.areaFill,
      title: data.config.title,
      subtitle: data.config.subtitle,
      zoomable: data.config.zoomable
  }, { amd: false, name: 'chart' });
}

The App should expose init and clean as well.

Example


What’s Next