Skip to content

Commit 9ae06ee

Browse files
foolipfoolip
authored
Update patching explainer with <!start> and <!end>
Names are now required. Live reviewed by @noamr.
1 parent 1fa3ae0 commit 9ae06ee

File tree

1 file changed

+33
-23
lines changed

1 file changed

+33
-23
lines changed

‎patching-explainer.md‎

Lines changed: 33 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ A `marker` attribute on the parent element is used to "expose" those markers for
2828
Example where a placeholder is replaced with actual content:
2929

3030
```html
31-
<section marker="gallery">
32-
<!marker start>Loading...<!marker end>
31+
<section range="gallery">
32+
<!start gallery>Loading...<!end gallery>
3333
</section>
3434

3535
<template for="gallery">
@@ -40,17 +40,17 @@ Example where a placeholder is replaced with actual content:
4040
The marker nodes and everything between them is replaced, so the resulting DOM is:
4141

4242
```html
43-
<section marker="gallery">
43+
<section range="gallery">
4444
Actual gallery content
4545
</section>
4646
```
4747

4848
To insert at a single point, a single `<!marker>` is used:
4949

5050
```html
51-
<ul marker="list">
51+
<ul range="list">
5252
<li>first item</li>
53-
<!marker>
53+
<!marker list>
5454
<li>last item</li>
5555
</ul>
5656

@@ -62,14 +62,14 @@ To insert at a single point, a single `<!marker>` is used:
6262
To support multiple ranges, marker nodes can be named. The names must match one of the tokens in the `marker` attribute, and any number of ranges can be exposed:
6363

6464
```html
65-
<div marker="part-one part-two">
66-
<!marker start name="part-one">
65+
<div range="part-one part-two">
66+
<!start part-one>
6767
Placeholder content
68-
<!marker end name="part-one">
68+
<!end part-one>
6969
<hr>
70-
<!marker start name="part-two">
70+
<!start part-two>
7171
Placeholder content
72-
<!marker end name="part-two">
72+
<!end part-two>
7373
</div>
7474

7575
<template for="part-one">
@@ -87,15 +87,15 @@ A few details about patching:
8787
- If the patching element is not a direct child of `<body>`, the target element has to have a common ancestor with the patching element's parent.
8888
- The patch template has to be in the same tree (shadow) scope as the target element.
8989

90-
Note on compat risk: Current HTML parsers interpret `<!marker>` as a bogus comment, so it's important that `<!marker>` does not appear in existing web content for this to be viable. Another name could be chosen if necessary for web compat.
90+
Note on compat risk: Current HTML parsers interpret `<!...>` as a bogus comment, so it's important that `<!marker>`, `<!start>`, and `<!end>` does not appear in existing web content for this to be viable. Another name could be chosen if necessary for web compat.
9191

9292
### Interleaved patching
9393

9494
An element can be patched multiple times and patches for different elements can be interleaved. This allows for updates to different parts of the document to be interleaved. For example:
9595

9696
```html
97-
<div marker="product-carousel"><!marker start>Loading...</div>
98-
<div marker="search-results"><!marker start>Loading...</div>
97+
<div range="product-carousel"><!start product-carousel>Loading...</div>
98+
<div range="search-results"><!start search-results>Loading...</div>
9999
```
100100

101101
In this example, the search results populate in three steps while the product carousel populates in one step in between:
@@ -104,7 +104,7 @@ In this example, the search results populate in three steps while the product ca
104104
<template for="search-results">
105105
<p>first result</p>
106106
<!-- a new marker is added at the end for the following patch -->
107-
<!marker>
107+
<!marker search-results>
108108
</template>
109109

110110
<template for="product-carousel">
@@ -114,7 +114,7 @@ In this example, the search results populate in three steps while the product ca
114114
<template for="search-results">
115115
<p>second result</p>
116116
<!-- a new marker is added at the end for the following patch -->
117-
<!marker>
117+
<!marker search-results>
118118
</template>
119119

120120
<template for="search-results">
@@ -125,12 +125,12 @@ In this example, the search results populate in three steps while the product ca
125125

126126
## Marker APIs
127127

128-
The new `<!marker>` node would be represented with a new `Marker` interface inheriting from `Node`, with these attributes:
128+
The new `<!marker>`, `<!start>`, and `<!end>` nodes would be represented with a new `Marker` interface inheriting from `Node`, with these read-only attributes:
129129

130-
- `type`, an enum with values "start", "end", and the empty string
130+
- `type`, an enum with values "marker", "start", "end"
131131
- `name`, a string
132132

133-
Scripts can create marker nodes using `new Marker()` .
133+
Scripts can create marker nodes using `new Marker({ type, name })`.
134134

135135
To allow scripts to use markers in the same way a declarative patching would, an `element.markerRange("list")` method is introduced, returning a `Range` object spanning the same nodes that would be replaced.
136136

@@ -140,12 +140,22 @@ To allow scripts to use markers in the same way a declarative patching would, an
140140

141141
## Potential enhancement
142142

143+
### Custom highlights integration
144+
145+
Named ranges created by marker nodes are similar to the named highlights created by the [custom highlights API](https://drafts.csswg.org/css-highlight-api-1/). For declarative highlights, a possible direction is named `<!start>` and `<!end>` nodes together with a CSS rule to specify the highlight priority and type.
146+
147+
See https://github.com/w3c/csswg-drafts/issues/13381 for discussion.
148+
149+
## DOM Parts integration
150+
151+
[DOM Parts](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/DOM-Parts.md) could make use of marker nodes to annotate ranges created by the "{{}}" syntax, so that the ranges are represented in the DOM and not just in the `<template>` and JS APIs.
152+
143153
### Implicit markers
144154

145-
To simplify the common case of replacing all children of an element without requiring a `<!marker start>` node, the `marker` attribute could have a microsyntax to target ranges. Example:
155+
To simplify the common case of replacing all children of an element without requiring a `<!start>` node, the `marker` attribute could have a microsyntax to target ranges. Example:
146156

147157
```html
148-
<section marker="gallery:all">
158+
<section range="gallery:all">
149159
Loading...
150160
</section>
151161

@@ -157,7 +167,7 @@ To simplify the common case of replacing all children of an element without requ
157167
Appending could also be supported with another keyword:
158168

159169
```html
160-
<ul marker="gallery:last">
170+
<ul range="gallery:last">
161171
<li>first item</li>
162172
</ul>
163173

@@ -182,9 +192,9 @@ Enabling remote fetching of patch content would act as a script in terms of CSP,
182192

183193
### Marker pointers on `Element`
184194

185-
The main proposal treats `<!marker start>` and `<!marker end>` as two nodes, which can appear in any number and order. Error handling is done when trying to apply a `<template>` patch.
195+
The main proposal treats `<!start>` and `<!end>` as two nodes, which can appear in any number and order. Error handling is done when trying to apply a `<template>` patch.
186196

187-
An alternative is that the parser doesn't create `Marker` nodes, but instead sets pointers `element.beforeFirstMarker` and `element.afterLastMarker`. Serializing would insert `<!marker>` at the appropriate places.
197+
An alternative is that the parser doesn't create `Marker` nodes, but instead sets pointers `element.beforeFirstMarker` and `element.afterLastMarker`. Serializing would insert `<!start>` and `<!end>` at the appropriate places.
188198

189199
The chief downside of this approach is that it requires bookkeeping similar to live `Range` objects.
190200

0 commit comments

Comments
 (0)