Expresso.Element.Embed (expresso v0.1.0)

An element that shows a web page in a slide

The embed entity takes the source of the page as its first argument:

An address that starts with https:// or http://. The browser loads the page from the network.
The path of a local HTML file, relative to the working directory of the command or to the root option of the deck. sources/1 reads the file, and the document holds its text. The deck then stays one file, and the page works with no network.

The title option names the page for a screen reader, and it is required. The fallback option gives the path of an image, which shows on paper, in the handout view, in the overview and while the page loads.

The document holds a copy of each slide for the present view and one for each page of the handout view. A page in each copy would load the page many times, so no copy holds the source. The iframe element holds only data-embed, the number of the element in the deck, and the renderer writes the sources one time into the element expresso-embeds. The presenter loads a page when its slide shows in the present view, and the page then stays loaded.

By default the page does not take a click or the focus, so the keys and the clicks of the presenter still work on the slide. With interactive true, the page takes the clicks, and a key goes to the page after a click on it. docs/reference/embed-element.md gives the rules.

Summary

Types

t()

The struct of an embed element

Functions

address?(value)

Tell whether a source is an address on the network

aspect(value)

Make sure that an aspect option is a ratio, such as "16/9"

get_assigns(embed)

Make the assigns of the render function from the struct

json(deck)

Write the sources of the embeds of a deck as JSON, or return nil

number(deck)

Give each embed of a deck its number

render(assigns)

Make the HTML of an embed

source(value)

Make sure that the source of an embed is an address or the path of an HTML file

sources(deck)

Return the source of each embed of a deck, in the order of their numbers

Types

t()

@type t() :: %Expresso.Element.Embed{
  __spark_metadata__: term(),
  aspect: term(),
  at: term(),
  class: term(),
  easing: term(),
  effect: term(),
  el: term(),
  fallback: term(),
  index: term(),
  interactive: term(),
  morph: term(),
  on: term(),
  signature: term(),
  speed: term(),
  src: term(),
  steps: term(),
  title: term(),
  width: term(),
  window: term(),
  window_title: term()
}

The struct of an embed element

Functions

address?(value)

@spec address?(String.t()) :: boolean()

Tell whether a source is an address on the network

aspect(value)

@spec aspect(term()) :: {:ok, String.t()} | {:error, String.t()}

Make sure that an aspect option is a ratio, such as "16/9"

The value is two positive numbers with a slash between them.

get_assigns(embed)

@spec get_assigns(t()) :: map()

Make the assigns of the render function from the struct

The key overlay holds the attributes of the overlay contract, and the style attribute of the width and aspect options. The key fallback holds the data URI of the fallback image, or nil. The key sandbox holds the sandbox attribute of the frame.

json(deck)

@spec json(Expresso.Deck.t()) :: String.t() | nil

Write the sources of the embeds of a deck as JSON, or return nil

The value is a list with one object for each embed, in the order of their numbers, such as [{"kind":"src","value":"https://example.com/"}]. The renderer writes it into a script element, so the function escapes each <. A deck with no embed gets nil, and the document then holds no such element.

number(deck)

@spec number(Expresso.Deck.t()) :: Expresso.Deck.t()

Give each embed of a deck its number

The number is the position of the element in the deck, in document order, from 0. sources/1 writes the source of each embed at that position, and the render function writes the number into data-embed. Expresso.Renderer calls this function before the render.

render(assigns)

@spec render(map()) :: Phoenix.HTML.safe()

Make the HTML of an embed

The root tag holds the fallback image or a placeholder with the title, and the frame on it. The frame has no source, and the presenter gives it one. A frame that is not interactive gets tabindex="-1", so the key Tab does not go into it.

source(value)

@spec source(term()) :: {:ok, String.t()} | {:error, String.t()}

Make sure that the source of an embed is an address or the path of an HTML file

This function is the custom type of the first argument. An address starts with https:// or http://, and it has no space and no quotation mark. A path ends with .html or .htm. The function does not read the file, so a missing file gives an error at render time, as for an image.

iex> Expresso.Element.Embed.source("https://example.com/page")
{:ok, "https://example.com/page"}

iex> Expresso.Element.Embed.source("pages/demo.html")
{:ok, "pages/demo.html"}

iex> {:error, _message} = Expresso.Element.Embed.source("javascript:alert(1)")

sources(deck)

@spec sources(Expresso.Deck.t()) :: [%{kind: String.t(), value: String.t()}]

Return the source of each embed of a deck, in the order of their numbers

An address gives %{kind: "src", value: address}. A local file gives %{kind: "srcdoc", value: text}, and the function reads the file through Expresso.DeckFile, so the watch mode renders the deck again after a change to the file. The function raises for a file that it cannot read.