This repository has been archived by the owner on Sep 27, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
demo.html
771 lines (602 loc) · 20.8 KB
/
demo.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
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
<!DOCTYPE html>
<html lang="en">
<head>
<title>RetroV Demo and Tutorial</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
body {
background: #000; color: #FFF;
font-size: 18px;
max-width: 700px;
margin: auto;
}
a, a:hover, a:visited { color: #F0A; }
pre { padding: 1em; font-size: 0.8em; margin-left: 2em; overflow: auto; }
pre,code { color: #F4F; }
h2 { color: #acff47; margin-top: 2em; border-bottom: 2px solid #acff47; }
h3 { color: #47ffdd; margin-top: 3em; }
strong { color: #47ffdd; }
.container {
padding: 1em;
border: 1px solid #0cf;
margin-top: 10px;
}
.aqua {
background: #0CF; color: black; padding: 3px;
display: inline-block; margin: 5px;
animation: 0.5s attention;
position: relative; /* for attention anim */
border: 1px solid #000;
}
.orange {
background: orange; color: black; padding: 3px;
display: inline-block; margin: 5px;
animation: 0.5s attention;
position: relative; /* for attention anim */
border: 1px solid #000;
}
@keyframes attention { from { top: -5px; } to { top: 0; } }
.bold { font-weight: bold; }
button.toggle_state {
display: block;
background: #db01db;
margin: 10px;
color: white;
font-weight: bold;
border-style: none;
border-radius: 8px;
padding: 5px 8px;
float: right;
}
button.toggle_state:hover { background: #ff4aff; }
</style>
<script src="retrov.js"></script>
</head>
<body>
<center> <!-- A center tag! Now that's retro! -->
<h1>RetroV demo and tutorial</h1>
<img src="./retrov.svg" alt="RetroV 1970s colors svg logo">
</center>
<script>
function make_container(){
var script = document.currentScript;
var output = document.createElement('div');
output.className = "container";
script.after(output);
// script.parentNode.insertBefore(output, script);
window.test_container = output;
return output;
}
function toggle_state(c){
var after = false;
var states = c.states;
var btn = document.createElement('button');
btn.innerHTML = 'Toggle'; // "2" meaning "second"
btn.className = 'toggle_state';
btn.addEventListener('click', function(){
var s = after ? 'before' : 'after';
after = !after; //toggle
console.log("togglin' to ",s,states[s]);
RV.render(c, states[s]);
});
c.before(btn);
// c.append(btn);
}
var c; // re-used a bunch to hold example containers
</script>
<h2>Getting started</h2>
<p>You can add the RetroV library to a page
with nothing more than a script tag like so:
<pre>
<script src="retrov.js"></script>
</pre>
<p>This exposes a global <code>RV</code> object with a <code>render()</code>
method. The first render parameter is a target DOM element to render into. The
second parameter is an element or tree of "virtual node" data to be
rendered.<p>
<pre>
RV.render(document.body, 'Hello world.");
RV.render(document.getElementById('my_panel'), ['div', ...]);
</pre>
<p>RetroV can be used to render HTML from JavaScript once as a
template engine. Or it can be used to create interactive UIs with
functional "components".</p>
<p>The rest of this page is a series of increasingly interesting examples
that run live in the browser.</p>
<h3>Note</h3>
<p>This page makes heavy use of two utility functions. Both are part of this
page and have <em>nothing</em> to do with RetroV itself:
<ul>
<li><code>make_container()</code> creates a <div> and returns a
reference to it.</li>
<li><code>toggle_state()</code> creates a <strong>Toggle</strong> button
which renders "before" and "after" VNodes.</li>
</ul>
</p>
<p>With that out of the way, let's see some examples!</p>
<h2>Simple rendering</h2>
<h3>Text</h3>
<p>Strings and numbers are rendered as text nodes.</p>
<script data-mirror>
c = make_container();
RV.render(c, 'Hello world.');
</script>
<h3>HTML nodes</h3>
<p>In RetroV, an HTML tag is represented by an array with the tag name
as the first element of the array. Here is a paragraph tag with a
text node child:</p>
<script data-mirror>
c = make_container();
RV.render(c, ['p', 'Hello paragraph.']);
</script>
<h3>Arrays of siblings</h3>
<p>You can supply more than one element in an array. (<strong>Note:</strong>
you cannot have an array of strings because that would be indistinguishable
from an HTML tag.)</p>
<script data-mirror>
c = make_container();
RV.render(c, [
['p', 'Paragraph one.'],
['p', 'Paragraph two.'],
]);
</script>
<h3>Properties</h3>
<p>HTML tags can have a properties object as the second item. Let's make this
paragraph tag more interesting by assigning a class via the
<code>class</code> property.
After this object, any children follow as usual.</p>
<script data-mirror>
c = make_container();
RV.render(c, ['p', {'class': 'aqua'}, 'Classy paragraph.']);
</script>
<p>Note: Sharp-eyed JavaScript developers will recognize that 'class' is a reserved
word and is not used as the actual property in the JS interface to the DOM.
RetroV automatically converts
<code>class</code> to <code>className</code> (and <code>for</code> to <code>htmlFor</code>)
for you. You are welcome to use the second form directly.</p>
<h3>Class shorthand</h3>
<p>Because it's so common to apply a class name (or two) to
a tag, you can also use the "CSS selector" style shorthand
to apply one or more classes.</p>
<p>In addition, just a class name without a tag creates an
implicit <div>.</p>
<script data-mirror>
c = make_container();
RV.render(c, [
['span.aqua', 'aqua'],
['span.orange', 'orange'],
['span.orange.bold', 'orange bold'],
['.aqua', 'implicit div tag'],
]);
</script>
<h3>The style property</h3>
<p>Though <em>excessive</em> use of inline styles can get messy real fast,
sometimes they're unavoidable.</p>
<p>RetroV accepts a <code>style</code> property object containing the styles
you wish to set using standard JavaScript names (in which CSS properties
with hyphens are replaced with camelCase).</p>
<script data-mirror>
c = make_container();
RV.render(c,
['div', {
style: {
color: 'orange',
textShadow: '1px 1px #000, 3px 3px #0cf',
fontSize: '2em',
}},
"Fancy!"
]
);
</script>
<h3>HTML literals</h3>
<p>It is inevitable that you will eventually need to include a bit of raw
markup in your interface. RetroV supports this. If it detects that you have an
element name that starts with "<code><</code>...", it assumes the whole
string is raw HTML.</p>
<p>There are lots of ways to use this feature, including cloning another
element (and its children) by stealing its <code>innerHTML</code> content.</p>
<p><strong>Note:</strong> There are two caveats with this feature:
<strong>1.</strong> Only <em>one</em> top-level item will be created
(it can have as many children as you like).
<strong>2.</strong> For efficiency, the HTML will not be re-evaluated,
so modifying the HTML string and re-rendering won't do anything.
</p>
<script data-mirror>
c = make_container();
var svg_smiley = '<svg xmlns="http://www.w3.org/2000/svg" width="215.123" height="215.123" viewBox="0 0 56.918 56.918"><circle cx="28.459" cy="28.459" r="28.084" fill="#faf100" stroke="#070707" stroke-width=".75"/><ellipse cx="18.074" cy="20.509" rx="4.972" ry="7.382"/><ellipse cx="38.712" cy="20.509" rx="4.972" ry="7.382"/><path d="M11.739 38.311c7.173 11.435 26.554 11.585 33.419 0" fill="none" stroke="#070707" stroke-width="1.55"/></svg>';
RV.render(c, ['.aqua',
['<div style="font-size: 1.7em">Have a nice day!</div>'],
[svg_smiley],
]);
</script>
<h3>Nested HTML nodes</h3>
<p>So far, we've seen tags with just a single text node child.
But arbitrary HTML structures can be nested as children.</p>
<script data-mirror>
c = make_container();
RV.render(c,
['.aqua',
'Enjoy',
['.orange',
'those',
['.aqua', 'antique'],
],
['.orange',
['.aqua.bold', 'spicy'],
['.aqua', 'rats'],
],
]
);
</script>
<h2>Dynamic updates</h2>
<p>When you render more than once to the same DOM element, RetroV will check
for changes in the "virtual DOM" VNodes from the previous rendering and apply
any differences to the real DOM.</p>
<h3>Changing an HTML node property</h3>
<p>Here, the <code>class</code> (class) property is being updated.
Click the <strong>Toggle</strong> button to see the change applied.
Click it again to revert to the original state.</p>
<script data-mirror>
c = make_container();
c.states = {
before: ['div', {'class':'aqua'}, 'Hello world'],
after: ['div', {'class':'orange'}, 'Hello world'],
};
RV.render(c, c.states.before);
toggle_state(c);
</script>
<h3>Same, but with class shorthand</h3>
<p>Change class property via shorthand and implicit div tags.</p>
<script data-mirror>
c = make_container();
c.states = {
before: ['.aqua','Hello again'],
after: ['.orange','Hello again'],
};
RV.render(c, c.states.before);
toggle_state(c);
</script>
<h3>Adding an item to a list</h3>
<p>In the example below, a third <div> element is added to the
list. Clicking <strong>Toggle</strong> a <em>second</em> time removes the
element and so on.</p>
<p>Note how the new element "jumps" when it is added. This is done with
a CSS animation when the element is added to the DOM.
By watching which elements jump, you can see which nodes RetroV is
adding/replacing and which ones are being left alone.
(Property changes and text node changes won't make an element
jump, though. Only elements being added to the DOM.)</p>
<script data-mirror>
c = make_container();
c.states = {
before: [['.aqua','A'],['.orange','B']],
after: [['.aqua','A'],['.orange','B'],['.aqua','C']],
};
RV.render(c, c.states.before);
toggle_state(c);
</script>
<h3>Changing a sibling element in a list</h3>
<p>Since the middle item is being changed from an (implicit) div to
a span tag, it will be replaced completely. It will "jump" as
the new element replaces the existing one. Notice how the two
elements on either side remain untouched since they have not changed.</p>
<script data-mirror>
c = make_container();
c.states = {
before: [['.aqua','A'],['.aqua','B'],['.aqua','C']],
after: [['.aqua','A'],['span.orange','Q'],['.aqua','C']],
};
RV.render(c, c.states.before);
toggle_state(c);
</script>
<h3>Removing a sibling element from a list</h3>
<p>Completely removing an element from a list will cause all elements
after it to be re-evaluated. Since the tags alternate between divs and
spans, the new list won't line up with the old list and all the
following tags will end up being replaced entirely.</p>
<script data-mirror>
c = make_container();
c.states = {
before: [['.aqua','A'],['span.orange','B'],['.aqua','C'],['span.aqua','D']],
after: [['.aqua','A'],['.aqua','C'],['span.aqua','D']],
};
RV.render(c, c.states.before);
toggle_state(c);
</script>
<h3>"Nulling" a sibling element from a list</h3>
<p>On the other hand, replacing an element with the value <code>null</code>
will render an HTML comment placeholder, which keeps subsequent items lined up
in their original position.</p>
<p>Compare the "jumping" between this and the previous example. This one
is much more efficient since only the affected item is redrawn.</p>
<script data-mirror>
c = make_container();
c.states = {
before: [['.aqua','A'],['span.orange','B'],['.aqua','C'],['span.aqua','D']],
after: [['.aqua','A'],null,['.aqua','C'],['span.aqua','D']],
};
RV.render(c, c.states.before);
toggle_state(c);
</script>
<h3>"Nulling" a child</h3>
<p>You can use <code>null</code> anywhere you might otherwise have an element
(not just in an array, like above). Here, it is taking the place of several
child nodes. Notice how the last element does not jump since it is still in the
same child position.</p>
<script data-mirror>
c = make_container();
c.states = {
before: ['.aqua','Flowers',
['.orange','Roses'],
['.orange','Sunflowers'],
['.orange','Lavender'],
],
after: ['.aqua','Flowers',
null,
null,
['.orange','Lavender'],
]
};
RV.render(c, c.states.before);
toggle_state(c);
</script>
<h3>A <code>false</code> means "no change"</h3>
<p>This looks just like the <code>null</code> example above, except
with <code>false</code> in place of two of the items. The visual difference
is that the items remain. This is because as long as <code>false</code>
is given for a position, it will be <em>left alone</em>.</p>
<p>Note how the flowers "jump" when you click the <strong>Toggle</strong>
button a <em>second</em> time (as a non-false value is toggled back in).</p>
<p>See the Cookbook section below for an example of using <code>false</code>
to control rendering.</p>
<script data-mirror>
c = make_container();
c.states = {
before: ['.aqua','Flowers',
['.orange','Roses'],
['.orange','Sunflowers'],
['.orange','Lavender'],
],
after: ['.aqua','Flowers',
false,
false,
['.orange','Lavender'],
]
};
RV.render(c, c.states.before);
toggle_state(c);
</script>
<h3>Special event: <code>oncreate</code></h3>
<p>It <em>should</em> be fairly rare, but sometimes you cannot avoid
directly manipulating DOM elements. RetroV has a special pseudo-event
called <code>oncreate</code> which takes a function. When the actual
DOM element for that virtual element is created and attached to the
DOM, the function is called and passed a reference to the element.
</p>
<p>In this example, we want to animate a div by manipulating the
element directly. We <em>could</em> do this by re-rendering the
entire scene through <code>RV.render()</code>, but that would be
wasteful.</p>
<script data-mirror>
c = make_container();
function twitchy_start(elem){
var twitch=false;
setInterval(
function(){
elem.style.marginLeft = (twitch?'10px':'0');
twitch=!twitch;
},
800, // fraction of a second
);
}
RV.render(c, ['.twitchy',
{
oncreate: twitchy_start,
},
'Twitchy Div!',
]);
</script>
<h2>Cookbook</h2>
<p>Ideas for solutions to common problems.</p>
<h3>Rendering with simple nested functions</h3>
<p>Here you can see that I've broken down the task of drawing lists of
numbers into drawing the list and drawing the numbers. It's a silly
example, of course, but the principle applies nicely to a larger and
more complex interface.</p>
<p>It's worth pointing out that in this case, RetroV doesn't know anything
about these functions. It's just seeing the returned data they generate.</p>
<script data-mirror>
c = make_container();
function draw_number(num){
return ['.orange', num];
}
function draw_number_list(num1, num2){
return ['.aqua',
draw_number(num1),
draw_number(num2),
];
}
RV.render(c,
['.orange', 'My number lists:',
draw_number_list(42, 13),
draw_number_list(11, 999),
]
);
</script>
<h3>Rendering with higher-order functions</h3>
<p>Creating interfaces by generating data also plays extremely well with
<em>functional programming</em> concepts, such as using <code>map()</code> to
render an array with a function.</p>
<p>(Map is a higher-order function because it takes another function
as input.)</p>
<script data-mirror>
c = make_container();
var fruits = [
'Apple',
'Pear',
'Lime',
'Strawberry',
];
function draw_fruit(num){
return ['.aqua', num];
}
RV.render(c, ['.orange', 'My fruit:', fruits.map(draw_fruit) ]);
</script>
<h3>Storing state in function closures</h3>
<p>RetroV is built with the philosophy that storing and updating state
should be separate from rendering the result of that state.</p>
<p>Thus, "components" which track a <em>lot</em> of state are antithetical to
the intention of RetroV. Having said that, it is nice to be able to
keep track of simple things locally sometimes.</p>
<p>Note that the <code>feed()</code> function in this example doesn't
just update the counter, it also re-renders <em>everything</em>.
The whole point of using a VDOM is to let the library detect changes
and efficiently perform only the updates that are needed.</p>
<script data-mirror>
// This example needs a unique container variable.
var c1 = make_container();
function Animal(name, color){
var fed = 0;
function feed(){
console.log("feed:",fed);
fed++;
render_animals();
}
return function draw_animal(){
return ['div', {'class':color},
name + ' has been fed: ' + fed +
(fed === 1 ? ' time.' : ' times.'),
['button', {onclick:feed}, 'Feed'],
];
};
}
var tiger = Animal('Tiger', 'orange');
var fish = Animal('Fish', 'aqua');
function render_animals(){
RV.render(c1, [tiger(), fish()]);
}
render_animals();
</script>
<h3>Controlling rendering with <code>false</code></h3>
<p>You may wish to have a section of a page only render
(or <em>stop</em> rendering) when some condition has been met.</p>
<p>This example has a "component" that renders exactly twice. It does
this by returning <code>false</code> after the second render.</p>
<p>Noticec how the area's render counter will continue to go up, but the
"component" will stop incrementing at 2.</p>
<script data-mirror>
// This example needs a unique container variable.
var c2 = make_container();
function RendersTwice(){
var render_count = 0;
return function draw(){
render_count++;
if(render_count > 2){
return false;
}
return ['.aqua', 'Renders Twice: ' + render_count];
};
}
var area_render_count = 0;
var renders_twice = RendersTwice();
function render_area(){
area_render_count++;
RV.render(c2, ['.orange', 'Area rendered: ' + area_render_count,
renders_twice(),
['button', {onclick:render_area}, 'Re-Render'],
]);
}
render_area();
</script>
<h3>Text input</h3>
<p>This isn't a special technique, but just an example of an extremely
common interaction that deserves an example somewhere.</p>
<p>There are countless ways to add abstraction to handle the tedious
redundancy of form elements. This example does not demonstrate any.</p>
<p>Keep in mind that RetroV is a rendering library. It has absolutely no
opinion about how you save/load/update data.</p>
<script data-mirror>
// This example needs a unique container variable.
var c3 = make_container();
var my_data = {
name: "Nothing",
age: 0,
};
function update_name(e){
my_data.name = e.target.value;
render_form();
}
function update_age(e){
my_data.age = e.target.value;
render_form();
}
function render_form(){
RV.render(c3, ['form.aqua',
['label', 'Name:',
['input', {
type: 'text',
value: my_data.name,
oninput: update_name,
}],
],
['label', 'Age:',
['input', {
type: 'text',
value: my_data.age,
oninput: update_age,
}],
],
['p', '"I am ' + my_data.name + ', ' + my_data.age + ' years old."'],
]); // end of form
}
render_form();
</script>
<h3>Element focus</h3>
<p>The <code>oncreate</code> pseudo-event is one of the few ways to
make sure certain dynamic properties such as input focus are handled
correctly on a page in certain circumstances.</p>
<p>This particualr example is silly, but it's the sort of real problem
that crops up in interfaces all the time.</p>
<script data-mirror>
c = make_container();
var my_input = null;
function input_created(elem){
my_input = elem;
}
function focus_input(){
my_input.focus();
}
RV.render(c, ['.orange',
['input', {oncreate:input_created}],
['button', {onclick:focus_input}, 'Focus the input'],
]);
</script>
<br><br>
<!-- End of Demo/Tutorial content! -->
<script>
// This helper displays the source of script tags:
/*/ The Mirror of Galadriel 2
* Copyright 2023 Dave Gauer (ratfactor.com)
* Released under the MIT License.
/*/
document.addEventListener("DOMContentLoaded", function(e) {
var scripts = document.querySelectorAll('script[data-mirror]');
if(scripts.length<1){
console.log("Galadriel's Mirror 2: No scripts with data-mirror found.");
}
scripts.forEach(function(script){
// remove initial blank line from script (if any)
var text = script.innerHTML
.replace(/^\r?\n/, '')
.replaceAll('<', '<')
.replaceAll('>', '>');
// create <pre> to mirror text contents
var mirror = document.createElement('pre');
mirror.innerHTML = text;
script.parentNode.insertBefore(mirror, script);
});
});
</script>
</body>
</html>