Skip to content

Commit cadbd09

Browse files
noherczegnoherczeg
committed
chore: update docs
1 parent 50bca14 commit cadbd09

File tree

3 files changed

+100
-110
lines changed

3 files changed

+100
-110
lines changed

‎README.md‎

Lines changed: 88 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -60,35 +60,32 @@ a custom service which will alter the application it self.
6060
<p id="text-to-invert">This text should be inverted!</p>
6161

6262
<script type="module">
63-
window.addEventListener('DOMContentLoaded', async () => {
64-
// 0. Import Pandino it self. Since we are running in the browsers with modules, we need
65-
// the .mjs version.
66-
const Pandino = (await import('./pandino.mjs')).default;
67-
const pandino = new Pandino({
68-
'pandino.manifest.fetcher': {
69-
fetch: async (uri) => (await fetch(uri)).json(),
70-
},
71-
'pandino.bundle.importer': {
72-
import: (activatorLocation) => import(activatorLocation),
73-
},
74-
});
75-
76-
await pandino.init();
77-
await pandino.start();
78-
79-
// Pandino should be up and running, which should be visible by looking at the console
80-
// window of your browser's dev-tools
63+
// 0. Import Pandino, and a bundle loader config preset.
64+
import Pandino from 'https://unpkg.com/@pandino/pandino/dist/esm/pandino.mjs';
65+
import loaderConfiguration from 'https://unpkg.com/@pandino/loader-configuration-dom/dist/loader-configuration-dom.mjs';
66+
67+
const pandino = new Pandino({
68+
...loaderConfiguration,
8169
});
70+
71+
await pandino.init();
72+
await pandino.start();
73+
74+
// Pandino should be up and running, which should be visible by looking at the console
75+
// window of your browser's dev-tools
8276
</script>
8377
</body>
8478
</html>
8579
```
8680

87-
Pandino has 2 mandatory init parameters:
81+
In this example we are importing a `loaderConfiguration`. This is only for our convenience, you can implement
82+
your own loader if for some reason the default is not sufficient!
83+
84+
Pandino has 2 mandatory init parameters (which the `loaderConfiguration` also implement):
8885
- `pandino.manifest.fetcher`: an object with a `fetch()` method where we implement the [Manifest](./docs/basics.md) loading mechanism
8986
- `pandino.bundle.importer`: an object with an `import()` method where we implement the [Activator](./docs/basics.md) loading mechanism
9087

91-
The reason for why we need to manually define `pandino.manifest.fetcher` and `pandino.bundle.importer` is that
88+
The reason for why we would want to manually define `pandino.manifest.fetcher` and `pandino.bundle.importer` is that
9289
Pandino it self is platform agnostic, which means that the "file loading" mechanism will be different in e.g. a Browser
9390
compared to NodeJS.
9491

@@ -107,6 +104,25 @@ Every Bundle consists of at least 2 artifacts:
107104
- One Activator JavaScript file with or without the source code bundled into it
108105
- the Activator it self **MUST** be default exported!
109106

107+
**string-inverter-manifest.json**
108+
```json
109+
{
110+
"Bundle-ManifestVersion": "1",
111+
"Bundle-SymbolicName": "@example/string-inverter",
112+
"Bundle-Name": "String Inverter",
113+
"Bundle-Version": "0.1.0",
114+
"Bundle-Activator": "./string-inverter.js"
115+
}
116+
```
117+
118+
The `Bundle-SymbolicName` property should be considered to be similar to the `name` property in a `package.json` file.
119+
120+
The `Bundle-SymbolicName` and `Bundle-Version` properties together serve as "composite keys" (make the bundle uniquely
121+
identifiable)!
122+
123+
A complete list of Bundle Manifest Header properties can be found in the corresponding source code:
124+
[bundle-manifest-headers.ts](packages/@pandino/pandino-api/src/bundle/bundle-manifest-headers.ts)
125+
110126
**string-inverter.js**
111127
```javascript
112128
const STRING_INVERTER_INTERFACE_KEY = '@example/string-inverter/StringInverter';
@@ -131,25 +147,6 @@ export default class Activator {
131147
}
132148
```
133149

134-
**string-inverter-manifest.json**
135-
```json
136-
{
137-
"Bundle-ManifestVersion": "1",
138-
"Bundle-SymbolicName": "@example/string-inverter",
139-
"Bundle-Name": "String Inverter",
140-
"Bundle-Version": "0.1.0",
141-
"Bundle-Activator": "./string-inverter.js"
142-
}
143-
```
144-
145-
The `Bundle-SymbolicName` property should be considered to be similar to the `name` property in a `package.json` file.
146-
147-
The `Bundle-SymbolicName` and `Bundle-Version` properties together serve as "composite keys" (make the bundle uniquely
148-
identifiable)!
149-
150-
A complete list of Bundle Manifest Header properties can be found in the corresponding source code:
151-
[bundle-manifest-headers.ts](packages/@pandino/pandino-api/src/bundle/bundle-manifest-headers.ts)
152-
153150
### 3) Wire the Bundle into our application
154151

155152
**index.html**
@@ -167,33 +164,28 @@ A complete list of Bundle Manifest Header properties can be found in the corresp
167164
<p id="text-to-invert">This text should be inverted!</p>
168165

169166
<script type="module">
170-
window.addEventListener('DOMContentLoaded', async () => {
171-
const Pandino = (await import('./pandino.mjs')).default;
172-
const pandino = new Pandino({
173-
'pandino.manifest.fetcher': {
174-
fetch: async (uri) => (await fetch(uri)).json(),
175-
},
176-
'pandino.bundle.importer': {
177-
import: (activatorLocation) => import(activatorLocation),
178-
},
179-
});
180-
181-
await pandino.init();
182-
await pandino.start();
183-
184-
// 1. Install our new bundle via it's manifest:
185-
const context = pandino.getBundleContext();
186-
187-
await context.installBundle('./string-inverter-manifest.json');
188-
189-
// 2. Obtain a Service Object
190-
const inverterReference = context.getServiceReference('@example/string-inverter/StringInverter');
191-
const inverterService = context.getService(inverterReference);
192-
193-
// 3. Use our Service to invert some text in our DOM
194-
const paragraphToInvert = document.getElementById('text-to-invert');
195-
paragraphToInvert.textContent = inverterService.invert(paragraphToInvert.textContent);
167+
import Pandino from 'https://unpkg.com/@pandino/pandino/dist/esm/pandino.mjs';
168+
import loaderConfiguration from 'https://unpkg.com/@pandino/loader-configuration-dom/dist/loader-configuration-dom.mjs';
169+
170+
const pandino = new Pandino({
171+
...loaderConfiguration,
196172
});
173+
174+
await pandino.init();
175+
await pandino.start();
176+
177+
// 1. Install our new bundle via it's manifest:
178+
const context = pandino.getBundleContext();
179+
180+
await context.installBundle('./string-inverter-manifest.json');
181+
182+
// 2. Obtain a Service Object
183+
const inverterReference = context.getServiceReference('@example/string-inverter/StringInverter');
184+
const inverterService = context.getService(inverterReference);
185+
186+
// 3. Use our Service to invert some text in our DOM
187+
const paragraphToInvert = document.getElementById('text-to-invert');
188+
paragraphToInvert.textContent = inverterService.invert(paragraphToInvert.textContent);
197189
</script>
198190
</body>
199191
</html>
@@ -216,7 +208,7 @@ folders.
216208
This repository contains extra packages, e.g.: specifications, corresponding reference-implementations solving
217209
common software development problems. Usage is opt-in of course.
218210

219-
### Default Configurations
211+
### Default Loader Configurations
220212

221213
- [Loader Configuration - DOM](./packages/@pandino/loader-configuration-dom)
222214
- [Loader Configuration - NodeJS](./packages/@pandino/loader-configuration-nodejs)
@@ -246,6 +238,36 @@ common software development problems. Usage is opt-in of course.
246238

247239
- [rollup-plugin-generate-manifest](./packages/@pandino/rollup-plugin-generate-manifest)
248240

241+
## Roadmap
242+
243+
### v0.8.x
244+
245+
**Context:** This version range is the first public version published.
246+
247+
**Goal:** Gather community feedback, improve stability and APIs, introduce missing key features.
248+
249+
Users should expect breaking changes somewhat often.
250+
251+
There is no official end of life, a couple of months should pass at least until
252+
we will bump the version.
253+
254+
### v0.9.x
255+
256+
**Context:** This version range is a Release Candidate.
257+
258+
**Goal:** Fix bugs, improve stability.
259+
260+
No API breaking changes are allowed.
261+
262+
Similarly to `v0.8.x`, this range will have a lifetime of at least a couple of months.
263+
264+
### v1.0.x
265+
266+
**Context:** This version range is considered to be production-ready.
267+
268+
From this point onwards, we only plan to maintain a single version line. Based on our community and user-base growth, we
269+
may consider LTS branches in the future.
270+
249271
## License
250272

251273
Eclipse Public License - v 2.0

‎docs/installation.md‎

Lines changed: 12 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,17 @@ In the sections below, we will showcase different use-cases in which you can ins
66

77
```html
88
<script type="module">
9-
window.addEventListener('DOMContentLoaded', async () => {
10-
const Pandino = (await import('./pandino.js')).default;
9+
import loaderConfiguration from 'https://unpkg.com/@pandino/loader-configuration-dom/dist/loader-configuration-dom.mjs';
10+
import Pandino from 'https://unpkg.com/@pandino/pandino/dist/esm/pandino.mjs';
11+
1112
const pandino = new Pandino({
12-
'pandino.bundle.importer': {
13-
import: (activatorLocation) => import(activatorLocation),
14-
},
15-
'pandino.manifest.fetcher': {
16-
fetch: async (uri) => (await fetch(uri)).json(),
17-
},
13+
...loaderConfiguration,
1814
});
1915
2016
await pandino.init();
2117
await pandino.start();
2218
2319
console.log(pandino.getBundleContext());
24-
});
2520
</script>
2621
```
2722

@@ -33,21 +28,10 @@ Initialize it somewhere close in you applications own init logic, e.g.:
3328

3429
```typescript
3530
import Pandino from '@pandino/pandino';
36-
import {
37-
PANDINO_MANIFEST_FETCHER_PROP,
38-
PANDINO_BUNDLE_IMPORTER_PROP,
39-
DEPLOYMENT_ROOT_PROP,
40-
} from '@pandino/pandino-api';
31+
import loaderConfiguration from '@pandino/loader-configuration-dom';
4132

4233
const pandino = new Pandino({
43-
[DEPLOYMENT_ROOT_PROP]: location.href + 'deploy',
44-
[PANDINO_MANIFEST_FETCHER_PROP]: {
45-
fetch: async (uri: string, deploymentRoot?: string) => (await fetch(uri)).json(),
46-
},
47-
[PANDINO_BUNDLE_IMPORTER_PROP]: {
48-
import: (activatorLocation: string, manifestLocation: string, deploymentRoot?: string) =>
49-
import(/* webpackIgnore: true */ activatorLocation),
50-
},
34+
...loaderConfiguration,
5135
});
5236

5337
await pandino.init();
@@ -65,29 +49,19 @@ Initialize it somewhere close in you applications own init logic, e.g.:
6549
```javascript
6650
const Pandino = require("@pandino/pandino");
6751
const path = require("path");
68-
const fs = require("fs");
52+
const loaderConfiguration = require("@pandino/loader-configuration-nodejs");
6953

7054
const deploymentRoot = path.normalize(path.join(__dirname, 'deploy'));
7155

7256
const pandino = new Pandino({
73-
'pandino.deployment.root': deploymentRoot,
74-
'pandino.bundle.importer': {
75-
import: (activatorLocation, manifestLocation, deploymentRoot) => {
76-
return require(path.normalize(path.join(deploymentRoot, activatorLocation)));
77-
},
78-
},
79-
'pandino.manifest.fetcher': {
80-
fetch: async (uri, deploymentRoot) => {
81-
const data = fs.readFileSync(path.normalize(path.join(deploymentRoot, uri)), { encoding: 'utf8' });
82-
return JSON.parse(data);
83-
},
84-
},
57+
...loaderConfiguration,
58+
'pandino.deployment.root': deploymentRoot,
8559
});
8660

8761
(async () => {
88-
await pandino.init();
89-
await pandino.start();
62+
await pandino.init();
63+
await pandino.start();
9064

91-
await pandino.getBundleContext().installBundle('some-bundle-manifest.json');
65+
await pandino.getBundleContext().installBundle('some-bundle-manifest.json');
9266
})();
9367
```

‎examples/string-inverter/src/index.html‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,19 +21,13 @@ <h1>Hello!</h1>
2121
await pandino.init();
2222
await pandino.start();
2323

24-
// Pandino should be up and running, which should be visible by looking at the console
25-
// window of your browser's dev-tools
26-
27-
// 1. Install our new bundle via it's manifest:
2824
const context = pandino.getBundleContext();
2925

3026
await context.installBundle('./string-inverter-manifest.json');
3127

32-
// 2. Obtain a Service Object
3328
const inverterReference = context.getServiceReference('@example/string-inverter/StringInverter');
3429
const inverterService = context.getService(inverterReference);
3530

36-
// 3. Use our Service to invert some text in our DOM
3731
const paragraphToInvert = document.getElementById('text-to-invert');
3832
paragraphToInvert.textContent = inverterService.invert(paragraphToInvert.textContent);
3933
</script>

0 commit comments

Comments
 (0)