HTML shapes

An HTML shape is a small web page that lives on the board: a calculator, a chart, a quiz, a mini game. Anything a web page can do, it can do inside its box.

• Code: it holds its own HTML, CSS, and JavaScript and runs them in a sandbox. The page can load libraries and data from the internet, but it can't reach the board or your logins on other sites. Turn on Show code and the code sits in a panel beside the shape, where every edit re-runs the page.
• Built by agents: an agent writes the page. Tell it which values you want to change later, such as a title, a color, a number, or an image, and they show up as settings in the HTML State section of the Attributes panel. The shape then works like a template that you duplicate and configure copy by copy, without reading a line of code.
• Animation: the settings in HTML State can change over time with an Attributes Animation, and the page redraws on every frame. A chart's values can grow, or a color can shift, while the animation plays.
• Memory: the page can save values, such as a score, a choice, or a setting, as its HTML State. Those values are saved with the board, belong to that one copy, survive a reload, and reach collaborators as they change. Anything the page doesn't save is lost when it reloads.
• Cover: it rests behind a picture and wakes up when activated, because a running web page costs far more than a drawing. The Cover section decides when it wakes.
• Outside the board: Download HTML saves a working .html file, with its settings and attached files inside, that runs in any browser without the board. Open in new tab runs the page on its own in a browser tab, away from the rest of the board, which suits heavy pages.

Creating an HTML shape

An HTML shape reaches the board in one of four ways: written by a connected agent, drawn with the HTML shape tool, pasted from HTML source, or converted from a file card that holds an HTML file.

Asking an agent

A shape written for you.

• Operation: connect an agent, see Connect board to AI, describe the page you want, and name the values you want to change from the board later.
• Result: the agent creates the shape with the complete code and places it. Later it can rewrite the code, change the settings, and attach or replace files, while the shape stays where it is.
• Tip: ask it to describe each setting, so its tooltip explains what it does, and to accept attached files if people should add their own. A value you want to animate, such as a number a chart draws, has to be a setting too. See Defining settings.

Drawing one with the tool

A starter page placed by hand.

• Operation:
  1. Pick HTML shape in the board objects multi-button of the Tools panel.
  2. Click where the shape should go for a default size, or drag to draw the box the page will occupy.
• Result: a shape showing a "Hello World" heading, with its code panel open on its left, ready to be edited or handed to an agent. The panel does not take space from the box you drew.
• Tip: while the tool is active, the Attributes panel sets the defaults for the next shape: its activation, whether the code panel opens and on which side, the panel's background, gutter, line numbers, wrapping, and typography, and the shape's stroke and corners.

Pasting HTML source

A shape made from the code of a page copied somewhere else.

• Operation: copy the source of a web page, or a self-contained piece of HTML with every tag closed, and paste it on the board while nothing is being edited.
• Needs: HTML that stands on its own, with every tag closed and no text outside the tags, up to 1,000,000 characters. Other pasted text becomes a different kind of shape. See Pasting.
• Result: a shape of the default size running the pasted HTML, with its code panel closed. Its Activation is Manual, so it waits for your click before it runs.

Converting a file card

A shape made from an HTML file that is already on the board as a card.

• Operation: select one or more file cards that hold .html or .htm files and click Convert to HTML in the Actions panel.
• Result: a shape of the default size centered on each card, running its file, with Activation Auto and the code panel closed.

Waking the shape

The page only runs while the shape is awake. The rest of the time the shape shows a picture and costs nothing. Activation, in the Cover section, sets when it wakes.

• At rest: the shape shows its cover, or, without one, a card with its name ("HTML shape" when it has none). A hand button sits over either, as long as the shape has code. Clicking it wakes the shape without entering it.
• Auto: pages that animate cost more than pages that only lay out text and images, and the HTML options section warns with Animated HTML detected.
• Manual: choosing it puts a running shape to rest at once. A woken shape also goes back to rest when its code is replaced.
• On a crowded board, when more Auto shapes want to run than the device can afford:
  • The ones nearest the center of the view run, and the rest wait behind their covers.
  • Animated pages get fewer places than static ones.
  • The choice is made once the view stops moving, and a shape you were using in the last 30 seconds keeps its place.
  • Active shapes always run and never take part in the choice.

