diff --git a/CHANGELOG.md b/CHANGELOG.md index a538844..fcaad35 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ All notable changes to this project will be documented in this file. +## [1.0.13] - 05-03-24 + +### Added + +- Add new `pages` module, which introduces the `page components` and `page properties` concepts +- Add new `validate` module, which adds an `assert_no_random_ids` that assets that Dash didn't generate any random component ids ## [1.0.12] - 04-02-23 diff --git a/dash_extensions/pages.py b/dash_extensions/pages.py index 61370d7..6407054 100644 --- a/dash_extensions/pages.py +++ b/dash_extensions/pages.py @@ -1,7 +1,8 @@ +import json import dash from collections import OrderedDict -from typing import Optional -from dash import html, Input, Output, clientside_callback +from typing import Optional, Any +from dash import html, Input, Output, State, clientside_callback, page_container from dash.development.base_component import Component """ @@ -9,23 +10,30 @@ """ _ID_CONTENT = "_component_content" -_PATH_REGISTRY = OrderedDict() -_CONTAINER_REGISTRY = {} -_COMPONENT_CONTAINER = html.Div(id=_ID_CONTENT, disable_n_clicks=True) +_COMPONENT_PATH_REGISTRY: dict[Component, list[str]] = OrderedDict() +_PROP_PATH_REGISTRY: dict[Component, dict[str, list[str]]] = OrderedDict() +_CONTAINER_REGISTRY: dict[Component, Component] = {} +_COMPONENT_CONTAINER = html.Div(id=_ID_CONTENT, disable_n_clicks=True, style=dict(display="contents")) # region Monkey patch page registration function _original_register_page = dash.register_page -def _register_page(*args, dynamic_components=None, **kwargs): +def _register_page(*args, page_components=None, page_properties=None, **kwargs): _original_register_page(*args, **kwargs) - if dynamic_components is None: - return + # Resolve page. module = kwargs['module'] if 'module' in kwargs else args[0] page = dash.page_registry[module] - for component in dynamic_components: - set_visible(component, page['path']) + # Register callbacks for page props. + if page_properties is not None: + for component in page_properties: + _set_props(component, page['path'], page_properties[component]) + # Resolve any page components. + if page_components is None: + return + for component in page_components: + _set_visible(component, page['path']) dash.register_page = _register_page @@ -35,11 +43,33 @@ def _register_page(*args, dynamic_components=None, **kwargs): # region Public interface +def set_page_container_style_display_contents(): + """ + Changes the style of the page container (and the page content container) so that their children are rendered + as if they were children of the page container's parent (see https://caniuse.com/css-display-contents). This is + an advantage if you are using css grid, as it makes it possible to mix the page components with other components. + """ + page_container.style = dict(display="contents") + for child in page_container.children: + if child.id == "_pages_content": + child.style = dict(display="contents") + + +def set_default_container(container: Component): + """ + Per default, page components are rendered into the '_COMPONENT_CONTAINER' declared above. + Use this function to change the default container. + :param container: the container into which page components will be rendered by default + :return: None + """ + _COMPONENT_CONTAINER = container + + def assign_container(component: Component, container: Component): """ - By default, dynamic components are rendered into the '_COMPONENT_CONTAINER' declared above. Call this function to + By default, page components are rendered into the '_COMPONENT_CONTAINER' declared above. Call this function to specify that the component should be rendered in a different container. - :param component: the (dynamic) component in question + :param component: the (page) component in question :param container: the container into which the component will be rendered :return: None """ @@ -48,21 +78,33 @@ def assign_container(component: Component, container: Component): _CONTAINER_REGISTRY[component] = container -def set_visible(component: Component, path: str): +def _set_visible(component: Component, path: str): """ Register path(s) for which a component should be visible. - :param component: the (dynamic) component in question + :param component: the (page) component in question :param path: the (url) path for which the component should be visible :return: None """ - _PATH_REGISTRY.setdefault(component, []).append(path) + _COMPONENT_PATH_REGISTRY.setdefault(component, []).append(path) + + +def _set_props(component: Component, path: str, prop_map: dict[str, Any]): + """ + Register path(s) for which a particular props should be set. + :param component: the (page) component in question + :param path: the (url) path for which the props should be set + :param prop_map: the props, i.e. (prop name, prop value) pairs + :return: None + """ + for prop in prop_map: + _PROP_PATH_REGISTRY.setdefault(component, OrderedDict()).setdefault(prop, {})[path] = prop_map[prop] -def setup_dynamic_components() -> html.Div: +def setup_page_components() -> html.Div: """ - Initializes the dynamic components and returns the (default) container into which the components are rendered. - :return: the default container, into which dynamic components are rendered. Should be included in the layout, - unless all (dynamic) components are assigned to custom containers (via 'assign_container') + Initializes the page components and returns the (default) container into which the components are rendered. + :return: the default container, into which page components are rendered. Must be included in the layout, + unless all (page) components are assigned to custom containers (via 'assign_container') """ _setup_callbacks() return _COMPONENT_CONTAINER @@ -85,17 +127,44 @@ def _prepare_container(container: Optional[Component] = None): def _setup_callbacks(): store = dash.dash._ID_STORE location = dash.dash._ID_LOCATION - components = list(_PATH_REGISTRY.keys()) + # Setup callbacks for page components. + components = list(_COMPONENT_PATH_REGISTRY.keys()) for component in components: - # Wrap in div to ensure 'hidden' prop exists. - wrapper = html.Div(component, disable_n_clicks=True, hidden=True) + # Wrap in div container, so we can hide it. + cid = component._set_random_id() + wrapper = html.Div(component, disable_n_clicks=True, style=dict(display="none"), id=f"{cid}_wrapper") # Add to container. container = _prepare_container(_CONTAINER_REGISTRY.get(component, _COMPONENT_CONTAINER)) container.children.append(wrapper) # Setup callback. - f = f"function(y, x){{const paths = {_PATH_REGISTRY[component]}; return !paths.includes(x);}}" - clientside_callback(f, Output(wrapper, "hidden"), + f = f"""function(y, x){{ + const paths = {_COMPONENT_PATH_REGISTRY[component]}; + if(paths.includes(x)){{ + return {{display: "contents"}}; + }} + return {{display: "none"}}; + }}""" + clientside_callback(f, Output(wrapper, "style", allow_duplicate=True), Input(store, "data"), - State(location, "pathname")) + State(location, "pathname"), + prevent_initial_call='initial_duplicate') + # Setup callbacks for page props. + components = list(_PROP_PATH_REGISTRY.keys()) + for component in components: + for prop in _PROP_PATH_REGISTRY[component]: + path_map = _PROP_PATH_REGISTRY[component][prop] + default = getattr(component, prop, None) + # Setup callback. + f = f"""function(y, x){{ + const path_map = JSON.parse(\'{json.dumps(path_map)}\'); + if (x in path_map){{ + return path_map[x]; + }} + return JSON.parse(\'{json.dumps(default)}\'); + }}""" + clientside_callback(f, Output(component, prop, allow_duplicate=True), + Input(store, "data"), + State(location, "pathname"), + prevent_initial_call='initial_duplicate') # endregion diff --git a/package-lock.json b/package-lock.json index 17eb199..ef6a443 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "dash-extensions", - "version": "1.0.12", + "version": "1.0.13", "lockfileVersion": 3, "requires": true, "packages": { diff --git a/package.json b/package.json index c99a183..c5e92bd 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "dash-extensions", - "version": "1.0.12", + "version": "1.0.13", "description": "Extensions for Plotly Dash.", "main": "build/index.js", "scripts": { diff --git a/pyproject.toml b/pyproject.toml index 78f7961..b8e3525 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "dash-extensions" -version = "1.0.12" +version = "1.0.13" description = "Extensions for Plotly Dash." authors = ["emher "] license = "MIT"