Skip to content

Commit 6e579cd

Browse files
FlorianRapplFlorianRappl
committed
Updated docs
1 parent 5edccb5 commit 6e579cd

File tree

9 files changed

+231
-10
lines changed

9 files changed

+231
-10
lines changed

‎data/diagrams.drawio

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
<mxfile host="Electron" modified="2024-07-10T09:04:32.024Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/16.5.1 Chrome/96.0.4664.110 Electron/16.0.7 Safari/537.36" etag="LR8aSIYFrbVT8OECjo-Z" version="16.5.1" type="device"><diagram id="_meZ_cWU2jmSIrhfbiGC" name="orchestrator">zZjbcto6FIafhksyPmNfBhLazrR7OjvdO+2lsGRbqZBcWQTo01eyZXwQONCYpmaGQb8OyGv9/rzsibtY795xkGefGERk4lhwN3HvJo4zCyz5rYR9JfiWXwkpx7CS7EZ4wD+RFvW8dIMhKjoDBWNE4LwrxoxSFIuOBjhn2+6whJHuv+YgRYbwEANiqo8YiqxSQ99q9PcIp1n9z7ale9agHqyFIgOQbVuSez9xF5wxUf1a7xaIqNjVcanmLU/0HjbGERXnTFhtYvcJijl0i8f/bp9+PFMxndZhfgZko89Y71bs6xBwtqEQqVXsiTvfZlighxzEqncrcy61TKyJ7i4EZ9/RghHGpUIZlcPmCSakliaOuywPqTO5DBbKGa4lm4DH2gChmsSoWII1Jqp/DjJaxBnHiTzXud4z4gLtTkbDPsRYehOxNRJ8L4fUE+q0aF+GurltkuzXQ7JWgh1Pi0AbKz0s3cRe/tDhvyAVgZGJDzQmG4iMhCAoLaqbjIuMpYwCct+o8yZlKq7NmI+M5TpRT0iIvQ432AjWTSPaYfFVTb/xdetbq+dup1cuG/u6QWUYWpNU81u7r5lWtup5A4kmYIXIHMTf0/KMeraqAqOiMWwCGTy24TEaug40WgBPkRgY5w+aamrdWLMg6hjL1X7hiACBn7tbPWYivfpnhuVJNENYkhRya32XHTbx+8azDeM9olUhr/IBElgvk6B30Se++uh0t/TqMMghe4LyuD4Jgi4JbNtEgX0MBcG1SBAaCVnICABMi78HBdYgCnq5hz4KoXcsx6Gzcl/K8TAEenaKZnfWbDYuHNwz4eBdDAfvr4eDa3jxE445k9KSy8gjCkelxOucMgINvLBLA8e135gGkZGBf2XUEX9TFrRJcODCC2WB3SkKmhrhVFnQu38kKIjjY86As2hlqRkQFNmhTh0LKMtlFJX3Jxn0W/VA0YyUyhKrZJb7LSQfRD0iJqAocFzLepg9Lpe8M7k07HjFJcvzOq6f2tHrwFQXP2F3xvU45R25Z65zmScqBgB1xgNNH1AAhclRGwZxiFbJ1QHlW/1yJTAAFR7hk38tPs2MyH9kwLwr/EE62RfQ6XLKjA6WEYngn0kEd9BiEgiR1y1UXg2E6xPAN3z4GceAw5sns2x+DQGSJHFOWCRYBX5dotRef+FeNAIRbKNk8d+WCLb5RDlxAqJON5NdQap+/cPUA2alyn9pOmoxr4VbsgX7Ql0iu1xSQf07lV9lFebftNbITy7xhQNa6Ig61upwhZ43++H/d+cNvFN1MWXVFvW7G0tk6htikHKwPrFOz57SC+LC12paKtQbNZpKwW9aX0p+Tp1T5TiT9ktIWbdkGEJEDRgPGLhHNas8zHd7Y/g88js+92bmg/rhdUvb6PZvOF02m1ezFaKa99vu/S8=</diagram></mxfile>
1+
<mxfile host="Electron" modified="2024-07-10T17:30:10.447Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/16.5.1 Chrome/96.0.4664.110 Electron/16.0.7 Safari/537.36" etag="ECwrDhsanksiN1a2M2c8" version="16.5.1" type="device"><diagram id="_meZ_cWU2jmSIrhfbiGC" name="orchestrator">zZjbcto6FIafhksyPmMuAwltZ9o9nZ3unfZSWLKtVEiuLAL06SvZ8lHgQGOakhmCfh2Q1/r9eaGJu9zs33GQpZ8YRGTiWHA/ce8mjmPbliP/KeVQKjNXCwnHUA9qhAf8E2nR0uoWQ5R3BgrGiMBZV4wYpSgSHQ1wznbdYTEj3W/NQIIM4SECxFQfMRRpqYa+1ejvEU5SUV+w7tmAarAW8hRAtmtJ7v3EXXLGRPlps18iooJXxaWctzrRW2+MIyrOmbDeRu4TFAvo5o//3T79eKZiOq3C/AzIVl+x3q04VCHgbEshUqvYE3exS7FADxmIVO9OJl1qqdgQ3Z0Lzr6jJSOMS4UyKoctYkxIJU0cd1W8pM7kMlgoZ7iWbAIeaQOEahKjYgU2mKj+BUhpHqUcx/JaF3rPiAu0PxkNu46xNCdiGyT4QQ6pJlRp0b4MdXPXJNmvhqStBDueFoE2VlIv3cReftDhvyAVgZGJDzQiW4iMhCAoLaqbjIuUJYwCct+oiyZlKq7NmI+MZTpRT0iIgw432ArWTSPaY/FVTb/xdetbq+dur1cuGoeqQWUYWpNU81u7r5lWtKp5A4kmYI3IAkTfk+KKerYqA6OiMWwCGTy25REaug80WgBPkBgY5w+aamrdWLNg3jGWq/3CEQECP3e3esxEevXPDMuLaIawOM7l1vouqzfx+8azDeM9onUu7/IBElgvk6B308e++tPpbunlyyCH7AmK1/VJEHRJYNsmCuxjKAiuRYLQSMhSRgBgmv89KLAGUdDLPfRRCL1jOQ6dtftSjoch0LPTfHZnzWbjwsE9Ew7exXDw/no4uIYXP+GIMymtuIw8onBUSrzOKSPQwAu7NHBc+41pMDcy8K+MOuJvyoI2CWouvFAW2J2ioKkRTpUFvedHjIIoOuYMOJuvLTUDgjyt69SxgLJazefF80kG/Vb9oGhGSmWFVTKL/eaSD6IaERGQ5ziqZD3MHpdL3plcGna84pLleR3XT+3568BUFT9hd8b1OOUdeWZuMpknKgYAdcYPmj6gAArjozYMohCt46sDyrf65UpgACo8wif/WnyaGZH/yID5VPiDdLIvoNPllBkdLCMSwT+TCO6gxSQQ5l63UHk1EK5PAN/w4WccAQ5vnsyy+TUEiOPYOWGRYB34VYlSef2FZ9EIRLCNksV/WyLY5i/KiRMQdbmp7AoS9ekfpn5glqr8lqajErNKuCU7cMjVLbLPJBXUt1P5VlRh/k1rjezkEl84oLmOqGOt6zv0vNkP/787b+CdqospK7eoz24skap3iEHCwebEOj17Si+IC4/VtJSrEzWaSMFvWl8Kfk6dU+U4k/aLSVG3pBhCRA0YDxjYoJplFZjsne2NUZp3bV4fz7VsXp+2tH1u/4bRZbM5mS0J1Zxvu/e/AA==</diagram></mxfile>

