iframe API

Let’s keep our iframe API’s sane and clean because we end up sharing these with third parties who want to integrate with Poll Everywhere and they’re insanely useful for internal hacks.

URL params

What’s the big deal about URL params? Lots actually! It’s easy for host applications to control the behavior of the iframe application via an URL params. For example, to show a visualization on a web page without the presenter hover controls, you’d do something like:

<iframe src="http://viz.polleverywhere.com/multiple_choice_poll/:permalink?controls=none">

URL params are a good way to bootstrap iframe applications within a certain context. To alter the behavior of the iframe application from the host website after it loads, you’ll want to use postMessage on the iframe.

Avoid boolean params; think in terms of sets

Generally there’s a tendancy for developers to have specific URL params that accept a boolean true/false value like:

# Don't do this
?sidebar_hidden=true&header_hidden=true
?presenter_controls=true

Think of URL param values as a set:

# Do this
?hide=sidebar,header
?controls=presenter

This gives future developers a littler more flexibility to add new modes without adding additional URL params.

Avoid negative params

If you have no_ in front of a parameter name like this:

# Don't do this
?force=no_instructions,no_title

Rename the parameter to accept the same values without a no or not:

# Do this
?hide=instructions,title

Interactive documentation

Interactive documentation should be developed for our APIs like we do at http://viz.polleverywhere.com/api/index.html. If you built your APIs per the URL param spec above, it should be trivial to document API values like:

%li
  %label Controls
  %p Specify what controls are displayed to users that hover over the top right of the poll visualization.
  %select#controls.parameter
    %option(data-description="Show all controls. Best suited for in-presentation software.") all
    %option(data-description="Show controls for a slideshow.") presentation
    %option(data-description="No controls are displayed.") embed
    %option(data-description="Controls that are displayed when a user goes fullscreen on the web.") fullscreen
    %option(data-description="Controls that we displayed from our Rails editor view.") editor
    %option(selected data-description="Hide all controls. Best suited for embedding in a website.") none

Note: The viz iframe API does not have a control for selecting multiple attributes to generate lists like hide=sidebar,header, but this could (and should) be implemented via an HTML multi-select.