Interacting

You can use an HTML shape in two ways. It works as a shape by default, and you enter it to use the page:

• As a shape: you select it to change its attributes, move it, and resize it, as with any other shape. The page shows but doesn't respond, and the scroll wheel moves the board.
• As a page: you click and drag what's inside it, type, and scroll it, as in a browser tab.
  • Entering, in one of three ways:
    • Double-click the shape.
    • Select it and click Enter edit mode in the Actions panel.
    • With the Explore canvas tool, click it once, selected or not, as in the Player.
  • While in it: the shape wakes if it was resting, and an outline marks it. The wheel scrolls the page and stops at its end without moving the board. A pinch still zooms the board.
  • Leaving: click an empty part of the board to use it as a shape again.

The values the page saves to its HTML State are kept as you use it, one undo step per stretch of editing, and each copy keeps its own. Anything else you do in the page, such as text in a field it doesn't save, is lost when it reloads.

Editing the code

Changes the HTML, CSS, and JavaScript the shape runs.

• Operation:
  1. Turn on Show code in the HTML options section. A shape drawn with the tool already has it on.
  2. Click the code panel to start editing, or double-click the shape.
  3. Type or paste the code.
  4. Click on empty board to finish.
• Needs: an upright shape. A rotated shape shows its code read only.
• Result: after a short pause in typing, the page re-runs with the new code and fades to the new version without going blank.
  • Code that fails at runtime shows an HTML shape error on the shape.
  • A version that takes long to load shows Preview update delayed while the previous one stays visible.
  • The panel works like code text fixed to HTML, with the same aids: highlighting, bracket closing, autocompletion, folding, and syntax errors marked in the gutter while it shows.
• Arranging the panel: its header shows the shape's name and moves the panel above, below, left, or right of the page, as Code position in HTML options does, and Hide code closes it. The Code and Text Style sections set its look.
• Tip: the panel is part of the shape. It shows in the Player and in exports while Show code is on, so turn it off when the code is not meant to be seen.

Configuring a shape

Changes what an HTML shape shows or does without editing its code. Its settings are the values and files its source code defines as settings, such as a title, a color, or an image, and they show in the HTML State section of the Attributes panel.

Changing a setting

• Operation:
  1. Select one HTML shape.
  2. In the HTML State section, change a setting.
• Result: the running page updates at once, without reloading. The new value is saved with the board and belongs to this copy only. The page can also change a setting itself, such as a score while people play, and the section shows the new value.
• Tip: hover a setting's name, or a toggle's icon, to read what it does, when the code describes it.

Each setting shows the control that fits it:

• Text: a text field.
• Number: a number field.
• Toggle: an on and off switch, with its own icon when the code gives it one.
• Color: a color picker, for an opaque color whose name has the word "color" or "colour" in it, such as bgColor.
• JSON: an editor for lists and objects.
• File: a row with the file's name and size, a button to replace it from your device, and a paste button for images. When the page accepts more files, Attach file adds one, and each file row gets a remove button.

Defining settings

Settings are defined in the shape's source code:

• Values: the code makes a value a setting by storing it in the shape. A value written straight into the code, such as a color typed into its CSS, changes only by editing the code.
• Files: each file attached to the shape is a File setting, which the code reads by name. One line in the code lets people attach and remove their own files.
• Descriptions and icons: the code can describe each setting, shown when you hover its name, and give toggles their own icon.

Writing the code yourself shows the code for each of these.

Using a shape as a template

One HTML shape can be repeated across the board, each copy with its own content: the same chart with different data, or the same card with a different title and photo.

• Duplicate the shape, then change each copy's settings. The copies start with the same code, so they look and work alike, and each one shows its own content.
• When the code of several copies is rewritten at once, each copy keeps its settings.
• Number, toggle, color, and text settings can also be animated. See Animating HTML shapes.

Writing the code yourself

You can write the page without an agent. Inside the sandbox, the page finds an irakasi object that connects it to the shape:

