Fork me on GitHub

p5.js-widget

This is a reusable widget that makes it easier to embed editable p5.js sketches in blog posts, interactive curricula, and other places.

Table of Contents

  1. Quick Start
  2. Autoplay
  3. Autosave
  4. Implicit setup()
  5. Error Handling
  6. Resizing
  7. Specifying The p5 Version
  8. Specifying The Base URL
  9. Loading From An External File
  10. Using the Widget with Wordpress

Quick Start

To use this widget, add the following script to your page:

The script will then automatically transform all script tags of type text/p5 on the page into editable widgets, like so:

Autoplay

Note that by default, the sketch will not start playing automatically. This can be changed via the data-autoplay attribute like so:

Autosave

The widget automatically saves the current editor content in the current page session, and restores it on page load. From the Mozilla Developer Network:

A page session lasts for as long as the browser is open and survives over page reloads and restores. Opening a page in a new tab or window will cause a new session to be initiated.

This generally means that if a user accidentally navigates away from the page, their work won't be lost if they navigate back to it via their browser's back/forward buttons or its undo closed tab functionality.

Users always have the freedom to revert the widget's code to its initial state (i.e., the code specified by the embedding page) via the "Revert" button on the toolbar.

In some cases, the above behavior may be undesirable. If you want to be able to disable it or otherwise configure it to behave differently, please feel free to file an issue.

Implicit setup()

It can be quite difficult for beginners to understand the concept (and syntax) of functions, so the widget will automatically wrap the user's code in a setup() function declaration behind the scenes if needed:

Error Handling

The widget is intended to be resilient against various types of user error. In the future, we'd like to improve the widget to provide more friendly errors.

Here's what happens when the sketch has runtime errors. Note that the exact description of the error is browser-specific and can't be changed.

Here's what happens when the sketch has syntax errors (which prevent the sketch from running entirely). Currently, the syntax errors are browser-specific, though this may change in the future.

Here's what happens when the sketch is in a loop for more than one second (which is a good indication that the user has accidentally written an infinite loop). The message is not browser-specific.

Resizing

The height of the widget (and consequently the sketch preview pane too) defaults to px and can be changed via the data-height attribute like so:

The width of the widget is always set to the full width of its container element.

The width of the sketch preview pane defaults to px and can be set via the data-preview-width attribute like so:

Specifying The p5 Version

Currently, the widget defaults to using p5 version , but this will change as new versions of p5 and this widget are released.

It's possible to optionally specify the p5 version to use in your widget via the data-p5-version attribute:

<script type="text/p5" data-p5-version="0.2.0">

A complete list of available versions can be found at cdnjs.com/libraries/p5.js.

Specifying The Base URL

By default, the widget will set the base URL of the sketch to the URL of the page embedding the widget. This means that if you're embedding this widget at http://example.org/index.html and have the following code in your sketch:

loadJSON('foo.json');

The actual URL retrieved will be http://example.org/foo.json.

If you'd like to override this default, you can specify a custom base URL with the data-base-url attribute like so:

<script type="text/p5" data-base-url="http://some-other-website.com/">

Loading From An External File

The src attribute can be used to load the widget's content from an external file instead of specifying it inline. For example, the following will load the widget's content from static/my-example.js:

If the URL is relative, then it will be retrieved relative to the URL of the embedding page. If it is absolute, then an attempt to retrieve it will be made; however, like many cross-origin network calls within p5 itself, the file must have Cross-Origin Resource Sharing (CORS) enabled, or it will not be retrieved successfully.

Using the Widget with Wordpress

To embed the widget on a Wordpress page, copy and paste the widget script into your page in "Text" mode as opposed to "Visual" mode. Then, enclose the widget script in <pre> tags. These <pre> tags instruct Wordpress to exactly reproduce whatever is inside of them without adding additional formatting. Here's what they look like wrapped around the widget script:

<pre>
<script type="text/p5">
function setup() {
  createCanvas(100, 100);
}

function draw() {
  background(255, 0, 200);
}

/* And so on... */
</script>
</pre>