forked from toolness/p5.js-widget
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
283 lines (226 loc) · 8.62 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
<!DOCTYPE html>
<meta charset="utf-8">
<meta name="viewport" content="width=768, initial-scale=1">
<link rel="stylesheet" href="static/vendor/prism.css">
<link rel="stylesheet" href="static/index.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.0/gh-fork-ribbon.min.css" />
<title>p5.js-widget</title>
<a class="github-fork-ribbon" href="https://github.com/toolness/p5.js-widget" title="Fork me on GitHub">Fork me on GitHub</a>
<h1>p5.js-widget</h1>
<p>
This is a reusable widget that makes it easier to embed editable
<a href="http://p5js.org">p5.js</a> sketches in blog posts,
interactive curricula, and other places.
</p>
<h2>Table of Contents</h2>
<ol>
<li><a href="#quick-start">Quick Start</a>
<li><a href="#autoplay">Autoplay</a>
<li><a href="#autosave">Autosave</a>
<li><a href="#implicit-setup">Implicit <code>setup()</code></a>
<li><a href="#error-handling">Error Handling</a>
<li><a href="#resizing">Resizing</a>
<li><a href="#specifying-p5-version">Specifying The p5 Version</a>
<li><a href="#base-url">Specifying The Base URL</a>
<li><a href="#src">Loading From An External File</a>
<li><a href="#wordpress">Using the Widget with Wordpress</a>
</ol>
<h2 id="quick-start">Quick Start</h2>
<p>
To use this widget, add the following script to your page:
</p>
<pre><code class="language-markup" id="script-tag-example"></code></pre>
<p>
The script will then automatically transform all script tags of
type <code>text/p5</code> on the page into editable widgets, like so:
</p>
<script type="text/p5">
function setup() {
createCanvas(100, 100);
}
function draw() {
background(255, 0, 200);
}
</script>
<h2 id="autoplay">Autoplay</h2>
<p>
Note that by default, the sketch will <em>not</em> start playing
automatically. This can be changed via the <code>data-autoplay</code>
attribute like so:
</p>
<script type="text/p5" data-autoplay>
function setup() {
createCanvas(100, 100);
background(255, 0, 200);
}
</script>
<h2 id="autosave">Autosave</h2>
<p>
The widget automatically saves the current editor content in the
current <em>page session</em>, and restores it on page load.
From the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage">Mozilla Developer Network</a>:
</p>
<blockquote>
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.
</blockquote>
<p>
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 <a href="http://www.computerhope.com/tips/tip16.htm">undo
closed tab</a> functionality.
</p>
<p>
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.
</p>
<p>
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
<a href="https://github.com/toolness/p5.js-widget/issues/new">file
an issue</a>.
</p>
<h2 id="implicit-setup">Implicit <code>setup()</code></h2>
<p>
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 <code>setup()</code> function declaration
behind the scenes if needed:
</p>
<script type="text/p5" data-autoplay>
background(255, 0, 200);
</script>
<h2 id="error-handling">Error Handling</h2>
<p>
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
<a href="http://processing.toolness.org">friendly errors</a>.
</p>
<p>
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.
</p>
<script type="text/p5" data-autoplay data-hide-sourcecode>
function setup() {
// Reference a non-existent variable...
KABOOM
}
</script>
<p>
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.
</p>
<script type="text/p5" data-autoplay data-hide-sourcecode>
// Syntax error (no parentheses after function name)
function setup {
}
</script>
<p>
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 <em>not</em> browser-specific.
</p>
<script type="text/p5" data-hide-sourcecode>
function setup() {
// Infinite loop!
while (true) {}
}
</script>
<h2 id="resizing">Resizing</h2>
<p>
The height of the widget (and consequently the sketch preview pane too)
defaults to <span data-insert-default="HEIGHT"></span>px and can be changed
via the <code>data-height</code> attribute like so:
</p>
<script type="text/p5" data-height="600"></script>
<p>
The width of the widget is always set to the full width of its
container element.
</p>
<p>
The width of the sketch preview pane defaults to
<span data-insert-default="PREVIEW_WIDTH"></span>px and can be set
via the <code>data-preview-width</code> attribute like so:
</p>
<script type="text/p5" data-autoplay data-preview-width="400">
function setup() {
createCanvas(300, 100);
background(255, 0, 200);
}
</script>
<h2 id="specifying-p5-version">Specifying The p5 Version</h2>
<p>
Currently, the widget defaults to using p5 version
<span data-insert-default="P5_VERSION"></span>, but this will change
as new versions of p5 and this widget are released.
</p>
<p>
It's possible to optionally specify the p5 version to use in your
widget via the <code>data-p5-version</code> attribute:
</p>
<pre><code class="language-markup"><script type="text/p5" data-p5-version="0.2.0"></code></pre>
<p>
A complete list of available versions can be found at
<a href="https://cdnjs.com/libraries/p5.js">cdnjs.com/libraries/p5.js</a>.
</p>
<h2 id="base-url">Specifying The Base URL</h2>
<p>
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
<code>http://example.org/index.html</code> and have the following
code in your sketch:
</p>
<pre><code class="language-javascript">loadJSON('foo.json');</code></pre>
<p>
The actual URL retrieved will be
<code>http://example.org/foo.json</code>.
</p>
<p>
If you'd like to override this default, you can specify a
custom base URL with the <code>data-base-url</code>
attribute like so:
</p>
<pre><code class="language-markup"><script type="text/p5" data-base-url="http://some-other-website.com/"></code></pre>
<h2 id="src">Loading From An External File</h2>
<p>
The <code>src</code> 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
<code><a href="static/my-example.js">static/my-example.js</a></code>:
</p>
<script type="text/p5" src="static/my-example.js"></script>
<p>
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 <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS">Cross-Origin Resource Sharing (CORS)</a>
enabled, or it will not be retrieved successfully.
</p>
<h2 id="wordpress">Using the Widget with Wordpress</h2>
<p>
To embed the widget on a Wordpress page, copy and paste the widget
script into your page in <a href="https://codex.wordpress.org/Writing_Posts#Visual_Versus_Text_Editor">"Text" mode</a> as opposed to "Visual" mode. Then, enclose the widget script in <code><pre></code> tags. These <code><pre></code> 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:
</p>
<pre><code class="language-markup"><pre>
<script type="text/p5">
function setup() {
createCanvas(100, 100);
}
function draw() {
background(255, 0, 200);
}
/* And so on... */
</script>
</pre>
</code></pre>
<script src="static/vendor/jquery.js"></script>
<script src="p5-widget.js" data-manual></script>
<script src="static/vendor/prism.js" data-manual></script>
<script src="static/index.js"></script>