‎data/~$diagrams.drawio.dtmp

-1
This file was deleted.

‎guide/components/pi-component.md

+30-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,32 @@
11
# Using `pi-component`
22

3-
...
3+
The `pi-component` can be used to render a component from a micro frontend on a website.
4+
5+
Consider the following HTML:
6+
7+
```html
8+
<div class="d-flex p-2 justify-content-center">
9+
<pi-component
10+
name="counter"
11+
source="https://assets.piral.cloud/pilets/picard-demos/pi-simple-html/1.0.1/index.meta.json"
12+
format="pilet"
13+
></pi-component>
14+
</div>
15+
```
16+
17+
Here we say "at this position, i.e., inside the `<div>` element, render the component named `counter` from the micro frontend (pilet) located at the given URL".
18+
19+
Using this instruction Picard.js will load the micro frontend, get the component definition, and finally mount the component in the `pi-component` element, which acts as a container.
20+
21+
In case the micro frontend was already loaded from a micro frontend discovery service we can simplify the markup significantly:
22+
23+
```html{4}
24+
<div class="d-flex p-2 justify-content-center">
25+
<pi-component
26+
name="counter"
27+
source="pi-simple-html"
28+
></pi-component>
29+
</div>
30+
```
31+
32+
Here, we only need to tell Picard the name of the micro frontend as `source`. Importantly, the `format` specifier (and others) are unnecessary now - as all this has already been fully determined from the micro frontend discovery response.