• irakasi.data is the saved state, a plain object. It starts empty and arrives a moment after the page loads, so draw the page from irakasi.onDataChange(listener) rather than reading it once at load.

• irakasi.saveData(next) replaces the state. It returns false and saves nothing when next is not a plain object or is longer than 65,536 characters as JSON. Saves are grouped and sent every 200 milliseconds, and the page's own saves don't call onDataChange, so redraw after saving.

• irakasi.assets lists the attached files by name, with their type and size, and irakasi.onAssetsChange(listener) reports every change. irakasi.readAsset(name) returns a promise of the bytes of one file as an ArrayBuffer. The promise fails when the file is unknown, not ready yet, or can't be fetched.

• <meta name="irakasi-allow-file-attachments" content="true"> in the head lets people attach and remove files from the HTML State section. Without it, the files already attached can be replaced, but not removed, and no new ones can be added.

• A script of type application/json with the data-irakasi-state-fields attribute describes the fields for the HTML State section. Each key is a saved value or an attached file name, with:

  • an optional description of up to 400 characters; a longer one is left out;
  • for toggles only, an inline SVG icon of up to 4,096 characters that starts with <svg.

  A declaration longer than 16,384 characters, or that isn't valid JSON, is ignored. A declared value shows as a field only once the page has saved it.

<script type="application/json" data-irakasi-state-fields>
	{
		"autoRotate": {
			"description": "Spin the model continuously.",
			"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"M20 7v5h-5M20 12a8 8 0 1 0-2 5\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\"/></svg>"
		},
		"model": { "description": "The GLB file the viewer loads." }
	}
</script>

Runtime errors do not reach the board: they show as an HTML shape error on the shape.

Exporting an HTML shape

• An image export, a print, or a copy as an image pictures the running page, through a capture of this tab that your browser asks you to approve. A resting shape, or one whose capture you decline, draws its cover, or the resting card when there is none.
• A GIF or video export records the running page frame by frame. A shape that is resting or doesn't start in time, or whose tab capture you decline, shows its cover in every frame.
• An open code panel is drawn beside the page, with the same highlighting the board shows.

Sizing

• The handles resize the box freely. The page lays itself out for the new size, as a web page does for a window.
• Locked Ratio keeps the proportions of the box.
• The code panel, when open, sits outside the box. Its length follows the side it sits on, and dragging its outer edge sets its width, from 320 to 1,600. Scale, in the Code section, shrinks or enlarges the whole panel.

Content scale

A web page lays itself out for the size of the window it's shown in. In an HTML shape, that window is the box: at a content scale of 1, the page sees a screen exactly the box's size. A small box then works like a tiny screen, so a page may show little of itself, or switch to its phone layout.

Scale, in the Fill section, sets the page's window apart from the box:

• Below 1: the page gets a window larger than the box, and is drawn smaller to fit. At 0.5, a 400 by 300 box shows the page as if on an 800 by 600 screen.
• Above 1: the page gets a smaller window, and is drawn larger, to enlarge text and controls that come out too small.
• The shape keeps its size on the board either way; only the page inside changes.

Attributes

A selected HTML shape shows these sections of the Attributes panel.

Selection info

The attributes that affect the shape as a whole.

• X: the horizontal position of the shape's pivot. Inside a frame, it's measured from the frame.
• Y: the vertical position of the pivot, also measured from the frame inside one. Which way it grows depends on the Y axis direction in the UI settings.
• W: the width of the shape.
• H: the height of the shape.
• Rotation: the angle around the pivot.
• Opacity: the transparency of the whole shape, stroke and fill included.
• Corners radius: rounds the corners of the shape.
• Locked Ratio: keeps the proportion between width and height while resizing.
• Proportional: scales the stroke width, dashes, hatching, and tiles along with the shape, so a resized shape keeps its look.

Cover

When the shape wakes up, and the picture shown while it rests.

• Activation: when the content runs.
  • Active: runs whenever the shape is visible.
  • Auto: runs when the device has capacity for it.
  • Manual: waits for a click on the shape, and goes back to rest when the shape leaves the visible canvas.
  • On devices with little memory, web embeds and HTML shapes wait for a click whatever their Activation. In the Player, phones and tablets always wait for a tap.
