Dash components are described declaratively by a set of attributes.
All of these attributes can be updated by callback functions but only
a subset of these attributes are updated through user interaction.
For example, when you click on an option in a `dcc.Dropdown` component, 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
''')),
Syntax('''df = pd.DataFrame({
'a': [1, 2, 3],
'b': [4, 1, 4],
'c': ['x', 'y', 'z'],
})
app.layout = html.Div([
dcc.Dropdown(
id='dropdown',
options=[{'label': i, 'value': i} for i in df['c'].unique()],
value='a'
),
html.Div(id='output'),
])
@app.callback(Output('output', 'children'),
[Input('dropdown', 'value')])
def update_output_1(value):
# Here, `df` is an example of a variable that is
# "outside the scope of this function".
# *It is not safe to modify or reassign this variable
# inside this callback.*
global df = df[df['c'] == value] # do not do this, this is not safe!
return len(df)
''',
summary='''
Here is a sketch of an app with a callback that modifies data
out of it's scope. This type of pattern *will not work reliably*
for the reasons outlined above.'''),
Syntax('''df = pd.DataFrame({
#### Generating HTML with Dash
Dash apps are composed of two parts. The first part is the "`layout`" of
the app and it describes what the application looks like.
The second part describes the interactivity of the application.
Dash provides Python classes for all of the visual components of
the application. We maintain a set of components in the
`dash_core_components` and the `dash_html_components` library
but you can also [build your own](https://github.com/plotly/dash-components-archetype)
with JavaScript and React.js.
'''.replace(' ', '')),
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(s('''
The Dash upload component allows your app's veiwers to upload files,
like excel spreadsheets or images, into your application.
Your Dash app can access the contents of an upload by listening to
the `contents` property of the `dcc.Upload` component.
`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('''
import tools
examples = {
'basic-input': tools.load_example('tutorial/examples/basic-input.py'),
'basic-state': tools.load_example('tutorial/examples/basic-state.py')
}
layout = html.Div([
html.H1('Dash State'),
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(
will feel snappier.
### Memoization
Since Dash's callbacks are functional in nature (they don't contain any state),
it's easy to add memoization caching. Memoization stores the results of a
function after it is called and re-uses the result if the function is called
with the same arguments.
To better understand how memoization works, let's start with a simple example.
'''),
Syntax('''import time
import functools32
@functools32.lru_cache(maxsize=32)
def slow_function(input):
time.sleep(10)
return 'Input was {}'.format(input)
'''),
dcc.Markdown('''
Calling `slow_function('test')` the first time will take 10 seconds.
Calling it a second time with the same argument will take almost no time
since the previously computed result was saved in memory and reused.
***
Dash apps are frequently deployed across multiple processes or threads.
In these cases, each process or thread contains its own memory, it doesn't
share memory across instances. This means that if we were to use `lru_cache`,
our cached results might not be shared across sessions.