‎guide/components/pi-part.md

+37-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,39 @@
11
# Using `pi-part`
22

3-
...
3+
The `pi-part` component is available exclusively on the server. On the client, this component won't render at all.
4+
5+
This component is essentially a replacement rule that is applied by the `decorate` function of Picard.
6+
7+
Consider the following HTML:
8+
9+
```html
10+
<!DOCTYPE html>
11+
<html lang="en">
12+
<head>
13+
<meta charset="UTF-8">
14+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
15+
<title>Picard.js</title>
16+
<pi-part name="style"></pi-part>
17+
</head>
18+
<body></body>
19+
</html>
20+
```
21+
22+
When the decorator sees a `pi-part` it will replace the covered span by the found replacement string. In case of a `style` replacement this might look similar to:
23+
24+
```html
25+
<!DOCTYPE html>
26+
<html lang="en">
27+
<head>
28+
<meta charset="UTF-8">
29+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
30+
<title>Picard.js</title>
31+
<style>pi-component, pi-slot { display: contents }</style>
32+
</head>
33+
<body></body>
34+
</html>
35+
```
36+
37+
::: tip
38+
You can define additional replacement services. The used service name is `part.{name}`, where `{name}` refers to the name of the part that you want to provide.
39+
:::

‎guide/components/pi-slot.md

+71-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,73 @@
11
# Using `pi-slot`
22

3-
...
3+
The `pi-slot` component introduces a micro frontend independent rendering slot. It will automatically look into all currently loaded micro frontends - trying to locate exposed components by the given `name` attribute. All found components will be rendered inside the `pi-slot`.
4+
5+
Consider the following HTML:
6+
7+
```html
8+
<div class="d-flex p-2 justify-content-center">
9+
<pi-slot name="counter"></pi-slot>
10+
</div>
11+
```
12+
13+
Inside this area all found components with the name `counter` will be rendered. Let's say we only found one. The resulting HTML would be:
14+
15+
```html
16+
<div class="d-flex p-2 justify-content-center">
17+
<pi-slot name="counter">
18+
<pi-component cid="12356"></pi-component>
19+
</pi-slot>
20+
</div>
21+
```
22+
23+
At this point the `pi-component` would take over; except that it does not need to resolve any micro frontend. As the `cid` attribute is set it can directly render the referenced component.
24+
25+
What if the `pi-slot` found multiple components? Let's say we found three. The resulting HTML could look like this:
26+
27+
```html
28+
<div class="d-flex p-2 justify-content-center">
29+
<pi-slot name="counter">
30+
<pi-component cid="12356"></pi-component>
31+
<pi-component cid="12357"></pi-component>
32+
<pi-component cid="12358"></pi-component>
33+
</pi-slot>
34+
</div>
35+
```
36+
37+
Maybe this is exactly what we want - maybe not. If not, we might be interested in actually containing these elements in another structure.
38+
39+
By using a `<template>` element together with the `item-template-id` attribute we can wrap each component in another structure:
40+
41+
```html
42+
<div class="d-flex p-2 justify-content-center">
43+
<pi-slot name="counter" item-template-id="my-template"></pi-slot>
44+
</div>
45+
<template id="my-template">
46+
<div class="some-class">
47+
<slot></slot>
48+
</div>
49+
</template>
50+
```
51+
52+
The resulting HTML is:
53+
54+
```html
55+
<div class="d-flex p-2 justify-content-center">
56+
<pi-slot name="counter" item-template-id="my-template">
57+
<div class="some-class">
58+
<pi-component cid="12356"></pi-component>
59+
</div>
60+
<div class="some-class">
61+
<pi-component cid="12357"></pi-component>
62+
</div>
63+
<div class="some-class">
64+
<pi-component cid="12358"></pi-component>
65+
</div>
66+
</pi-slot>
67+
</div>
68+
<template id="my-template">
69+
<div class="some-class">
70+
<slot></slot>
71+
</div>
72+
</template>
73+
```