• Cover: the image shown while the content rests.
  • Capture: takes the cover from the content itself.
  • Choose image: uses an image file from your device as the cover.
  • Paste image from clipboard: uses the image in the clipboard as the cover.
  • Remove cover: clears the cover. Shown once the shape has a cover.
  • Once the shape has a cover, Capture reads Recapture and Choose image reads Replace. Capture works with one shape selected, and puts a running shape to rest.
• For provider videos only:
  • Hide player interface in captures: replays the video silently before capturing, so the player's controls and overlays fade out of the cover.

HTML options

The code panel and its position.

• Show code: opens the source panel with the shape's HTML next to it.
• Code position: which side of the shape the source panel sits on. Shown while Show code is on.
  • Top
  • Bottom
  • Left
  • Right
• Animated HTML detected: a warning that the page keeps moving while it runs, which costs more than a still page. On a crowded board, animated pages get fewer places to run.
  • When it's checked: while the page runs, a couple of seconds after it loads and then from time to time, sooner after you click or type in it.
  • What counts as moving: a CSS animation that repeats forever, redrawing 30 or more times a second, a timer that fires more often than once a second, or a playing video or sound. Animated images, such as GIFs, don't count.
  • Remembered: the result is saved with the shape, so it applies the next time the page wakes. Code with no scripts, animations, or media is never checked and never warns.

HTML State

The settings and files of the page, editable one by one.

• Fields: one row per saved value, in the order the shape saved them, each with the control that fits its value.
  • Text: a text field.
  • Number: a number field.
  • Toggle: an on or off switch, with the custom icon when the code declares one.
  • Color: a color picker, for text values that hold an opaque color when the field's name has the word "color" or "colour" in it, such as bgColor. Translucent colors, and colors under other names, stay as text.
  • JSON: a JSON editor, for objects and lists. A value that cannot be edited as JSON is shown disabled with an explanation.
• Files: one row per attached file, showing its reference name, a file button, the file name, and its size. The reference name is the one the code uses and cannot be changed here.
  • Replace: the file button; click it to swap the file for another one from your device. Its tooltip names the file by its reference name.
  • Paste image from clipboard: for image files, replaces the file with the image in the clipboard.
  • Remove: deletes the file.
  • Attach file: adds a new file, up to twelve in total.
• Remove and Attach file need the shape's code to accept additional files. Every attached file can always be replaced.

In the Player, and on any board you cannot edit, HTML shapes stay interactive but nothing entered in them is saved.

Code

The look of the code panel. Shown while Show code is on.

• Language: the language used for syntax highlighting: Plain text, JavaScript, HTML, CSS, JSON, Python, or Markdown. HTML shapes always use HTML.
• Background: the background color of the source panel. Shown by HTML shapes and camera lens panes; the box of code text is colored in its Fill section.
• Line numbers: shows a number beside each line. Shown while the gutter is on.
• Line wrapping: wraps long lines instead of scrolling sideways.
• Gutter: shows the strip with line numbers, fold markers, and error markers beside the code. Hidden, the code keeps its place.
• Scale: shrinks or enlarges the whole source panel beside the shape, from 0.1 to 4. Shown for a selected HTML shape or camera lens pane.

Text Style

The typography of the code panel. Shown while Show code is on.

Font style and family

• Font style: the family of typefaces to choose from.
  • Sans Serif: plain letterforms without finishing strokes.
  • Serif: letterforms with finishing strokes, as in print.
  • Handwriting: letterforms that look written by hand.
  • Mono: every character takes the same width, as in code.
  • Display: decorative typefaces for titles.
• Font family: the typeface, within the chosen style.

Font variant

• Font variant: the weight or slant of that typeface.

Font size

• Font size: the size of the text.

Letter spacing

• Letter spacing: for text on a path, the extra space between characters along the path.
• Line height: the space between lines.

Stroke

The line around the box: none, solid, or dashed.

• Stroke style: the kind of line. The style decides which of the controls below appear.
  • No stroke: no line at all. Arrows don't offer it.
  • Solid stroke: a continuous line.
  • Dashed stroke: a line made of dashes.
