Skip to content

Commit e87a659

Browse files
juanigalan91juanigalan91
authored
Merge pull request #13 from lumapps/chore/events-and-state-api
Update api.md
2 parents d9a43f0 + 9e5056c commit e87a659

File tree

1 file changed

+89
-18
lines changed

1 file changed

+89
-18
lines changed

‎docs/javascript/api.md

Lines changed: 89 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -25,18 +25,21 @@ window.lumapps.customize(callback, configuration)
2525

2626
Where `callback` is a function that will receive a set of `parameters` and returns `void`. These are the `parameters` that the `callback` function expects:
2727

28-
| Parameter | Description |
29-
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
30-
| `targets` | The different [targets](#targets) that can be customized on your site. |
31-
| `placement` | The different [placements](#placements) that can be used for positioning components on your site. |
32-
| `components` | A group of [components](#components) that can be used for customizing your site. |
33-
| `constants` | A group of variables that hold the different [constants](#constants) that can be used for creating components on your site. |
34-
| `render` | Function that allows rendering a component in a specific placement and target. See more details for this function [here](#render). |
35-
| `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 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) |
39-
| `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) |
28+
| Parameter | Description |
29+
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
30+
| `targets` | The different [targets](#targets) that can be customized on your site. |
31+
| `placement` | The different [placements](#placements) that can be used for positioning components on your site. |
32+
| `components` | A group of [components](#components) that can be used for customizing your site. |
33+
| `constants` | A group of variables that hold the different [constants](#constants) that can be used for creating components on your site. |
34+
| `render` | Function that allows rendering a component in a specific placement and target. See more details for this function [here](#render). |
35+
| `session` | Object that contains several values from the current session that can be useful when creating customizatio ns. See more details for this function [here](#session) |
36+
| `on` | Function that will be executed upon user actions or component rendering. See more details for this function [here](#on) |
37+
| `pushEvent` | Function that generates custom events. See more details for this function [here](#pushEvent) |
38+
| `getLatestEvents` | Function that retrieves the latest events generated on the application. See more details for this function [here](#getLatestEvents) |
39+
| `state` | Object that provides state management capabilities. See more details for this function [here](#state) |
40+
| `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) |
41+
| `onWidgetRendered` (**deprecated**) | Function that will be executed once the application has performed a navigation. See more details for this function [here](#on-navigation) |
42+
| `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) |
4043

4144
And `configuration` is an object that allows these properties:
4245

@@ -51,9 +54,9 @@ And `configuration` is an object that allows these properties:
5154

5255
| Target | Description | Compatibilities |
5356
|----------------------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------|
54-
| `events.NAVIGATION` | Event id for user navigation events. | [Documentation](#event-navigation) |
55-
| `events.SEARCH` | Event id for the user search page interaction events. | [Documentation](#event-search) |
56-
| `events.WIDGET_RENDERED` | Event id for the event triggered after rendering a widget. | [Documentation](#event-widget-rendered) |
57+
| `events.NAVIGATION` | Event id for user navigation events. | [Documentation](#event-navigation) |
58+
| `events.SEARCH` | Event id for the user search page interaction events. | [Documentation](#event-search) |
59+
| `events.WIDGET_RENDERED` | Event id for the event triggered after rendering a widget. | [Documentation](#event-widget-rendered) |
5760

5861
### targets
5962

@@ -1222,16 +1225,16 @@ Contains two `Promises`, one for the main navigation and another one for the sub
12221225
### on
12231226
```js
12241227
window.lumapps.customize(({ on, events }) => {
1225-
on(events, (props) => {
1226-
// Retrieve props based on a specific event and execute additional customisations.
1228+
on(events, (data) => {
1229+
// Retrieve data based on a specific event and execute additional customisations.
12271230
});
12281231
});
12291232
```
12301233

12311234
`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
12321235
across the entire platform, or if you need to communicate information between customizable components.
12331236

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).
1237+
The `data` parameter will have information depending on the event type. For a full list of all events, please refer to the [documentation](./api#events).
12351238

12361239
#### Event Search
12371240

@@ -1321,6 +1324,74 @@ It is an event that will be called on each navigation. It receives the following
13211324
**Limitations and best practices**
13221325
- 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.
13231326

1327+
### pushEvent
1328+
The `pushEvent` function allows to generate custom events so that they can be retrieved using the [on](#on) callback.
1329+
1330+
```js
1331+
window.lumapps.customize(({ pushEvent }) => {
1332+
pushEvent('custom event', { test: '123' });
1333+
});
1334+
```
1335+
1336+
```js
1337+
window.lumapps.customize(({ on }) => {
1338+
on('custom event', (data) => {
1339+
console.log('custom event registered', data);
1340+
});
1341+
});
1342+
```
1343+
1344+
This function has two parameters:
1345+
- id: this is the id of the event, that will be used to retrieve said event afterwards
1346+
- data: object or value that will be send over with the event, so that it can be retrieved on the `on` callback.
1347+
1348+
### getLatestEvents
1349+
The function `getLatestEvents` retrieves the last 10 events that occurred on the user's current session. This is useful when you want to subscribe to a specific event but the code that adds the subscription is executed AFTER the event has occurred. With this, a developer would be able to retrieve the latest events that they might have missed.
1350+
1351+
```js
1352+
window.lumapps.customize(({ getLatestEvents }) => {
1353+
const events = getLatestEvents(); // retrieves all latest events
1354+
});
1355+
```
1356+
1357+
You can also filter the list of events by providing a specific type
1358+
```js
1359+
window.lumapps.customize(({ getLatestEvents }) => {
1360+
const events = getLatestEvents('navigation'); // retrieves all latest events that have the navigation type.
1361+
});
1362+
```
1363+
1364+
Some precisions:
1365+
- Only the last 10 events will be retrieved, previous events will be dismissed and cannot be retrieved
1366+
- Custom and LumApps events are both supported
1367+
- Events come with a timestamp so that developers can figure out when did they occur
1368+
1369+
**IMPORTANT**
1370+
This only retrieves the events from the current session, so the data will be lost once the user leaves the current page, or the user navigates between applications (including navigations between legacy and NGI pages). Events will only be saved if the user remains on the same application.
1371+
1372+
### state
1373+
The state management API allows developers no longer need to manage state on their end. It has two methods:
1374+
1375+
`state.set` allows to save either a value or an object in memory, associating it to a specific key. Key needs to be a string.
1376+
1377+
```js
1378+
window.lumapps.customize(({ state }) => {
1379+
state.set('key', 'value');
1380+
});
1381+
```
1382+
1383+
`state.get` allows to retrieve a previously saved value or an object in memory, associated to a specific key. Key needs to be a string.
1384+
1385+
```js
1386+
window.lumapps.customize(({ state }) => {
1387+
state.get('key'); // returns 'value'
1388+
});
1389+
```
1390+
1391+
Some precisions on this API:
1392+
- This only saves in-memory state, so the data will be lost once the user leaves the current page, or the user navigates between applications (including navigations between legacy and NGI pages). State will only be saved if the user remains on the same application.
1393+
- It is also worth mentioning that this state is shared across customizations.
1394+
13241395
### on navigation
13251396
**IMPORTANT**
13261397
`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.

0 commit comments

Comments
 (0)