Calendar Widgets: Utilities

By default, the Economic Calendar widgets are rendered after our fxsWidgets JS library has been loaded (on page load). The library looks for all widget div declarations and renders the corresponding widget inside.

There might be some cases where widget declarations are not yet in the DOM of the page (e.g. client-rendered elements, single-page applications...) when our widgets library is loaded and the widgets are painted. For a better handling of these cases, we provide a set of utilities that can help developers address it easily.

Events

fxsWidgetsLoaded

The fxsWidgetsLoaded event is fired when the fxsWidgets JS library has been completely loaded. You can listen for this event on the Window interface.

This event guarantees the successful load of our library, as the load or DOMContentLoaded events might be fired before.

Basic Usage

window.addEventListener('fxsWidgetsLoaded', () => {
console.log('FXS Widgets have been loaded');
});

If the event listener is added when the widget library has been already loaded, the event listener will not be executed. This can be handled by checking the fxsWidgets.loaded property, please see the example below.

Properties

fxsWidgets.loaded

fxsWidgets.loaded : boolean | undefined // or 'window.fxsWidgets.loaded'

Indicates if the widgets library has been successfully loaded. If the widgets have not been loaded yet, it is undefined.

Usage

if (fxsWidgets && fxsWidgets.loaded) { /* Library already loaded */
console.log('FXS Widgets loaded');
// DO SOMETHING
} else { /* Widgets not loaded yet */
window.addEventListener('fxsWidgetsLoaded', () => {
console.log('FXS Widgets loaded');
// DO SOMETHING
})
}

Methods

fxsWidgets.load

fxsWidgets.load(widgetName: string, force?: boolean) // or 'window.fxsWidgets.load'

The load method is used to trigger a load of the widgets of name widgetName (to be used after page load).

By default, this method only loads the widgets that were not previously loaded. By using the force parameter, all widgets of name widgetName are re-loaded.

Parameters

  • widgetName - The name of the type of widgets to load. Required.
  • force - If true, all matching widgets are completely re-rendered. Optional. Default: false

Usage

fxsWidgets.load('calendar-historical');
fxsWidgets.load('calendar-historical', true);

fxsWidgets.loadAll

fxsWidgets.loadAll(force?: boolean): void // or 'window.fxsWidgets.loadAll'

The load method is used to trigger a load of all widgets of any name (to be used after page load).

By default, this method only loads the widgets that were not previously loaded. By using the force parameter, all widgets of name widgetName are re-loaded.

Parameters

  • widgetName - The name of the type of widgets to load. Required.
  • force - If true, all matching widgets are completely re-rendered. Optional. Default: false

Usage

fxsWidgets.loadAll();
fxsWidgets.loadAll(true);

Other utilities

Set widget parameters dynamically

There are some cases where the widget parameters are not always the same, for example, the event ID for the widgets of the event dashboard. In such cases, we have implemented the possiblity of dynamically setting the parameters in our widgets. This is useful when trying to get the ID from the path, a variable, a query string, etc.

Instead of using a fixed ID or if the dynamic generation of the div element is not possible like in this situation:

<div
fxs-widget
name="calendar-title-description"
type="title"
event-id="9cdf56fd-99e4-4026-aa99-2b6c0ca92811">
</div>

We can pass a string to the widget contaning a JavaScript statement that will be evaluated. (The widget tries to evaluate it as a JS statement, otherwise, it is interpreted as a string). Here is an example:

<script>
function getEventId() {
var urlParams = new URLSearchParams(window.location.search);
return urlParams.get('eventId');
}
</script>
<div
fxs-widget
name="calendar-title-description"
type="title"
event-id="getEventId()">
</div>
Be careful

You should be careful with this feature. As widget parameters are evaluated as JS statements, they can be a weak point in your page. Our recommendation is to always pass as either a string or use an auxiliary function.

In the case of getting the event ID from a query string, if it were retrieved without the auxiliary function, it could be subject to Cross Site Scripting (XSS) as seen below:

<script>
var urlParams = new URLSearchParams(window.location.search);
var eventId = urlParams.get('eventId');
</script>
<div
fxs-widget
name="calendar-title-description"
type="title"
event-id="eventId">
</div>

In this case, a script could be injected using the eventId query string parameter and be executed when evaluating the function.