Skip to content

Commit 8728e9d

Browse files
Richard-lumappsRichard-lumapps
committed
chore(events): add events related documentation
CF-144
1 parent 24f0750 commit 8728e9d

File tree

3 files changed

+127
-16
lines changed

3 files changed

+127
-16
lines changed

‎docs/javascript/api.md

Lines changed: 87 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,9 @@ Where `callback` is a function that will receive a set of `parameters` and retur
3333
| `constants` | A group of variables that hold the different [constants](#constants) that can be used for creating components on your site. |
3434
| `render` | Function that allows rendering a component in a specific placement and target. See more details for this function [here](#render). |
3535
| `session` | Object that contains several values from the current session that can be useful when creating customizations. See more details for this function [here](#session). |
36-
| `onNavigation` | Function that will be executed once any widget in a content is rendered. See more details for this function [here](#on-widget-rendered) |
37-
| `onWidgetRendered` | Function that will be executed once the application has performed a navigation. See more details for this function [here](#on-navigation) |
36+
| `on` | Function that will be executed upon user actions or component rendrering. See more details for this function [here](#on) |
37+
| `onNavigation` (deprecated) | Function that will be executed once any widget in a content is rendered. See more details for this function [here](#on-widget-rendered) |
38+
| `onWidgetRendered` (deprecated) | Function that will be executed once the application has performed a navigation. See more details for this function [here](#on-navigation) |
3839
| `api` | [Axios](https://github.com/axios/axios) instance that allows the developer to execute AJAX requests. See more details for this function [here](#axios-api) |
3940

4041
And `configuration` is an object that allows these properties:
@@ -44,6 +45,19 @@ And `configuration` is an object that allows these properties:
4445
| `shouldRenderOnNavigation` | whether the customization callback should be executed upon navigation. If `true`, the `callback` will be executed on every navigation that the application executes. **IMPORTANT:** Please make sure that this option applies and is needed to your use case in order to avoid having an unnecessary performance impact. Normally you would not need to set it to true |
4546
| `shouldRenderOnNavigation` | if the customization uses data from the current content (by executing `window.lumapps.getCurrentContent()`). As of right now, other than that use case, `shouldRenderOnNavigation` should always be `false`. |
4647

48+
### events
49+
50+
`events` is a key/value object that holds the available events that can be subcribed to on LumApps. This variable allows developers to avoid figuring out which ids to use in order to listen to a specific event, and it also defines the available events that can be used for customization. As of now, these are the values for this object:
51+
52+
| Target | Description | Compatibilities |
53+
|----------------------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------|
54+
| `events.NAVIGATION` | Event id for user navigation events. | [Documentation](./capabilities#event-navigation) |
55+
| `events.SEARCH_BOX` | Event id for the user searchbox interaction events. | [Documentation](./capabilities#event-searchbox) |
56+
| `events.SEARCH_FILTER` | Event id for the user filter interaction events on the search page. | [Documentation](./capabilities#event-search-filter) |
57+
| `events.SEARCH_RESULT` | Event id for the search result events triggered when user makes a search query. | [Documentation](./capabilities#event-search-result) |
58+
| `events.SEARCH_SORT` | Event id for the user sort interaction events on the search page. | [Documentation](./capabilities#event-search-sort) |
59+
| `events.WIDGET_RENDERED` | Event id for the event triggered after rendering a widget. | [Documentation](./capabilities#event-widget-rendered) |
60+
4761
### targets
4862

4963
`targets` is a key/value object that holds the available targets that can be customized on LumApps. This variable allows developers to avoid figuring out which ids to use in order to customize a specific target, and it also defines the available targets that can be customized. As of now, these are the values for this object:
@@ -1174,6 +1188,20 @@ Contains two `Promises`, one for the main navigation and another one for the sub
11741188
| `navigationItem.title` | Key/value where the key is a language id and the value is the title for the item in that language. This value contains the text that should be displayed on the navigation item. It takes into consideration the title of the item to display and if there is a specific override for that item's title | `Record<string, string>` |
11751189
| `navigationItem.slug` | Key/value where the key is a language id and the value is the slug for the item in that language. | `Record<string, string>` |
11761190

1191+
### on
1192+
```js
1193+
window.lumapps.customize(({ on, events }) => {
1194+
on(events, (props) => {
1195+
// Retrieve props based on a specific event and execute additional customisations.
1196+
});
1197+
});
1198+
```
1199+
1200+
`on` is a function that will be called each time a user perform a specific action or a component is rendered depending on the event. This callback is ideal if you need to trigger additional customisations based on user actions
1201+
across the entire platform, or if you need to communicate information between customizable components.
1202+
1203+
The `props` parameter will have information depending on the event type. For a full list of all events, please refer to the [documentation](./api#events).
1204+
11771205
### on navigation
11781206
```js
11791207
window.lumapps.customize(({ onNavigation }) => {
@@ -1185,22 +1213,53 @@ window.lumapps.customize(({ onNavigation }) => {
11851213
});
11861214
```
11871215

1188-
`onNavigation` is a function that will be called on each navigation. It receives the following parameters:
1189-
- `currentPage`: Id of the current page.
1216+
`onNavigation` is a function that will be called on each navigation. **This function is now deprecated**. Please `on` function with the [Navigation event](./api#eventsnavigation) instead.
11901217

1191-
**Limitations and best practices**
1192-
- This specific function should be used for tracking purposes as well as triggering other external services. It should not be used in combination with the `render` function, since this is not intended to work by design. Targets and placement should already help in rendering customizations on specific pages.
1218+
#### events.SEARCH_BOX
11931219

1194-
### on widget rendered
1195-
```js
1196-
window.lumapps.customize(({ onWidgetRendered }) => {
1197-
onWidgetRendered((widget) => {
1198-
// Retrieve data from the widget and execute additional customisations.
1199-
});
1200-
});
1201-
```
1220+
Event triggered each time the user interacts with the search box and displays suggestions. Please find below the props available for this event.
1221+
1222+
| Option | Description | Option type |
1223+
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1224+
| `props.searchQuery` | Query typed by the user. | `string` |
1225+
| `widget.suggestions` | Displayed suggestions. Contains label, counterClick, type and siteId | `object[]` |
1226+
1227+
#### events.SEARCH_FILTER
12021228

1203-
`onWidgetRendered` is a function that will be called each time a widget is rendered on the page. This callback is ideal if you need to trigger additional customisations for a specific widget
1229+
Event triggered each time the user interacts with the search filters. Please find below the props available for this event.
1230+
1231+
| Option | Description | Option type |
1232+
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1233+
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). | `number` |
1234+
| `props.query` | Current query used to display search results | `string` |
1235+
| `props.filters` | List of filters available. Contains id, label, value (all selected values) and choices (all available choices for a given filter) | `object[]` |
1236+
1237+
#### events.SEARCH_RESULT
1238+
1239+
Event triggered each time the user makes a search query. Please find below the props available for this event.
1240+
1241+
| Option | Description | Option type |
1242+
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1243+
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). | `number` |
1244+
| `props.query` | Current query used to display search results | `string` |
1245+
| `props.selectedFilters` | List of filters currently applied. Contains id, label, value (all selected values) and choices (all available choice for a given filter) | `object[]` |
1246+
| `props.selectedTabInfo` | Information for the current search tab. Contains label and totalResultCount | `object[]` |
1247+
| `props.results` | Information for the current search tab. Contains label and totalResultCount | `object[]` |
1248+
1249+
#### events.SEARCH_SORT
1250+
1251+
Event triggered each time the user makes apply a new sort order. Please find below the props available for this event.
1252+
1253+
| Option | Description | Option type |
1254+
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1255+
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). | `number` |
1256+
| `props.query` | Current query used to display search results | `string` |
1257+
| `props.selectedSort` | Curretn sort applied. | `string` |
1258+
| `props.sortOrders` | List of all sort values available. Contains a value and a label | `object[]` |
1259+
1260+
#### events.WIDGET_RENDERED
1261+
1262+
Event triggered each time a widget is rendered on the page. This event is ideal if you need to trigger additional customisations for a specific widget
12041263
across the entire platform, or if you need to communicate information between widgets.
12051264

12061265
The `widget` parameter will have basic information of the rendered widget, plus additional information depending on the widget type
@@ -1220,7 +1279,19 @@ The `widget` parameter will have basic information of the rendered widget, plus
12201279
**Limitations and best practices**
12211280
- LumApps widgets are rendered in a lazy fashion, meaning that they are rendered depending whether they are visible on your current viewport or not. This means that when you visit a content, `onWidgetRendered` will be executed for the widgets that are visible on the viewport, and when the user starts scrolling, `onWidgetRendered` will be executed after those widgets have loaded.
12221281
- `widget.items` can contain information that you can use in order to retrieve information from the rendered items on the given widget. However, it is worth mentioning that these items ARE NOT stable and can suffer changes at any time. Please consider this while developing any of your features. Only the properties documented in this section are considered stable.
1223-
- This function is only supported on contents compatible with our next gen interface (`NGI`) system
1282+
- This event is only supported on contents compatible with our next gen interface (`NGI`) system
1283+
1284+
#### events.NAVIGATION
1285+
1286+
It is an event that will be called on each navigation. It receives the following parameters:
1287+
- `currentPage`: Id of the current page.
1288+
1289+
**Limitations and best practices**
1290+
- This specific event should be used for tracking purposes as well as triggering other external services. It should not be used in combination with the `render` function, since this is not intended to work by design. Targets and placement should already help in rendering customizations on specific pages.
1291+
1292+
### on widget rendered
1293+
1294+
`onWidgetRendered` is a function that will be called each time a widget is rendered on the page. **This function is now deprecated**. Please `on` function with the [Widget rendered event](./api#eventswidget_rendered) instead.
12241295

12251296
### api
12261297
```js

‎docs/javascript/assets/event-example.png

27 KB
Loading

‎docs/javascript/capabilities.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -717,3 +717,43 @@ Dynamic target that allows customizing the surroundings of a [widget](https://do
717717
#### Use cases
718718

719719
- [Adding a customization to a widget](./use-cases#adding-a-customization-to-a-widget)
720+
721+
## Listening to events
722+
723+
The Customizations API allows, among other things, developers to listen predefined events on several sections of their sites. One of the goals of this API is to expose set of props based on user actions that can be easily used for instance for component customization in order to render additional components in some specific cases while reusing the Customization API `render` function.
724+
725+
In order to understand the possibilities that we have with this API, we need to first define the different elements that compose a `Event`. These components are:
726+
- **Event**: This is the event that we want to use as reference for our customization. It is to be noted that there is a predefined list of events that are marked as [events](./api.md#events).
727+
728+
- **Callback**: This is where props from a given event can be retrieved. Each events has its own set of props that can be used for rendering a custom components based on props values or send tracking events to collect data on users actions. Using this capabilities it becomes possible to have one component communicating with another one.
729+
730+
As an example, inserting the following code in your LumApps site will display an icon in the search tab based on the number of result type filters selected:
731+
732+
```js
733+
window.lumapps.customize(({ on, events, render, placement, targets, components }) => {
734+
const { Icon } = components;
735+
on(events.SEARCH_FILTER, (props) => {
736+
const resultTypeFilter = props.filters.find((f) => f.id === '_metadata.type');
737+
const tabs = [
738+
{
739+
uid: 'all',
740+
icon: `numeric-${resultTypeFilter.value === undefined ? 0 : resultTypeFilter.value.length}-box-outline`,
741+
},
742+
];
743+
render({
744+
placement: placement.LEFT,
745+
target: targets.SEARCH_TAB,
746+
toRenderWithContext: (id) => {
747+
const tabToFormat = tabs.find((tab) => tab.uid === id);
748+
if (tabToFormat === undefined) return;
749+
return Icon({
750+
icon: tabToFormat.icon,
751+
className: 'search-filters-tab__custom-tab-icon',
752+
});
753+
},
754+
});
755+
});
756+
});
757+
```
758+
759+
![Customization using event Example](./assets/event-example.png "Customization Using Event Example")

0 commit comments

Comments
 (0)