‎guide/frameworks/html.md

+21-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,24 @@ HTML is the foundational layer of everything - the markup that is understood by
66

77
## Using HTML Fragments in Picard.js
88

9-
...
9+
Let's see how an example HTML fragment can be exposed:
10+
11+
```js
12+
const html = `<div>Hello World!</div>`;
13+
14+
export default html;
15+
```
16+
17+
With this definition your component is properly exported. The exported string indicates the content of the component.
18+
19+
Now you can use this HTML fragment in a `pi-component` as follows:
20+
21+
```html{4}
22+
<pi-component
23+
name="MyComponent"
24+
source="some-mfe"
25+
framework="html"
26+
></pi-component>
27+
```
28+
29+
This will work on the client, as well as on the server. In both cases the retrieved string represents the `innerHTML` of the `pi-component`.

‎guide/frameworks/single-spa.md

+35-1
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,38 @@ The key advantage of single-spa's component model is its support for gradual upg
88

99
## Using single-spa in Picard.js
1010

11-
...
11+
Let's see how an example single-spa component can be exposed:
12+
13+
```js
14+
import React from 'react';
15+
import ReactDOM from 'react-dom';
16+
import singleSpaReact from 'single-spa-react';
17+
18+
const lifecycles = singleSpaReact({
19+
React,
20+
ReactDOM,
21+
errorBoundary() {
22+
return <div>Error</div>;
23+
},
24+
loadRootComponent: () => import('./Product').then((mod) => mod.default),
25+
});
26+
27+
export const bootstrap = lifecycles.bootstrap;
28+
export const mount = lifecycles.mount;
29+
export const unmount = lifecycles.unmount;
30+
export const update = lifecycles.update;
31+
```
32+
33+
With this definition your component lifecycle is properly exported. The exported methods are all part of the standard single-spa component model.
34+
35+
Now you can use this single-spa component in a `pi-component` as follows:
36+
37+
```html{4}
38+
<pi-component
39+
name="MyComponent"
40+
source="some-mfe"
41+
framework="single-spa"
42+
></pi-component>
43+
```
44+
45+
This will only work in the client, as single-spa does not define any functions that could be used for server-side rendering.

‎guide/frameworks/web-components.md

+34-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,37 @@ Web components are a set of standardized APIs for creating reusable, encapsulate
66

77
## Using Web Components in Picard.js
88

9-
...
9+
Let's see how an example web component can be exposed:
10+
11+
```js
12+
class MyWebComponent extends HTMLElement {
13+
constructor() {
14+
super();
15+
}
16+
17+
connectedCallback() {
18+
// your display logic
19+
}
20+
}
21+
22+
const name = 'my-component';
23+
customElements.define(name, MyWebComponent);
24+
25+
export default name;
26+
```
27+
28+
With this definition your component is properly exported. The exported string indicates the name of the web component.
29+
30+
Now you can use this web component in a `pi-component` as follows:
31+
32+
```html{4}
33+
<pi-component
34+
name="MyComponent"
35+
source="some-mfe"
36+
framework="web-component"
37+
></pi-component>
38+
```
39+
40+
This will automatically create an HTML structure like `<my-component></my-component>`; working on the client, as well as on the server.
41+
42+
The incoming data will be spread as attributes into the component.

‎guide/index.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ Now start creating regions in the HTML for the components of the micro frontends
3131
name="MyComponent"
3232
source="https://yourcompany.com/example/remoteEntry.js"
3333
format="module"
34-
remote-name="example">
35-
</pi-component>
34+
remote-name="example"
35+
></pi-component>
3636
```
3737

3838
The `pi-component` web component acts as a container element to display the content brought in by the component (in this case `MyComponent`) of the referenced micro frontend (specified by its `source`, `format`, and - necessary in this case - `remote-name`).

0 commit comments

Comments
 (0)