diff --git a/docs/components_page/components/__tests__/test_snippets.py b/docs/components_page/components/__tests__/test_snippets.py index a5e8249e0..fdc979d4b 100644 --- a/docs/components_page/components/__tests__/test_snippets.py +++ b/docs/components_page/components/__tests__/test_snippets.py @@ -120,10 +120,38 @@ def test_jl_snippets(dash_thread_server, dashjl_server, config): ) +def test_landing_page_example(dash_thread_server, dashr_server, dashjl_server): + index_dir = HERE.parent / "index" + py_source = (index_dir / "simple.py").read_text() + r_source = ( + (index_dir / "simple.R").read_text().replace("8050", str(R_PORT)) + ) + jl_source = ( + (index_dir / "simple.jl").read_text().replace("8050", str(JL_PORT)) + ) + + app = py_source_to_app(py_source, {}) + dash_thread_server.start(app, port=8050) + py_layout = requests.get(f"{dash_thread_server.url}/_dash-layout").json() + + dashr_server.start(r_source) + r_layout = requests.get(f"{dashr_server.url}/_dash-layout").json() + + dashjl_server.start(jl_source) + jl_layout = requests.get(f"{dashjl_server.url}/_dash-layout").json() + + # Test layouts match + unittest.TestCase().assertDictEqual( + drop_keys(py_layout), drop_keys(r_layout) + ) + unittest.TestCase().assertDictEqual( + drop_keys(py_layout), drop_keys(jl_layout) + ) + + def assert_layouts_equal( compare, runner, wrapper, port, py_runner, py_env, py_port ): - # Get python snippet layout app = py_source_to_app( PY_WRAPPER.format( diff --git a/docs/components_page/components/index.md b/docs/components_page/components/index.md index 2a4a3c90b..27960fb32 100644 --- a/docs/components_page/components/index.md +++ b/docs/components_page/components/index.md @@ -3,19 +3,25 @@ title: Components lead: Usage examples for all components in dash-bootstrap-components --- -The component documentation for _dash-bootstrap-components_ contains many snippets showing example usage, as well as api documentation for each component explaining the different props that you can set. +The component documentation for _dash-bootstrap-components_ contains many snippets showing example usage, as well as API documentation for each component explaining the different props that you can set. Example snippets for the different components will look something like this, with tabs to switch between R or Julia versions of the examples. -{{example:components/index/simple.py:layout}} +{{example:components/badge/simple.py:badge}} ## Adding the snippets to your app Note that the contents of each snippet **do not by themselves constitute a working app**. We generally omit boilerplate code such as standard imports and instantiation of the app. In the above example you would additionally need to: -1. import Dash -2. create a Dash app instance (making sure to link a Bootstrap stylesheet, see the [themes documentation](/docs/themes/) for details) -3. assign `layout` to the app layout -4. start the Dash server. +1. Import Dash. +2. Create a Dash app instance (making sure to link a Bootstrap stylesheet, see the [themes documentation](/docs/themes/) for details). +3. Add the example to the app's layout. +4. Start the Dash server. -If any of the above steps are unclear, please take a look at the [Quickstart](/docs/quickstart/) instructions for creating a basic app, the [examples](https://github.com/facultyai/dash-bootstrap-components/tree/main/examples) in our GitHub repository, or refer to the official Dash documentation for [Python](https://dash.plotly.com/), [R](https://dashr.plotly.com/), or [Julia](https://dash-julia.plotly.com/). +For example, a simple application incorporating example above could look like this, where we wrap the snippet in a container and add it to the layout. + +{{code-example:components/index/simple.py}} + +There is more detail on this in the [Quickstart](/docs/quickstart/) instructions for creating a basic app. Additionally, the [examples](https://github.com/facultyai/dash-bootstrap-components/tree/main/examples) in our GitHub repository demonstrate how multiple components can be combined to create a feature rich application. + +For more details on Dash in general, please refer to the official Dash documentation for [Python](https://dash.plotly.com/), [R](https://dashr.plotly.com/), or [Julia](https://dash-julia.plotly.com/). diff --git a/docs/components_page/components/index/simple.R b/docs/components_page/components/index/simple.R index d19304adf..c8eb95f16 100644 --- a/docs/components_page/components/index/simple.R +++ b/docs/components_page/components/index/simple.R @@ -1,10 +1,23 @@ +# 1. Import Dash +library(dash) library(dashBootstrapComponents) -library(dashHtmlComponents) -layout <- dbcAlert( - paste( - "This is an example of a component being used in the wild.", - "Below me, you can find the code used to create me." +# 2. Create a Dash app instance +app <- Dash$new(external_stylesheets = dbcThemes$BOOTSTRAP) + +# 3. Add the example to the app's layout +# First we copy the snippet from the docs +badge <- dbcButton( + list( + "Notifications", + dbcBadge("4", color = "light", text_color = "primary", className = "ms-1") ), - color = "info" + color = "primary" ) + +# Then we incorporate the snippet into our layout. +# This example keeps it simple and just wraps it in a Container +app$layout(dbcContainer(badge, fluid = TRUE)) + +# 5. Start the Dash server +app$run_server(port = 8050) diff --git a/docs/components_page/components/index/simple.jl b/docs/components_page/components/index/simple.jl index cce1ef80d..77cda2d2d 100644 --- a/docs/components_page/components/index/simple.jl +++ b/docs/components_page/components/index/simple.jl @@ -1,7 +1,22 @@ -using DashBootstrapComponents, DashHtmlComponents +# 1. Import Dash +using Dash, DashBootstrapComponents -layout = dbc_alert( - "This is an example of a component being used in the wild. " * - "Below me, you can find the code used to create me.", - color = "info", +# 2. Create a Dash app instance +app = dash(external_stylesheets = [dbc_themes.BOOTSTRAP]) + +# 3. Add the example to the app's layout +# First we copy the snippet from the docs +badge = dbc_button( + [ + "Notifications", + dbc_badge("4", color = "light", text_color = "primary", className = "ms-1"), + ], + color = "primary", ) + +# Then we incorporate the snippet into our layout. +# This example keeps it simple and just wraps it in a Container +app.layout = dbc_container(badge, fluid = true) + +# 5. Start the Dash server +run_server(app, "0.0.0.0", 8050) diff --git a/docs/components_page/components/index/simple.py b/docs/components_page/components/index/simple.py index ba872b27c..c2195dd05 100644 --- a/docs/components_page/components/index/simple.py +++ b/docs/components_page/components/index/simple.py @@ -1,7 +1,24 @@ +# 1. Import Dash +import dash import dash_bootstrap_components as dbc -layout = dbc.Alert( - "This is an example of a component being used in the wild. " - "Below me, you can find the code used to create me.", - color="info", +# 2. Create a Dash app instance +app = dash.Dash(external_stylesheets=[dbc.themes.BOOTSTRAP]) + +# 3. Add the example to the app's layout +# First we copy the snippet from the docs +badge = dbc.Button( + [ + "Notifications", + dbc.Badge("4", color="light", text_color="primary", className="ms-1"), + ], + color="primary", ) + +# Then we incorporate the snippet into our layout. +# This example keeps it simple and just wraps it in a Container +app.layout = dbc.Container(badge, fluid=True) + +# 5. Start the Dash server +if __name__ == "__main__": + app.run_server() diff --git a/docs/components_page/components/layout.md b/docs/components_page/components/layout.md index fcbb7f8b1..c4b361e8b 100644 --- a/docs/components_page/components/layout.md +++ b/docs/components_page/components/layout.md @@ -82,7 +82,7 @@ You can also control horizontal alignment of columns using the `justify` keyword Sometimes you may wish to use Bootstrap's grid system for specifying the layout of your app, but you don't want the changes Bootstrap makes to the typography, or to load all the additional CSS classes that Bootstrap specifies. In such a situation, you can link only the CSS required for the grid system using the `themes` module. -{{code-example:components/layout/grid_only.py:python}} +{{code-example:components/layout/grid_only.py}} Alternatively download `bootstrap-grid.css` from the [Bootstrap website](https://getbootstrap.com/docs/4.2/getting-started/download/) and place it in your app's `assets/` directory. See the [Plotly Dash documentation](https://dash.plot.ly/external-resources) for details. diff --git a/docs/components_page/helpers.py b/docs/components_page/helpers.py index 4241bf025..b67ace311 100644 --- a/docs/components_page/helpers.py +++ b/docs/components_page/helpers.py @@ -2,7 +2,7 @@ from dash import dcc, html -def HighlightedSource(py_source, r_source, jl_source): +def HighlightedSource(py_source, r_source, jl_source, className="px-3"): return dbc.Tabs( [ dbc.Tab( @@ -17,7 +17,7 @@ def HighlightedSource(py_source, r_source, jl_source): ] if source is not None ], - className="px-3", + className=className, ) diff --git a/docs/components_page/markdown_parser.py b/docs/components_page/markdown_parser.py index c2dddb24d..c7036a740 100644 --- a/docs/components_page/markdown_parser.py +++ b/docs/components_page/markdown_parser.py @@ -5,7 +5,11 @@ import markdown from dash import dcc, html -from .helpers import ExampleContainer, load_source_with_environment +from .helpers import ( + ExampleContainer, + HighlightedSource, + load_source_with_environment, +) __all__ = ["parse"] @@ -91,12 +95,17 @@ def _safe_load_source(source_path, ext): return None -def _parse_code_example(data): - source_path, language = data.split(":") - source = (HERE / source_path).read_text().strip() +def _parse_code_example(filename): + source_path = HERE / filename + py_source = (HERE / source_path).read_text().strip() + r_source = _safe_load_source(source_path, "R") + jl_source = _safe_load_source(source_path, "jl") + return html.Div( - dcc.Markdown(f"```{language}\n{source}\n```"), - className="source-container", + HighlightedSource( + py_source, r_source, jl_source, className="pb-0 card-header" + ), + className="border source-container rounded", )