I’ve been selected for Google Summer Of Code 2024 to work on project : O3 User Onboarding.
I will use this thread to share the project updates and for general communication purposes.
I’m excited to share my community bonding journey through this blog. Week 1 started with an excellent GSoC orientation session led by @jayasanka and @grace.
Project update | Community bonding period 2024-05-04T18:30:00Z→2024-05-25T18:30:00Z
I had call with my mentors on 2024-05-15T18:30:00Z and 2024-05-22T18:30:00Z, we discussed about the project plan and the timeline. Also discussed about the following things:
Where all we need to show these user onboarding flows?
Suggestion: Identify in perspective of an experienced developer and a normal user who is beginner on OpenMRS
Regarding the designs of these workflows across all O3 modules
Suggestion: Get an early feedback from the UI/UX design team in order to get the designs for onboarding flows.
Suggestion: Try to join in the UI/UX design call sessions.
Where we can keep onboarding mode button? (which is triggered manually by the user)
Suggestion: This more specifically it goes to UI/UX team and implementation goes on the esm-core repository.
I noticed that for the flow of tutorials , Is there any patient specific tutorial flow for the Walkthroughs in the tutorials?
consider If I’m in home page and I need to see onboardings for order-basket, how will the onboarding flows from home page to order-basket page listed in the tutorials section?
I had a conversation with @ibacher today about the best location and approach for defining these tutorials. Here’s a summary of what we came up with:
Apart from having onboarding tutorials in O3, the primary beneficiaries would be implementors, such as those in implementations like Kenya EMR. Therefore, these tutorials should be configurable.
The technical architecture would involve an extension mounted during the initialization of O3. This extension will include a configuration schema that allows developers to provide a set of walkthroughs in a JSON array. Each tutorial would be loaded into the Tutorial modal in the help menu. When a user clicks on a specific tutorial, it will guide them step by step.
{
tutorials: [
{
"name": "Patient Registration",
"description": "A description",
"steps": [
{
"target": ".register_button",
"content": "Click this button to navigate to the registration page"
},
{
"target": '[aria-label="Contact Details Section"]',
"content": "Here you can update the patient's contact information."
}
...
},
{
"name": "Basic Tutorial",
"description": "Lorem ipsum",
"steps": []
}
]
}
Since this feature is still under development, we can house it in a new repository. Once we have made significant progress, we can consider moving it to an appropriate monorepo.
Here are some screenshots from the proposed design to give you more context:
After doing some experiments with React Joyride, I’ve found some interesting things that could be helpful when implementing this feature:
The <Joyride /> component doesn’t need to wrap the elements we’re using for the tutorial. Even when Joyride is set up in a deeply nested child component, it can still target any rendered element in the application.
This flexibility allows us to set up Joyride in a separate microfrontend module dedicated to tutorials. We can configure the route in routes.json to ensure it’s always rendered, similar to what we did with the help-menu button.
This will also allow us to keep all the tutorials in one place (for now), so we can continue development without affecting the other microfrontend apps or monorepos.
Since most tutorials in OpenMRS will span multiple routes (because almost everything will start from /home), we need to find a good way to handle multi-route tutorials.
Anyway, I’ve created this brief demo showcasing a sample multi-route tutorial with a custom callback function and shared state:
This approach is successful up to some point. But the most challenging part would be managing the state. Also, the custom callback handler needs to be carefully designed and implemented to handle various scenarios across different tutorials. (PS: I’ll try to comeup with some sample scenarios to explain this)
Fantastic demo, @piumal1999! I really like the highlight effect, it matches our onboarding designs perfectly. Also, you were right about not needing to wrap anything; it turns out that was a misunderstanding on our part. I realized this too, which is why I came up with the architecture mentioned above. Apologies for not mentioning it earlier.
Just to reiterate, the tutorials can be provided as config, so the tutorials for O3 will always be in the esm-onboarding app (as the default config). This means implementers can easily add or modify tutorials as needed.
I created a new repo for this project. @piumal1999 could you please push your changes to this?
Agreed, the highlighting looks really nice @piumal1999 !
Thank you so much @jayasanka for explaining how these will be configured, and for kicking off that repo. Looks like someone needs to clean out all the esm-template-app generic content from it though Maybe Vijay can do that?
@grace The repo is just a fresh copy of the template and has nothing on it yet. Piumal created a cleaned-up demo earlier here. We need to move it to the new repo: GitHub - Piumal1999/openmrs-esm-tutorials-app
here are the steps from Piumal’s demo. Those have to be cleaned up by removing unnecessary properties and probably should be moved to a separate file.
@jayasanka since this is a separate microfrontend module, can’t we use it without creating an extension? Implementors can choose not to install the module by updating the SPA config file. In dev3, we can keep the module under a feature flag. WDYT?
Yes, my apologies for the confusion in calling it an extension. It will function more like a page (I understand this might sound unusual, but it’s for a specific use case). It will be rendered consistently across all pages, similar to the example provided here:
While having tutorials across multiple pages, I’m facing issues regarding the rendering of elements in other (multiple) pages where the element even not present in that page.
so currently the tutorials are getting started by first navigating to the specific tutorials page and thereafter showing these tutorial steps.
The current implementation is not considered as an good approach as it doesn’t guides the users through each steps from the page they are currently in.
Suppose we trigger patient registration tutorial from any patient specific page ( for eg like from vitals page ), then the joyride element looks for the selector ( eg:[name=“AddPatientIcon”])
where the element (Add Patient) is not present in the current page, but it yet shows the tutorial steps because its selector is present in the page as you can see in the above attached video.
Thanks for the explanation. As we discussed, each tutorial should begin from the homepage. So, if you’re not on the homepage, you should navigate there first before starting the tutorial.
Set up the Onboardings for Patient Registration PR #9
Also added a custom tooltip inorder to include the buttons from carbon design system and to match with the Zeplin designs.
Refactored some code and came up with an better approach to automate the steps and wait for a specific element to load. Thanks to @jayasanka
This is done by having an creating two functions named waitFortarget , onStepChange which add time Interval to the steps and looks for the next target element respectively and passing it over the Joyride events.
case EVENTS.TOUR_START:
waitForTarget(0);
break;
case EVENTS.STEP_BEFORE:
onStepChange(index);
break;
case EVENTS.STEP_AFTER:
setStepIndex(index + (action === ACTIONS.PREV ? -1 : 1));
break;
case EVENTS.TARGET_NOT_FOUND:
waitForTarget(index);
break;
case EVENTS.TOUR_END:
setStepIndex(0);
setShowTutorial(false);
Additionally from the above, we must also pass the next target inside the steps like below and it’s implementation in root component can be found out here.
data: {
autoNextOn: 'next step selector',
}
Currently working on the next item in the milestone.
Maybe Vijay can do that?