Skip to content

Commit f548f8b

Browse files
juanigalan91juanigalan91
authored
Merge pull request #12 from lumapps/chore/CF-144_add_doc_for_event
chore(events): add events related documentation
2 parents 5e37de3 + d54775f commit f548f8b

File tree

3 files changed

+147
-23
lines changed

3 files changed

+147
-23
lines changed

‎docs/javascript/api.md

Lines changed: 106 additions & 23 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 rendering. 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,16 @@ 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` | Event id for the user search page interaction events. | [Documentation](./capabilities#event-search) |
56+
| `events.WIDGET_RENDERED` | Event id for the event triggered after rendering a widget. | [Documentation](./capabilities#event-widget-rendered) |
57+
4758
### targets
4859

4960
`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:
@@ -1208,33 +1219,79 @@ Contains two `Promises`, one for the main navigation and another one for the sub
12081219
| `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>` |
12091220
| `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>` |
12101221

1211-
### on navigation
1222+
### on
12121223
```js
1213-
window.lumapps.customize(({ onNavigation }) => {
1214-
onNavigation(({ currentPage }) => {
1215-
sendTrack({
1216-
page: currentPage,
1217-
})
1218-
})
1224+
window.lumapps.customize(({ on, events }) => {
1225+
on(events, (props) => {
1226+
// Retrieve props based on a specific event and execute additional customisations.
1227+
});
12191228
});
12201229
```
12211230

1222-
`onNavigation` is a function that will be called on each navigation. It receives the following parameters:
1223-
- `currentPage`: Id of the current page.
1231+
`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
1232+
across the entire platform, or if you need to communicate information between customizable components.
12241233

1225-
**Limitations and best practices**
1226-
- 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.
1234+
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).
12271235

1228-
### on widget rendered
1229-
```js
1230-
window.lumapps.customize(({ onWidgetRendered }) => {
1231-
onWidgetRendered((widget) => {
1232-
// Retrieve data from the widget and execute additional customisations.
1233-
});
1234-
});
1235-
```
1236+
#### events.SEARCH
1237+
1238+
There are four main types of search events, all of them can ben easily identified using the `cause` props which can be found in all those events:
1239+
- `searchbox-interaction`
1240+
- `filter-interaction`
1241+
- `sort-interaction`
1242+
- `fetch-results`
1243+
1244+
**Limitation**: The search events are 100% compatible with our native search. For other search engine (Coveo, Google Cloud Search...), please note that they could be unstable or return incorrect values. Please keep this in mind if you are in this situation.
1245+
1246+
##### searchbox-interaction
1247+
1248+
Event triggered each time the user interacts with the search box and displays suggestions. Please find below the props available for this event.
1249+
1250+
| Option | Description | Option type |
1251+
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1252+
| `props.query` | Query typed by the user. | `string` |
1253+
| `props.suggestions` | Displayed suggestions. Contains label, counterClick, type and siteId | `object[]` |
1254+
| `props.cause` | Cause of the search event. Always set to `searchbox-interaction` | `string` |
1255+
1256+
##### filter-interaction
1257+
1258+
Event triggered each time the user interacts with the search filters. Please find below the props available for this event.
1259+
1260+
| Option | Description | Option type |
1261+
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1262+
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). If result count is not available -1 is returned. | `number` |
1263+
| `props.query` | Current query used to display search results | `string` |
1264+
| `props.filters` | List of filters available. Contains id, label, value (all selected values) and choices (all available choices for a given filter) | `object[]` |
1265+
| `props.cause` | Cause of the search event. Always set to `filter-interaction` | `string` |
12361266

1237-
`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
1267+
##### fetch-results
1268+
1269+
Event triggered each time the user makes a search query or change tabs. Please find below the props available for this event.
1270+
1271+
| Option | Description | Option type |
1272+
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1273+
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). If result count is not available -1 is returned. | `number` |
1274+
| `props.query` | Current query used to display search results | `string` |
1275+
| `props.filters` | List of filters. Contains id, label, value (all selected values) and choices (all available choice for a given filter) | `object[]` |
1276+
| `props.selectedTabInfo` | Information for the current search tab. Contains label and totalResultCount | `object[]` |
1277+
| `props.results` | Information for the current search tab. Contains label and totalResultCount | `object[]` |
1278+
| `props.cause` | Cause of the search event. Always set to `fetch-results` | `string` |
1279+
1280+
##### sort-interaction
1281+
1282+
Event triggered each time the user makes apply a new sort order. Please find below the props available for this event.
1283+
1284+
| Option | Description | Option type |
1285+
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1286+
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). If result count is not available -1 is returned. | `number` |
1287+
| `props.query` | Current query used to display search results | `string` |
1288+
| `props.selectedSort` | Curretn sort applied. | `string` |
1289+
| `props.sortOrders` | List of all sort values available. Contains a value and a label | `object[]` |
1290+
| `props.cause` | Cause of the search event. Always set to `sort-interaction` | `string` |
1291+
1292+
#### events.WIDGET_RENDERED
1293+
1294+
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
12381295
across the entire platform, or if you need to communicate information between widgets.
12391296

