@newswire/frames
@newswire/frames
is a greenfield take on responsive iframes in the spirit of Pym.js.
Key features
- 🐜 1 kilobyte gzipped for both parent and frame code
- 🌴 Tree-shakable by default - import only what you need to achieve responsiveness
- ⚡️ Speaks AMP and is compatible with
amp-iframe
Supported browsers
Browser | Supported |
---|---|
Safari | ✅ |
Mozilla Firefox | ✅ |
Google Chrome | ✅ |
Opera | ✅ |
Microsoft Edge | ✅ |
Internet Explorer 11 | ✅ |
Internet Explorer 10 and lower | ⛔️ |
Installation
@newswire/frames
is available via npm
.
npm install @newswire/frames
You can also use it directly via unpkg.com.
<!-- Now available at `window.newswireFrames` -->
You can also import it as a module via unpkg!
Usage
From the host page (framer or parent)
The page that contains the embeds needs to use the Framer
class to set up instances for each embed.
Assume we have the following markup in our HTML:
Loading...
Then, in our script:
; const container = document;const src = 'https://i-am-an-embed/'; const framer = container src ;// Now the iframe has been added to the page and is listening for height changes notifications from within the iframe
A popular feature of Pym.js was the ability to automatically initialize embeds that had matching attibutes on their container elements. @newswire/frames
also includes this capability.
Assume we have the following markup in our HTML:
Then in our script, we can skip the fanfare of setting up a Framer
for each one and use the data-frame-src
attribute to find them.
; // looks for any elements with `data-frame-src` that haven't been initialized yet, and sets them up;
If you're needing to pass any of the other options to Framer
when you're automatically creating the embeds, you can add matching data attributes that the initializer will pick up and pass along.
From the embedded page (frame or child)
While the code to setup the host page is similar to Pym's Parent
class, the methods for making the iframed page communicate with the host page are a little different.
Want to set it and forget it? You can import a function that sets up listeners and sends the initial height of the frame's content.
; // 1. Sends the initial frame's content height// 2. Sets up an one-time istener to send the height on load// 3. Sets up a listener to send the height every time the frame resizes;
You can also automatically set up long polling for height changes as well.
; // 1. Sends the initial frame's content height// 2. Sets up an one-time listener to send the height on load// 3. Sets up a listener to send the height every time the frame resizes// 4. Sets up an interval to send a new height update every 300ms;
Alternatively, you can set and use function independently depending on the needs of your frame's content.
; // 1. Sends the initial frame's content height; // 2. Sets up an one-time listener to send the height on load; // 3. Sets up a listener to send the height every time the frame resizes; // 4. Sets up an interval to send a new height update every 150ms; // 1-3 is identical to initFrame()! 1-4 is identical to initFrameAndPoll()!
Typically using initFrame()
will be enough, but if you have code that will potentially change the height of the frame's content (like with an <input>
or <button>
press) and would rather not use polling, you can use sendFrameHeight()
to manually recalculate and send an update to the parent page.
API
Table of Contents
- Framer
- autoInitFrames
- sendFrameHeight
- sendHeightOnLoad
- sendHeightOnResize
- sendHeightOnPoll
- initFrame
- initFrameAndPoll
Framer
The Framer object to be called in the host page. Effectively a wrapper around interactions with an embedded iframe.
Parameters
options
object options used to prepare the iframeoptions.allowfullscreen
boolean? toggles theallowfullscreen
attribute (optional, defaultfalse
)options.container
Element the containing DOM element for the iframeoptions.name
string? sets thename
attributeoptions.referrerpolicy
string? sets thereferrerpolicy
attributeoptions.sandbox
string? sets thesandbox
attribute (optional, default'allow-scripts'
)options.src
string the URL to set as thesrc
of the iframeoptions.title
string? sets thetitle
attribute
remove
Removes event listeners and removes the iframe from the container.
Examples
const framer = ...;// tears down the Framerframer;
Returns void
autoInitFrames
Automatically initializes any frames that have not already been auto-activated.
Examples
// sets up all frames that have not been initialized yet;
Returns Array An array of all the created Framers
sendFrameHeight
Sends the current document's height or provided value to the host window using postMessage.
Parameters
height
number? The height to pass to the host page, is determined automatically if not passed (optional, defaultgetDocumentHeight()
)
Examples
// Uses the document's height to tell the host page; // Pass a height you've determined in another way;
Returns void
sendHeightOnLoad
Sets up an event listener for the load event that sends the new frame height to the host. Automatically removes itself once fired.
Examples
// once the frame's load event is fired, tell the host page its new height;
Returns void
sendHeightOnResize
Sets up an event listener for the resize event that sends the new frame height to the host.
Examples
// every time the frame is resized, tell the host page what its new height is;
Returns void
sendHeightOnPoll
Sends height updates to the host page on an interval.
Parameters
delay
number? How long to set the interval (optional, default300
)
Examples
// will call sendFrameHeight every 300ms; // will call sendFrameHeight every 150ms;
Returns void
initFrame
A helper for running the standard functions for setting up a frame.
Automatically calls an sendFrameHeight, sendHeightOnLoad and sendHeightOnResize.
Examples
;
Returns void
initFrameAndPoll
Initializes a frame, then sets up a poll to continue to update on an interval.
Parameters
delay
number? An optional custom delay to pass to sendHeightOnPoll
Examples
// calls initFrame, then calls sendHeightOnPoll;
Returns void
License
MIT