Skip to content

Commit 8a25911

Browse files
janechujanechu
authored
Adds some more nesting examples with hydration markup (#7123)
# Pull Request ## 📖 Description This change adds a bit more to the documentation for rendering hydratable markup by adding more nesting examples to showcase how nested templates interact with each other. ## ✅ Checklist ### General <!--- Review the list and put an x in the boxes that apply. --> - [x] I have included a change request file using `$ npm run change` - [ ] I have added tests for my changes. - [ ] I have tested my changes. - [x] I have updated the project documentation to reflect my changes. - [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.
1 parent f5beeed commit 8a25911

File tree

2 files changed

+193
-0
lines changed

2 files changed

+193
-0
lines changed

‎change/@microsoft-fast-html-e9fa77b7-9279-44a2-94d1-d496d5587c23.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"type": "none",
3+
"comment": "Adds some more nesting examples with hydration markup",
4+
"packageName": "@microsoft/fast-html",
5+
"email": "[email protected]",
6+
"dependentChangeType": "none"
7+
}

‎packages/web-components/fast-html/RENDERING.md

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,21 @@ An attribute binding is tracked using a dataset attribute with the name `data-fe
185185

186186
#### Examples
187187

188+
**Note**
189+
Examples shown below mostly skip the wrapping custom element and the internal template element with `shadowrootmode="open"`.
190+
191+
Typically along with the content from the examples below, the rendering should include:
192+
193+
```html
194+
<my-component defer-hydration needs-hydration>
195+
<template shadowrootmode="open" shadowroot="open">
196+
<!-- hydratable content -->
197+
</template>
198+
</my-component>
199+
```
200+
201+
The `needs-hydration` attribute is controlled by the hydration logic once `defer-hydration` has been removed, there is no need to modify it manually but it must be included to indicate that this component has not yet been hydrated.
202+
188203
**Simple content example**
189204

190205
Content bindings such as:
@@ -334,4 +349,175 @@ Should result in:
334349
```html
335350
<!--fe-b$$start$$0$$t01oHhokPY$$fe-b-->
336351
<!--fe-b$$end$$0$$t01oHhokPY$$fe-b-->
352+
```
353+
354+
#### More Examples
355+
356+
##### Nested Whens
357+
358+
Example when binding:
359+
```html
360+
<f-when value="{show}">
361+
<span>{{text}}</span>
362+
<f-when value="{showInternal}">
363+
<span>{{internalText}}</span>
364+
</f-when>
365+
</f-when>
366+
```
367+
368+
Combined with state:
369+
```json
370+
{
371+
"show": true,
372+
"text": "Hello world",
373+
"showInternal": true,
374+
"internalText": "Hello pluto"
375+
}
376+
```
377+
378+
Should result in:
379+
```html
380+
<!--fe-b$$start$$0$$jrvV0wUQrP$$fe-b-->
381+
<span>
382+
<!--fe-b$$start$$0$$CdUO4vHUmG$$fe-b-->Hello world<!--fe-b$$end$$0$$CdUO4vHUmG$$fe-b-->
383+
</span>
384+
<!--fe-b$$start$$1$$CdUO4vHUmG$$fe-b-->
385+
<span>
386+
<!--fe-b$$start$$0$$dF9tRRuOjZ$$fe-b-->Hello pluto<!--fe-b$$end$$0$$dF9tRRuOjZ$$fe-b-->
387+
</span>
388+
<!--fe-b$$end$$1$$CdUO4vHUmG$$fe-b-->
389+
<!--fe-b$$end$$0$$jrvV0wUQrP$$fe-b-->
390+
```
391+
392+
##### Nested Repeats
393+
394+
Example when binding:
395+
```html
396+
<f-repeat value="{item in items}">
397+
<div>
398+
<span>{{item.name}}</span>
399+
<f-when value="{!!item.nested}">
400+
<ul>
401+
<f-repeat value="{person in item.nested}">
402+
<li>{{person.name}}</li>
403+
</f-repeat>
404+
</ul>
405+
</f-when>
406+
</div>
407+
</f-repeat>
408+
```
409+
410+
Combined with state:
411+
```json
412+
{
413+
"items": [
414+
{
415+
"name": "Bob"
416+
},
417+
{
418+
"name": "Alice"
419+
},
420+
{
421+
"name": "Sue",
422+
"nested": [
423+
{
424+
"name": "Amy"
425+
},
426+
{
427+
"name": "Clarice"
428+
},
429+
{
430+
"name": "Lawrence"
431+
}
432+
]
433+
}
434+
]
435+
}
436+
```
437+
438+
Should result in:
439+
```html
440+
<!--fe-b$$start$$0$$kk4YD4Dgs4$$fe-b-->
441+
<!--fe-repeat$$start$$0$$fe-repeat-->
442+
<div>
443+
<span><!--fe-b$$start$$0$$gNrHXYDXTx$$fe-b-->Bob<!--fe-b$$end$$0$$gNrHXYDXTx$$fe-b--></span>
444+
<!--fe-b$$start$$1$$gNrHXYDXTx$$fe-b--><!--fe-b$$end$$1$$gNrHXYDXTx$$fe-b-->
445+
</div>
446+
<!--fe-repeat$$end$$0$$fe-repeat--><!--fe-repeat$$start$$1$$fe-repeat-->
447+
<div>
448+
<span><!--fe-b$$start$$0$$gNrHXYDXTx$$fe-b-->Alice<!--fe-b$$end$$0$$gNrHXYDXTx$$fe-b--></span>
449+
<!--fe-b$$start$$1$$gNrHXYDXTx$$fe-b--><!--fe-b$$end$$1$$gNrHXYDXTx$$fe-b-->
450+
</div>
451+
<!--fe-repeat$$end$$1$$fe-repeat--><!--fe-repeat$$start$$2$$fe-repeat-->
452+
<div>
453+
<span><!--fe-b$$start$$0$$gNrHXYDXTx$$fe-b-->Sue<!--fe-b$$end$$0$$gNrHXYDXTx$$fe-b--></span>
454+
<!--fe-b$$start$$1$$gNrHXYDXTx$$fe-b-->
455+
<ul>
456+
<!--fe-b$$start$$0$$ZfcR5fBAPc$$fe-b-->
457+
<!--fe-repeat$$start$$0$$fe-repeat-->
458+
<li>
459+
<!--fe-b$$start$$0$$gLPEVysLM5$$fe-b-->Amy<!--fe-b$$end$$0$$gLPEVysLM5$$fe-b-->
460+
</li>
461+
<!--fe-repeat$$end$$0$$fe-repeat-->
462+
<!--fe-repeat$$start$$1$$fe-repeat-->
463+
<li>
464+
<!--fe-b$$start$$0$$gLPEVysLM5$$fe-b-->Clarice<!--fe-b$$end$$0$$gLPEVysLM5$$fe-b-->
465+
</li>
466+
<!--fe-repeat$$end$$1$$fe-repeat-->
467+
<!--fe-repeat$$start$$2$$fe-repeat-->
468+
<li>
469+
<!--fe-b$$start$$0$$gLPEVysLM5$$fe-b-->Lawrence<!--fe-b$$end$$0$$gLPEVysLM5$$fe-b-->
470+
</li>
471+
<!--fe-repeat$$end$$2$$fe-repeat-->
472+
<!--fe-b$$end$$0$$ZfcR5fBAPc$$fe-b-->
473+
</ul>
474+
<!--fe-b$$end$$1$$gNrHXYDXTx$$fe-b-->
475+
</div>
476+
<!--fe-repeat$$end$$2$$fe-repeat-->
477+
<!--fe-b$$end$$0$$kk4YD4Dgs4$$fe-b-->
478+
```
479+
480+
##### Nested components with `<slot>`
481+
482+
This example shows the wrapping custom element tag as well as the template component with `shadowrootmode="open"` for the sake of illustrating an example that would exist in the DOM.
483+
484+
Example template of component "nested-component":
485+
```html
486+
<f-when value="{showButton}">
487+
<my-button appearance="{{appearance}}">{{text}}</my-button>
488+
</f-when>
489+
```
490+
491+
Example template of component "my-button":
492+
```html
493+
<button class="{{appearance}}">
494+
<slot></slot>
495+
</button>
496+
```
497+
498+
Combined with state:
499+
```json
500+
{
501+
"showButton": true,
502+
"text": "Hello world",
503+
"appearance": "fancy"
504+
}
505+
```
506+
507+
Should result in:
508+
```html
509+
<nested-components defer-hydration needs-hydration>
510+
<template shadowrootmode="open" shadowroot="open">
511+
<!--fe-b$$start$$0$$3oGiwLq7Ct$$fe-b-->
512+
<my-button data-fe-b-0 appearance="fancy" defer-hydration needs-hydration>
513+
<template shadowrootmode="open" shadowroot="open">
514+
<button class="default" data-fe-b-0>
515+
<slot></slot>
516+
</button>
517+
</template>
518+
<!--fe-b$$start$$1$$SUBjh6rowl$$fe-b-->Hello world<!--fe-b$$end$$1$$SUBjh6rowl$$fe-b-->
519+
</my-button>
520+
<!--fe-b$$end$$0$$3oGiwLq7Ct$$fe-b-->
521+
</template>
522+
</nested-components>
337523
```

0 commit comments

Comments
 (0)