EmbedBox

Get your embed code or web plugin on millions of websites.

EmbedBox is an open-source UI you can simply drop in to provide instructions for installing your embed code or plugins on every major CMS.

Clean customizable UI.
EmbedBox tries to remain as neutral as possible, allowing it to blend into any existing site by just picking a few colors. Need full CSS control? No problem, just include a stylesheet when instantiating.
Learn more
Built-in documentation.
EmbedBox includes install instructions for every major CMS platform.
Help us add more
Got plugins?
EmbedBox painlessly showcases your existing CMS plugins, all inside an interface which is easy to integrate into your site.
Learn more

Documentation

How to use

Download the latest release and add this to your page:

<script src="embed-box.min.js"></script>

new EmbedBox({
  name: "Example Plugin",
  embedCode: "" +
  "<script src='http://embedbox.io/examples/library.js'></script>\n" +
  "<script>\n" +
  "  (function(){\n" +
  "    var options = { /*  ... */ };\n" +
  "    Library.init(options);\n" +
  "  })();\n" +
  "</script>"
})

You can use EmbedBox with bundlers like Webpack and Browserify too:

npm install --save embed-box

import EmbedBox from "embed-box"

new EmbedBox({
  name: "Example Plugin",
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>"
})

EmbedBox supports Chrome, Safari, Firefox, and IE10+

Embed code

In virtually every installation, things start with your existing HTML embed code. By providing EmbedBox with this user‘s specific code, it can be included inside the docs for each platform.

<script src="embed-box.min.js"></script>

new EmbedBox({
  name: "Example Plugin",
  embedCode: "" +
  "<script src='http://embedbox.io/examples/library.js'></script>\n" +
  "<script>\n" +
  "  (function(){\n" +
  "    var options = { /*  ... */ };\n" +
  "    Library.init(options);\n" +
  "  })();\n" +
  "</script>"
})

Targets are the instruction pages for each type of CMS. For example, the WordPress target is the instructions for installing your tool onto WordPress. Targets default to the global options defined at the top level, but any option can be overridden for a specific target.

In this example all targets except Weebly will use the same embedCode:

new EmbedBox({
  name: "Example Plugin",
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>",
  targets: {
    weebly: {
      embedCode: "<script src='http://embedbox.io/examples/weebly-example-library.js'></script>"
    }
  }
})

If your script should be loaded in the <head> tag, set insertInHead: true and the instructions will update accordingly.

Options

assetPath

EmbedBox's assets are hosted by MaxCDN via RawGit.

Set assetPath to specify where assets are hosted.

Download assets

new EmbedBox({
  assetPath: "/assets/images/embed-box"
})

container

EmbedBox can appear inline by specifying container in the config. This can be a CSS selector.

new EmbedBox({
  container: ".my-element"
})

...or an HTML element.

new EmbedBox({
  container: document.querySelector(".my-element")
})

initialTarget

The target search screen can be skipped with initialTarget. Instead the box will render with a specific target already set.

new EmbedBox({
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>",
  initialTarget: "wordpress"
})

pluginURL

If you have an existing plugin for a CMS, specify it in that targets configuration and the docs will update automatically:

new EmbedBox({
  embedCode: "<script src='http://embedbox.io/examples/example-library.js'></script>",
  targets: {
    wordpress: {
      pluginURL: "http://embedbox.io/examples/wordpress-plugin.zip"
    },
    drupal: {
      pluginURL: "http://embedbox.io/examples/drupal-plugin.zip"
    },
    joomla: {
      pluginURL: "http://embedbox.io/examples/joomla-plugin.zip"
    }
  }
})

Not every target supports both embedCode and pluginURL installations.

If, for example, a given target only supports plugins and you don‘t provide one, that target will be automatically hidden.

ID	`embedCode`	`pluginUrl`	`insertInto.head`	`insertInto.body`

autoDownload

Plugins will automatically download when a target is selected.

Set autoDownload: false to disable to this behavior.

autoShow

EmbedBox will automatically appear on creation.

Set autoShow: false to disable to this behavior.

routing

EmbedBox can automatically update the hash of the page to allow visitors to link to a specific target’s instructions. If you don’t use the hash for another purpose, it’s a good idea to enable this by setting routing: true.

