How-to
Website
Web app
Show another page in a frame
Show another page inside yours (a video player, a map, a preview your app builds) with Frame, and hear what that page posts back. This page embeds a video player and a preview of the site's own, and shows what the preview sends back. The player is on another origin, so the config names it in meta.frame; without it, the page's Content-Security-Policy blocks the frame and it stays blank:
Needs: the meta.frame setting below in webfluent.app.json, and a page at /preview/ for the second frame to show.
{ "meta": { "frame": ["https://www.youtube-nocookie.com"] } }
page Talk(path: "/", title: "The talk", description: "The launch talk, and what the preview says.") {
state heard = ""
Heading("The talk").h1
Frame(src: "https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ", title: "The launch talk", allow: "fullscreen")
Frame(src: "/preview/", title: "Preview", sandbox: "allow-scripts") {
on message(m) {
if let .string(said) = m.data { heard = said }
}
}
Text(heard)
}
How it works
title:says what the frame shows. A screen reader announces a frame by its title, and a frame without one draws anA17warning.on message(m)hears what the framed page posts withwindow.parent.postMessage(…), and nothing that any other page posts.m.datais what it sent, asJson:if let .string(said)takes it when it is text.sandbox:limits what the framed page may do:"allow-scripts allow-forms"allows scripts and forms, and an empty string allows nothing.allow:names the browser features the framed page may use.
A frame from another origin must be named in meta.frame, or the page's Content-Security-Policy refuses it (Security). The build and wf check do not warn about a missing one: the frame is simply blank in the browser. meta.frame takes origins only (https://www.youtube-nocookie.com), not paths.
Frame your own pages
A page of your own site (src: "/preview/") needs no extra setting. The site's pages are served refusing to be framed by anyone (X-Frame-Options: DENY). A project that places a Frame with a site-relative src: is served SAMEORIGIN instead, both by wf serve and in the _headers file a build writes. Your site may frame its own pages, and no other site may.
Troubleshooting
| What you see | Why, and what to do |
|---|---|
|
|
Add a |
| A frame from another site stays blank |
Its origin is not in |
Variations
Draw HTML you give the frame
To draw HTML instead of loading an address (an example a page renders, or a preview of what a reader is writing), use srcdoc:. This page previews a note as the reader types it:
page Preview(path: "/preview-note", title: "Preview", description: "A note, drawn as it will look.") {
state note = "Hello"
Heading("Preview").h1
Input(bind: note, label: "Note")
Frame(srcdoc: "<p>{note}</p>", title: "The note, drawn", sandbox: "")
}
The frame draws the HTML sandboxed as sandbox: says, so sandbox: "" draws it with no script and no reach into your page. HTML from a value with no sandbox: is given sandbox="" — what a value holds is somebody else's document, scripts and all — and the build names it with a V03. A value that reads state draws the new HTML each time it changes, and the pre-rendered page has the HTML before any script runs.
A frame's on message hears what its own document posts, from the origin that document has: its address's, or the opaque "null" of a sandbox without allow-same-origin. A page the frame was navigated to is no longer its own.