Skip to content

Commit d54775f

Browse files
Richard-lumappsRichard-lumapps
committed
feat(events): update documentation for search event + feedbacks from review
CF-144
1 parent 8728e9d commit d54775f

File tree

2 files changed

+65
-52
lines changed

2 files changed

+65
-52
lines changed

‎docs/javascript/api.md

Lines changed: 42 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +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-
| `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) |
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) |
3939
| `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) |
4040

4141
And `configuration` is an object that allows these properties:
@@ -52,10 +52,7 @@ And `configuration` is an object that allows these properties:
5252
| Target | Description | Compatibilities |
5353
|----------------------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------|
5454
| `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) |
55+
| `events.SEARCH` | Event id for the user search page interaction events. | [Documentation](./capabilities#event-search) |
5956
| `events.WIDGET_RENDERED` | Event id for the event triggered after rendering a widget. | [Documentation](./capabilities#event-widget-rendered) |
6057

6158
### targets
@@ -1202,60 +1199,61 @@ across the entire platform, or if you need to communicate information between cu
12021199

12031200
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).
12041201

1205-
### on navigation
1206-
```js
1207-
window.lumapps.customize(({ onNavigation }) => {
1208-
onNavigation(({ currentPage }) => {
1209-
sendTrack({
1210-
page: currentPage,
1211-
})
1212-
})
1213-
});
1214-
```
1202+
#### events.SEARCH
1203+
1204+
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:
1205+
- `searchbox-interaction`
1206+
- `filter-interaction`
1207+
- `sort-interaction`
1208+
- `fetch-results`
12151209

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.
1210+
**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.
12171211

1218-
#### events.SEARCH_BOX
1212+
##### searchbox-interaction
12191213

12201214
Event triggered each time the user interacts with the search box and displays suggestions. Please find below the props available for this event.
12211215

12221216
| Option | Description | Option type |
12231217
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1224-
| `props.searchQuery` | Query typed by the user. | `string` |
1225-
| `widget.suggestions` | Displayed suggestions. Contains label, counterClick, type and siteId | `object[]` |
1218+
| `props.query` | Query typed by the user. | `string` |
1219+
| `props.suggestions` | Displayed suggestions. Contains label, counterClick, type and siteId | `object[]` |
1220+
| `props.cause` | Cause of the search event. Always set to `searchbox-interaction` | `string` |
12261221

1227-
#### events.SEARCH_FILTER
1222+
##### filter-interaction
12281223

12291224
Event triggered each time the user interacts with the search filters. Please find below the props available for this event.
12301225

12311226
| Option | Description | Option type |
12321227
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1233-
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). | `number` |
1228+
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). If result count is not available -1 is returned. | `number` |
12341229
| `props.query` | Current query used to display search results | `string` |
12351230
| `props.filters` | List of filters available. Contains id, label, value (all selected values) and choices (all available choices for a given filter) | `object[]` |
1231+
| `props.cause` | Cause of the search event. Always set to `filter-interaction` | `string` |
12361232

1237-
#### events.SEARCH_RESULT
1233+
##### fetch-results
12381234

1239-
Event triggered each time the user makes a search query. Please find below the props available for this event.
1235+
Event triggered each time the user makes a search query or change tabs. Please find below the props available for this event.
12401236

12411237
| Option | Description | Option type |
12421238
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1243-
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). | `number` |
1239+
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). If result count is not available -1 is returned. | `number` |
12441240
| `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[]` |
1241+
| `props.filters` | List of filters. Contains id, label, value (all selected values) and choices (all available choice for a given filter) | `object[]` |
12461242
| `props.selectedTabInfo` | Information for the current search tab. Contains label and totalResultCount | `object[]` |
12471243
| `props.results` | Information for the current search tab. Contains label and totalResultCount | `object[]` |
1244+
| `props.cause` | Cause of the search event. Always set to `fetch-results` | `string` |
12481245

1249-
#### events.SEARCH_SORT
1246+
##### sort-interaction
12501247

12511248
Event triggered each time the user makes apply a new sort order. Please find below the props available for this event.
12521249

12531250
| Option | Description | Option type |
12541251
|--------------------------|---------------------------------------------------------------------------------------------------------------------|--------------------------|
1255-
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). | `number` |
1252+
| `props.filteredResultCount` | Number of results available with the current filters applied (if any). If result count is not available -1 is returned. | `number` |
12561253
| `props.query` | Current query used to display search results | `string` |
12571254
| `props.selectedSort` | Curretn sort applied. | `string` |
12581255
| `props.sortOrders` | List of all sort values available. Contains a value and a label | `object[]` |
1256+
| `props.cause` | Cause of the search event. Always set to `sort-interaction` | `string` |
12591257

12601258
#### events.WIDGET_RENDERED
12611259

@@ -1289,9 +1287,23 @@ It is an event that will be called on each navigation. It receives the following
12891287
**Limitations and best practices**
12901288
- 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.
12911289

1290+
### on navigation
1291+
**IMPORTANT**
1292+
`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.
1293+
1294+
```js
1295+
window.lumapps.customize(({ onNavigation }) => {
1296+
onNavigation(({ currentPage }) => {
1297+
sendTrack({
1298+
page: currentPage,
1299+
})
1300+
})
1301+
});
1302+
```
1303+
12921304
### on widget rendered
12931305

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.
1306+
**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.
12951307

12961308
### api
12971309
```js

‎docs/javascript/capabilities.md

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -730,28 +730,29 @@ In order to understand the possibilities that we have with this API, we need to
730730
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:
731731

732732
```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-
});
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+
},
755756
});
756757
});
757758
```

0 commit comments

Comments
 (0)