@newswire/frames

`@newswire/frames` is a minimalistic take on responsive iframes in the spirit of [Pym.js](http://blog.apps.npr.org/pym.js/). ## Key features - 🐜 **<1 kilobyte** gzipped for both parent and frame code - 🌴 **Tree-shakable** - import only what you need for your use case - ⚡️ **Speaks [AMP](https://www.ampproject.org)** and is compatible with [`amp-iframe`](https://www.ampproject.org/docs/reference/components/amp-iframe) - 🕰 **Legacy [Pym.js](http://blog.apps.npr.org/pym.js/) support** - recognizes `height` updates from Pym.js iframes - 🧪 **Fully tested** in Safari, Chrome and Firefox with [Playwright](https://playwright.dev) ## 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`. ```sh npm install @newswire/frames ``` You can also use it directly via [unpkg.com](https://unpkg.com/). ```html ``` You can also import it as a module via unpkg! ```html ``` ## 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: ```html

Loading...

``` Then, in our script: ```js import { Framer } from '@newswire/frames'; const container = document.getElementById('embed-container'); const src = 'https://i-am-an-embed/'; const attributes = { sandbox: 'allow-scripts allow-same-origin' }; const framer = new Framer(container, { src, attributes }); // Now the iframe has been added to the page and is listening for height changes notifications from within the iframe ``` It is also possible to observe existing iframes on a page if the content of the frames are compatible with `@newswire/frames`. This is handy if you already have your own method to dynamically add iframes to the page, or are using a custom method to lazy load them and don't need the heavy hand of `Framer`. ```js import { observeIframe } from '@newswire/frames'; // grab a reference to an existing iframe const iframe = document.getElementById('my-embed'); // returns a `unobserve()` function if you need to stop listening const unobserve = observeIframe(iframe); // later, if you need to disconnect from the iframe unobserve(); ``` Pym.js had the ability to automatically initialize embeds that had matching attibutes on their container elements — `@newswire/frames` can do this as well. Assume we have the following markup in our HTML: ```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. ```js import { autoInitFrames } from '@newswire/frames'; // looks for any elements with `data-frame-src` that haven't been initialized yet, and sets them up autoInitFrames(); ``` If you're needing to pass any of the other options to `Framer` when you're automatically creating the embeds, you can add attributes that the initializer will pick up and pass along using the `data-frame-attribute-*` prefix. ```html

``` ### 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. ```js import { initFrame } from '@newswire/frames'; // 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 // 4. Sets up an event listener that sends the height once the parent window begins watching initFrame(); ``` You can also automatically set up long polling for height changes as well. ```js import { initFrameAndPoll } from '@newswire/frames'; // 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 event listener that sends the height once the parent window begins watching // 5. Sets up an interval to send a new height update every 300ms initFrameAndPoll(); ``` Alternatively, you can set and use function independently depending on the needs of your frame's content. ```js import { sendFrameHeight, sendHeightOnLoad, sendHeightOnResize, sendHeightOnPoll, sendHeightOnFramerInit, } from '@newswire/frames'; // 1. Sends the initial frame's content height sendFrameHeight(); // 2. Sets up an one-time listener to send the height on load sendHeightOnLoad(); // 3. Sets up a listener to send the height every time the frame resizes sendHeightOnResize(); // 4. Sets up an event listener that sends the height once the parent window begins watching sendHeightOnFramerInit(); // 5. Sets up an interval to send a new height update every 150ms sendHeightOnPoll(150); // 1-4 is identical to initFrame()! 1-5 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 `` or `