Allow using a custom JS module for advanced customisation (#726)

Author: Dreamsorcerer

admin-js/src/App.js

@@ -44,20 +44,33 @@ const DatagridSingle = (props) => (
 );
 
 // Create a mapping of components, so we can reference them by name later.
-const COMPONENTS = Object.freeze({
+const COMPONENTS = {
     Datagrid, DatagridSingle,
 
     BooleanField, DateField, NumberField, ReferenceField, ReferenceManyField,
     ReferenceOneField, SelectField, TextField,
 
     BooleanInput, DateInput, DateTimeInput, NumberInput, ReferenceInput, SelectInput,
     TextInput, TimeInput
-});
-const VALIDATORS = Object.freeze(
-    {email, maxLength, maxValue, minLength, minValue, regex, required});
+};
+const USER_FUNCS = {};
+const VALIDATORS = {email, maxLength, maxValue, minLength, minValue, regex, required};
 const _body = document.querySelector("body");
 const STATE = Object.freeze(JSON.parse(_body.dataset.state));
 
+let MODULE_LOADER;
+if (STATE["js_module"]) {
+    // The inline comment skips the webpack import() and allows us to use the native
+    // browser's import() function. Needed to dynamically import a module.
+    MODULE_LOADER = import(/* webpackIgnore: true */ STATE["js_module"]).then((mod) => {
+        Object.assign(COMPONENTS, mod.components);
+        Object.assign(VALIDATORS, mod.validators);
+        Object.assign(USER_FUNCS, mod.funcs);
+    });
+} else {
+    MODULE_LOADER = Promise.resolve();
+}
+
 /** Make an authenticated API request and return the response object. */
 function apiRequest(url, options) {
     const headers = new Headers({
@@ -386,4 +399,4 @@ const App = () => (
     </Admin>
 );
 
-export default App;
+export {App, MODULE_LOADER};

admin-js/src/index.js

@@ -1,10 +1,12 @@
 import React from "react";
 import ReactDOM from "react-dom/client";
-import App from "./App";
+import {App, MODULE_LOADER} from "./App";
 
 const root = ReactDOM.createRoot(document.getElementById("root"));
-root.render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
+MODULE_LOADER.then(() => {
+    root.render(
+        <React.StrictMode>
+            <App />
+        </React.StrictMode>
+    );
+});

aiohttp_admin/__init__.py

@@ -76,7 +76,7 @@ def value(r: web.RouteDef) -> tuple[str, str]:
     admin.on_startup.append(on_startup)
     admin["check_credentials"] = schema["security"]["check_credentials"]
     admin["identity_callback"] = schema["security"].get("identity_callback")
-    admin["state"] = {"view": schema.get("view", {})}
+    admin["state"] = {"view": schema.get("view", {}), "js_module": schema.get("js_module")}
 
     max_age = schema["security"].get("max_age")
     secure = schema["security"].get("secure", True)

aiohttp_admin/routes.py

@@ -8,8 +8,6 @@
 from . import views
 from .types import Schema
 
-_VALIDATORS = ("email", "maxLength", "maxValue", "minLength", "minValue", "regex", "required")
-
 
 def setup_resources(admin: web.Application, schema: Schema) -> None:
     admin["resources"] = []
@@ -37,8 +35,6 @@ def setup_resources(admin: web.Application, schema: Schema) -> None:
         inputs = copy.deepcopy(m.inputs)
 
         for name, validators in r.get("validators", {}).items():
-            if not all(v[0] in _VALIDATORS for v in validators):
-                raise ValueError(f"First value in validators must be one of {_VALIDATORS}")
             inputs[name] = inputs[name].copy()
             inputs[name]["validators"] = tuple(inputs[name]["validators"]) + tuple(validators)
 

aiohttp_admin/types.py

@@ -84,6 +84,7 @@ class Resource(_Resource):
 
 class _Schema(TypedDict, total=False):
     view: _ViewSchema
+    js_module: str
 
 
 class Schema(_Schema):
@@ -105,3 +106,4 @@ class State(TypedDict):
     resources: dict[str, _ResourceState]
     urls: dict[str, str]
     view: _ViewSchema
+    js_module: Optional[str]

examples/validators.py

@@ -11,6 +11,16 @@
 import aiohttp_admin
 from aiohttp_admin.backends.sqlalchemy import SAResource
 
+JS = """
+const odd = () => (value, allValues) => {
+    if (value % 2 === 0)
+        return "Votes must be an odd number";
+    return undefined;
+};
+
+export const validators = {odd};
+"""
+
 
 class Base(DeclarativeBase):
     """Base model."""
@@ -26,13 +36,18 @@ class User(Base):
     votes: Mapped[int] = mapped_column()
 
     __table_args__ = (sa.CheckConstraint(sa.func.char_length(username) >= 3),
-                      sa.CheckConstraint(votes >= 1), sa.CheckConstraint(votes < 5))
+                      sa.CheckConstraint(votes >= 1), sa.CheckConstraint(votes < 6),
+                      sa.CheckConstraint(votes % 2 == 1))
 
 
 async def check_credentials(username: str, password: str) -> bool:
     return username == "admin" and password == "admin"
 
 
+async def serve_js(request: web.Request) -> web.Response:
+    return web.Response(text=JS, content_type="text/javascript")
+
+
 async def create_app() -> web.Application:
     engine = create_async_engine("sqlite+aiosqlite:///:memory:")
     session = async_sessionmaker(engine, expire_on_commit=False)
@@ -41,10 +56,11 @@ async def create_app() -> web.Application:
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
     async with session.begin() as sess:
-        sess.add(User(username="Foo", votes=4))
+        sess.add(User(username="Foo", votes=5))
         sess.add(User(username="Spam", votes=1, note="Second user"))
 
     app = web.Application()
+    app.router.add_get("/js", serve_js, name="js")
 
     # This is the setup required for aiohttp-admin.
     schema: aiohttp_admin.Schema = {
@@ -54,7 +70,12 @@ async def create_app() -> web.Application:
         },
         "resources": ({"model": SAResource(engine, User),
                        "validators": {User.username.name: (("regex", r"^[A-Z][a-z]+$"),),
-                                      User.email.name: (("email",),)}},)
+                                      User.email.name: (("email",),),
+                                      # Custom validator from our JS module.
+                                      # Min/Max validators are automatically included.
+                                      User.votes.name: (("odd",),)}},),
+        # Use our JS module to include our custom validator.
+        "js_module": str(app.router["js"].url_for())
     }
     aiohttp_admin.setup(app, schema)
 

