Skip to content

Commit 4a93837

Browse files
imagoiqgfellerph
imagoiq
and
gfellerph
authored
fix(documentation,internet-header): Clarify and fix internet-header getting started doc (#1792)
Co-authored-by: Philipp Gfeller <[email protected]>
1 parent 61a47e8 commit 4a93837

File tree

4 files changed

+154
-81
lines changed

4 files changed

+154
-81
lines changed

‎.changeset/few-ducks-design.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@swisspost/internet-header': patch
3+
'@swisspost/design-system-documentation': patch
4+
---
5+
6+
Clarified and fixed which internet-header versions are available and how to use them.

‎packages/documentation-v6/src/stories/internet-header/getting-started.stories.mdx

Lines changed: 51 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,14 @@ The header for client-facing applications.
1717

1818
## Installation
1919

20-
### Angular, Vue JS, React (or any other bundler setup)
20+
### Choosing between lazy-loaded or bare component version
21+
22+
Internet-header package provide two versions:
23+
24+
* Lazy-loaded (default): it allows better performance by dynamically load the component when used, so it reduces bundle size, startup time and first paint.
25+
* Bare component: if you already manage the lazy-loading or don't need it for any reason, you can use the component without any overhead.
26+
27+
### Angular, Vue.js, React (or any other bundler setup)
2128

2229
All the popular frameworks come with some form of bundler. This makes it easy to use npm packages like the Internet Header as you can import, bundle and deliver the header with your own code.
2330

@@ -27,13 +34,6 @@ When working with Angular or any other framework, the easiest installation metho
2734
npm install @swisspost/internet-header
2835
```
2936

30-
```typescript
31-
// main.ts / index.js / ...
32-
import { defineCustomElements } from '@swisspost/internet-header';
33-
34-
defineCustomElements();
35-
```
36-
3737
```html
3838
<!-- index.html -->
3939
<body>
@@ -42,59 +42,77 @@ defineCustomElements();
4242
</body>
4343
```
4444

45+
#### Lazy-loaded
46+
47+
```javascript
48+
// main.ts / index.js / ...
49+
import { defineCustomElements } from '@swisspost/internet-header/loader';
50+
51+
defineCustomElements();
52+
```
53+
54+
#### Bare component
55+
56+
```javascript
57+
// main.ts / index.js / ...
58+
import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm';
59+
```
60+
4561
### Include from a CDN
4662

47-
If you are not using any loader or don't want to install from npm, you can load the `internet-header` from your favourite [CDN](https://en.wikipedia.org/wiki/Content_delivery_network).<br/>
48-
There are two options available. Make sure to replace `{version}` with the version you want to use.
63+
If you are not using any bundler or don't want to install from npm, you can load the `internet-header` from your favourite [CDN](https://en.wikipedia.org/wiki/Content_delivery_network).<br/>
64+
Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version.
65+
66+
Available CDNs:
4967

50-
- [jsDelivr](https://www.jsdelivr.com/)
51-
- [unpkg](https://unpkg.com/)
68+
* [jsDelivr](https://www.jsdelivr.com/): replace `{cdnURL}` with [https://cdn.jsdelivr.net/npm/@swisspost/internet-header](https://cdn.jsdelivr.net/npm/@swisspost/internet-header).
69+
* [unpkg](https://unpkg.com/): replace `{cdnURL}` with [https://unpkg.com/@swisspost/internet-header](https://unpkg.com/@swisspost/internet-header).
5270

53-
#### jsDelivr
71+
#### Lazy-loaded
72+
73+
```html
74+
<!DOCTYPE html>
75+
<html>
76+
<body>
77+
<swisspost-internet-header project="your-project-id"></swisspost-internet-header>
78+
</body>
79+
<script type="module">
80+
import { defineCustomElements } from '{cdnUrl}@{version}/loader/index.es2017.js';
81+
82+
defineCustomElements();
83+
</script>
84+
</html>
85+
```
86+
#### Bare component
5487

5588
```html
5689
<!-- index.html -->
5790
<head>
5891
<script
5992
async
6093
type="module"
61-
src="https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
94+
src="{cdnUrl}@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
6295
></script>
6396
</head>
6497
<body>
6598
<swisspost-internet-header project="your-project-id"></swisspost-internet-header>
6699
</body>
67100
```
68101

69-
```javascript
70-
// main.js | main.ts
71-
import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/loader/index.min.js';
72-
73-
defineCustomElements();
74-
```
75-
76-
#### unpkg
77-
78-
```javascript
79-
// main.js | main.ts
80-
import { defineCustomElements } from 'https://unpkg.com/@swisspost/internet-header@{version}/loader/index.min.js';
81-
82-
defineCustomElements();
83-
```
84-
85102
## Configuration
86103

87104
The Internet Header is built to support the already existing Portal Configuration used for the old Internet Header.
88105

89106
If you're working on a new project, you probably need a new configuration. Please click the button below.
90107

91108
<a
92-
class="mb-small-r btn-primary btn"
109+
className="mb-small-r btn-primary btn"
93110
href="mailto:[email protected]"
94111
target="_blank"
95112
rel="noopener"
96113
>
97-
Contact Post Portal Team<post-icon name="1001" class="fs-large"></post-icon>
114+
Contact Post Portal Team
115+
<post-icon name="1001" className="fs-large"></post-icon>
98116
</a>
99117

100118
Not every Online Service has configurations for all environments. For example, "TOPOS" only has `int02` configured and cannot use `int01` as value for environment. If you are not sure what's configured for your project, please reach out to the post-portal team as well.
@@ -103,4 +121,4 @@ For settings on the header itself, see the examples provided in the left menu ba
103121

104122
## Help
105123

106-
If you noticed a bug or need assistance with migrating to the new Internet Header, please post your enquiry at the [Design System Github Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a).
124+
If you noticed a bug or need assistance with migrating to the new Internet Header, please post your enquiry at the [Design System GitHub Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a).

‎packages/documentation/src/stories/internet-header/getting-started.docs.mdx

Lines changed: 53 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,22 @@ import { BADGE } from '../../../.storybook/constants';
1212

1313
The header for client-facing applications.
1414

15-
- [Installation](#installation)
16-
- [Configuration](#configuration)
17-
- [Help](#help)
15+
<ul>
16+
<li><a href="#installation" target="_self">Installation</a></li>
17+
<li><a href="#configuration" target="_self">Configuration</a></li>
18+
<li><a href="#help" target="_self">Help</a></li>
19+
</ul>
1820

1921
## Installation
2022

21-
### Angular, Vue JS, React (or any other bundler setup)
23+
### Choosing between lazy-loaded or bare component version
24+
25+
Internet-header package provide two versions:
26+
27+
* Lazy-loaded (default): it allows better performance by dynamically load the component when used, so it reduces bundle size, startup time and first paint.
28+
* Bare component: if you already manage the lazy-loading or don't need it for any reason, you can use the component without any overhead.
29+
30+
### Angular, Vue.js, React (or any other bundler setup)
2231

2332
All the popular frameworks come with some form of bundler.
2433
This makes it easy to use npm packages like the Internet Header as you can import,
@@ -30,13 +39,6 @@ When working with Angular or any other framework, the easiest installation metho
3039
npm install @swisspost/internet-header
3140
```
3241

33-
```typescript
34-
// main.ts / index.js / ...
35-
import { defineCustomElements } from '@swisspost/internet-header';
36-
37-
defineCustomElements();
38-
```
39-
4042
```html
4143
<!-- index.html -->
4244
<body>
@@ -45,49 +47,62 @@ defineCustomElements();
4547
</body>
4648
```
4749

50+
#### Lazy-loaded
51+
52+
```javascript
53+
// main.ts / index.js / ...
54+
import { defineCustomElements } from '@swisspost/internet-header/loader';
55+
56+
defineCustomElements();
57+
```
58+
59+
#### Bare component
60+
61+
```javascript
62+
// main.ts / index.js / ...
63+
import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm';
64+
```
65+
4866
### Include from a CDN
4967

50-
If you are not using any loader or don't want to install from npm,
51-
you can load the `internet-header` from your favourite
52-
[CDN](https://en.wikipedia.org/wiki/Content_delivery_network).<br/>
53-
There are two options available.
54-
Make sure to replace `{version}` with the version you want to use.
68+
If you are not using any bundler or don't want to install from npm, you can load the `internet-header` from your favourite [CDN](https://en.wikipedia.org/wiki/Content_delivery_network).<br/>
69+
Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version.
70+
71+
Available CDNs:
5572

56-
- [jsDelivr](https://www.jsdelivr.com/)
57-
- [unpkg](https://unpkg.com/)
73+
* [jsDelivr](https://www.jsdelivr.com/): replace `{cdnURL}` with [https://cdn.jsdelivr.net/npm/@swisspost/internet-header](https://cdn.jsdelivr.net/npm/@swisspost/internet-header).
74+
* [unpkg](https://unpkg.com/): replace `{cdnURL}` with [https://unpkg.com/@swisspost/internet-header](https://unpkg.com/@swisspost/internet-header).
5875

59-
#### jsDelivr
76+
#### Lazy-loaded
77+
78+
```html
79+
<!DOCTYPE html>
80+
<html>
81+
<body>
82+
<swisspost-internet-header project="your-project-id"></swisspost-internet-header>
83+
</body>
84+
<script type="module">
85+
import { defineCustomElements } from '{cdnUrl}@{version}/loader/index.es2017.js';
86+
defineCustomElements();
87+
</script>
88+
</html>
89+
```
90+
#### Bare component
6091

6192
```html
6293
<!-- index.html -->
6394
<head>
6495
<script
6596
async
6697
type="module"
67-
src="https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
98+
src="{cdnUrl}@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
6899
></script>
69100
</head>
70101
<body>
71102
<swisspost-internet-header project="your-project-id"></swisspost-internet-header>
72103
</body>
73104
```
74105

75-
```javascript
76-
// main.js | main.ts
77-
import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/loader/index.min.js';
78-
79-
defineCustomElements();
80-
```
81-
82-
#### unpkg
83-
84-
```javascript
85-
// main.js | main.ts
86-
import { defineCustomElements } from 'https://unpkg.com/@swisspost/internet-header@{version}/loader/index.min.js';
87-
88-
defineCustomElements();
89-
```
90-
91106
## Configuration
92107

93108
The Internet Header is built to support the already existing Portal Configuration used for the old Internet Header.
@@ -99,7 +114,7 @@ If you're working on a new project, you probably need a new configuration. Pleas
99114
href="mailto:[email protected]"
100115
target="_blank"
101116
rel="noopener"
102-
>Contact Post Portal Team <post-icon name="1001" className="fs-large"/></a>
117+
>Contact Post Portal Team <post-icon name="1001" className="fs-large" /></a>
103118

104119
Not every Online Service has configurations for all environments.
105120
For example, "TOPOS" only has `int02` configured and cannot use `int01` as value for environment.
@@ -109,5 +124,4 @@ For settings on the header itself, see the examples provided in the left menu ba
109124

110125
## Help
111126

112-
If you noticed a bug or need assistance with migrating to the new Internet Header,
113-
please post your enquiry at the [Design System GitHub Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a).
127+
If you noticed a bug or need assistance with migrating to the new Internet Header, please post your enquiry at the [Design System GitHub Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a).

‎packages/internet-header/readme.md

Lines changed: 44 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,36 +14,71 @@ The header docs are part of the storybook docs for the Design System.
1414

1515
There are two possibilities to install the header on a page.
1616

17-
### npm installation
17+
### Npm installation
1818

1919
Use this if your project uses a bundler or a framework like Angular, React or Vue.
2020

2121
```bash
2222
npm install @swisspost/internet-header
2323
```
2424

25-
`main.ts`
25+
```html
26+
<!-- index.html -->
27+
<body>
28+
<swisspost-internet-header project="your-project-id"></swisspost-internet-header>
29+
...
30+
</body>
31+
```
32+
33+
#### Lazy-loaded
2634

27-
```ts
28-
import { defineCustomElements } from '@swisspost/internet-header';
35+
```javascript
36+
// main.ts / index.js / ...
37+
import { defineCustomElements } from '@swisspost/internet-header/loader';
2938

3039
defineCustomElements();
3140
```
3241

42+
#### Bare component
43+
44+
```javascript
45+
// main.ts / index.js / ...
46+
import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm';
47+
```
48+
3349
### Basic installation
3450

3551
Use this if you want to use the CDN version and if you don't use a bundler or a framework.
52+
Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version.
3653

37-
`index.html`
54+
#### Lazy-loaded
3855

3956
```html
40-
<body>
41-
<swisspost-internet-header project="your-project-id"></swisspost-internet-header>
42-
...
57+
<!DOCTYPE html>
58+
<html>
59+
<body>
60+
<swisspost-internet-header project="your-project-id"></swisspost-internet-header>
61+
</body>
62+
<script type="module">
63+
import { defineCustomElements } from 'https://unpkg.com/@swisspost/internet-header@{version}/loader/index.es2017.js';
64+
65+
defineCustomElements();
66+
</script>
67+
</html>
68+
```
69+
#### Bare component
70+
71+
```html
72+
<!-- index.html -->
73+
<head>
4374
<script
75+
async
4476
type="module"
45-
src="https://unpkg.com/@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
77+
src="https://unpkg.com/@swisspost/internet-header@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js"
4678
></script>
79+
</head>
80+
<body>
81+
<swisspost-internet-header project="your-project-id"></swisspost-internet-header>
4782
</body>
4883
```
4984

0 commit comments

Comments
 (0)