@govflanders/vl-widget-global-header-types 0.0.6 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +24 -0
  2. package/README.md +74 -2
  3. package/package.json +4 -3
package/LICENSE ADDED
@@ -0,0 +1,24 @@
1
+ (The MIT License)
2
+
3
+ Copyright (c) 2009-2014 TJ Holowaychuk <tj@vision-media.ca>
4
+ Copyright (c) 2013-2014 Roman Shtylman <shtylman+expressjs@gmail.com>
5
+ Copyright (c) 2014-2015 Douglas Christopher Wilson <doug@somethingdoug.com>
6
+
7
+ Permission is hereby granted, free of charge, to any person obtaining
8
+ a copy of this software and associated documentation files (the
9
+ 'Software'), to deal in the Software without restriction, including
10
+ without limitation the rights to use, copy, modify, merge, publish,
11
+ distribute, sublicense, and/or sell copies of the Software, and to
12
+ permit persons to whom the Software is furnished to do so, subject to
13
+ the following conditions:
14
+
15
+ The above copyright notice and this permission notice shall be
16
+ included in all copies or substantial portions of the Software.
17
+
18
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
19
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
21
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
22
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
23
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
24
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -4,6 +4,60 @@ The **`@govflanders/vl-widget-global-header-types`** package provides TypeScript
4
4
 
5
5
  By using the types defined in this package, developers can ensure type-safe interactions with the widget while improving their development experience (DX) by utilizing autocompletion and built-in documentation.
6
6
 
7
+ ## Adding a Flanders Global Header to Your Website
8
+
9
+ You can integrate the **Flanders Global Header** into your website using one of two methods: the **entry script** or the **embed script**. Each serves a different purpose:
10
+
11
+ ### 1. Using the Entry Script
12
+
13
+ The entry script should be placed in the `<head>` section of your HTML, preferably at the top. This is essential because the `globalHeaderClient` object is only available after this script has loaded. With the entry script, the header does not render automatically, so you'll need to call the `mount` method to display it.
14
+
15
+ Example of using the entry script:
16
+
17
+ ```html
18
+ <!DOCTYPE html>
19
+ <html lang="nl">
20
+ <head>
21
+ <script src="https://widgets.test-vlaanderen.be/api/v2/widget/9717ae3b-84e8-43b2-a814-e35a2547927f/entry"></script>
22
+ <meta charset="UTF-8" />
23
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
24
+ <title>Global header entry script example</title>
25
+ </head>
26
+ <body>
27
+ <div class="your-website-code">👋 Hello world</div>
28
+ <script>
29
+ globalHeaderClient.mount(); // Mount the header manually after the script has loaded
30
+ </script>
31
+ </body>
32
+ </html>
33
+ ```
34
+
35
+ ### 2. Using the Embed Script
36
+
37
+ The embed script is meant to be placed directly inside the DOM where you want the header to appear. It automatically renders the header at the script's location in the HTML.
38
+
39
+ Example of using the embed script:
40
+
41
+ ```html
42
+ <!DOCTYPE html>
43
+ <html lang="nl">
44
+ <head>
45
+ <meta charset="UTF-8" />
46
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
47
+ <title>Global header embed script example</title>
48
+ </head>
49
+ <body>
50
+ <script src="https://widgets.test-vlaanderen.be/api/v2/widget/9717ae3b-84e8-43b2-a814-e35a2547927f/embed"></script>
51
+ <div class="your-website-code">👋 Hello world</div>
52
+ </body>
53
+ </html>
54
+ ```
55
+
56
+ ### Summary
57
+
58
+ - **Entry script**: Use in the `<head>`, requires manual mounting with [`globalHeaderClient.mount()` method](#mountelement-htmlelement-promiseboolean).
59
+ - **Embed script**: Place directly in the DOM, automatically renders the header at the script's location.
60
+
7
61
  ## Installation
8
62
 
9
63
  To install the `global-header-types` package, use the following command:
@@ -81,7 +135,7 @@ The `mount` method allows you to control where the **Global Header Widget** is r
81
135
  When you include the widget via the following script:
82
136
 
83
137
  ```html
84
- <script src="https://prod.widgets.burgerprofiel.vlaanderen.be/api/v1/widget/__global_header_id__/entry"></script>
138
+ <script src="https://prod.widgets.burgerprofiel.vlaanderen.be/api/v2/widget/__global_header_id__/entry"></script>
85
139
  ```
86
140
 
87
141
  The widget is **not automatically rendered** on the page. Instead, you must call the `mount` method from the `window.globalHeaderClient` object to display it. This gives you control over where and when the widget is added. You can either:
@@ -105,7 +159,7 @@ The `mount` method allows you to control where the **Global Header Widget** is r
105
159
  If you use this script instead:
106
160
 
107
161
  ```html
108
- <script src="https://prod.widgets.burgerprofiel.vlaanderen.be/api/v1/widget/__global_header_id__/embed"></script>
162
+ <script src="https://prod.widgets.burgerprofiel.vlaanderen.be/api/v2/widget/__global_header_id__/embed"></script>
109
163
  ```
110
164
 
111
165
  The widget will **automatically render** at the location where the script is placed in the HTML. No additional action is needed to mount the widget in this case.
@@ -115,6 +169,24 @@ The `mount` method returns a promise that resolves to `true` if the widget was s
115
169
 
116
170
  ## Notes
117
171
 
172
+ ### Language Switching
173
+
174
+ The widget automatically adapts to the language of the document. It observes the `lang` attribute on the `<html>` tag, so it's the implementer's responsibility to handle any language switching functionality. If the `lang` attribute changes, the widget will update to display the correct language.
175
+
176
+ Supported languages:
177
+ - nl (Dutch)
178
+ - fr (French)
179
+ - de (German)
180
+ - en (English)
181
+
182
+ To change the document language, you can use the following JavaScript snippet:
183
+
184
+ ```js
185
+ window.document.documentElement.lang = 'nl'; // 'nl', 'en', 'de' or 'fr'
186
+ ```
187
+
188
+ This will switch the document's language to Dutch, and the widget will automatically reflect the change.
189
+
118
190
  ### Translatable Type
119
191
 
120
192
  The `Translatable<T>` type allows an object to either be a single value or a language-specific dictionary. This is useful when content needs to be available in multiple languages.
package/package.json CHANGED
@@ -1,11 +1,13 @@
1
1
  {
2
2
  "name": "@govflanders/vl-widget-global-header-types",
3
- "version": "0.0.6",
3
+ "version": "0.0.8",
4
4
  "description": "TypeScript definitions for GlobalHeaderClient",
5
5
  "main": "",
6
6
  "types": "dist/index.d.ts",
7
7
  "files": [
8
- "dist"
8
+ "dist",
9
+ "LICENSE",
10
+ "README.md"
9
11
  ],
10
12
  "keywords": [
11
13
  "typescript",
@@ -23,7 +25,6 @@
23
25
  "scripts": {
24
26
  "build": "tsc -p tsconfig.json",
25
27
  "watch": "tsc -w",
26
- "prepublishOnly": "npm run build",
27
28
  "release": "yarn build && yarn version --patch --no-git-tag-version && git add . && git commit -m \"Release global-header-types $(node -p \"require('./package.json').version\")\" && git tag \"global-header-types-$(node -p \"require('./package.json').version\")\" && git push && git push --tags",
28
29
  "publish": "npm_config_registry=https://registry.npmjs.org/ npm publish --access public"
29
30
  }