12401297
The `widget` parameter will have basic information of the rendered widget, plus additional information depending on the widget type
@@ -1254,7 +1311,33 @@ The `widget` parameter will have basic information of the rendered widget, plus
12541311
**Limitations and best practices**
12551312
- 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.
12561313
- `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.
1257-
- This function is only supported on contents compatible with our next gen interface (`NGI`) system
1314+
- This event is only supported on contents compatible with our next gen interface (`NGI`) system
1315+
1316+
#### events.NAVIGATION
1317+
1318+
It is an event that will be called on each navigation. It receives the following parameters:
1319+
- `currentPage`: Id of the current page.
1320+
1321+
**Limitations and best practices**
1322+
- 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.
1323+
1324+
### on navigation
1325+
**IMPORTANT**
1326+
`onNavigation` is a function that will be called on each navigation. **This function is now deprecated**. Please use `on` function with the [Navigation event](./api#eventsnavigation) instead.
1327+
1328+
```js
1329+
window.lumapps.customize(({ onNavigation }) => {
1330+
onNavigation(({ currentPage }) => {
1331+
sendTrack({
1332+
page: currentPage,
1333+
})
1334+
})
1335+
});
1336+
```
1337+
1338+
### on widget rendered
1339+
1340+
**IMPORTANT** `onWidgetRendered` is a function that will be called each time a widget is rendered on the page. **This function is now deprecated**. Please use `on` function with the [Widget rendered event](./api#eventswidget_rendered) instead.
12581341

12591342
### api
12601343
```js

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

27 KB
Loading

‎docs/javascript/capabilities.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -717,3 +717,44 @@ 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+
on(events.SEARCH, (props) => {
734+
const resultTypeFilter = props.filters.find((f) => f.id === '_metadata.type');
735+
const tabs = [
736+
{
737+
uid: 'all',
738+
icon: `numeric-${
739+
resultTypeFilter === undefined || resultTypeFilter.value === undefined
740+
? 0
741+
: resultTypeFilter.value.length
742+
}-box-outline`,
743+
},
744+
];
745+
render({
746+
placement: placement.LEFT,
747+
target: targets.SEARCH_TAB,
748+
toRenderWithContext: (id) => {
749+
const tabToFormat = tabs.find((tab) => tab.uid === id);
750+
if (tabToFormat === undefined) return;
751+
return Icon({
752+
icon: tabToFormat.icon,
753+
className: 'search-filters-tab__custom-tab-icon',
754+
});
755+
},
756+
});
757+
});
758+
```
759+
760+
![Customization using event Example](./assets/event-example.png "Customization Using Event Example")

0 commit comments

Comments
 (0)