Syntax(examples[0][0],
summary='''
To get started, create a file named `app.py` with the following code:
'''),
dcc.Markdown('''
Run the app with
```
$ python app.py
...Running on http://127.0.0.1:8050/ (Press CTRL+C to quit)
```
and visit [http:127.0.0.1:8050/](http:127.0.0.1:8050/)
in your web browser. You should see an app that looks like this.
'''.replace(' ', '')),
Example(examples[0][1]),
dcc.Markdown('''
Note:
1. The `layout` is composed of a tree of "components" like `html.Div`
and `dcc.Graph`.
2. The `dash_html_components` library has a component for every HTML
tag. The `html.H1(children='Hello Dash')` component generates
a `<h1>Hello Dash</h1>` HTML element in your application.
3. Not all components are pure HTML. The `dash_core_components` describe
higher-level components that are interactive and are generated with
JavaScript, HTML, and CSS through the React.js library.
4. Each component is described entirely through keyword attributes.
Dash is _declarative_: you will primarily describe your application
through these attributes.
5. The `children` property is special. By convention, it's always the
first attribute which means that you can omit it:
generate_prop_info('RangeSlider')
])
# Checklist
Checklist = html.Div(children=[
html.H3('Checklist Properties'),
generate_prop_info('Checklist')
])
# Input
Input = html.Div(children=[
html.H1('Input Examples and Reference'),
html.Hr(),
html.H3('Supported Input Types'),
Syntax(examples['input-all-types'][0]),
Example(examples['input-all-types'][1]),
html.Br(),
html.H3('Debounce delays the Input processing'),
Syntax(examples['input-basic'][0]),
Example(examples['input-basic'][1]),
html.Br(),
html.H3('Number Input'),
dcc.Markdown("""
*fixed and enhanced in Dash v1.1*
Number type is now close to native HTML5 `input` behavior across
browsers. We also apply a strict number casting in callbacks:
valid number converts into corresponding number types, and invalid number
converts into None. E.g.
`dcc.Input(id='range', type='number', min=2, max=10, step=1)` typing 3 and
when you click on an option in a `dcc.Dropdown` component and the
`value` property of that component changes.
The `dcc.Graph` component has four attributes that can change
through user-interaction: `hoverData`, `clickData`, `selectedData`,
`relayoutData`.
These properties update when you hover over points, click on points, or
select regions of points in a graph.
'''.replace(' ', '')),
Syntax(examples['simple-graph-events'][0],
summary="""
Here's an simple example that
prints these attributes in the screen.
"""),
Example(examples['simple-graph-events'][1]),
html.Hr(),
html.H3('Update Graphs on Hover'),
Syntax(examples['world-indicators'][0],
summary="""
Let's update our world indicators example from the previous chapter
by updating time series when we hover over points in our scatter plot.
"""),
Example(examples['world-indicators'][1]),
dcc.Markdown(
s('''
Try mousing over the points in the scatter plot on the left.
Notice how the line graphs on the right update based off of the point that
you are hovering over.
''')),
html.Hr(),
- **`persisted_props`** (list of strings; optional): These are the props
whose values will persist. Typically this defaults to all user-editable
props, which in many cases is just one (ie `'value'`). `dash-table` has
many props users can edit, and all of them except `'data'` are included
here by default. Sometimes only a *part* of a prop is saved; this happens
with table headers, which are only part of the `columns` prop.
The corresponding `persisted_props` value is `'columns.name'`.
In the following example, notice that a callback that depends on persisted
values receives those persisted values, even if the layout initially
provided something else. Also the city is persisted in `localStorage` so
will be saved indefinitely, but the neighborhood - which remembers a
different value for each city - resets if you open the page in a new tab.
'''),
Syntax(examples['persistence'][0]),
Example(examples['persistence'][1]),
dcc.Markdown('''
## Explicitly clearing saved data
Persistence continues (subject to `persistence_type`) as long as the
component `id`, the `persistence` value, and the prop provided by the
server when creating or updating the *entire* component has the same value
as it had before the user changed it. But if you have a callback whose
`Output` is the specific persisted prop itself, that takes precedence over
any saved value. This lets you reset user edits, using `PreventUpdate` or
`dash.no_update` until you detect the reset condition.
'''),
Syntax(examples['persistence_clear'][0]),
Example(examples['persistence_clear'][1]),
dcc.Markdown('''
## For component developers
**A:** *New in v0.38.0!* In addition to event properties like `n_clicks`
that change whenever an event happens (in this case a click), there is a
global variable `dash.callback_context`, available only inside a callback.
It has properties:
- `triggered`: list of changed properties. This will be empty on initial
load, unless an `Input` prop got its value from another initial callback.
After a user action it is a length-1 list, unless two properties of a
single component update simultaneously, such as a value and a timestamp
or event counter.
- `inputs` and `states`: allow you to access the callback params
by id and prop instead of through the function args. These have the form
of dictionaries `{ 'component_id.prop_name': value }`
Here's an example of how this can be done:''')),
Syntax(examples['last_clicked_button'][0]),
Example(examples['last_clicked_button'][1]),
dcc.Markdown(
s('''
Prior to v0.38.0, you needed to compare timestamp properties like
`n_clicks_timestamp` to find the most recent click. While existing uses of
`*_timestamp` continue to work for now, this approach is deprecated, and
may be removed in a future update. The one exception is
`modified_timestamp` from `dcc.Store`, which is safe to use, it is NOT
deprecated.
------------------------
**Q:** *Can I use Jinja2 templates with Dash?*
**A:** Jinja2 templates are rendered on the server (often in a Flask app)
`contents` is a base64 encoded string that contains the files contents,
no matter what type of file: text files, images, zip files,
excel spreadsheets, etc.
''')),
Syntax(examples['upload-datafile'][0], summary=dcc.Markdown(s('''
Here's an example that parses CSV or Excel files and displays
the results in a table. Note that this example uses the
`DataTable` prototype from the
[dash-table-experiments](https://github.com/plotly/dash-table-experiments)
project.
'''))),
Example(examples['upload-datafile'][1]),
html.Hr(),
Syntax(examples['upload-image'][0], summary=dcc.Markdown(s('''
This next example responds to image uploads by displaying them
in the app with the `html.Img` component.
'''))),
Example(examples['upload-image'][1]),
Syntax(examples['upload-gallery'][0], summary=dcc.Markdown(s('''
The `children` attribute of the `Upload` component accepts any
Dash component. Clicking on the children element will trigger the
upload action, as will dragging and dropping files.
Here are a few different ways that you could style the upload
component using standard dash components.
dcc.Markdown(s('''
> This is the *4th* chapter of the [Dash Tutorial](/).
> The [previous chapter](/getting-started-part-2) covered Dash Callbacks
> and the [next chapter](/interactive-graphing) covers interactive
> graphing and crossfiltering.
> Just getting started? Make sure to
> [install the necessary dependencies](/installation).
''')),
dcc.Markdown(s('''
In the previous chapter on
[basic Dash callbacks](/getting-started-part-2),
our callbacks looked something like:
''')),
Syntax(examples['basic-input'][0]),
Example(examples['basic-input'][1]),
dcc.Markdown(s('''
In this example, the callback function is fired whenever any of the
attributes described by the `dash.dependencies.Input` change.
Try it for yourself by entering data in the inputs above.
`dash.dependencies.State` allows you to pass along extra values without
firing the callbacks. Here's the same example as above but with the
`dcc.Input` as `dash.dependencies.State` and a button as
`dash.dependencies.Input`.
''')),
Syntax(examples['basic-state'][0]),
Example(examples['basic-state'][1]),
dcc.Markdown(s('''
dcc.Markdown('''
## Dash State
> This is the *4th* chapter of the [Dash Tutorial](/).
> The [previous chapter](/getting-started-part-2) covered Dash Callbacks
> and the [next chapter](/interactive-graphing) covers interactive
> graphing and crossfiltering.
> Just getting started? Make sure to
> [install the necessary dependencies](/installation).
'''),
dcc.Markdown('''
In the previous chapter on
[basic Dash callbacks](/getting-started-part-2),
our callbacks looked something like:
'''),
Syntax(examples['basic-input'][0]),
Example(examples['basic-input'][1]),
dcc.Markdown('''
In this example, the callback function is fired whenever any of the
attributes described by the `dash.dependencies.Input` change.
Try it for yourself by entering data in the inputs above.
`dash.dependencies.State` allows you to pass along extra values without
firing the callbacks. Here's the same example as above but with the
`dcc.Input` as `dash.dependencies.State` and a button as
`dash.dependencies.Input`.
'''),
Syntax(examples['basic-state'][0]),
Example(examples['basic-state'][1]),
dcc.Markdown('''
In this example, changing text in the `dcc.Input` boxes won't fire
the callback but clicking on the button will. The current values of
`contents` is a base64 encoded string that contains the files contents,
no matter what type of file: text files, images, zip files,
excel spreadsheets, etc.
''')),
Syntax(examples['upload-datafile'][0],
summary=dcc.Markdown(
s('''
Here's an example that parses CSV or Excel files and displays
the results in a table. Note that this example uses the
`DataTable` prototype from the
[dash-table-experiments](https://github.com/plotly/dash-table-experiments)
project.
'''))),
Example(examples['upload-datafile'][1]),
html.Hr(),
Syntax(examples['upload-image'][0],
summary=dcc.Markdown(
s('''
This next example responds to image uploads by displaying them
in the app with the `html.Img` component.
'''))),
Example(examples['upload-image'][1]),
Syntax(examples['upload-gallery'][0],
summary=dcc.Markdown(
s('''
The `children` attribute of the `Upload` component accepts any
Dash component. Clicking on the children element will trigger the
upload action, as will dragging and dropping files.
Here are a few different ways that you could style the upload