logo

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.

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

    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.

    IDembedCodepluginUrlinsertInto.headinsertInto.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!")
        }
      }
    })
    

    Reference

    EmbedBox#destroy()

    Hides and removes EmbedBox from the page. This is irreversible.

    EmbedBox#hide()

    Hides EmbedBox.

    EmbedBox#show()

    Shows EmbedBox.

    EmbedBox#mode

    The mode is determined by the container element.

    An EmbedBox instance in the <body> will be "modal". Otherwise this is set to "inline".

    EmbedBox#visible

    Retrieve visibility.

    Contributing

    Please do, we would love for this to become a project of the community. Feel free to open an issue, submit a PR or contribute to the docs.

    Is there a CMS target that you'd like to see here?

    Read more about adding new targets.

    Made by