window.location.hash = "!/embed/drupal"

new EmbedBox({
  routing: true,
  embedCode: "<script src='http://example.com/plugin.js'></script>"
})

Customization

Theme

The theme option allows you to customize the colors used to render EmbedBox.

The instruction number labels will default to a provided accentColor unless stepNumberColor is set.

new EmbedBox({
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>",
  name: "Example Theme App",
  theme: {
    accentColor: "#665292",
    backgroundColor: "#e0e0e0",
    screenshotAnnotationColor: "#665292",
    stepNumberColor: "#665292",
    textColor: "#444444"
  }
})

branding

EmbedBox includes a branded link when rendered as a modal. Set branding: false to hide the link entirely.

If you need more configuration, the EmbedBox stylesheet can be extended.

new EmbedBox({
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>",
  name: "Example Stylesheet App",
  style: "" +
  ".header .title {" +
  "  color: hotpink;" +
  "  text-shadow: 0 0 4px pink;" +
  "}"
})

Content slots

Content can be inserted before and after the target instructions to provide extra instructions to your users.

You can also include content only for specific targets.

new EmbedBox({
  name: "FooBar",
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>",
  beforeContent: "Having some trouble? " +
    "Call us at <strong>(555)-123-4567</strong>",
  afterContent: "You should receive an email with your account password.",
  targets: {
    wordpress: {
      beforeContent: "FooBar works best with WordPress 4.0 or higher."
    }
  }
})

Labels

The labels used in the EmbedBox UI itself can be customized. They can be added as strings or functions. If you use functions, the EmbedBox config is passed to label functions.

new EmbedBox({
  name: "Acme plugin",
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>",
  labels: {
    title: function(config) { return config.name + " install guide" },
    searchHeader: "Press or enter the type of website you have.",
    searchPlaceholder: "Filter..."
  }
})

Ordering

Targets can be ordered with the priority option. A target will remain in the original order if not specified.

Set priority: -1 to disable a target entirely.

new EmbedBox({
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>",
  targets: {
    wordpress: {
      priority: 1
    },
    drupal: {
      priority: 2
    },
    weebly: {
      priority: 3
    },
    joomla: {
      priority: -1
    }
  }
})

The target selection screen will be skipped if only one target is visible.

Custom targets

If you need to fully customize the targets you can create your own.

Download the Custom Target and add this to your page:

<script src="embed-box-custom-target.min.js"></script>

var CustomTarget = EmbedBoxCustomTarget.extend({
  id: "custom-test",
  label: "Custom Target",
  templateVars: {
    registerURL: "http://example.com/register"
  },
  template: function(vars) {
    return "" +
    "<ol class='steps'>" +
    "  <li>" +
    "    <p>" +
    "      <a href='" + vars.registerURL + "'>Register an account</a> before installing." +
    "    </p>" +
    "  </li>" +
    "</ol>"
  }
})

new EmbedBox({
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>",
  customTargets: [CustomTarget]
})

If you'd like to omit the default targets, download EmbedBox Custom.

For more information on creating new targets, see the docs.

API

Lifecycle

Capturing the new EmbedBox() instance in a variable lets us call the lifecycle methods when needed.

var embedBox = new EmbedBox({
  autoShow: false,
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>"
})

embedBox.show()

setTimeout(function () {
  embedBox.destroy()
}, 5000)

fetchedTargets

Targets are populated in the EmbedBox.fetchedTargets array.

EmbedBox.getTargetIDs() can be used to programatically get the bundled target IDs if desired.

EmbedBox.getTargetIDs()

// {{TARGET_IDS}}

Events

While the EmbedBox constructor is synchronous, the browser will load the internal iframe asynchronously.

The onLoad event will fire when the full EmbedBox is ready.

var embedBox = new EmbedBox({
  embedCode: "<script src='http://embedbox.io/examples/library.js'></script>",
  events: {
    onLoad: function() {
      console.log(this) // EmbedBox instance
      alert("EmbedBox loaded!")
    }
  }
})

EmbedBox

Get your embed code or web plugin on millions of websites.

Clean customizable UI.

Built-in documentation.

Got plugins?