tests/test_admin.py

@@ -19,6 +19,24 @@ def test_path() -> None:
     assert str(admin.router["index"].url_for()) == "/another/admin"
 
 
+def test_js_module() -> None:
+    app = web.Application()
+    schema: aiohttp_admin.Schema = {"security": {"check_credentials": check_credentials},
+                                    "resources": (), "js_module": "/custom_js.js"}
+    admin = aiohttp_admin.setup(app, schema)
+
+    assert admin["state"]["js_module"] == "/custom_js.js"
+
+
+def test_no_js_module() -> None:
+    app = web.Application()
+    schema: aiohttp_admin.Schema = {"security": {"check_credentials": check_credentials},
+                                    "resources": ()}
+    admin = aiohttp_admin.setup(app, schema)
+
+    assert admin["state"]["js_module"] is None
+
+
 def test_validators() -> None:
     dummy = DummyResource(
         "dummy", {"id": {"type": "NumberField", "props": {}}},
@@ -34,12 +52,6 @@ def test_validators() -> None:
     assert validators == (("required",), ("minValue", "3"))
     assert ("minValue", "3") not in dummy.inputs["id"]["validators"]
 
-    # Invalid validator
-    schema = {"security": {"check_credentials": check_credentials},
-              "resources": ({"model": dummy, "validators": {"id": (("bad", 3),)}},)}
-    with pytest.raises(ValueError, match="validators must be one of"):
-        aiohttp_admin.setup(app, schema)
-
 
 def test_re() -> None:
     test_re = DummyResource("testre", {"id": {"type": "NumberField", "props": {}},