Skip to content

Commit db9fc9c

Browse files
kethinovkethinov
authored
Merge pull request #17 from kethinov/docs-update
docs update
2 parents 70e4f8e + abc7488 commit db9fc9c

File tree

4 files changed

+176
-191
lines changed

4 files changed

+176
-191
lines changed

‎CHANGELOG.md‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,3 @@
1-
# Changelog
2-
3-
## Next version
4-
5-
- Put your changes here...
6-
71
## 1.0.4
82

93
- Fixed a bug that would cause the module to crash if the file list provided by the user wasn't a directory.

‎CONFIGURATION.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
When you call:
2+
3+
```javascript
4+
const editedFiles = require('progressively-enhance-web-components')({
5+
templatesDir: './mvc/views'
6+
})
7+
```
8+
9+
There are other params you can pass to it besides `templatesDir`.
10+
11+
The full list of params available is:
12+
13+
- `templatesDir` *[String]*: What folder to examine. This is required.
14+
- `disableBeautify` *[Boolean]*: If set to true, this module will not beautify the HTML in the outputted markup. Default: `false`.
15+
- `beautifyOptions` *[Object]*: Options to pass to [js-beautify](https://github.com/beautifier/js-beautify). Default: `{ indent_size: 2 }`.

‎README.md‎

Lines changed: 11 additions & 185 deletions
Original file line numberDiff line numberDiff line change
@@ -1,199 +1,25 @@
1-
progressively-enhance-web-components
2-
===
3-
4-
[![Build Status](https://github.com/rooseveltframework/progressively-enhance-web-components/workflows/CI/badge.svg
5-
)](https://github.com/rooseveltframework/progressively-enhance-web-components/actions?query=workflow%3ACI) [![npm](https://img.shields.io/npm/v/progressively-enhance-web-components.svg)](https://www.npmjs.com/package/progressively-enhance-web-components)
1+
[![npm](https://img.shields.io/npm/v/progressively-enhance-web-components.svg)](https://www.npmjs.com/package/progressively-enhance-web-components)
62

73
A template file preprocessor for [progressively enhancing](https://en.wikipedia.org/wiki/Progressive_enhancement) web components in Node.js.
84

95
It works by reading a directory of HTML templates for your web application, identifying any web components, and replacing custom element invocations with fallback markup that will work if JavaScript is disabled which will then be progressively enhanced into the desired web component when the JavaScript loads.
106

117
This allows you to use web components in server-side templating the same way you would with client-side templating without creating a hard dependency on JavaScript for rendering templates with web components and without having to write two different templates for each context.
128

13-
This module was built and is maintained by the [Roosevelt web framework](https://github.com/rooseveltframework/roosevelt) [team](https://github.com/orgs/rooseveltframework/people), but it can be used independently of Roosevelt as well.
9+
This module was built and is maintained by the [Roosevelt web framework](https://rooseveltframework.org) [team](https://rooseveltframework.org/contributors), but it can be used independently of Roosevelt as well.
10+
11+
<details open>
12+
<summary>Documentation</summary>
13+
<ul>
14+
<li><a href="./USAGE.md">Usage</a></li>
15+
<li><a href="./CONFIGURATION.md">CONFIGURATION</a></li>
16+
</ul>
17+
</details>
1418

1519
## Technique
1620

1721
To leverage this module's progressive enhancement technique, you will need to follow some simple rules when authoring your web component:
1822

1923
1. Always define the markup structure using a `<template>` element. The definition can exist anywhere in any of your templates, but the definition must exist.
2024
2. The template element you create to define your web component must have an `id` matching the name of the web component. So `<my-component>` must have a corresponding `<template id="my-component">` somewhere in your templates.
21-
3. Use `${templateLiteral}` values for values in your `<template>` markup. See how that works in the example below.
22-
23-
## Usage
24-
25-
We will demo this technique end-to-end using a `<word-count>` component that counts the number of words a user types into a `<textarea>`.
26-
27-
Suppose the intended use of the `<word-count>` component looks like this:
28-
29-
```html
30-
<word-count text="Once upon a time... " id="story">
31-
<p slot="description">Type your story in the box above!</p>
32-
</word-count>
33-
```
34-
35-
And suppose also that you have an Express application with templates loaded into `mvc/views`.
36-
37-
To leverage this module's progressive enhancement technique, you will need to define this component using a `<template>` element in any one of your templates as follows:
38-
39-
```html
40-
<template id="word-count">
41-
<style>
42-
div {
43-
position: relative;
44-
}
45-
textarea {
46-
margin-top: 35px;
47-
width: 100%;
48-
box-sizing: border-box;
49-
}
50-
span {
51-
display: block;
52-
position: absolute;
53-
top: 0;
54-
right: 0;
55-
margin-top: 10px;
56-
font-weight: bold;
57-
}
58-
</style>
59-
<div>
60-
<textarea rows="10" cols="50" name="${id}" id="${id}">${text}</textarea>
61-
<slot name="description"></slot>
62-
<span class="word-count"></span>
63-
</div>
64-
</template>
65-
```
66-
67-
*Note: Any `${templateLiterals}` present in the template markup will be replaced with attribute values from the custom element invocation. More on that below.*
68-
69-
Then, in your Express application:
70-
71-
```javascript
72-
const fs = require('fs-extra')
73-
74-
// load progressively-enhance-web-components.js
75-
const editedFiles = require('progressively-enhance-web-components')({
76-
templatesDir: './mvc/views'
77-
})
78-
79-
// copy unmodified templates to a modified templates directory
80-
fs.copySync('mvc/views', 'mvc/.preprocessed_views')
81-
82-
// update the relevant templates
83-
for (const file in editedFiles) {
84-
fs.writeFileSync(file.replace('mvc/views', 'mvc/.preprocessed_views'), editedFiles[file])
85-
}
86-
87-
// configure express
88-
const express = require('express')
89-
const app = express()
90-
app.engine('html', require('teddy').__express) // set teddy as view engine that will load html files
91-
app.set('views', 'mvc/.preprocessed_views') // set template dir
92-
app.set('view engine', 'html') // set teddy as default view engine
93-
94-
// start the server
95-
const port = 3000
96-
app.listen(port, () => {
97-
console.log(`🎧 express sample app server is running on http://localhost:${port}`)
98-
})
99-
```
100-
101-
*Note: The above example uses the [Teddy](https://github.com/rooseveltframework/teddy) templating system, but you can use any templating system you like.*
102-
103-
In the above sample Express application, the `mvc/views` folder is copied to `mvc/.preprocessed_views`, then any template files in there will be updated to replace any uses of `<word-count>` with a more progressive enhancement-friendly version of `<word-count>` instead.
104-
105-
So, for example, any web component in your templates that looks like this:
106-
107-
```html
108-
<word-count text="Once upon a time... " id="story">
109-
<p slot="description">Type your story in the box above!</p>
110-
</word-count>
111-
```
112-
113-
Will be replaced with this:
114-
115-
```html
116-
<word-count text="Once upon a time... " id="story">
117-
<div>
118-
<textarea rows="10" cols="50" name="story" id="story">Once upon a time... </textarea>
119-
<span class="word-count"></span>
120-
</div>
121-
<p slot="description">Type your story in the box above!</p>
122-
</word-count>
123-
```
124-
125-
The fallback markup is derived from the `<template>` element and is inserted into the "light DOM" of the web component, so it will display to users with JavaScript disabled.
126-
127-
Because the `<template>` element has `${templateLiteral}` values for the `name` attribute, the `id` attribute, and the contents of the `<textarea>`, those values are prefilled properly on the fallback markup.
128-
129-
Any tag in the `<template>` element that has a `slot` attribute will be moved to the top level of the fallback markup DOM because that is a requirement for the web component to work when JavaScript is enabled. That's why the `<p>` tag is not a child of the `<div>` in the replacement example like it is in the `<template>`. That is done intentionally by this module's preprocessing.
130-
131-
Then, once the frontend JavaScript takes over, the web component can be progressively enhanced into the JS-driven version.
132-
133-
Here's an example implementation for the frontend JS side:
134-
135-
```javascript
136-
class WordCount extends window.HTMLElement {
137-
connectedCallback () { // called whenever a new instance of this element is inserted into the dom
138-
this.shadow = this.attachShadow({ mode: 'open' }) // create and attach a shadow dom to the custom element
139-
this.shadow.appendChild(document.getElementById('word-count').content.cloneNode(true)) // create the elements in the shadow dom from the template element
140-
141-
// set textarea attributes
142-
const textarea = this.shadow.querySelector('textarea')
143-
textarea.value = this.getAttribute('text') || ''
144-
textarea.id = this.getAttribute('id') || ''
145-
textarea.name = this.getAttribute('id') || ''
146-
147-
// function for updating the word count
148-
const updateWordCount = () => {
149-
this.shadow.querySelector('span').textContent = `Words: ${textarea.value.trim().split(/\s+/g).filter(a => a.trim().length > 0).length}`
150-
}
151-
152-
// update count when textarea content changes
153-
textarea.addEventListener('input', updateWordCount)
154-
updateWordCount() // update it on load as well
155-
}
156-
}
157-
158-
window.customElements.define('word-count', WordCount) // define the new element
159-
```
160-
161-
Once that JS executes, the "light DOM" fallback markup will be hidden and the JS-enabled version of the web component will take over and behave as normal.
162-
163-
### Available options
164-
165-
When you call:
166-
167-
```javascript
168-
const editedFiles = require('progressively-enhance-web-components')({
169-
templatesDir: './mvc/views'
170-
})
171-
```
172-
173-
There are other params you can pass to it besides `templatesDir`.
174-
175-
The full list of params available is:
176-
177-
- `templatesDir`: What folder to examine. This is required.
178-
- `disableBeautify`: If set to true, this module will not beautify the HTML in the outputted markup. Default: `false`.
179-
- `beautifyOptions`: Options to pass to [js-beautify](https://github.com/beautifier/js-beautify). Default: `{ indent_size: 2 }`.
180-
181-
### Sample app
182-
183-
Here's how to run the sample app:
184-
185-
- `cd sampleApps/express`
186-
187-
- `npm ci`
188-
189-
- `cd ../../`
190-
191-
- `npm run express-sample`
192-
193-
- Or `npm run sample`
194-
195-
- Or `cd` into `sampleApps/express` and run `npm ci` and `npm start`
196-
197-
- Go to [http://localhost:3000](http://localhost:3000)
198-
199-
- The page with the web component is located at http://localhost:3000/pageWithForm
25+
3. Use `${templateLiteral}` values for values in your `<template>` markup. See "Usage" for more details.

‎USAGE.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
We will demo this technique end-to-end using a `<word-count>` component that counts the number of words a user types into a `<textarea>`.
2+
3+
Suppose the intended use of the `<word-count>` component looks like this:
4+
5+
```html
6+
<word-count text="Once upon a time... " id="story">
7+
<p slot="description">Type your story in the box above!</p>
8+
</word-count>
9+
```
10+
11+
And suppose also that you have an Express application with templates loaded into `mvc/views`.
12+
13+
To leverage this module's progressive enhancement technique, you will need to define this component using a `<template>` element in any one of your templates as follows:
14+
15+
```html
16+
<template id="word-count">
17+
<style>
18+
div {
19+
position: relative;
20+
}
21+
textarea {
22+
margin-top: 35px;
23+
width: 100%;
24+
box-sizing: border-box;
25+
}
26+
span {
27+
display: block;
28+
position: absolute;
29+
top: 0;
30+
right: 0;
31+
margin-top: 10px;
32+
font-weight: bold;
33+
}
34+
</style>
35+
<div>
36+
<textarea rows="10" cols="50" name="${id}" id="${id}">${text}</textarea>
37+
<slot name="description"></slot>
38+
<span class="word-count"></span>
39+
</div>
40+
</template>
41+
```
42+
43+
*Note: Any `${templateLiterals}` present in the template markup will be replaced with attribute values from the custom element invocation. More on that below.*
44+
45+
Then, in your Express application:
46+
47+
```javascript
48+
const fs = require('fs-extra')
49+
50+
// load progressively-enhance-web-components.js
51+
const editedFiles = require('progressively-enhance-web-components')({
52+
templatesDir: './mvc/views'
53+
})
54+
55+
// copy unmodified templates to a modified templates directory
56+
fs.copySync('mvc/views', 'mvc/.preprocessed_views')
57+
58+
// update the relevant templates
59+
for (const file in editedFiles) {
60+
fs.writeFileSync(file.replace('mvc/views', 'mvc/.preprocessed_views'), editedFiles[file])
61+
}
62+
63+
// configure express
64+
const express = require('express')
65+
const app = express()
66+
app.engine('html', require('teddy').__express) // set teddy as view engine that will load html files
67+
app.set('views', 'mvc/.preprocessed_views') // set template dir
68+
app.set('view engine', 'html') // set teddy as default view engine
69+
70+
// start the server
71+
const port = 3000
72+
app.listen(port, () => {
73+
console.log(`🎧 express sample app server is running on http://localhost:${port}`)
74+
})
75+
```
76+
77+
*Note: The above example uses the [Teddy](https://rooseveltframework.org/docs/teddy) templating system, but you can use any templating system you like.*
78+
79+
In the above sample Express application, the `mvc/views` folder is copied to `mvc/.preprocessed_views`, then any template files in there will be updated to replace any uses of `<word-count>` with a more progressive enhancement-friendly version of `<word-count>` instead.
80+
81+
So, for example, any web component in your templates that looks like this:
82+
83+
```html
84+
<word-count text="Once upon a time... " id="story">
85+
<p slot="description">Type your story in the box above!</p>
86+
</word-count>
87+
```
88+
89+
Will be replaced with this:
90+
91+
```html
92+
<word-count text="Once upon a time... " id="story">
93+
<div>
94+
<textarea rows="10" cols="50" name="story" id="story">Once upon a time... </textarea>
95+
<span class="word-count"></span>
96+
</div>
97+
<p slot="description">Type your story in the box above!</p>
98+
</word-count>
99+
```
100+
101+
The fallback markup is derived from the `<template>` element and is inserted into the "light DOM" of the web component, so it will display to users with JavaScript disabled.
102+
103+
Because the `<template>` element has `${templateLiteral}` values for the `name` attribute, the `id` attribute, and the contents of the `<textarea>`, those values are prefilled properly on the fallback markup.
104+
105+
Any tag in the `<template>` element that has a `slot` attribute will be moved to the top level of the fallback markup DOM because that is a requirement for the web component to work when JavaScript is enabled. That's why the `<p>` tag is not a child of the `<div>` in the replacement example like it is in the `<template>`. That is done intentionally by this module's preprocessing.
106+
107+
Then, once the frontend JavaScript takes over, the web component can be progressively enhanced into the JS-driven version.
108+
109+
Here's an example implementation for the frontend JS side:
110+
111+
```javascript
112+
class WordCount extends window.HTMLElement {
113+
connectedCallback () { // called whenever a new instance of this element is inserted into the dom
114+
this.shadow = this.attachShadow({ mode: 'open' }) // create and attach a shadow dom to the custom element
115+
this.shadow.appendChild(document.getElementById('word-count').content.cloneNode(true)) // create the elements in the shadow dom from the template element
116+
117+
// set textarea attributes
118+
const textarea = this.shadow.querySelector('textarea')
119+
textarea.value = this.getAttribute('text') || ''
120+
textarea.id = this.getAttribute('id') || ''
121+
textarea.name = this.getAttribute('id') || ''
122+
123+
// function for updating the word count
124+
const updateWordCount = () => {
125+
this.shadow.querySelector('span').textContent = `Words: ${textarea.value.trim().split(/\s+/g).filter(a => a.trim().length > 0).length}`
126+
}
127+
128+
// update count when textarea content changes
129+
textarea.addEventListener('input', updateWordCount)
130+
updateWordCount() // update it on load as well
131+
}
132+
}
133+
134+
window.customElements.define('word-count', WordCount) // define the new element
135+
```
136+
137+
Once that JS executes, the "light DOM" fallback markup will be hidden and the JS-enabled version of the web component will take over and behave as normal.
138+
139+
### Sample app
140+
141+
See an end-to-end demo of this by running the sample app:
142+
143+
- `cd sampleApps/express`
144+
- `npm ci`
145+
- `cd ../../`
146+
- `npm run express-sample`
147+
- Or `npm run sample`
148+
- Or `cd` into `sampleApps/express` and run `npm ci` and `npm start`
149+
- Go to [http://localhost:3000](http://localhost:3000)
150+
- The page with the web component is located at [http://localhost:3000/pageWithForm](http://localhost:3000/pageWithForm)

0 commit comments

Comments
 (0)