[Guided onboarding] Update readme with steps to register a new guide #152232
Conversation
yuliacech
added
release_note:skip
|
Pinging @elastic/platform-onboarding (Team:Journey/Onboarding) |
| 1. Declare the `guidedOnboarding` plugin as a dependency in your plugin's `kibana.json` file. Add the guided onboarding plugin's client-side start contract to your plugin's client-side start dependencies and the guided onboarding plugin's server-side setup contract to your plugin's server-side dependencies. | ||
| 2. Define the configuration for your guide. At a high level, this includes a title, description, and list of steps. See this [example config](https://github.com/elastic/kibana/blob/main/packages/kbn-guided-onboarding/src/common/test_guide_config.ts) or consult the `GuideConfig` interface. | ||
| 3. Register your guide during your plugin's server-side setup by calling a function exposed by the guided onboarding plugin: `registerGuideConfig(guideId: GuideId, guideConfig: GuideConfig)`. For an example, see this [example plugin](https://github.com/elastic/kibana/blob/main/examples/guided_onboarding_example/server/plugin.ts). | ||
| 4. Update the cards on the landing page to include your guide in the use case selection. Landing page cards are configured in this [kbn-guided-onboarding package](https://github.com/elastic/kibana/blob/main/packages/kbn-guided-onboarding/src/components/landing_page/guide_cards.constants.tsx). |
There was a problem hiding this comment.
I have a suspicion that a lot of the new guides will be replacing the hard-coded links on the landing page. Do you think it's worth noting that? Something like... if the use case already exists, you will need to remove the navigateTo field and define the guideId.
There was a problem hiding this comment.
Yes, I'll add exactly that about navigateTo and guideId properties
|
|
||
| Besides the internal API routes, the server-side code also exposes a function to register guide configs from the server-side setup start contract. This function is intended for external use by any plugin that need to add a new guide or modify an existing one. | ||
|
|
||
| ### Adding a new guide |
There was a problem hiding this comment.
[nit] What do you think about colocating this near the "Development" section?
There was a problem hiding this comment.
Yeah, I think it could actually make more sense at the very end of the readme. We can link directly to the section when needed
| 2. Define the configuration for your guide. At a high level, this includes a title, description, and list of steps. See this [example config](https://github.com/elastic/kibana/blob/main/packages/kbn-guided-onboarding/src/common/test_guide_config.ts) or consult the `GuideConfig` interface. | ||
| 3. Register your guide during your plugin's server-side setup by calling a function exposed by the guided onboarding plugin: `registerGuideConfig(guideId: GuideId, guideConfig: GuideConfig)`. For an example, see this [example plugin](https://github.com/elastic/kibana/blob/main/examples/guided_onboarding_example/server/plugin.ts). | ||
| 4. Update the cards on the landing page to include your guide in the use case selection. Landing page cards are configured in this [kbn-guided-onboarding package](https://github.com/elastic/kibana/blob/main/packages/kbn-guided-onboarding/src/components/landing_page/guide_cards.constants.tsx). | ||
| 5. Integrate the new guide into your Kibana pages by using the guided onboarding client-side API service. Make sure your Kibana pages correctly display UI elements depending on the active guide step and the UI flow is straight forward to complete the guide. See existing guides for an example and read more about the API service in this file, the section "Client-side: API service". |
There was a problem hiding this comment.
What if we add some info about using the example plugin to help with development? I think there is already something under the "Architecture" section, but I wonder if we should move it up. Thoughts?
There was a problem hiding this comment.
You mean to use the example plugin to set the state, right? I haven't thought about it but I think that could be like the last optional step in the list. Something like, you can update the example plugin to make the development process easier.
|
Thanks a lot for the review, @alisonelizabeth! I added your suggestion in this commit. Would you like to have another look? |
|
@elasticmachine merge upstream |
💚 Build Succeeded
Metrics [docs]Unknown metric groupsESLint disabled line counts
Total ESLint disabled count
History
To update your PR or re-run it, just comment with: |
Summary
This PR updates the readme file of the guided onboarding plugin with a list of steps needed when adding a new guide. This section is intended for other teams that will start using guided onboarding in the future.