Onboarding Hints React Component
@smarter/onboarding holds the web console’s onboarding hints, which point a
new user to where to go next. Smarter’s users are often students who have never
programmed and know little about generative AI yet, so the hints lead them, one
step at a time, from the welcome tour to their first conversation with an
LLMClient, and explain what they see along the way:
The sidebar’s LLM Clients link. Once the welcome dialog is closed, a sparkling ring circles the link, with the note “Start building your AI masterpiece here.” and a Got it button. A user who is already among their LLMClients, on the list or in the workbench, has got there, and the hint is recorded without showing.
The Get Weather LLMClient. On the list of LLMClients, the same spotlight circles the name of the Get Weather example, whose link opens its chat in the Prompt Engineer’s Workbench. It waits for the list to load, in either the list or the thumbnail view.
The workbench’s guided tour. Once the chat is ready, and the welcome dialog closed, the workbench opens its Console and starts a tour, step by step, in plain words: the chat, the message box, sandbox and production modes, the Console and each of its tabs (the manifest, the architecture, the server logs, the tool calls, the configuration and the deployment), and the Help menu, which has the docs and takes the tour again at any time. A step about a part that the page doesn’t have, e.g. the Server Logs tab when the server logs are off, is left out.
Each hint shows by itself until the user has done something with it: clicked
what it points to, clicked Got it, finished or skipped the tour, or was
already where it points. The first outcome is recorded once per user, in the
dashboard app’s OnboardingHint model, so that a hint never shows again by
itself, on any device. The enable_web_console_onboarding_hints waffle
switch, active by default, turns the hints off.
The package is a library, built into its dist folder like @smarter/common:
Spotlight: a sparkling ring around one element, which stays clickable, and a short note beside it. A click on the element, Got it or Escape ends it.Tour: a guided tour, a modal dialog that dims the page around the part that each step is about. Next, Back and the arrow keys move between its steps, and Skip tour or Escape ends it. A step can have an icon, and can activate its element when it shows, e.g. select a Console tab, so that the page shows what the step is about.useOnboarding(): which hints show by themselves, andrecord(), which tells the onboarding seen api what the user did with one.waitForTarget()andwaitUntil(): wait for an element to come on screen, e.g. a row of a list that is still loading, or for the welcome dialog to close.
A hint finds what it points to by a data-smarter-onboarding attribute, e.g.
data-smarter-onboarding="sidebar-llmclients" on the sidebar’s link in
templates/dashboard/sidebar.html, or by a css selector. Each console page
holds the hints’ state as JSON, which templates/dashboard/base.html writes
with templates/react/onboarding.html for signed-in users, so that a hint
needs no request before it shows. The rings and notes use the welcome dialog’s
orange accent and its warm gradient, with a Keen icon badge, an arrow that
points at the element, and, in a tour, a progress bar. They follow the light
and dark themes, and keep still for users who prefer reduced motion.
To add a hint, add its id to OnboardingHints in the dashboard app’s
models.py and in the package’s src/lib/const.ts (a test checks that the
two match), mark what it points to, and show a Spotlight or a Tour in
the page’s React app while shouldShow() is true.
API
API view for the web console’s onboarding hints, which the React package @smarter/onboarding shows.
An onboarding hint points a new user to where to go next: a spotlight on the sidebar’s LLM Clients
link, then on the Get Weather LLMClient, then a guided tour of the Prompt Engineer’s Workbench. Each
shows by itself until the user has done something with it, which onboarding/seen/ records, as an
OnboardingHint. Each page learns which hints the user has
seen from onboarding_context(), which templates/react/onboarding.html writes into the page,
so that a hint needs no request before it shows.
- class smarter.apps.dashboard.views.views.api.onboarding.OnboardingApiResponse(**data)[source]
Bases:
BaseModelThe response of the onboarding seen api.
- Parameters:
seen – The hints that the user has seen, which no longer show by themselves.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.dashboard.views.views.api.onboarding.OnboardingContext(**data)[source]
Bases:
BaseModelThe onboarding state that
templates/react/onboarding.htmlwrites into each console page, as JSON.- Parameters:
enabled – Whether hints show by themselves: the
enable_web_console_onboarding_hintswaffle switch.api_url – The onboarding seen api.
seen – The hints that the user has seen.
csrf_cookie_name – The name of the CSRF cookie, which the api requires.
cookie_domain – The domain of the session cookies.
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.dashboard.views.views.api.onboarding.OnboardingSeenRequest(**data)[source]
Bases:
BaseModelThe body of a request to the onboarding seen api.
- Parameters:
hint – The hint, one of
OnboardingHints.outcome – What the user did with it, one of
OnboardingOutcomes.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.dashboard.views.views.api.onboarding.OnboardingSeenView(**kwargs)[source]
Bases:
SmarterAuthenticatedWebViewRecords what the user did with an onboarding hint, which then no longer shows by itself.
The body is an
OnboardingSeenRequest, as JSON. The first outcome is kept: a hint that the user has already seen is left as it is. The response is anOnboardingApiResponse:{"seen": ["sidebar_llmclients", "llmclient_weather"]}
- smarter.apps.dashboard.views.views.api.onboarding.onboarding_context(user, api_url)[source]
The onboarding state of a console page.
- smarter.apps.dashboard.views.views.api.onboarding.seen_onboarding_hints(user_id)[source]
The onboarding hints that the user has seen, in the order of
OnboardingHints.Every console page asks, so the answer is cached until
OnboardingSeenViewinvalidates it.
Model
- class smarter.apps.dashboard.models.OnboardingHint(*args, **kwargs)[source]
An onboarding hint that a user has seen, and what they did with it.
A hint shows by itself until the user has a row for it, in any of their accounts, so that it shows once per user, on any device.
created_atis when they first saw it to the end.- Parameters:
user – The Django user.
hint – The hint, one of
OnboardingHints.outcome – What the user did with it, one of
OnboardingOutcomes.id (Unknown) – Primary key: ID
created_at (Unknown) – Created at
updated_at (Unknown) – Updated at
- exception DoesNotExist
- exception MultipleObjectsReturned
- exception NotUpdated
- created_at
-
Created at
Timestamp indicating when the model instance was created.
This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.
- Type:
Type
- updated_at
-
Updated at
Timestamp indicating when the model instance was last updated.
This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.
- Type:
Type