Child Page API
The Child API is for use on the page contained within the <iframe>
tag. It is split into three sections.
Settings contains settings that can be passed when calling iframe-resizer. Events are
triggered by updates to the iframe, or messages from the iframe. Methods allow you to interact with
iframe-resizer after the initial resizing.
Settings
The following Settings can be set from within the iframe page by creating a window.iframeResizer
object on the page.
With options that can be set in both the parent page and in the iframe, then the setting in the iframe takes preference.
offsetSize
Modify the computed size of the iframe. This is useful if the page in the iframe returns a size value that is constantly slightly different to how you want the iframe to be sized. This can be set to a positive or negative value.
Note: Setting this value in the iframe will override any value set in the parent page. Set to 0
to disable
this option in the parent page.
sizeSelector
Use a CSS Selector to specify which element should be used to calculate the content size in the iframe. When the selector returns multiple elements, all of them are inspected and the largest value returned, every time time the page updates or resizes.
Alternatively you can directly add a data-iframe-size
attribute to an element to achieve the same effect.
targetOrigin
This option allows you to restrict the domain of the parent page, to prevent other sites mimicking your parent page. This option is really a last line of defense and you should also setup a Content Security Policy on your web server.
Events
The following events can be included in the Settings object attached to the iframed page.
onMessage
Receive message posted from the parent page with the iframe.iframeResizer.sendMessage()
method.
onReady
This function is called once iframe-resizer has been initialized after receiving a call from the parent page. If you need to call any of the following methods during page load, then they should be called from this event handler.
Methods
These methods are available in the iframe via the window.parentIframe
object. These method should be
contained by a test for the window.parentIframe
object, in case the page is not loaded inside an iframe.
For example:
autoResize(bool)
Turn autoResizing of the iframe on and off. Returns bool of current state.
close()
Remove the iframe from the parent page.
getId()
Returns the ID of the iframe that the page is contained in.
getParentProps(callback)
Ask the containing page for its positioning coordinates. You need to provide a callback which receives an object with the following read only properties:
Your callback function will be recalled when the parent page is scrolled or resized.
This method returns a disable()
function, that you can call to stop updates from
the parent page. The following example requests the properties from the parent page
and passes a callback that logs them to the console and then disables further updates.
scrollBy(x, y)
Scroll the parent page by the given amount.
scrollTo(x, y)
Scroll the parent page to the coordinates x and y.
scrollToOffset(x, y)
Scroll the parent page to the coordinates x and y relative to the position of the iframe.
sendMessage(message, [targetOrigin])
Send data to the containing page, message
can be any data type that can be serialized into JSON.
The targetOrigin
option is used to restrict where the message is sent to; to stop an attacker
mimicking your parent page. See the MDN documentation on
postMessage for more details.
resize()
Manually force iframe to resize. If for some reason a change in content size is not detected, this method allows you to nudge iframe-resizer to recalculate the page size.