Add docs for custom routers

Author: Archmonger

CHANGELOG.md

@@ -19,6 +19,10 @@ Don't forget to remove deprecated code on each major release!
 
 ## [Unreleased]
 
+### Added
+
+-   Support for custom routers.
+
 ### Changed
 
 -   Set maximum ReactPy version to `<2.0.0`.

docs/examples/python/custom_router_easy_resolver.py

@@ -0,0 +1,16 @@
+from reactpy_router.resolvers import ConversionInfo, ReactPyResolver
+
+
+# Create a custom resolver that uses the following pattern: "{name:type}"
+class CustomResolver(ReactPyResolver):
+    def __init__(
+        self,
+        route,
+        param_pattern=r"{(?P<name>\w+)(?P<type>:\w+)?}",  # Match parameters that use the "{name:type}" format
+        converters={  # Enable matching for the following types: int, str, any
+            "int": ConversionInfo(regex=r"\d+", func=int),
+            "str": ConversionInfo(regex=r"[^/]+", func=str),
+            "any": ConversionInfo(regex=r".*", func=str),
+        },
+    ) -> None:
+        super().__init__(route, param_pattern, converters)

docs/examples/python/custom_router_easy_router.py

@@ -0,0 +1,6 @@
+from example.resolvers import CustomResolver
+
+from reactpy_router.routers import create_router
+
+# This can be used in any location where `browser_router` was previously used
+custom_router = create_router(CustomResolver)

docs/examples/python/example/resolvers.py

@@ -0,0 +1,4 @@
+from reactpy_router.resolvers import ReactPyResolver
+
+
+class CustomResolver(ReactPyResolver): ...

docs/mkdocs.yml

@@ -6,7 +6,7 @@ nav:
       - Advanced Topics:
           - Routers, Routes, and Links: learn/routers-routes-and-links.md
           - Hooks: learn/hooks.md
-          - Creating a Custom Router 🚧: learn/custom-router.md
+          - Creating a Custom Router: learn/custom-router.md
   - Reference:
       - Routers: reference/routers.md
       - Components: reference/components.md

docs/src/learn/custom-router.md

@@ -1,3 +1,28 @@
-# Custom Router
+Custom routers can be used to define custom routing logic for your application. This is useful when you need to implement a custom routing algorithm or when you need to integrate with an existing URL routing system.
 
-Under construction 🚧
+---
+
+## Step 1: Creating a custom resolver
+
+You may want to create a custom resolver to allow ReactPy to utilize an existing routing syntax.
+
+To start off, you will need to create a subclass of `#!python ReactPyResolver`. Within this subclass, you have two attributes which you can modify to support your custom routing syntax:
+
+-   `#!python param_pattern`: A regular expression pattern that matches the parameters in your URL. This pattern must contain the regex named groups `name` and `type`.
+-   `#!python converters`: A dictionary that maps a `type` to it's respective `regex` pattern and a converter `func`.
+
+=== "resolver.py"
+
+    ```python
+    {% include "../../examples/python/custom_router_easy_resolver.py" %}
+    ```
+
+## Step 2: Creating a custom router
+
+Then, you can use this resolver to create your custom router...
+
+=== "resolver.py"
+
+    ```python
+    {% include "../../examples/python/custom_router_easy_router.py" %}
+    ```

src/reactpy_router/resolvers.py

@@ -20,7 +20,7 @@ class ReactPyResolver:
     def __init__(
         self,
         route: Route,
-        param_pattern=r"{(?P<name>\w+)(?P<type>:\w+)?}",
+        param_pattern: str = r"{(?P<name>\w+)(?P<type>:\w+)?}",
         converters: dict[str, ConversionInfo] | None = None,
     ) -> None:
         self.element = route.element