• Stroke color: the color of the line.
• Stroke opacity: the transparency of the line alone.
• Stroke width: the thickness of the line.

Dashed stroke

Fill

The zoom and transparency of the page. The page draws its own background, so there is no fill color.

• Scale: how big the page thinks its window is, from 0.1 to 100. At 1 the page lays itself out for the shape's own size. Lower it to fit more of the page, drawn smaller; raise it to enlarge text and controls that come out too small.
• Fill opacity: the transparency of the page.

Filter

A chain of SVG filter primitives applied to how the shape is drawn: the running page, its cover, the resting card, and exports alike. See Shape filters.

• Changing the filter never reloads the page, so nothing typed in it is lost.
• A page that embeds another site inside it may show that inner part unfiltered.

Mask

An HTML shape can be masked. See Masks.

Actions

Besides the actions every shape has, covered in What every shape shares, an HTML shape offers these in the Actions panel.

Download HTML

Saves the shape as one file that opens in any browser.

• Operation: click Download HTML.
• Needs: a single HTML shape whose attached files have finished uploading.
• Result: an .html file named after the shape, with the code, the current settings, and the attached files written into it, so it works from disk without the board. The shape on the board is not changed.
  • Libraries the code loads from the internet still need a connection.
  • Whatever you enter in the downloaded page lasts until you close or reload it; opening the file again starts from the settings it was saved with.

Open in new tab

Runs the page by itself in a browser tab.

• Operation: click Open in new tab.
• Needs: attached files that have finished uploading.
• Result: a tab running a copy of the page with the settings and files it had at that moment. What you do in the tab stays in the tab and never comes back to the board.

Convert to Image

Replaces the shape with a picture of it as shown, which draws faster but is no longer interactive.

• Operation: click Convert to Image. A dialog lists what the conversion loses, and you confirm with Convert.
• Needs: for a running shape, the browser's permission to take a screenshot of the tab, the only way to photograph its page. See Convert to Image. Close the code panel first unless you want it in the picture.
• Result: one image in place of the shape, at up to double resolution, as a JPEG when the picture is opaque or a PNG when it needs transparency.
  • The stroke, corners, filter, and mask carry over.
  • A resting shape, or one whose screenshot you decline, converts from its cover, or from the resting card when there is none.
  • Position, rotation, scale, resize, and opacity animations move to the image, and attribute animations are dropped.
• Tip: a running shape is captured first: the view jumps to it and the screen may flicker, so wait until the board is back. After that, an empty image marks its place while it is saved, and the original stays untouched, so you can keep working.

Player interaction

• Activation: the shape wakes as set in its Cover section. On phones and tablets it always waits for a tap anywhere on its cover, which also starts using the page.
• Using the page: one click or tap on a running shape uses its page directly. A button inside it works on the first click, and the shape becomes the one you interact with.
• Scroll wheel: a wheel over the shape moves the board until you click inside it. After that, it scrolls the page and stops at its end without moving the board.
• Starting fresh: nothing typed or chosen in the page is saved, so every viewing starts from what the board holds.
• Code panel: it shows, read only, while Show code is on.

Animating HTML shapes

• Like any other shape: it can be moved, rotated, scaled, resized, and faded in or out. An opacity animation fades the whole shape, page included. See Transforming shapes and Revealing and hiding shapes.
• Through its settings: Attributes Animation changes its HTML State settings over time, and the page redraws on every frame. The animation then reaches inside the page: a chart's bars grow, a counter counts up, or a scene changes color as the timeline plays.
  • Numbers count, colors blend, and toggles and text switch halfway.
  • Lists, objects, and files can't be animated.
  • The same block can animate its stroke, corners, and opacity.

Limits

• The code is limited to 1,000,000 characters, the saved state to 65,536 characters, and the attached files to 12 of up to 25 MB each, with names of up to 64 characters.
• The sandbox runs scripts and nothing else: no form submission, no popups, no dialogs such as alerts, and no access to the board or to other sites' cookies. Libraries can still load from the internet.
• An HTML shape cannot be flipped and cannot be used as a mask.