diff --git a/docs/source/_custom_js/package-lock.json b/docs/source/_custom_js/package-lock.json index ee2c660bf..58de595e2 100644 --- a/docs/source/_custom_js/package-lock.json +++ b/docs/source/_custom_js/package-lock.json @@ -19,7 +19,7 @@ } }, "../../../src/client/packages/idom-client-react": { - "version": "0.43.0", + "version": "0.44.0", "integrity": "sha512-pIK5eNwFSHKXg7ClpASWFVKyZDYxz59MSFpVaX/OqJFkrJaAxBuhKGXNTMXmuyWOL5Iyvb/ErwwDRxQRzMNkfQ==", "license": "MIT", "dependencies": { diff --git a/docs/source/about/changelog.rst b/docs/source/about/changelog.rst index 4400e9483..3adac87a4 100644 --- a/docs/source/about/changelog.rst +++ b/docs/source/about/changelog.rst @@ -23,7 +23,46 @@ more info, see the :ref:`Contributor Guide `. Unreleased ---------- -No changes. +**Changed** + +- :pull:`841` - Revamped element constructor interface. Now instead of passing a + dictionary of attributes to element constructors, attributes are declared using + keyword arguments. For example, instead of writing: + + .. code-block:: + + html.div({"className": "some-class"}, "some", "text") + + You now should write: + + .. code-block:: + + html.div("some", "text", class_name="some-class") + + .. note:: + + All attributes are written using ``snake_case``. + + In conjunction, with these changes, IDOM now supplies a command line utility that + makes a "best effort" attempt to automatically convert code to the new API. Usage of + this utility is as follows: + + .. code-block:: bash + + idom update-html-usages [PATHS] + + Where ``[PATHS]`` is any number of directories or files that should be rewritten. + + .. warning:: + + After running this utility, code comments and formatting may have been altered. It's + recommended that you run a code formatting tool like `Black + `__ and manually review and replace any comments that + may have been moved. + +**Fixed** + +- :issue:`755` - unification of component and VDOM constructor interfaces. See above. v0.44.0 diff --git a/docs/source/guides/creating-interfaces/html-with-idom/index.rst b/docs/source/guides/creating-interfaces/html-with-idom/index.rst index 0afb4116d..c3a5c16cc 100644 --- a/docs/source/guides/creating-interfaces/html-with-idom/index.rst +++ b/docs/source/guides/creating-interfaces/html-with-idom/index.rst @@ -71,7 +71,7 @@ Adding HTML Attributes ---------------------- That's all well and good, but there's more to HTML than just text. What if we wanted to -display an image? In HTMl we'd use the `` element and add attributes to it order +display an image? In HTMl we'd use the ```` element and add attributes to it order to specify a URL to its ``src`` and use some ``style`` to modify and position it: .. code-block:: html @@ -80,23 +80,27 @@ to specify a URL to its ``src`` and use some ``style`` to modify and position it src="https://picsum.photos/id/237/500/300" style="width: 50%; margin-left: 25%;" alt="Billie Holiday" + tabindex="0" /> -In IDOM we add these attributes to elements using dictionaries. There are some notable -differences though. The biggest being the fact that all names in IDOM use ``camelCase`` -instead of dash-separated words. For example, ``margin-left`` becomes ``marginLeft``. -Additionally, instead of specifying ``style`` using a string, we use a dictionary: +In IDOM we add these attributes to elements using keyword arguments. There are two main +notable differences though. First, all names in IDOM use ``snake_case`` instead of +dash-separated words. For example, ``tabindex`` and ``margin-left`` become ``tab_index`` +and ``margin_left`` respectively. Second, instead of specifying ``style`` using a +string, we use a dictionary. Given this, you can rewrite the ```` element above as: .. testcode:: html.img( src="https://picsum.photos/id/237/500/300", - style={"width": "50%", "marginLeft": "25%"}, + style={"width": "50%", "margin_left": "25%"}, alt="Billie Holiday", + tab_index="0", ) .. raw:: html + response.HTTPResponse: return response.html(index_html) - spa_blueprint.add_route(single_page_app_files, "/") - spa_blueprint.add_route(single_page_app_files, "/<_:path>") + spa_blueprint.add_route( + single_page_app_files, + "/", + name="single_page_app_files_root", + ) + spa_blueprint.add_route( + single_page_app_files, + "/<_:path>", + name="single_page_app_files_path", + ) async def asset_files( request: request.Request, @@ -185,8 +193,16 @@ async def model_stream( recv, ) - api_blueprint.add_websocket_route(model_stream, f"/{STREAM_PATH.name}") - api_blueprint.add_websocket_route(model_stream, f"/{STREAM_PATH.name}//") + api_blueprint.add_websocket_route( + model_stream, + f"/{STREAM_PATH.name}", + name="model_stream_root", + ) + api_blueprint.add_websocket_route( + model_stream, + f"/{STREAM_PATH.name}//", + name="model_stream_path", + ) def _make_send_recv_callbacks(