URL options form in your editor

Designed for the use with text editors and CMS, Iframely URL Options let your authors fine-tune individual reach media, choosing from specific micro parameters each publisher supports for their embed codes.

Iframely declares available micro customization options as additional, provider- and content-specific query-string parameters for each individual URL you give us.

You can see and test exact options form for individual URLs when you Check URLs in your Iframely dashboard. The customization form is right below embed code, if any options are available for your URL:

Options declaration comes as a simple JSON structure. Use it to generate an HTML form and give it to your authors and editors. Once a user selects any option, send it to Iframely as the query-string parameter (&param=value).

URL Options are available on Editorial API plan and higher. Plus, during your trial period.

Options JSON format

Options declaration should be intuitive and easy to read. Here's the simplest JSON declaration of text caption option for individual Instagram's posts:

options: {
    _showcaption: {
        value: true,
        label: "Show author's text caption"

Essentially, we declare available query-string parameters for API calls. You can repeat your API calls with those options as parameters that are unique for each provider and URL:

iframe.ly/api/oembed?url= ... &_showcaption=false
  • Available query parameters come as the keys in options object.
  • Each parameter is an object with current value, as well as label for the description of that option to end-user.
  • Type of value as well as other attributes describe the form UI element for that option.
  • For example, boolean value simply translates into a checkbox.

Parameters that are specific to publisher's rich media will start with _ underscore prefix. Iframely will also add its own parameters based on URL content. These options will not be underscored (say, for &media=0 parameter).

Options JSON may also have a reserved query key. It echoes any API parameters that you send to us. That way your app can tell the difference between default option values and the ones that were selected by user:

query: ["_theme", "_playlist","_artwork"]

Parameter input types

Checkbox (ex. Twitter):

_hide_thread: {
    value: true,
    label: "Hide parent Tweet"

Text input (ex. YouTube):

_start: {    
    value: "7",
    label: "Start from",
    placeholder: "ex.: 11, 1m10s"

Radio group / selectbox (ex. Soundcloud):

_height: {
    value: 400,
    label: "Adjust height",
    values: {
        "300": "300px",
        "400": "400px",
        "600": "600px"

Range input (ex. Google Maps):

_zoom: {
    value: 17,
    label: "Zoom",
    range: {
        max: 21,
        min: 3

These're all the option types you may get. See below for hints on the options form UI.

Example & test

Here's an example of full options object with most of these types (CodePen):

options: {
    _theme: {
        value: "dark",    
        values: {
            auto: "Default",
            dark: "Dark",
            light: "Light"
        label: "Theme color"
    _click_to_load: {
        value: true,
        label: "Use click-to-load"
    _height: {
        value: 600,    
        label: "Adjust height",
        placeholder: "ex.: 600, in px",    
    query: ['_height', '_theme']

Can you tell what's a checkbox, what's a radiogroup and what's a text input? Which options are not default?

Check yourself.

The options flow

Iframely assumes the following workflow.

  • You get available parameters JSON from us in two ways: a) as part of an API response and/or b) as event message from iFrames itself.
  • If options JSON is available, you generate a form UI for your URL using declared parameters and give that form to your users to fine-tune their rich media.
  • When user chooses any option, you need to listen for or request a new options JSON. Selecting parameters may affect further customization options. Then, re-render the form with updated options.
  • Please store the parameters selected by your users. We suggest your keep them as data- attributes of the URL element in your CMS for future use.
  • To retrieve an updated embed code, or when you need to refresh URL's cache, repeat API calls to Iframely with the user-selected options as API query-string parameters.

This flow doesn't require the use of Hosted iFrames and will work just as well if you opt for native embed codes from publisher (retreive options only via API requests in that case).

However, if you choose to use our iFrames as WYSIWYG preview, you can simply append the query-string to iFrame's src and get an updated preview right away (and your CMS can later on retrieve the actual optimized embed codes for that URL and parameters, hosted iFrames or native).

Rendering an options form

Spoiler: Iframely also offers options.js with handy render helpers. Skip to next.

Mapping parameters to input types

Mapping parameters to HTML inputs should be fairly intuitive and follow HTML naming specs for the attributes. Here're some less obvious considerations:

  • For options with values, we recommend radio group instead of a select box if there's less than 3 choice values.
  • You may go as far as to have "inline" one-line radio group if the labels of the values are short.
  • If the current value of a text input is integer, you might consider input type number.
  • Text inputs will also help placeholder attribute to hint your users.
  • For range sliders, use min and max of a range object of an option.

Before you render

Make sure you understand the following caveats.

  • Iterate through options keys, but don't forget to skip the reserved query key.
  • Store initial state of options the first time your receive it. This way you won't need to send us the default values if user changes the form back to defaults.
  • Not only options are unique for each provider. They also depend on URL content itself, as well as on previously selected options.
  • Therefore, please change the request's query-string and re-render the form each time your user updates any option. A new option may become available or some older ones become disabled.
  • If you use our iFrames for WYSIWYG previews and simply append the parameters as query-string to its src, don't forget to run an API request with the same query-string before you publish the codes to the end-user. This way you'll get an optimized and production-ready HTML with proper sizing and other attributes.
  • As form is on your side (we only suggest options), you control which parameters to use. Say, you might skip all options that do not start with _ as these are Iframely's own options (ex.: for iframe=card-small when we return a card).
  • Labels internationalization is out-of-scope, at least for now. To translate labels on your end, see the suggestion in the next section.

Not every URL will declare customization options. The options part will be skipped in API responses for such URLs and no iFrame event will be triggered.

We'll be happy to add more customization options if we miss any you need. Ping support.

An exception to options mapping

Last, but not least, a unique case. When Iframely thinks that a particular Iframely's own query-string parameter can be interesting for your end-user, we may add it this way:

media: {
    value: "",
    values: {
        "1": "Just the image"

This example is for &media=1 parameter, say, for Imgur. The default behaviour would be to skip that parameter completely. On the other hand, if you send us &media=0, it'll just disable any rich media and generate a summary card instead. We don't believe it's what your end-user would be interested in, and do skip media=0 option, leaving just one value in values.

We recommend that you treat all such single values as a checkbox, and if it's checked - send the actual value to us. If unchecked - skip that parameter completely.

Render a form with options.js

We have built options.js script that takes an options object and outputs form's HTML code that you can contextually add to your text editor. Use it as-is, or customize, or just take a look as the implementation reference.

See it on GitHub

Source options.js

options.js is an extension of our embed.js script, and can be sourced from our CDN as cdn.iframe.ly/options.js. Or you can get it on Github and adapt/host yourself.

Please add embed.js to your page before you load options.js.

Register URL options

If you use hosted iFrames with Content IDs, you can start by listening for a message from them:

iframely.on('options', function(widget, options) {

    // register options to the context, perhaps invisible
    // set any context ID - you'll need it next

    // when user clicks for the context edit menu
    // show form, using the next method


Or simply register options when you get it in an API response in a similar way.

Build options form

When it's time to build and show the form, call:

iframely.buildOptionsForm(id, formContainer, options[, translator]);
  • id - any id, likely unique to URL. Used to remember default options and is echoed back when options change.
  • formContainer - HTML DOM Element where the script will add form's HTML to.
  • options - options JSON you received from Iframely, either as iFrame message or API response.
  • translator - optional translator function that takes a label and returns a new string. You can use built-in iframely.optionsTranslator('fr') (with user's language) or create your own. Built-oin function, however, requires building options.js with additional JSON files with the translation of known labels to your user's language.

Act on option changes

options.js will add HTML and event listeners for inputs. You'll get notified when user changes options in the following way:

iframely.on('options-changed', function(id, formContainer, query) {

    // id and form container are echoed from the build request
    // query contains key: value object with the modified options (excluding the default ones, if user undid the previous choice)

    // keep query string here,
    // update iFrame src for WYSIWYG
    // or request new embed codes by repeating API requests

    // then build the form anew, as the options are conditional and may have changed


Customize the script

The default options.js package has pre-determined HTML templates. You simply customize them via CSS on your end, or change the templates in the library and build anew. Here are the templates.

The included translator function (iframely.optionsTranslator) simply takes the strings from JSON mapping for all known options. To add new languages, just add more JSON files to the build. Here's the JSON template and example for French (Pull-request with more translations are welcome).

Previous article: Content IDs
Next article: Omit CSS