|
1 | | -# JavaScript reference |
| 1 | +# JavaScript |
2 | 2 |
|
3 | 3 | [Observable Markdown](./markdown) supports reactive JavaScript. JavaScript runs on the client, powered by the [Observable Runtime](https://github.com/observablehq/runtime). (In the future, JavaScript may also run during build to support data snapshot generation and server-side rendering.) |
4 | 4 |
|
5 | | -## Reactivity |
| 5 | +In addition to standard Markdown features — headings, formatting, tables, images, and the like — Observable Markdown supports reactive JavaScript that runs on the client. Live JavaScript can be expressed either as [fenced code blocks](#fenced-code-blocks) (<code>```js</code>) or [inline expressions](#inline-expressions) (<code>$\{…}</code>). |
6 | 6 |
|
7 | | -You may be accustomed to code running sequentially from top to bottom, and manually evaluating code in a notebook; Observable is different: we use [dataflow](https://en.wikipedia.org/wiki/Dataflow_programming), as in a spreadsheet, to *automatically* run code in topological order as determined by [top-level variable](#top-level-variables) references. For example, here we reference variables `x` and `y` even though they are defined in a code block below: |
| 7 | +### Fenced code blocks |
8 | 8 |
|
9 | | -```js show |
10 | | -x + y |
11 | | -``` |
12 | | - |
13 | | -When code (such as `x + y`) references variables (such as `x` and `y`) defined by other code, the *referencing* code automatically runs after the *defining* code. Since code runs independently of its order on the page, giving you the flexibility to arrange your code however you like. |
14 | | - |
15 | | -### Top-level variables |
16 | | - |
17 | | -A top-level variable declared in a JavaScript fenced code block can be referenced in another code block or inline expression on the same page. So if you say: |
18 | | - |
19 | | -```js show |
20 | | -const x = 1, y = 2; |
21 | | -``` |
22 | | - |
23 | | -Then you can reference `x` and `y` elsewhere on the page (with values ${x} and ${y}, respectively). Top-level variable declarations are effectively [hoisted](https://developer.mozilla.org/en-US/docs/Glossary/Hoisting); you can reference variables even if the defining code block appears later on the page, and code runs in topological rather than top-down document order. If multiple blocks define top-level variables with the same name, references to these variables will throw a duplicate definition error. |
24 | | - |
25 | | -To prevent variables from being visible outside the current block, make them local with a block statement: |
| 9 | +JavaScript fenced code blocks are typically used to display content such as charts and inputs. They can also declare top-level variables, say to load data or declare helper functions. An expression code block looks like this (note the lack of semicolon): |
26 | 10 |
|
27 | | -```js show |
28 | | -{ |
29 | | - const z = 3; |
30 | | -} |
| 11 | +````md |
| 12 | +```js |
| 13 | +1 + 2 |
31 | 14 | ``` |
| 15 | +```` |
32 | 16 |
|
33 | | -### Promises |
| 17 | +This produces: |
34 | 18 |
|
35 | | -When code refers to a promise defined in another code block, the referencing code implicitly awaits the promise. Most often, promises are used to load files, fetch data from a remote server, or query a database. As a contrived example, within the block below, `hello` is a promise that resolves via `setTimeout`; if you reference `hello` from another code block or expression, the other code won’t run until the timeout fires and will see `hello` as a string. |
36 | | - |
37 | | -```js show |
38 | | -const hello = new Promise((resolve) => { |
39 | | - setTimeout(() => { |
40 | | - resolve("hello"); |
41 | | - }, 1000); |
42 | | -}); |
43 | | -``` |
44 | | - |
45 | | -Hello is: ${hello}. |
46 | | - |
47 | | -### Generators |
48 | | - |
49 | | -When code refers to a [generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator) defined in another code block, the referencing code automatically runs each time the generator yields a value. Values that change over time, such as interactive inputs and animation parameters, are often represented as generators. For example, you can use [Observable Inputs](https://github.com/observablehq/inputs) and the built-in [`view` function](#view(input)) to construct a live text input. Try entering your name into the box below: |
50 | | - |
51 | | -```js show |
52 | | -const name = view(Inputs.text({label: "Name", placeholder: "Enter your name"})); |
| 19 | +```js |
| 20 | +1 + 2 |
53 | 21 | ``` |
54 | 22 |
|
55 | | -Name is: ${name}. |
56 | | - |
57 | | -The `view` function calls `Generators.input` under the hood, which takes an input element and returns a generator that yields the input’s value whenever it changes. The code above can be written more explicitly as: |
58 | | - |
59 | | -```js no-run |
60 | | -const nameInput = Inputs.text({label: "Name", placeholder: "Enter your name"}); |
61 | | -const name = Generators.input(nameInput); |
| 23 | +If the expression evaluates to a DOM node, the node is displayed. For example, here is an SVG element generated by [Observable Plot](https://observablehq.com/plot): |
62 | 24 |
|
63 | | -display(nameInput); |
| 25 | +````md |
| 26 | +```js |
| 27 | +Plot.lineY(aapl, {x: "Date", y: "Close"}).plot({y: {grid: true}}) |
64 | 28 | ``` |
| 29 | +```` |
65 | 30 |
|
66 | | -As another example, you can use the built-in `Generators.observe` to represent the current pointer coordinates: |
| 31 | +This produces: |
67 | 32 |
|
68 | | -```js show |
69 | | -const pointer = Generators.observe((notify) => { |
70 | | - const pointermoved = (event) => notify([event.clientX, event.clientY]); |
71 | | - addEventListener("pointermove", pointermoved); |
72 | | - notify([0, 0]); |
73 | | - return () => removeEventListener("pointermove", pointermoved); |
74 | | -}); |
| 33 | +```js |
| 34 | +Plot.lineY(aapl, {x: "Date", y: "Close"}).plot({y: {grid: true}}) |
75 | 35 | ``` |
76 | 36 |
|
77 | | -Pointer is: ${pointer.map(Math.round).join(", ")}. |
| 37 | +A program code block looks like this: |
78 | 38 |
|
79 | | -#### Mutable(*value*) |
80 | | - |
81 | | -Normally, only the code block that declares a top-level variable can define it or assign to it. (This constraint may helpfully encourage you to decouple code.) You can however use the `Mutable` function to declare a mutable generator, allowing other code to mutate the generator’s value. This approach is akin to React’s `useState` hook. For example: |
82 | | - |
83 | | -```js show |
84 | | -const count = Mutable(0); |
85 | | -const increment = () => ++count.value; |
86 | | -const reset = () => count.value = 0; |
| 39 | +````md |
| 40 | +```js |
| 41 | +const x = 1 + 2; |
87 | 42 | ``` |
| 43 | +```` |
88 | 44 |
|
89 | | -In other code, you can now create buttons to increment and reset the count like so: |
90 | | - |
91 | | -```js show |
92 | | -Inputs.button([["Increment", increment], ["Reset", reset]]) |
| 45 | +```js |
| 46 | +const x = 1 + 2; |
93 | 47 | ``` |
94 | 48 |
|
95 | | -<style type="text/css"> |
96 | | -@keyframes flash { |
97 | | - from { background-color: var(--theme-foreground-focus); } |
98 | | - to { background-color: none; } |
99 | | -} |
100 | | -.flash { |
101 | | - animation-name: flash; |
102 | | - animation-duration: 1s; |
103 | | -} |
104 | | -</style> |
105 | | - |
106 | | -Count is: ${htl.html`<span class="flash">${count}</span>`}. |
107 | | - |
108 | | -Within the defining code block, `count` is a generator and `count.value` can be read and written to as desired; in other code, `count` is the generator’s current value. Other code that references `count` will re-run automatically whenever `count.value` is reassigned — so be careful you don’t cause an infinite loop! |
109 | | - |
110 | | -## Displaying content |
111 | | - |
112 | | -A JavaScript fenced code block containing an expression will automatically display its value, as will an inline JavaScript expression. You can also manually display elements or inspect values by calling the built-in `display` function. |
113 | | - |
114 | | -### display(*value*) |
| 49 | +A program code block doesn’t display anything by default, but you can call the built-in [`display` function](./javascript/display) explicitly. The above block defines the top-level variable `x` with a value of ${x}. |
115 | 50 |
|
116 | | -If `value` is a DOM node, adds it to the DOM. Otherwise, converts the given `value` to a suitable DOM node and displays that instead. Returns the given `value`. |
| 51 | +(A technical note: the parser first attempts to parse the input as an expression; if that fails, it parses it as a program. So, code such as `{foo: 1}` is interpreted as an object literal rather than a block with a labeled statement.) |
117 | 52 |
|
118 | | -When `value` is not a DOM node, display will automatically create a suitable corresponding DOM node to display. The exact behavior depends on the input `value`, and whether display is called within a fenced code block or an inline expression. In fenced code blocks, display will use the [Observable Inspector](https://github.com/observablehq/inspector); in inline expressions, display will coerce non-DOM values to strings, and will concatenate values when passed an iterable. |
| 53 | +### Inline expressions |
119 | 54 |
|
120 | | -You can call display multiple times within the same code block or inline expression to display multiple values. The display will be automatically cleared if the associated code block or inline expression is re-run. |
| 55 | +Inline JavaScript expressions interpolate live values into Markdown. They are typically used to display dynamic numbers such as metrics, or to arrange visual elements such as charts into rich HTML layouts. |
121 | 56 |
|
122 | | -### view(*input*) |
| 57 | +For example, this paragraph simulates rolling a 20-sided dice: |
123 | 58 |
|
124 | | -As described above, this function displays the given `input` and then returns its corresponding generator via `Generators.input`. Use this to display an input element while also declaring the input’s current value as a reactive top-level variable. |
125 | | - |
126 | | -## Imports |
127 | | - |
128 | | -You can import a library from npm like so: |
129 | | - |
130 | | -```js show |
131 | | -import confetti from "npm:canvas-confetti"; |
132 | | -``` |
133 | | - |
134 | | -Now you can reference the imported `confetti` anywhere on the page. |
135 | | - |
136 | | -```js show |
137 | | -Inputs.button("Throw confetti!", {reduce: () => confetti()}) |
| 59 | +```md |
| 60 | +You rolled ${Math.floor(Math.random() * 20) + 1}. |
138 | 61 | ``` |
139 | 62 |
|
140 | | -You can also import JavaScript from local ES modules. This allows you to move code out of Markdown and into vanilla JavaScript files that can be shared by multiple pages — or even another application. And you can write tests for your code. |
| 63 | +You rolled ${Math.floor(Math.random() * 20) + 1}. Reload the page to re-roll. |
141 | 64 |
|
142 | | -## Files |
| 65 | +As with code blocks, if an inline expression evaluates to a DOM node, it will be displayed. For example, you can interpolate a sparkline ${Plot.plot({axis: null, margin: 0, width: 80, height: 17, x: {type: "band", round: false}, marks: [Plot.barY(aapl.slice(-15), {x: "Date", y1: 150, y2: "Close", fill: "steelblue"})]})} or even a reactive input ${Inputs.bind(htl.html`<input type=range style="width: 120px;">`, numberInput)} ${number} into prose. |
143 | 66 |
|
144 | | -You can load files using the built-in `FileAttachment` function. |
145 | | - |
146 | | -```js show |
147 | | -const gistemp = FileAttachment("gistemp.csv").csv({typed: true}); |
| 67 | +```js |
| 68 | +const numberInput = Inputs.input(0); |
| 69 | +const number = Generators.input(numberInput); |
148 | 70 | ``` |
149 | 71 |
|
150 | | -The following type-specific methods are supported: *csv*, *html*, *image*, *json*, *sqlite*, *text*, *tsv*, *xlsx*, *xml*, and *zip*. There are also generic methods: *arrayBuffer*, *blob*, and *url*. Each method returns a promise to the file’s contents (or URL). |
151 | | - |
152 | | -We use static analysis to determine which files are used so that we can include only referenced files when building. The `FileAttachment` function accepts only literal strings; code such as `FileAttachment("my" + "file.csv")` or similar dynamic invocation is invalid syntax. |
| 72 | +Unlike code blocks, expressions cannot declare top-level variables. |
0 commit comments