@govflanders/vl-widget-global-footer-types
v1.0.15
Published
TypeScript definitions for GlobalFooterClient
Downloads
824
Readme
The @govflanders/vl-widget-global-footer-types package provides TypeScript types and interfaces for interacting with the Global Footer Widget. This widget is embedded in customer web pages and exposes a client object (window.globalFooterClient) that allows for dynamic configuration and interaction with the global footer.
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.
Adding a Flanders Global Footer to Your Website
You can integrate the Flanders Global Footer into your website using one of two methods: the entry script or the embed script. Each serves a different purpose:
Using the Entry Script
The entry script should be placed in the <head> section of your HTML, preferably at the top. This ensures that the globalFooterClient object is available after the script has loaded. With the entry script, the footer does not render automatically, so you'll need to call the mount method to display it.
Example of using the entry script:
<!DOCTYPE html>
<html lang="nl">
<head>
<script src="https://widgets.test-vlaanderen.be/api/v2/widget/your-global-footer-id/entry"></script>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Global footer entry script example</title>
</head>
<body>
<div class="your-website-code">👋 Hello world</div>
<script>
globalFooterClient.mount(); // Mount the footer manually after the script has loaded
</script>
</body>
</html>Using the Embed Script
The embed script is meant to be placed directly inside the DOM where you want the footer to appear. It automatically renders the footer at the script's location in the HTML.
Example of using the embed script:
<!DOCTYPE html>
<html lang="nl">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Global footer embed script example</title>
</head>
<body>
<div class="your-website-code">👋 Hello world</div>
<script src="https://widgets.test-vlaanderen.be/api/v2/widget/your-global-footer-id/embed"></script>
</body>
</html>Summary
- Entry script: Use in the
<head>, requires manual mounting with theglobalFooterClient.mount()method. - Embed script: Place directly in the DOM, automatically renders the footer at the script's location.
Installation
To install the global-footer-types package, use the following command:
npm install -D @govflanders/vl-widget-global-footer-typesor
yarn add -D @govflanders/vl-widget-global-footer-typesNote: It’s recommended to use the caret (^) symbol in your package.json to stay updated with the latest minor and patch versions.
Usage
This package provides all the types required for working with the Global Footer Widget. The widget is available on the global window object as window.globalFooterClient. You can import the types from global-footer-types to use them in your project.
Example of using the types to interact with the widget:
import { GlobalFooterClient, NavigationLink } from '@govflanders/vl-widget-global-footer-types';
const client: GlobalFooterClient = window.globalFooterClient;
const privacyLink: NavigationLink = {
title: 'Privacy Policy',
href: '/privacy-policy',
};
const termsLink: NavigationLink = {
title: 'Terms of Service',
href: '/terms',
};
client.setNavigationLinks([
privacyLink,
termsLink,
]);Checkout the GlobalFooterClient here to see all the available methods.
Migration guide: Upgrading from v4 to v5
If you’re currently using version 4 of the Global Footer Widget, please follow this guide to upgrade to version 5. This guide highlights the key changes and steps you need to take to ensure a smooth transition.
Remove client library script links
No more client library or polyfill scripts: In version 5, you no longer need to include any additional client library or polyfill script links in your HTML. Access to the window.globalFooterClient object is automatically provided when you include either the entry script or the embed script.
Action Required:
- Remove any
<script>tags that reference client libraries or polyfill libraries for the widget. - Ensure that either the entry script or the embed script is included in your HTML.
Eliminate installable packages
Script-based integration only: Version 5 removes the need for installable packages via npm or yarn. All functionalities are now accessible by including script tags directly in your HTML’s <head> or <body> section.
Action Required:
- Uninstall any npm or yarn packages related to the widget
- Delete any import or require statements in your JavaScript code that reference the widget.
Update Embed script links
Version Update in Embed Links: If you’re using the embed script method to include the widget, you need to update the version number in your script’s src URL from 'v1' to 'v2'. Example here.
Update API usage
API Changes: The globalFooterClient API has been updated in version 5. Methods, their signatures, and usage patterns may have changed. Refer to the API section for detailed information on the new methods and their parameters.
Action Required:
- Review all instances where you interact with globalFooterClient.
- Update your code to align with the new API methods and their signatures.
- Pay special attention to asynchronous methods that now return promises.
Example:
// Using widgets V4
- vl.widget.client.capture(
- // Verplichte capture functie.
- function(widget) {
- if (widget.getPluginTypeId() === 'global_footer') {
- widget.getUmbrella();
- }
- },
- );
// Using widgets V5
+ await globalFooterClient.getUmbrella();Accessing window.globalFooterClient
Unified Access via Scripts: In version 5, you can access the window.globalFooterClient object regardless of whether you use the entry script or the embed script.
Action Required:
- Ensure that you include either the entry script or the embed script in your HTML.
- Remove any additional scripts previously used to access
window.globalFooterClient.
Verify Styling and Rendering
After integrating version 5 of the widget into your website, it’s important to thoroughly review its appearance and functionality to ensure everything works as expected. Some styling adjustments might be necessary due to changes in the widget’s design or your site’s CSS.
Action Required:
- Test Across Browsers: Check the widget in all supported browsers to confirm consistent styling and behavior.
- Inspect for Conflicts: Look for any CSS conflicts between the widget and your site’s stylesheets.
- Adjust Styles if Needed: Modify your CSS or override styles to resolve any layout or design issues.
- Seek Assistance: If problems persist, don’t hesitate to contact us for support.
Language Switching
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.
Supported languages:
- nl (Dutch)
- fr (French)
- de (German)
- en (English)
To change the document language, you can use the following JavaScript snippet:
window.document.documentElement.lang = 'nl'; // 'nl', 'en', 'de' or 'fr'This will switch the document's language to Dutch, and the widget will automatically reflect the change.
Browser Support
The Global Footer Widget supports the two most recent versions of all major browsers:
- Google Chrome
- Mozilla Firefox
- Microsoft Edge
- Safari
Please ensure your users are on the latest versions of these browsers to guarantee full functionality of the widget.
Contact Information
If you need assistance or have any questions regarding the Global Footer Widget, feel free to reach out to us:
- Support Portal: Wiget platform
Our team is here to help with any issues or inquiries you might have.