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.
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:
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.
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.
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
# Do this ?hide=instructions,title
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.