dash-yada lets you easily create interactive tutorials for your Dash app.
$ pip install dash-yadaCheck out the Live Demo to see dash-yada in action!
See the code for this demo in the /docs folder.
See more examples in the /examples folder
To get started, simply add the Yada() component to the app's layout.
You will see the Yada image, in the top right corner. On hover, it displays a default welcome message.
import dash
from dash import html
import dash_bootstrap_components as dbc
from dash_yada import YadaAIO
app = dash.Dash(__name__, external_stylesheets=[dbc.themes.BOOTSTRAP])
app.layout = dbc.Container(
[
YadaAIO(yada_id="yada"),
html.H4("My Dashboard", className="p-3 bg-primary text-white text center"),
],
fluid=True,
)
if __name__ == "__main__":
app.run(debug=True)The default yada image is from Flaticon.com. If you use this image, please include an attribution.
Use the following props to change the yada image and the hover message:
-
yada_src(string; optional): Location src of the yada image. -
hover_message_dict(dict; optional): Props to display for the message when yada is not clicked and not playing a script.- The
hover_message_dicthas keys: name(string; optional) The default name is "yada". Ifnameis""a header is not displayed.greeting(string; optional) Ifgreetingis""the default greeting is not displayed.style(dict; optional) Sets the style of the hover message card.
- The
-
Set the initial position and size with CSS:
The default CSS for the Yada image when the app starts is:
.yada.sleeping {
right: 30px;
top: 5px;
height: 50px;
width: 35px;
}
yada_img = "https://user-images.githubusercontent.com/72614349/236646464-1471e596-b234-490d-bf84-e2ef7a63b233.png"
hover_message_dict = {
"name": "Hedwig",
"greeting": "Let's explore! Just pick a tour and we'll get started",
"style": {"backgroundColor": "lightgreen"}
}
yada = YadaAIO(yada_id="my_yada", yada_src=yada_img, hover_message_dict=hover_message_dict)
Script playback and editing are available in dash-yada-pro.
Use YadaProAIO and ScriptEditorAIO for guided tours and the built-in scripts editor.
You can add one or more scripts for the user to select the tour.
Yada navigates by CSS selector, so it can go to any element on a page. Learn more about selectors at Mozilla web-docs
For example you could use a component's id prop like this: "#component_id". You can use a CSS class selector like this: ".close-btn"
scripts(dict of list of dicts; optional): Dictionary of keys to scripts:- each key will have an array of: {target (string; required), convo (string; optional), show_text (bool; optional), highlight_target (bool; optional), action (string; optional), action_args (string|dict; optional)}
- If
show_text=False(orconvo=""), the step runs as an automation and won't show step text. - If
highlight_target=False, the step runs without adding the highlight ring and Yada will not move to that target. set_propsaction supports:action_args={"id": "<component-id>", "props": {"value": "new value"}}- or direct props in
action_argswhentargetis an id selector (for example"#my-input").
Here is a simple example of one script with one step. You can find more script examples in the demo app: yada_scripts.py file
Use the action field on a step to automate interactions:
clickto click an elementdblclickto double click an elementtypeto set an input valuesendKeysto dispatch keyboard eventsset_propsto update Dash component props directly
scripts = {
"Action Examples": [
{
"target": "#save-btn",
"convo": "Click a button",
"action": "click",
},
{
"target": "#name-input",
"convo": "Type into an input",
"action": "type",
"action_args": "Alice",
},
{
"target": "#rows-grid .ag-row[row-index=\"2\"] .ag-cell[aria-colindex=\"3\"]",
"convo": "Double-click to open inline edit",
"action": "dblclick",
},
{
"target": "#rows-grid .ag-cell-editor input",
"convo": "Send Enter key to commit edit",
"action": "sendKeys",
"action_args": {
"key": "Enter",
"code": "Enter",
"keyCode": 13,
},
},
{
"target": "#search-input",
"convo": "Use keyboard modifiers (Ctrl+A)",
"action": "sendKeys",
"action_args": {
"ctrlKey": True,
"key": "a",
"code": "KeyA",
"keyCode": 65,
},
},
{
"target": "#status-message",
"convo": "Update component props directly",
"action": "set_props",
"action_args": {
"props": {
"children": "Saved successfully",
"style": {"color": "green", "fontWeight": 700},
}
},
"show_text": False,
},
{
"target": "#search-input",
"convo": "You can also pass direct props when target is an id selector",
"action": "set_props",
"action_args": {
"value": "Africa",
"placeholder": "Filter by region",
},
"show_text": False,
},
]
}For click and dblclick, optional action_args can include event flags such as shiftKey, ctrlKey, altKey, and metaKey.
import dash
from dash import html
import dash_bootstrap_components as dbc
from dash_yada import YadaAIO
app = dash.Dash(__name__, external_stylesheets=[dbc.themes.BOOTSTRAP])
yada = YadaAIO(
yada_id="yada",
scripts={
"Intro": [
{
"target": "#title",
"convo": "Welcome to My Dashboard tour!",
},
]
},
)
app.layout = dbc.Container(
[
yada,
html.H4(
"My Dashboard",
className="p-3 bg-primary text-white text center",
id="title",
),
],
fluid=True,
)
if __name__ == "__main__":
app.run(debug=True)The steps in the script are displayed in a dbc.Offcanvas component. You can change the style using the steps_offcanvas_style prop.
Note that in the scripts prop you can also use Markdown in the convo
This example shows how to style the dbc.Offcanvas component like in the live demo.
import dash
from dash import html
import dash_bootstrap_components as dbc
from dash_yada import YadaAIO
app = dash.Dash(__name__, external_stylesheets=[dbc.themes.BOOTSTRAP])
steps_offcanvas_style = {
"boxShadow": "0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)",
"margin": "8px auto",
"padding": "0px 24px 5px",
"backgroundColor": "var(--bs-gray-500)",
"color": "white",
"borderRadius": 12,
"maxWidth": 800,
}
yada = YadaAIO(
yada_id="yada",
steps_offcanvas_style=steps_offcanvas_style,
scripts={
"Intro": [
{
"target": "#title",
"convo": """
### Welcome to My Dashboard tour!
The tour steps are are displayed in an offcanvas component and can be styled with the `steps_offcanvas_style` prop.
Note that you can use Markdown in the "convo" prop.
""",
},
]
},
)
app.layout = dbc.Container(
[
yada,
html.H4(
"My Dashboard",
className="p-3 bg-primary text-white text center",
id="title",
),
],
fluid=True,
)
if __name__ == "__main__":
app.run(debug=True)dash-yada.YadaAIO is an All-In-One component. Learn more about AIO components in the Dash documentation.
Keyword arguments:
- yada_id (string; optional):
The ID used to identify this component in Dash callbacks.
- hover_message_dict (dict; optional {name, greeting, style}):
Props to display for the message when yada is not clicked and not playing a script.
If not defined, the default name is "yada". Set name to "" to not display a header. Set message to "" to not display a greeting
{name (string; optional), greeting (string; optional), style (dict; optional}
- script_message (dict; optional):
String to display for the message when yada is clicked and not playing a script.
- play_script_props (dict; optional):
Props to control the options for the play button to run the scripts. dbc.Button props.
- yada_src (string; optional):
Location src of the image that you want to display for yada.
- scripts (dict of list of dicts; optional):
Dictionary of keys to scripts:
- each key will have an array of a directory:
{target (string; required), convo (string; optional), show_text (bool; optional),
highlight_target (bool; optional),
action (string; optional), action_args (string|dict; optional)}
- next_button_props (dict; optional):
Props to control the options for the next button. dbc.Button props.
- prev_button_props (dict; optional):
Props to control the options for the previous button. dbc.Button props.
- end_button_props (dict; optional):
Props to control the options for the end button. dbc.Button props.
- steps_offcanvas_style (dict; optional):
Style to control the offcanvas style while playing a script.