You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+22-15
Original file line number
Diff line number
Diff line change
@@ -4,14 +4,6 @@
4
4
5
5
Your Svelte components can seamlessly react to your ObservableJS code, making it quick and easy to build visuals that animate in response to [user inputs](https://observablehq.com/@observablehq/inputs?collection=@observablehq/inputs) or other changing data in your document.
6
6
7
-
## 💭 Why Sverto?
8
-
9
-
[Quarto](https://quarto.org) helps users build beautiful documents regardless of their language of choice, and it encourages data analysts and scientists to explore web visualisation by making JavaScript accessible and easy to use. It makes interactive visualisations intuitive to write, but animated visuals are still a challenge that require either dipping into a high-level JavaScript library or learning a lower-level one like [d3](https://d3js.org).
10
-
11
-
[Svelte](https://svelte.dev) is a framework for building web visualisations and apps in JavaScript. Svelte goes out of its way to make writing self-contained components, like charts, comfortable and intuitive. It has a great [playground environment](https://svelte.dev/repl/hello-world?version=3.55.1) for developing and testing components, but like many web frameworks, the experience is much more complex when you start developing locally.
12
-
13
-
_Sverto aims to make it as easy to use Svelte components in Quarto documents as it is to work on them in the Svelte REPL: just write a `.svelte` file, add it to a Quarto document, and Sverto should take care of the rest._
14
-
15
7
## 📋 Prerequisites
16
8
17
9
You'll need to install two things to run Sverto:
@@ -35,7 +27,15 @@ npm install
35
27
36
28
This will add the extension itself (which includes some project scripts) to the `_extension` folder, as well as a few other files.
37
29
38
-
> **Note:** Sverto depends on running [project pre-render scripts](https://quarto.org/docs/projects/scripts.html#pre-and-post-render), so you can't currently use it with single documents.
30
+
### 📦 What's in the box?
31
+
32
+
When you use the Sverto template in a project, it creates some files for you:
33
+
34
+
*[`example.qmd`](./example.qmd): an example Quarto doc that uses a Svelte component
35
+
*[`Circles.svelte`](./Circles.svelte): an example Svelte visualisation
36
+
*[`package.json`](./package.json): this is used to keep track of the dependencies of your Svelte components. **You should add this to version control.**
37
+
*`package-lock.json` is created once you run `npm install`. You should add this to version control.
38
+
*`node_modules/`: This folder is created once you rum `npm install`. Don't add it to version control.
> **Note:**`quarto preview` won't "live reload" when you modify your Svelte component—but if you modify and save the Quarto doc that imports it, that will trigger a re-render. You may need to hard reload the page in your browser to see the updated Svelte component.
86
+
> ![NOTE]
87
+
> `quarto preview` won't "live reload" when you modify your Svelte component—but if you modify and save the Quarto doc that imports it, that will trigger a re-render. You may need to hard reload the page in your browser to see the updated Svelte component.
87
88
>
88
-
> If you want to quickly iterate on the Svelte component and you aren't too concerned about the rest of your Quarto doc, you might find the [Svelte Preview](https://marketplace.visualstudio.com/items?itemName=RafaelMartinez.svelte-preview) extension for VSCode handy.
89
+
> If you want to quickly iterate on the Svelte component, you might find the [Svelte Preview](https://marketplace.visualstudio.com/items?itemName=RafaelMartinez.svelte-preview) extension for VSCode handy.
89
90
90
91
## 📦 What's in the box?
91
92
@@ -105,14 +106,20 @@ As well as the project format, Sverto ships with document formats (the default i
105
106
If you want to refer to other JavaScript libraries in your Svelte component (like d3, for example), add them to the project using `npm install package1 [package2 ...]`. For example:
106
107
107
108
```
108
-
npm install d3-scale
109
+
npm install d3
109
110
```
110
111
111
-
## Use pre-compiled Svelte components
112
+
# 💭 Why Sverto?
113
+
114
+
[Quarto](https://quarto.org) helps data scientists and analysts build beautiful documents regardless of their language of choice, and it encourages data analysts and scientists to explore web visualisation by making JavaScript accessible and easy to use.
115
+
116
+
Quarto makes interactive charts intuitive to write, but animated ones are still a challenge that require either dipping into a high-level JavaScript library or learning a lower-level one like [d3](https://d3js.org).
117
+
118
+
[Svelte](https://svelte.dev) is a framework for building charts, web visualisations and even apps in HTML, CSS and JavaScript. Svelte goes out of its way to make writing self-contained components, like charts, comfortable and intuitive.
112
119
113
-
If you'd prefer to compile your own Svelte components instead of letting this extension do it, you can skip steps 1 and 2 and simply refer to the compiled bundle with, for example, `Component = import("Component.js")` in an OJS block.
120
+
Svelte has a great [playground environment](https://svelte.dev/repl/hello-world?version=3.55.1) for developing and testing components, but like many web frameworks, the experience is much more complex when you start developing locally.
114
121
115
-
> **Note:** you must compile the Svelte component to an ES6 bundle, and you must enable accessors when compiling if you want to be able to update them from OJS. Refer to `_extensions/sverto/rollup.config.js` for guidance on configuring Rollup to do this.
122
+
_Sverto aims to make it as easy to build and use animated Svelte charts in Quarto documents as it is to work on them in the Svelte playground: just write a `.svelte` file, add it to a Quarto document, and Sverto takes care of the rest._
@@ -165,7 +164,7 @@ Here's the code in the Svelte file:
165
164
```
166
165
:::
167
166
168
-
if you'd like to start practising your Svelte, start with [the official tutorial](https://learn.svelte.dev/tutorial/welcome-to-svelte). Sverto is designed to make using Svelte components in Quarto as easy as working in the tutorial.
167
+
If you'd like to start practising your Svelte, start with [the official tutorial](https://learn.svelte.dev/tutorial/welcome-to-svelte). Sverto is designed to make using Svelte components in Quarto as easy as working in the tutorial.
169
168
170
169
This Svelte component's pretty basic, though. What else is it missing?
171
170
@@ -188,4 +187,10 @@ The bars are all the same colour. We could write a function that converts each b
188
187
`d3` is included with OJS, but if you want to use `d3-scale-chromatic` (or any other part of d3) in your Svelte components, you'll have to add it yourself by:
189
188
190
189
- running `npm install d3-scale-chromatic` in the terminal, then
191
-
- adding `import XXXX from "d3-scale-chromatic"`, where `XXXX` is the name of the thing you want to import (or `*`).
190
+
- adding `import XXXX from "d3-scale-chromatic"`, where `XXXX` is the name of the thing you want to import (or `*`).
191
+
192
+
### A more complex example
193
+
194
+
If you'd like to see an example that addresses some of these shortcomings, check out the [time series chart example](../time-series), which automatically resizes and adds axes that transition!
195
+
196
+
[See the time series chart →]((../time-series)){.btn .btn-success}
description: "**Sverto** is an extension for [Quarto](https://quarto.org) that lets you seamlessly write and include [Svelte](https://svelte.dev) components, like charts and other visuals, in your Quarto website."
4
-
author: James Goldie
5
-
date: last-modified
6
4
format:
7
5
html:
8
6
toc: true
9
7
toc-location: left
10
8
---
11
9
12
-
Your Svelte components can seamlessly react to your ObservableJS code, making it quick and easy to build bespoke visuals that animate in response to [user inputs](https://observablehq.com/@observablehq/inputs?collection=@observablehq/inputs) or other changing data in your document.
10
+
Your Svelte components can seamlessly react to your [Observable JavaScript](https://quarto.org/docs/interactive/ojs/) code, making it quick and easy to build bespoke visuals that animate in response to [user inputs](https://observablehq.com/@observablehq/inputs?collection=@observablehq/inputs) or other changing data in your document.
13
11
14
-
## 💭 Why Sverto?
15
-
16
-
[Quarto](https://quarto.org) helps users build beautiful documents regardless of their language of choice, and it encourages data analysts and scientists to explore web visualisation by making JavaScript accessible and easy to use. It makes interactive visualisations intuitive to write, but animated visuals are still a challenge that require either dipping into a high-level JavaScript library or learning a lower-level one like [d3](https://d3js.org).
17
-
18
-
[Svelte](https://svelte.dev) is a framework for building web visualisations and apps in JavaScript. Svelte goes out of its way to make writing self-contained components, like charts, comfortable and intuitive. It has a great [playground environment](https://svelte.dev/repl/hello-world?version=3.55.1) for developing and testing components, but like many web frameworks, the experience is much more complex when you start developing locally.
19
-
20
-
_Sverto aims to make it as easy to use animated Svelte charts in Quarto documents as it is to work on them in the Svelte REPL: just write a `.svelte` file, add it to a Quarto document, and Sverto should take care of the rest._
21
-
22
-
## 📋 Prerequisites
12
+
# 📋 Prerequisites
23
13
24
14
You'll need to install two things to run Sverto:
25
15
26
16
-[Quarto](https://quarto.org)
27
17
-[Node and the Node Package Manager (npm)](https://nodejs.org)
28
18
29
-
##⚙️ Installation
19
+
# ⚙️ Installation
30
20
31
21
Install the project extension using:
32
22
@@ -42,15 +32,21 @@ npm install
42
32
43
33
This will add the extension itself (which includes some project scripts) to the `_extension` folder, as well as a few other files.
44
34
45
-
:::{.callout-note}
46
-
Sverto depends on running [project pre-render scripts](https://quarto.org/docs/projects/scripts.html#pre-and-post-render), so you can't currently use it with single documents.
47
-
:::
35
+
## 📦 What's in the box?
36
+
37
+
When you use the Sverto template in a project, it creates some files for you:
48
38
49
-
## 🎉 Use
39
+
*[`example.qmd`](./example.qmd): an example Quarto doc that uses a Svelte component. If you're adding Sverto to an existing document, you can delete this.
40
+
*[`Circles.svelte`](./Circles.svelte): an example Svelte visualisation. If you have a Svelte component that you want to use instead, you can delete this.
41
+
*[`package.json`](./package.json): this is used to keep track of the dependencies of your Svelte components. **You should add this to version control.**
42
+
*`package-lock.json` is created once you run `npm install`. You should add this to version control.
43
+
*`node_modules/`: This folder is created once you rum `npm install`. Don't add it to version control.
50
44
51
-
Here's the quick guide to add Svelte component you've written to a Quarto doc:
45
+
# 🎉 Use
52
46
53
-
### Step 1: add Svelte to your document
47
+
Here's the quick guide to add a Svelte component you've written to a Quarto doc:
48
+
49
+
## Step 1: add Svelte to your document
54
50
55
51
In the document frontmatter, add `sverto` to `filters`, and add one or more `.svelte` files to `sverto.use`:
56
52
@@ -60,21 +56,18 @@ title: "My document"
60
56
filters: ["sverto"]
61
57
sverto:
62
58
use:
63
-
example.svelte
59
+
- example.svelte
64
60
---
65
61
```
66
62
67
-
###Step 2: bring your Svelte component to life
63
+
## Step 2: bring your Svelte component to life
68
64
69
65
Use an [Observable JS](https://quarto.org/docs/interactive/ojs/) chunk to _instantiate_ your Svelte component.
70
66
71
67
````js
72
68
```{ojs}
73
69
myChart = new example.default({
74
70
target: document.querySelector("#chart")
75
-
props: {
76
-
chartData: {}
77
-
}
78
71
})
79
72
```
80
73
@@ -83,10 +76,10 @@ myChart = new example.default({
83
76
````
84
77
85
78
- the `target` is where it will appear. This needs to be an existing part of the document — you can put a [Pandoc div](https://quarto.org/docs/authoring/markdown-basics.html#divs-and-spans) right after this code, or put one anywhere else on the page
86
-
-`example` is the file name of your Svelte component, without the file extension
87
-
- if your Svelte component has any `props`, add default values here too. Don't put reactive OJS code in here; we'll update the props separately!
79
+
-`example` is the file name of your Svelte component, without the file extension (so if your file is called `example.svelte` call `example.default()`)
80
+
- if your Svelte component has any `props` that don't have defaults built in, supply default values here for them too. Don't put reactive OJS code in here; we'll update the props separately!
88
81
89
-
###Step 3: make your visual reactive
82
+
## Step 3: make your visual reactive
90
83
91
84
If your visual has `props` that allow it to change or transition in response to other OJS code, you can update it by assigning the prop directly.
92
85
@@ -96,36 +89,45 @@ For example, if we have a dataset called `myData` in OJS, and a year slider call
**To see this all in practice, check out [`example.qmd`](https://github.com/jimjam-slam/sverto/blob/main/example.qmd).**
92
+
If you're writing a single document, you're done! Run `quarto render` and see your hard work.
100
93
101
-
:::{.callout-tip}
102
-
If you're using a [Quarto project](https://quarto.org/docs/projects/quarto-projects.html) and you have documents that share Quarto components, add project `project.type: sverto`. All of the Svelte components in your project will be built together, avoiding duplication.
103
-
:::
94
+
**To see this all in practice, check out the [simple bar chart example](examples/barchart).**
104
95
105
-
:::{.callout-note}
96
+
## Step 4 (for websites): set the project type
97
+
98
+
If you're using a [Quarto website](https://quarto.org/docs/projects/quarto-projects.html), change the `project.type` in `_quarto.yml` from `website` to `sverto`.
99
+
100
+
This way, your website pages can share Sverto components when you're rendering the whole website.
The `quarto preview` command won't "live reload" when you modify your Svelte component—but if you modify and save the Quarto doc that imports it, that will trigger a re-render. You may need to hard reload the page in your browser to see the updated Svelte component.
107
104
108
-
If you want to quickly iterate on the Svelte component and you aren't too concerned about the rest of your Quarto doc, you might find the [Svelte Preview](https://marketplace.visualstudio.com/items?itemName=RafaelMartinez.svelte-preview) extension for VSCode handy.
105
+
If you want to quickly iterate on a Svelte component you're building, you might find the [Svelte Preview](https://marketplace.visualstudio.com/items?itemName=RafaelMartinez.svelte-preview) extension for VSCode handy.
109
106
:::
110
107
108
+
# Advanced use
109
+
111
110
## 🛍 Use other libraries in your Svelte component
112
111
113
112
If you want to refer to other JavaScript libraries in your Svelte component (like d3, for example), add them to the project using `npm install package1 [package2 ...]`. For example:
114
113
115
114
```sh
116
-
npm install d3-scale
115
+
npm install d3
117
116
```
117
+
# 💭 Why Sverto?
118
118
119
-
## 🔨 Use pre-compiled Svelte components
119
+
[Quarto](https://quarto.org) helps data scientists and analysts build beautiful documents regardless of their language of choice, and it encourages data analysts and scientists to explore web visualisation by making JavaScript accessible and easy to use.
120
120
121
-
If you'd prefer to compile your own Svelte components instead of letting this extension do it, you can skip steps 1 and 2 and simply refer to the compiled bundle with, for example, `Component = import("Component.js")` in an OJS block.
121
+
Quarto makes interactive charts intuitive to write, but animated ones are still a challenge that require either dipping into a high-level JavaScript library or learning a lower-level one like [d3](https://d3js.org).
122
122
123
-
:::{.callout-note}
124
-
You must compile the Svelte component to an ES6 bundle, and you must enable accessors when compiling if you want to be able to update them from OJS. Refer to [`_extensions/sverto/rollup.config.js`](https://github.com/jimjam-slam/sverto/blob/firstrelease/_extensions/sverto/rollup.config.js) for guidance on configuring Rollup to do this.
125
-
:::
123
+
[Svelte](https://svelte.dev) is a framework for building charts, web visualisations and even apps in HTML, CSS and JavaScript. Svelte goes out of its way to make writing self-contained components, like charts, comfortable and intuitive.
124
+
125
+
Svelte has a great [playground environment](https://svelte.dev/repl/hello-world?version=3.55.1) for developing and testing components, but like many web frameworks, the experience is much more complex when you start developing locally.
126
+
127
+
_Sverto aims to make it as easy to build and use animated Svelte charts in Quarto documents as it is to work on them in the Svelte playground: just write a `.svelte` file, add it to a Quarto document, and Sverto takes care of the rest._
126
128
127
-
##❓ Issues
129
+
# ❓ Issues
128
130
129
-
If you have any problems with the extension, please feel free to [create an issue](https://github.com/jimjam-slam/sverto)!
131
+
If you have any problems with Sverto, please feel free to [create an issue](https://github.com/jimjam-slam/sverto)!
130
132
131
133
Special thanks to [Carlos Scheidegger](https://github.com/cscheid) from [Posit](https://posit.co) for his time and advice!
0 commit comments