Skip to content

Commit 197e0ac

Browse files
ioquatixioquatix
committed
Updated documentation.
1 parent 7744577 commit 197e0ac

File tree

5 files changed

+262
-74
lines changed

5 files changed

+262
-74
lines changed

‎context/index.yaml‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,8 @@ files:
1919
title: Server Setup
2020
description: This guide explains how to deploy a `utopia` web application.
2121
- path: integrating-with-javascript.md
22-
title: Installing JavaScript Libraries
23-
description: Utopia integrates with Yarn and provides a [bake task](https://github.com/ioquatix/bake)
24-
to simplify deployment packages distributed using `yarn` that implement the `dist`
25-
sub-directory convention.
22+
title: Integrating with JavaScript
23+
description: This guide explains how to integrate JavaScript into your Utopia application.
2624
- path: what-is-xnode.md
2725
title: What is XNode?
2826
description: This guide explains the `xnode` view layer and how it can be used to

‎context/integrating-with-javascript.md‎

Lines changed: 129 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,153 @@
1-
# Installing JavaScript Libraries
1+
# Integrating with JavaScript
22

3-
Utopia integrates with Yarn and provides a [bake task](https://github.com/ioquatix/bake) to simplify deployment packages distributed using `yarn` that implement the `dist` sub-directory convention.
3+
This guide explains how to integrate JavaScript into your Utopia application.
44

5-
## Installing Yarn
5+
## Using Import Maps
66

7-
If you don't already have yarn installed, make sure you have npm installed and then run the following command:
7+
Import maps provide a modern way to manage JavaScript module dependencies. Utopia includes built-in support for import maps through the {ruby Utopia::ImportMap} class.
8+
9+
### Installing JavaScript Libraries
10+
11+
First, install the library using npm:
812

913
```bash
10-
$ sudo npm install -g yarn
14+
$ npm install jquery
1115
```
1216

13-
## Installing jQuery
14-
15-
Firstly, ensure your project has a `package.json` file:
17+
Copy the distribution files to `public/_components`:
1618

1719
```bash
18-
$ yarn init
20+
$ bundle exec bake utopia:node:update
1921
```
2022

21-
Then install jquery using `yarn`:
23+
This will copy the library's distribution files (typically from `node_modules/*/dist/`) to your `public/_components/` directory, making them available for local serving.
2224

23-
```bash
24-
$ yarn add jquery
25+
### Creating the Import Map
26+
27+
Create a global import map in `lib/my_website/import_map.rb`:
28+
29+
```ruby
30+
require "utopia/import_map"
31+
32+
module MyWebsite
33+
IMPORT_MAP = Utopia::ImportMap.build(base: "/_components/") do |map|
34+
map.import("jquery", "./jquery/jquery.js")
35+
end
36+
end
2537
```
2638

27-
Copy the distribution scripts to `public/_components`:
39+
Then load this in `lib/my_website.rb`:
2840

29-
```bash
30-
$ bundle exec bake utopia:node:update
41+
```ruby
42+
require_relative "my_website/import_map"
43+
```
44+
45+
### Adding to Your Pages
46+
47+
Add it to your page template (`pages/_page.xnode`), using `relative_to` to adjust paths for the current page:
48+
49+
```xrb
50+
<html>
51+
<head>
52+
#{MyWebsite::IMPORT_MAP.relative_to(request.path + "/")}
53+
</head>
54+
<body>
55+
<!-- Your content -->
56+
</body>
57+
</html>
58+
```
59+
60+
### Using the Library
61+
62+
Once the import map is set up, you can import and use the library in your scripts:
63+
64+
```xrb
65+
<script type="module">
66+
// <![CDATA[
67+
import $ from 'jquery';
68+
69+
$(document).ready(function() {
70+
console.log("jQuery is ready!");
71+
});
72+
// ]]>
73+
</script>
74+
```
75+
76+
77+
### Advanced Import Map Features
78+
79+
#### Using CDN URLs
80+
81+
Import maps support direct CDN imports without downloading files:
82+
83+
```ruby
84+
IMPORT_MAP = Utopia::ImportMap.build do |map|
85+
map.import("react", "https://esm.sh/react@18")
86+
map.import("vue", "https://cdn.jsdelivr.net/npm/vue@3/dist/vue.esm-browser.js")
87+
end
88+
```
89+
90+
#### Nested Base URLs
91+
92+
You can organize imports from different sources using nested `with(base:)` blocks:
93+
94+
```ruby
95+
IMPORT_MAP = Utopia::ImportMap.build do |map|
96+
# Local components
97+
map.with(base: "/_components/") do |local|
98+
local.import "app", "./app.js"
99+
end
100+
101+
# CDN imports
102+
map.with(base: "https://cdn.jsdelivr.net/npm/") do |cdn|
103+
cdn.import "lit", "lit@2.7.5/index.js"
104+
cdn.import "lit/decorators.js", "lit@2.7.5/decorators.js"
105+
end
106+
end
31107
```
32108

33-
Then add the appropriate `<script>` tags to `pages/_page.xnode`:
109+
#### Subresource Integrity
110+
111+
Add integrity hashes for enhanced security:
34112

35-
```html
36-
<script type="text/javascript" src="/_components/jquery/jquery.min.js"></script>
113+
```ruby
114+
IMPORT_MAP = Utopia::ImportMap.build do |map|
115+
map.import("react", "https://esm.sh/react@18", integrity: "sha384-...")
116+
end
37117
```
38118

39-
## Using JavaScript
119+
#### Scoped Imports
120+
121+
Use scopes to resolve imports differently based on the **referrer URL** (the page or module location where the import is being made):
122+
123+
```ruby
124+
IMPORT_MAP = Utopia::ImportMap.build do |map|
125+
map.import("utils", "/utils.js")
126+
127+
# When importing from any page under /admin/, use a different utils module
128+
map.scope("/admin/", {"utils" => "/admin/utils.js"})
129+
end
130+
```
40131

41-
You can use JavaScript by embedding it directly into your HTML, or by creating a JavaScript source file and referencing that.
132+
When you're on a page at `/admin/dashboard` and you `import "utils"`, it will resolve to `/admin/utils.js`. On other pages, it resolves to `/utils.js`.
133+
134+
## Traditional JavaScript
135+
136+
You can also use JavaScript by embedding it directly into your HTML, or by creating a JavaScript source file and referencing that.
42137

43138
### Embedding Code
44139

45-
In your HTML view:
140+
When embedding JavaScript directly in XRB templates, wrap the code in CDATA comments to prevent XRB's parser from interpreting special characters like `<`, `>`, and `&`:
46141

47-
```trenni
142+
```xrb
48143
<html>
49-
<body>
50-
<script type="text/javascript">
51-
//<![CDATA[
52-
console.log("Hello World")
53-
//]]>
54-
</script>
55-
</body>
144+
<body>
145+
<script type="text/javascript">
146+
// <![CDATA[
147+
console.log("Hello World")
148+
// ]]>
149+
</script>
150+
</body>
56151
</html>
57152
```
58153

@@ -66,10 +161,10 @@ console.log("Hello World")
66161

67162
In your HTML view:
68163

69-
```trenni
164+
```xrb
70165
<html>
71-
<body>
72-
<script type="text/javascript" src="script.js"></script>
73-
</body>
166+
<body>
167+
<script type="text/javascript" src="script.js"></script>
168+
</body>
74169
</html>
75-
```
170+
```

0 commit comments

Comments
 (0)