def create_doc_page(examples,
component_names,
component_hyphenated,
component_examples=None,
interactive_examples_flag="None"):
'''Generates a documentation page for a component.
:param (dict[object]) examples: A dictionary that contains the
loaded examples for all components.
:param (dict[list]) component_names: A dictionary defining which
components are React components, and which are Python
components. The keys in the dictionary are 'react' and 'python',
and the values for each are lists containing the names of the
components that belong to each category.
:param (string) component_hyphenated: The name of the component in snake
case, with underscores (_) replaced with dashes (-).
:rtype (object): A div containing the contents of the component's
documentation page.
'''
component_name = component_hyphenated\
.replace('-', ' ')\
.title()\
.replace(' ', '')\
.replace('.Py', '')
if component_examples is None:
component_examples = []
component_examples = create_examples(component_examples)
if component_name == 'Molecule3DViewer':
component_name = 'Molecule3dViewer'
elif component_name == 'Molecule2DViewer':
component_name = 'Molecule2dViewer'
interactive_examples = [
examples[k] for k in examples if interactive_examples_flag in k
]
return html.Div(
children=[html.H1('{} Examples and Reference'.format(component_name))
] + create_default_example(
component_name, examples[component_hyphenated], styles,
component_hyphenated.replace('.py', '')) +
create_interactive_examples(component_name, interactive_examples) +
component_examples +
[rc.ComponentReference(component_name, lib=dash_bio)])
# -*- coding: utf-8 -*-
import dash_core_components as dcc
import dash_html_components as html
from dash_docs import styles
from dash_docs import tools
from dash_docs import reusable_components as rc
examples = tools.load_examples(__file__)
layout = html.Div(children=[
html.H1('dcc.Link'),
rc.Markdown(
'To learn more about links, see the chapter on <dccLink href="/urls" children="Dash URLs"/>.'
),
html.H3('Link Properties'),
rc.ComponentReference('Link')
])
rc.ComponentBlock('''import dash_core_components as dcc
from datetime import datetime as dt
dcc.DatePickerRange(
minimum_nights=5,
clearable=True,
with_portal=True,
start_date=dt(2017,6,21)
)'''),
html.Hr(),
html.H3("Right to Left Calendars and First Day of Week"),
rc.Markdown("When the `is_RTL` property is set to `True` \
the calendar will be rendered from right to left."),
rc.Markdown("The `first_day_of_week` property allows you to \
define which day of the week will be set as the first \
day of the week. In the example below, Tuesday is \
the first day of the week."),
rc.ComponentBlock('''import dash_core_components as dcc
from datetime import datetime as dt
dcc.DatePickerRange(
is_RTL=True,
first_day_of_week=3,
start_date=dt(2017,6,21)
)''',
style=styles.code_container),
html.Hr(),
html.H3('DatePickerRange Properties'),
rc.ComponentReference('DatePickerRange')
])
import dash_core_components as dcc
import dash_html_components as html
from dash_docs import styles
from dash_docs import tools
from dash_docs import reusable_components as rc
examples = tools.load_examples(__file__)
layout = html.Div([
html.H1('dcc.Loading Component Documentation'),
rc.Markdown('''
Here’s a simple example that wraps the outputs for a couple of `Input`
components in the `Loading` component.
As you can see, you can define the type of spinner you would like to show
(refer to the reference table below for all possible types of spinners).
You can modify other attributes as well, such as `fullscreen=True`
if you would like the spinner to be displayed fullscreen.
Notice that, the Loading component traverses all
of its children to find a loading state, as demonstrated in the
second callback, so that even nested children will get picked up.
'''),
rc.Syntax(examples['loading_component.py'][0]),
rc.Example(examples['loading_component.py'][1]),
rc.Markdown('''
Please also check out <dccLink href="/loading-states" children="this section on loading states"/> if you want a more customizable experience.
'''),
html.H2('dcc.Loading Properties'),
rc.ComponentReference('Loading')
])
for selecting a single option at a time or
<dccLink href="/dash-core-components/dropdown" children="Dropdown"/> for
a more compact view.
'''),
rc.ComponentBlock('''import dash_core_components as dcc
dcc.Checklist(
options=[
{'label': 'New York City', 'value': 'NYC'},
{'label': 'Montréal', 'value': 'MTL'},
{'label': 'San Francisco', 'value': 'SF'}
],
value=['NYC', 'MTL']
)''',
style=styles.code_container),
rc.ComponentBlock('''import dash_core_components as dcc
dcc.Checklist(
options=[
{'label': 'New York City', 'value': 'NYC'},
{'label': 'Montréal', 'value': 'MTL'},
{'label': 'San Francisco', 'value': 'SF'}
],
value=['NYC', 'MTL'],
labelStyle={'display': 'inline-block'}
)''',
style=styles.code_container),
html.H2('dcc.Checklist Properties'),
rc.ComponentReference('Checklist')
])
import dash_html_components as html
from dash_docs import styles
from dash_docs import tools
from dash_docs import reusable_components as rc
examples = tools.load_examples(__file__)
layout = html.Div(children=[
html.H1('Button Examples and Reference'),
html.H2('Button Basic Example'),
rc.Markdown("An example of a default button without any extra properties \
and `n_clicks` in the callback. `n_clicks` is an integer that represents \
that number of times the button has been clicked. Note that the original \
value is `None`."),
rc.Syntax(examples['button_basic.py'][0]),
rc.Example(examples['button_basic.py'][1]),
html.Br(),
html.H2([
'Determining which Button Changed with ',
html.Code('callback_context')
]),
rc.Markdown("This example utilizes the `dash.callback_context` property, \
to determine which input was changed."),
rc.Syntax(examples['button_ctx.py'][0]),
rc.Example(examples['button_ctx.py'][1]),
html.Br(),
html.H2('Button Properties'),
rc.ComponentReference('Button', html)
])
```
''')
````
"""),
html.Div(rc.Markdown('''
Inline code snippet: `True`
Block code snippet:
```py
import dash
external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
```
'''), className='example-container'),
rc.Markdown('''
Only certain languages are supported by default in
`dcc.Markdown`. For more details about how to customize the
languages and colour schemes, please see ["Syntax Highlighting
With
Markdown"](https://dash.plot.ly/external-resources#md-syntax-highlight).
'''),
html.H2('dcc.Markdown Properties'),
rc.ComponentReference('Markdown')
])
# -*- coding: utf-8 -*-
import dash_core_components as dcc
import dash_html_components as html
from dash_docs import styles
from dash_docs import tools
from dash_docs import reusable_components as rc
examples = tools.load_examples(__file__)
layout = html.Div(children=[
html.H1('dcc.Tab Reference'),
rc.Markdown('''
The `dcc.Tab` and `dcc.Tabs` components can be used to create tabbed sections in your app.
The `Tab` component controls the style and value of the individual tab
and the `Tabs` component hold a collection of `Tab` components.
See complete examples in the [dcc.Tabs](/dash-core-components/tabs) chapter.
'''),
html.H2('Tab properties'),
rc.ComponentReference('Tab')
])
# -*- coding: utf-8 -*-
import dash_core_components as dcc
import dash_html_components as html
from dash_docs import styles
from dash_docs import tools
from dash_docs import reusable_components as rc
examples = tools.load_examples(__file__)
layout = html.Div([
html.H1('dcc.Interval'),
rc.Markdown('''
`dcc.Interval` is a component that will fire a callback periodically.
Use `dcc.Interval` to update your app in realtime without needing to
refresh the page or click on any buttons.
See also the <dccLink href="/live-updates" children="live updates"/>
chapter for other examples and strategies.
'''),
html.H2('dcc.Interval Properties'),
rc.ComponentReference('Interval')
])
0: {'label': '0 °C', 'style': {'color': '#77b0b1'}},
26: {'label': '26 °C'},
37: {'label': '37 °C'},
100: {'label': '100 °C', 'style': {'color': '#f50'}}
},
included=False
)'''),
html.H3('Non-Linear Slider and Updatemode'),
rc.Markdown("Create a logarithmic slider by setting the labels of the \
`marks` property \
to be logarithmic and adjusting the slider's output \
`value` in the callbacks. The `updatemode` property \
allows us to determine when we want a callback to be \
triggered. The following example has `updatemode='drag'` \
which means a callback is triggered everytime the handle \
is moved. The default setting is `mouseup` which triggers \
the callback when you release your mouse from the slider."),
rc.Markdown(
examples['slider_updatemode.py'][0],
style=styles.code_container,
),
html.Div(examples['slider_updatemode.py'][1],
className='example-container',
style={
'overflow': 'hidden',
'padding': '20px'
}),
html.H3("Slider Properties"),
rc.ComponentReference('Slider')
])
''')),
rc.Example(examples['download-text.py'][1]),
html.Hr(),
html.H3('Download Dataframe as CSV file'),
rc.Syntax(examples['download-dataframe-csv.py'][0],
summary=rc.Markdown('''
For downloading dataframes, the many pandas export methods are
supported. Below we are downloading a dataframe as a CSV:
''')),
rc.Example(examples['download-dataframe-csv.py'][1]),
html.Hr(),
html.H3('Download Dataframe as Excel file'),
rc.Syntax(examples['download-dataframe-xlxs.py'][0],
summary=rc.Markdown('''
To download a dataframe as an Excel file with pandas, add
`xlsxwriter` or `openpyxl` as an app dependency:
''')),
rc.Example(examples['download-dataframe-xlxs.py'][1]),
html.Hr(),
html.H3('Downloading Images'),
rc.Syntax(examples['download-image.py'][0],
summary=rc.Markdown('''
To download a file from disk use `dcc.send_file`, taking care to
specify the file path.
''')),
rc.Example(examples['download-image.py'][1]),
html.Hr(),
html.H2('dcc.Download Component Properties'),
rc.ComponentReference('Download'),
])
import dash_html_components as html
import dash_vtk
from dash_docs import reusable_components as rc
components = [
"Algorithm", "Calculator", "CellData", "DataArray", "FieldData",
"GeometryRepresentation", "ImageData", "Mesh", "PointCloudRepresentation",
"PointData", "PolyData", "Reader", "ShareDataSet", "SliceRepresentation",
"View", "Volume", "VolumeController", "VolumeDataRepresentation",
"VolumeRepresentation"
]
sections = [html.H1("Dash VTK Reference")]
for component in components:
sections.extend(
[html.H2(component),
rc.ComponentReference(component, dash_vtk)])
layout = html.Div(sections)
from dash_docs import styles
from dash_docs import tools
from dash_docs import reusable_components as rc
examples = tools.load_examples(__file__)
layout = html.Div(children=[
html.H3('dcc.Textarea Documentation'),
dcc.Markdown(
'''
`dcc.Textarea` is a wrapper around the [<textarea/> HTML component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea).
It is like a `dcc.Input` except that allows for multiple lines of text.
'''
),
html.H2('Simple dcc.Textarea Example'),
rc.Syntax(examples['textarea_basic.py'][0]),
rc.Example(examples['textarea_basic.py'][1]),
html.H2('Update dcc.Textarea callback on button press'),
rc.Syntax(examples['textarea_state.py'][0]),
rc.Example(examples['textarea_state.py'][1]),
html.H2('dcc.Textarea Properties'),
rc.ComponentReference('Textarea')
])
# -*- coding: utf-8 -*-
import dash_core_components as dcc
import dash_html_components as html
from dash_docs import styles
from dash_docs import tools
from dash_docs import reusable_components as rc
examples = tools.load_examples(__file__)
layout = html.Div([
html.H1('ConfirmDialog component'),
rc.Markdown('''
ConfirmDialog is used to display the browser's native "confirm" modal,
with an optional message and two buttons ("OK" and "Cancel").
This ConfirmDialog can be used in conjunction with buttons when the user
is performing an action that should require an extra step of verification.
See <dccLink href="/dash-core-components/confirmdialogprovider" children="dcc.ConfirmDialogProvider"/>
for an easier way to display an alert when clicking on an item.
'''),
rc.Syntax(examples['confirm.py'][0]),
rc.Example(examples['confirm.py'][1]),
html.H2('dcc.ConfirmDialog Properties'),
rc.ComponentReference('ConfirmDialog')
])
"""),
html.H3('How Resizing Works - Advanced'),
rc.Markdown("""
The properties of `dcc.Graph` that can control the size of the
graph (other than `responsive`) are:
* `figure.layout.height` - explicitly sets the height
* `figure.layout.width` - explicitly sets the width
* `figure.layout.autosize` - if `True`, sets the height and width
of the graph to that of its parent container
* `config.responsive` - if `True`, changes the height and width of
the graph upon window resize
The `responsive` property works in conjunction with the above
properties in the following way:
* `True`: `config.responsive` and `figure.layout.autosize` are
overriden with `True` values, and `figure.layout.height` and
`figure.layout.width` are unset
* `False`: `config.responsive` and `figure.layout.autosize` are
both overriden with `False` values
* `'auto'`: the resizability of the plot is determined the
same way as it used to be (i.e., with the four properties above)
"""),
html.H3('Graph Properties'),
rc.ComponentReference('Graph')
])
rc.Example(examples['input_all_types.py'][1]),
html.Br(),
html.H2('Debounce delays the Input processing'),
rc.Syntax(examples['input-basic.py'][0]),
rc.Example(examples['input-basic.py'][1]),
html.Br(),
html.H2('Number Input'),
rc.Markdown("""
_Fixed and enhanced in Dash v1.1.0_
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
11 will return respectively integer three and None in Python callbacks.
### Important Notice re Integer vs Float
There is a limitation when converting numbers like 1.0 or 0.0, the
corresponding number type in callbacks is **Integer** instead of **Float**.
Please add extra guard casting like `float()` within callbacks if needed.
"""),
rc.Syntax(examples['input_number_type.py'][0]),
rc.Example(examples['input_number_type.py'][1]),
html.Br(),
html.H2('Input Properties'),
rc.ComponentReference('Input')
])
)''',
style=styles.code_container),
html.Hr(),
html.H3('Disable Options'),
rc.Markdown("To disable a particular option inside the dropdown \
menu, set the `disabled` property in the options."),
rc.ComponentBlock('''import dash_core_components as dcc
dcc.Dropdown(
options=[
{'label': 'New York City', 'value': 'NYC', 'disabled': True},
{'label': 'Montreal', 'value': 'MTL'},
{'label': 'San Francisco', 'value': 'SF', 'disabled': True}
],
)''',
style=styles.code_container),
html.H3('Dynamic Options'),
html.P("This is an example on how to update the options on the server \
depending on the search terms the user types. For example purpose \
the options are empty on first load, as soon as you start typing \
they will be loaded with the corresponding values."),
rc.Markdown(examples['dropdown_dynamic_options.py'][0],
style=styles.code_container),
html.Div(examples['dropdown_dynamic_options.py'][1],
className='example-container',
style={'overflow-x': 'initial'}),
html.Hr(),
html.H3("Dropdown Properties"),
rc.ComponentReference('Dropdown')
])
# -*- coding: utf-8 -*-
import dash_core_components as dcc
import dash_html_components as html
from dash_docs import styles
from dash_docs import tools
from dash_docs import reusable_components as rc
examples = tools.load_examples(__file__)
layout = html.Div([
html.H1('Location Component'),
rc.Markdown('''
The `dcc.Location` component represents the location or address bar in your web
browser. Through its `href`, `pathname`, `search` and `hash` properties
you can access different portions of the url that the app is loaded on.
See the <dccLink href="/urls" children="URLs & Multipage Apps chapter"/>
for more details.
For example, given the url `http://127.0.0.1:8050/page-2?a=test#quiz`:
- `href` = `"http://127.0.0.1:8050/page-2?a=test#quiz"`
- `pathname` = `"/page-2"`
- `search` = `"?a=test"`
- `hash` = `"#quiz"`
'''),
rc.ComponentReference('Location')
])
import dash_html_components as html
import dash_cytoscape as cyto
from dash_docs import reusable_components as rc
layout = html.Div([
html.H1("Cytoscape Reference"),
rc.ComponentReference("Cytoscape", cyto),
html.H2("utils.Tree"),
rc.Markdown("""
A class to facilitate tree manipulation in Cytoscape.
**param** node_id: The ID of this tree, passed to the node data dict
**param** children: The children of this tree, also Tree objects
**param** data: Dictionary passed to this tree's node data dict
**param** edge_data: Dictionary passed to the data dict of the edge connecting this tree to its
parent
#### Tree.is_leaf()
**return:** If the Tree is a leaf or not.
#### Tree.add_children(children)
Add a list of children to the current children of a Tree.
**param** children: List of Tree objects
#### Tree.get_edges()
dcc.DatePickerSingle(
clearable=True,
with_portal=True,
date=date(2017,6,21)
)'''),
html.Hr(),
html.H3("Right to Left Calendars and First Day of Week"),
rc.Markdown("""
When the `is_RTL` property is set to `True`
the calendar will be rendered from right to left.
"""),
rc.Markdown("""
The `first_day_of_week` property allows you to
define which day of the week will be set as the first
day of the week. In the example below, Tuesday is
the first day of the week.
"""),
rc.ComponentBlock('''import dash_core_components as dcc
from datetime import date
dcc.DatePickerSingle(
is_RTL=True,
first_day_of_week=3,
date=date(2017,6,21)
)'''),
html.Hr(),
html.H3('DatePickerSingle Properties'),
rc.ComponentReference('DatePickerSingle')
])
html.Hr(),
html.H3('Disabled Switch'),
rc.Markdown(
"To disable the Boolean Switch set the property `disabled` to `True`."
),
rc.ComponentBlock('''import dash_daq as daq
daq.BooleanSwitch(
disabled=True,
label="Disabled",
labelPosition="bottom"
)''',
style=styles.code_container),
html.Hr(),
html.H3("Boolean Switch Properties"),
rc.ComponentReference('BooleanSwitch', lib=daq)
])
# ColorPicker
ColorPicker = html.Div(children=[
html.H1('Color Picker Examples and Reference'),
html.Hr(),
html.H3('Default Color Picker'),
html.P("An example of a default Color Picker without \
any extra properties."),
rc.Markdown(examples['color-picker.py'][0], style=styles.code_container),
html.Div(examples['color-picker.py'][1],
className='example-container',
style={'overflow-x': 'initial'}),
html.Hr(),
html.H3('Size'),
# -*- coding: utf-8 -*-
import dash_core_components as dcc
import dash_html_components as html
from dash_docs import styles
from dash_docs import tools
from dash_docs import reusable_components as rc
examples = tools.load_examples(__file__)
layout = html.Div([
html.H1('dcc.ConfirmDialogProvider Documentation'),
rc.Markdown('''
Send a <dccLink href="/dash-core-components/confirmdialog" children="ConfirmDialog"/> when the user
clicks the children of this component, usually a button.
'''),
rc.Syntax(examples['confirm_provider.py'][0]),
rc.Example(examples['confirm_provider.py'][1]),
html.H1('dcc.ConfirmDialogProvider Reference'),
rc.ComponentReference('ConfirmDialogProvider')
])
for selecting multiple options at a time
<dccLink href="/dash-core-components/dropdown">Dropdown</dccLink> for
a more compact view.
'''),
rc.ComponentBlock('''import dash_core_components as dcc
dcc.RadioItems(
options=[
{'label': 'New York City', 'value': 'NYC'},
{'label': 'Montréal', 'value': 'MTL'},
{'label': 'San Francisco', 'value': 'SF'}
],
value='MTL'
)''',
style=styles.code_container),
rc.ComponentBlock('''import dash_core_components as dcc
dcc.RadioItems(
options=[
{'label': 'New York City', 'value': 'NYC'},
{'label': 'Montréal', 'value': 'MTL'},
{'label': 'San Francisco', 'value': 'SF'}
],
value='MTL',
labelStyle={'display': 'inline-block'}
)''',
style=styles.code_container),
html.H2('RadioItems Properties'),
rc.ComponentReference('RadioItems')
])
import dash_html_components as html
import dash_table
from dash_docs import reusable_components as rc
layout = html.Div([
html.H1(html.Code('dash_table.DataTable')),
rc.ComponentReference('DataTable', dash_table)
])
'''),
rc.Syntax(examples['upload-datafile.py'][0],
summary=rc.Markdown('''
Here's an example that parses CSV or Excel files and displays
the results in a table. Note that this example uses the
`DataTable` from the
[dash-table](https://github.com/plotly/dash-table)
project.
''')),
rc.Example(examples['upload-datafile.py'][1]),
html.Hr(),
rc.Syntax(examples['upload-image.py'][0],
summary=rc.Markdown('''
This next example responds to image uploads by displaying them
in the app with the `html.Img` component.
''')),
rc.Example(examples['upload-image.py'][1]),
rc.Syntax(examples['upload-gallery.py'][0],
summary=rc.Markdown('''
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.
''')),
rc.Example(examples['upload-gallery.py'][1]),
html.Hr(),
html.H2('dcc.Upload Component Properties'),
rc.ComponentReference('Upload')
])
'''),
html.H2('Store clicks example'),
rc.Syntax(examples['store_clicks.py'][0]),
rc.Example(examples['store_clicks.py'][1]),
html.H2('Share data between callbacks'),
rc.Syntax(examples['store_share.py'][0]),
rc.Example(examples['store_share.py'][1]),
rc.Markdown('''
## Storage Limitations
- The maximum browser [storage space](https://demo.agektmr.com/storage/) is determined by the following factors:
- Mobile or laptop
- The browser, under which a sophisticated algorithm is implemented within *Quota Management*
- Storage encoding where UTF-16 can end up saving only half of the size of UTF-8
- It's generally safe to store up to 2MB in most environments, and 5~10MB in most desktop-only applications.
- `modified_timestamp` is read only.
## Retrieving the initial store data
If you use the `data` prop as an output, you cannot get the
initial data on load with the `data` prop. To counter this,
you can use the `modified_timestamp` as `Input` and the `data` as `State`.
'''),
html.H2('dcc.Store Properties'),
rc.ComponentReference('Store'),
])
min=0,
max=30,
value=[10, 15],
allowCross=False
)
''',
style=styles.code_container),
html.H3('Non-Linear Slider and Updatemode'),
rc.Markdown("Create a logarithmic slider by setting `marks`\
to be logarithmic and adjusting the slider's output \
`value` in the callbacks. The `updatemode` property \
allows us to determine when we want a callback to be \
triggered. The following example has `updatemode='drag'` \
which means a callback is triggered everytime the handle \
is moved. \
Contrast the callback output with the first example on this \
page to see the difference."),
rc.Markdown(
examples['rangeslider_nonlinear.py'][0],
style=styles.code_container,
),
html.Div(examples['rangeslider_nonlinear.py'][1],
className='example-container',
style={
'overflow': 'hidden',
'padding': '20px'
}),
html.H3("RangeSlider Properties"),
rc.ComponentReference('RangeSlider')
])
