-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
fix(documentation,internet-header): Clarify and fix internet-header g…
…etting started doc (#1792) Co-authored-by: Philipp Gfeller <[email protected]>
- Loading branch information
Showing
4 changed files
with
154 additions
and
81 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| --- | ||
| '@swisspost/internet-header': patch | ||
| '@swisspost/design-system-documentation': patch | ||
| --- | ||
|
|
||
| Clarified and fixed which internet-header versions are available and how to use them. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -17,7 +17,14 @@ The header for client-facing applications. | |
|
|
||
| ## Installation | ||
|
|
||
| ### Angular, Vue JS, React (or any other bundler setup) | ||
| ### Choosing between lazy-loaded or bare component version | ||
|
|
||
| Internet-header package provide two versions: | ||
|
|
||
| * Lazy-loaded (default): it allows better performance by dynamically load the component when used, so it reduces bundle size, startup time and first paint. | ||
| * 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. | ||
|
|
||
| ### Angular, Vue.js, React (or any other bundler setup) | ||
|
|
||
| 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. | ||
|
|
||
|
|
@@ -27,13 +34,6 @@ When working with Angular or any other framework, the easiest installation metho | |
| npm install @swisspost/internet-header | ||
| ``` | ||
|
|
||
| ```typescript | ||
| // main.ts / index.js / ... | ||
| import { defineCustomElements } from '@swisspost/internet-header'; | ||
|
|
||
| defineCustomElements(); | ||
| ``` | ||
|
|
||
| ```html | ||
| <!-- index.html --> | ||
| <body> | ||
|
|
@@ -42,59 +42,77 @@ defineCustomElements(); | |
| </body> | ||
| ``` | ||
|
|
||
| #### Lazy-loaded | ||
|
|
||
| ```javascript | ||
| // main.ts / index.js / ... | ||
| import { defineCustomElements } from '@swisspost/internet-header/loader'; | ||
|
|
||
| defineCustomElements(); | ||
| ``` | ||
|
|
||
| #### Bare component | ||
|
|
||
| ```javascript | ||
| // main.ts / index.js / ... | ||
| import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm'; | ||
| ``` | ||
|
|
||
| ### Include from a CDN | ||
|
|
||
| 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/> | ||
| There are two options available. Make sure to replace `{version}` with the version you want to use. | ||
| 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/> | ||
| Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version. | ||
|
|
||
| Available CDNs: | ||
|
|
||
| - [jsDelivr](https://www.jsdelivr.com/) | ||
| - [unpkg](https://unpkg.com/) | ||
| * [jsDelivr](https://www.jsdelivr.com/): replace `{cdnURL}` with [https://cdn.jsdelivr.net/npm/@swisspost/internet-header](https://cdn.jsdelivr.net/npm/@swisspost/internet-header). | ||
| * [unpkg](https://unpkg.com/): replace `{cdnURL}` with [https://unpkg.com/@swisspost/internet-header](https://unpkg.com/@swisspost/internet-header). | ||
|
|
||
| #### jsDelivr | ||
| #### Lazy-loaded | ||
|
|
||
| ```html | ||
| <!DOCTYPE html> | ||
| <html> | ||
| <body> | ||
| <swisspost-internet-header project="your-project-id"></swisspost-internet-header> | ||
| </body> | ||
| <script type="module"> | ||
| import { defineCustomElements } from '{cdnUrl}@{version}/loader/index.es2017.js'; | ||
| defineCustomElements(); | ||
| </script> | ||
| </html> | ||
| ``` | ||
| #### Bare component | ||
|
|
||
| ```html | ||
| <!-- index.html --> | ||
| <head> | ||
| <script | ||
| async | ||
| type="module" | ||
| src="https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js" | ||
| src="{cdnUrl}@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js" | ||
| ></script> | ||
| </head> | ||
| <body> | ||
| <swisspost-internet-header project="your-project-id"></swisspost-internet-header> | ||
| </body> | ||
| ``` | ||
|
|
||
| ```javascript | ||
| // main.js | main.ts | ||
| import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/loader/index.min.js'; | ||
|
|
||
| defineCustomElements(); | ||
| ``` | ||
|
|
||
| #### unpkg | ||
|
|
||
| ```javascript | ||
| // main.js | main.ts | ||
| import { defineCustomElements } from 'https://unpkg.com/@swisspost/internet-header@{version}/loader/index.min.js'; | ||
|
|
||
| defineCustomElements(); | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| The Internet Header is built to support the already existing Portal Configuration used for the old Internet Header. | ||
|
|
||
| If you're working on a new project, you probably need a new configuration. Please click the button below. | ||
|
|
||
| <a | ||
| class="mb-small-r btn-primary btn" | ||
| className="mb-small-r btn-primary btn" | ||
| href="mailto:[email protected]" | ||
| target="_blank" | ||
| rel="noopener" | ||
| > | ||
| Contact Post Portal Team<post-icon name="1001" class="fs-large"></post-icon> | ||
| Contact Post Portal Team | ||
| <post-icon name="1001" className="fs-large"></post-icon> | ||
| </a> | ||
|
|
||
| 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 | |
|
|
||
| ## Help | ||
|
|
||
| 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). | ||
| 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). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -12,13 +12,22 @@ import { BADGE } from '../../../.storybook/constants'; | |
|
|
||
| The header for client-facing applications. | ||
|
|
||
| - [Installation](#installation) | ||
| - [Configuration](#configuration) | ||
| - [Help](#help) | ||
| <ul> | ||
| <li><a href="#installation" target="_self">Installation</a></li> | ||
| <li><a href="#configuration" target="_self">Configuration</a></li> | ||
| <li><a href="#help" target="_self">Help</a></li> | ||
| </ul> | ||
|
|
||
| ## Installation | ||
|
|
||
| ### Angular, Vue JS, React (or any other bundler setup) | ||
| ### Choosing between lazy-loaded or bare component version | ||
|
|
||
| Internet-header package provide two versions: | ||
|
|
||
| * Lazy-loaded (default): it allows better performance by dynamically load the component when used, so it reduces bundle size, startup time and first paint. | ||
| * 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. | ||
|
|
||
| ### Angular, Vue.js, React (or any other bundler setup) | ||
|
|
||
| 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, | ||
|
|
@@ -30,13 +39,6 @@ When working with Angular or any other framework, the easiest installation metho | |
| npm install @swisspost/internet-header | ||
| ``` | ||
|
|
||
| ```typescript | ||
| // main.ts / index.js / ... | ||
| import { defineCustomElements } from '@swisspost/internet-header'; | ||
|
|
||
| defineCustomElements(); | ||
| ``` | ||
|
|
||
| ```html | ||
| <!-- index.html --> | ||
| <body> | ||
|
|
@@ -45,49 +47,62 @@ defineCustomElements(); | |
| </body> | ||
| ``` | ||
|
|
||
| #### Lazy-loaded | ||
|
|
||
| ```javascript | ||
| // main.ts / index.js / ... | ||
| import { defineCustomElements } from '@swisspost/internet-header/loader'; | ||
|
|
||
| defineCustomElements(); | ||
| ``` | ||
|
|
||
| #### Bare component | ||
|
|
||
| ```javascript | ||
| // main.ts / index.js / ... | ||
| import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm'; | ||
| ``` | ||
|
|
||
| ### Include from a CDN | ||
|
|
||
| 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/> | ||
| There are two options available. | ||
| Make sure to replace `{version}` with the version you want to use. | ||
| 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/> | ||
| Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version. | ||
|
|
||
| Available CDNs: | ||
|
|
||
| - [jsDelivr](https://www.jsdelivr.com/) | ||
| - [unpkg](https://unpkg.com/) | ||
| * [jsDelivr](https://www.jsdelivr.com/): replace `{cdnURL}` with [https://cdn.jsdelivr.net/npm/@swisspost/internet-header](https://cdn.jsdelivr.net/npm/@swisspost/internet-header). | ||
| * [unpkg](https://unpkg.com/): replace `{cdnURL}` with [https://unpkg.com/@swisspost/internet-header](https://unpkg.com/@swisspost/internet-header). | ||
|
|
||
| #### jsDelivr | ||
| #### Lazy-loaded | ||
|
|
||
| ```html | ||
| <!DOCTYPE html> | ||
| <html> | ||
| <body> | ||
| <swisspost-internet-header project="your-project-id"></swisspost-internet-header> | ||
| </body> | ||
| <script type="module"> | ||
| import { defineCustomElements } from '{cdnUrl}@{version}/loader/index.es2017.js'; | ||
| defineCustomElements(); | ||
| </script> | ||
| </html> | ||
| ``` | ||
| #### Bare component | ||
|
|
||
| ```html | ||
| <!-- index.html --> | ||
| <head> | ||
| <script | ||
| async | ||
| type="module" | ||
| src="https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js" | ||
| src="{cdnUrl}@{version}/dist/swisspost-internet-header/swisspost-internet-header.esm.js" | ||
| ></script> | ||
| </head> | ||
| <body> | ||
| <swisspost-internet-header project="your-project-id"></swisspost-internet-header> | ||
| </body> | ||
| ``` | ||
|
|
||
| ```javascript | ||
| // main.js | main.ts | ||
| import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/loader/index.min.js'; | ||
|
|
||
| defineCustomElements(); | ||
| ``` | ||
|
|
||
| #### unpkg | ||
|
|
||
| ```javascript | ||
| // main.js | main.ts | ||
| import { defineCustomElements } from 'https://unpkg.com/@swisspost/internet-header@{version}/loader/index.min.js'; | ||
|
|
||
| defineCustomElements(); | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| 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 | |
| href="mailto:[email protected]" | ||
| target="_blank" | ||
| rel="noopener" | ||
| >Contact Post Portal Team <post-icon name="1001" className="fs-large"/></a> | ||
| >Contact Post Portal Team <post-icon name="1001" className="fs-large" /></a> | ||
|
|
||
| Not every Online Service has configurations for all environments. | ||
| 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 | |
|
|
||
| ## Help | ||
|
|
||
| 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). | ||
| 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). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters