c2cgeoportal-admin 2.5.0.100__py3-none-any.whl → 2.9rc44__py3-none-any.whl

c2cgeoportal_admin/views/themes.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-
-# Copyright (c) 2017-2020, Camptocamp SA
+# Copyright (c) 2017-2024, Camptocamp SA
 # All rights reserved.
 
 # Redistribution and use in source and binary forms, with or without
@@ -29,9 +27,18 @@
 
 
 from functools import partial
+from typing import cast
 
+import sqlalchemy
 from c2cgeoform.schema import GeoFormSchemaNode
-from c2cgeoform.views.abstract_views import ListField
+from c2cgeoform.views.abstract_views import (
+    DeleteResponse,
+    GridResponse,
+    IndexResponse,
+    ListField,
+    ObjectResponse,
+    SaveResponse,
+)
 from deform.widget import FormWidget
 from pyramid.view import view_config, view_defaults
 from sqlalchemy.orm import subqueryload
@@ -39,7 +46,7 @@ from sqlalchemy.sql.functions import concat
 
 from c2cgeoportal_admin.schemas.functionalities import functionalities_schema_node
 from c2cgeoportal_admin.schemas.interfaces import interfaces_schema_node
-from c2cgeoportal_admin.schemas.metadata import metadatas_schema_node
+from c2cgeoportal_admin.schemas.metadata import metadata_schema_node
 from c2cgeoportal_admin.schemas.roles import roles_schema_node
 from c2cgeoportal_admin.schemas.treegroup import children_schema_node
 from c2cgeoportal_admin.views.treeitems import TreeItemViews
@@ -49,18 +56,19 @@ _list_field = partial(ListField, Theme)
 
 base_schema = GeoFormSchemaNode(Theme, widget=FormWidget(fields_template="theme_fields"))
 base_schema.add(children_schema_node(only_groups=True))
-base_schema.add(functionalities_schema_node.clone())
-base_schema.add(roles_schema_node("restricted_roles"))
-base_schema.add(interfaces_schema_node.clone())
-base_schema.add(metadatas_schema_node.clone())
+base_schema.add(functionalities_schema_node(Theme.functionalities, Theme))
+base_schema.add(roles_schema_node(Theme.restricted_roles))
+base_schema.add(interfaces_schema_node(Theme.interfaces))
+base_schema.add(metadata_schema_node(Theme.metadatas, Theme))
 base_schema.add_unique_validator(Theme.name, Theme.id)
 
 
 @view_defaults(match_param="table=themes")
-class ThemeViews(TreeItemViews):
+class ThemeViews(TreeItemViews[Theme]):
+    """The theme administration view."""
 
     _list_fields = (
-        TreeItemViews._list_fields
+        TreeItemViews._list_fields  # type: ignore[misc] # pylint: disable=protected-access
         + [
             _list_field("ordering"),
             _list_field("public"),
@@ -69,8 +77,8 @@ class ThemeViews(TreeItemViews):
                 "functionalities",
                 renderer=lambda themes: ", ".join(
                     [
-                        "{}={}".format(f.name, f.value)
-                        for f in sorted(themes.functionalities, key=lambda f: f.name)
+                        f"{f.name}={f.value}"
+                        for f in sorted(themes.functionalities, key=lambda f: cast(str, f.name))
                     ]
                 ),
                 filter_column=concat(Functionality.name, "=", Functionality.value),
@@ -83,52 +91,56 @@ class ThemeViews(TreeItemViews):
             _list_field(
                 "interfaces",
                 renderer=lambda themes: ", ".join(
-                    [i.name or "" for i in sorted(themes.interfaces, key=lambda i: i.name)]
+                    [i.name or "" for i in sorted(themes.interfaces, key=lambda i: cast(str, i.name))]
                 ),
                 filter_column=Interface.name,
             ),
         ]
-        + TreeItemViews._extra_list_fields_no_parents
+        + TreeItemViews._extra_list_fields_no_parents  # pylint: disable=protected-access
     )
 
     _id_field = "id"
     _model = Theme
     _base_schema = base_schema
 
-    def _base_query(self, query=None):
-        return super()._base_query(
+    def _base_query(self) -> sqlalchemy.orm.query.Query[Theme]:
+        return super()._sub_query(
             self._request.dbsession.query(Theme)
             .distinct()
-            .outerjoin("interfaces")
-            .outerjoin("restricted_roles")
-            .outerjoin("functionalities")
-            .options(subqueryload("functionalities"))
-            .options(subqueryload("restricted_roles"))
-            .options(subqueryload("interfaces"))
+            .outerjoin(Theme.interfaces)
+            .outerjoin(Theme.restricted_roles)
+            .outerjoin(Theme.functionalities)
+            .options(subqueryload(Theme.functionalities))
+            .options(subqueryload(Theme.restricted_roles))
+            .options(subqueryload(Theme.interfaces))
         )
 
-    @view_config(route_name="c2cgeoform_index", renderer="../templates/index.jinja2")
-    def index(self):
+    def _sub_query(self, query: sqlalchemy.orm.query.Query[Theme]) -> sqlalchemy.orm.query.Query[Theme]:
+        del query
+        return self._base_query()
+
+    @view_config(route_name="c2cgeoform_index", renderer="../templates/index.jinja2")  # type: ignore[misc]
+    def index(self) -> IndexResponse:
         return super().index()
 
-    @view_config(route_name="c2cgeoform_grid", renderer="fast_json")
-    def grid(self):
+    @view_config(route_name="c2cgeoform_grid", renderer="fast_json")  # type: ignore[misc]
+    def grid(self) -> GridResponse:
         return super().grid()
 
-    @view_config(route_name="c2cgeoform_item", request_method="GET", renderer="../templates/edit.jinja2")
-    def view(self):
+    @view_config(route_name="c2cgeoform_item", request_method="GET", renderer="../templates/edit.jinja2")  # type: ignore[misc]
+    def view(self) -> ObjectResponse:
         return super().edit()
 
-    @view_config(route_name="c2cgeoform_item", request_method="POST", renderer="../templates/edit.jinja2")
-    def save(self):
+    @view_config(route_name="c2cgeoform_item", request_method="POST", renderer="../templates/edit.jinja2")  # type: ignore[misc]
+    def save(self) -> SaveResponse:
         return super().save()
 
-    @view_config(route_name="c2cgeoform_item", request_method="DELETE", renderer="fast_json")
-    def delete(self):
+    @view_config(route_name="c2cgeoform_item", request_method="DELETE", renderer="fast_json")  # type: ignore[misc]
+    def delete(self) -> DeleteResponse:
         return super().delete()
 
-    @view_config(
+    @view_config(  # type: ignore[misc]
         route_name="c2cgeoform_item_duplicate", request_method="GET", renderer="../templates/edit.jinja2"
     )
-    def duplicate(self):
+    def duplicate(self) -> ObjectResponse:
         return super().duplicate()

c2cgeoportal_admin/views/themes_ordering.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-
-# Copyright (c) 2017-2020, Camptocamp SA
+# Copyright (c) 2017-2024, Camptocamp SA
 # All rights reserved.
 
 # Redistribution and use in source and binary forms, with or without
@@ -28,20 +26,22 @@
 # either expressed or implied, of the FreeBSD Project.
 
 
-from c2cgeoform.schema import GeoFormSchemaNode
-from c2cgeoform.views.abstract_views import AbstractViews
 import colander
+from c2cgeoform.schema import GeoFormSchemaNode
+from c2cgeoform.views.abstract_views import AbstractViews, ObjectResponse, SaveResponse
 from deform import ValidationFailure
 from pyramid.httpexceptions import HTTPFound
 from pyramid.view import view_config
-from sqlalchemy.sql.expression import literal_column
 
 from c2cgeoportal_admin import _
-from c2cgeoportal_admin.widgets import ChildrenWidget, ThemeOrderWidget
-from c2cgeoportal_commons.models.main import Theme
+from c2cgeoportal_admin.schemas.treegroup import treeitem_edit_url
+from c2cgeoportal_admin.widgets import ChildrenWidget, ChildWidget
+from c2cgeoportal_commons.models.main import Theme, TreeItem
 
 
 class ThemeOrderSchema(GeoFormSchemaNode):  # pylint: disable=abstract-method
+    """The theme order schema."""
+
     def objectify(self, dict_, context=None):
         context = self.dbsession.query(Theme).get(dict_["id"])
         context = super().objectify(dict_, context)
@@ -49,52 +49,72 @@ class ThemeOrderSchema(GeoFormSchemaNode):  # pylint: disable=abstract-method
 
 
 @colander.deferred
-def treeitems(node, kw):  # pylint: disable=unused-argument
-    return kw["dbsession"].query(Theme, literal_column("0")).order_by(Theme.ordering, Theme.name)
+def themes(node, kw):  # pylint: disable=unused-argument
+    """Get some theme metadata."""
+    query = kw["dbsession"].query(Theme).order_by(Theme.ordering, Theme.name)
+    return [
+        {"id": item.id, "label": item.name, "icon_class": f"icon-{item.item_type}", "group": "All"}
+        for item in query
+    ]
 
 
 def themes_validator(node, cstruct):
+    """Validate the theme."""
     for dict_ in cstruct:
-        if not dict_["id"] in [item.id for item, dummy in node.treeitems]:
+        if not dict_["id"] in [item["id"] for item in node.candidates]:
             raise colander.Invalid(
                 node,
-                _("Value {} does not exist in table {}").format(dict_["treeitem_id"], Theme.__tablename__),
+                _("Value {} does not exist in table {}").format(dict_["id"], Theme.__tablename__),
             )
 
 
-class ThemesOrderingSchema(colander.MappingSchema):
+class ThemesOrderingSchema(colander.MappingSchema):  # type: ignore[misc]
+    """The theme ordering schema."""
+
     themes = colander.SequenceSchema(
-        ThemeOrderSchema(Theme, includes=["id", "ordering"], name="theme", widget=ThemeOrderWidget()),
+        ThemeOrderSchema(
+            Theme,
+            includes=["id", "ordering"],
+            name="theme",
+            widget=ChildWidget(
+                input_name="id",
+                model=TreeItem,
+                label_field="name",
+                icon_class=lambda item: f"icon-{item.item_type}",
+                edit_url=treeitem_edit_url,
+            ),
+        ),
         name="themes",
-        treeitems=treeitems,
+        candidates=themes,
         validator=themes_validator,
-        widget=ChildrenWidget(add_subitem=False, category="structural"),
+        widget=ChildrenWidget(child_input_name="id", add_subitem=False, orderable=True),
     )
 
 
-class ThemesOrdering(AbstractViews):
+class ThemesOrdering(AbstractViews[ThemesOrderingSchema]):
+    """The theme ordering admin view."""
 
     _base_schema = ThemesOrderingSchema()
 
-    @view_config(route_name="layertree_ordering", request_method="GET", renderer="../templates/edit.jinja2")
-    def view(self):
+    @view_config(route_name="layertree_ordering", request_method="GET", renderer="../templates/edit.jinja2")  # type: ignore[misc]
+    def view(self) -> ObjectResponse:
         form = self._form()
         dict_ = {
             "themes": [
                 form.schema["themes"].children[0].dictify(theme)
-                for theme, dummy in form.schema["themes"].treeitems
+                for theme in self._request.dbsession.query(Theme).order_by(Theme.ordering)
             ]
         }
         return {
             "title": form.title,
             "form": form,
-            "form_render_args": (dict_,),
+            "form_render_args": [dict_],
             "form_render_kwargs": {"request": self._request, "actions": []},
             "deform_dependencies": form.get_widget_resources(),
         }
 
-    @view_config(route_name="layertree_ordering", request_method="POST", renderer="../templates/edit.jinja2")
-    def save(self):
+    @view_config(route_name="layertree_ordering", request_method="POST", renderer="../templates/edit.jinja2")  # type: ignore[misc]
+    def save(self) -> SaveResponse:
         try:
             form = self._form()
             form_data = self._request.POST.items()
@@ -111,7 +131,7 @@ class ThemesOrdering(AbstractViews):
             return {
                 "title": form.title,
                 "form": e,
-                "form_render_args": tuple(),
+                "form_render_args": [],
                 "form_render_kwargs": {"request": self._request, "actions": []},
                 "deform_dependencies": form.get_widget_resources(),
             }

c2cgeoportal_admin/views/treeitems.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-
-# Copyright (c) 2017-2020, Camptocamp SA
+# Copyright (c) 2017-2024, Camptocamp SA
 # All rights reserved.
 
 # Redistribution and use in source and binary forms, with or without
@@ -29,18 +27,26 @@
 
 
 from functools import partial
+from typing import Generic, TypeVar
 
-from c2cgeoform.views.abstract_views import AbstractViews, ListField
+import sqlalchemy
+from c2cgeoform.views.abstract_views import ListField, SaveResponse
 from pyramid.view import view_config
 from sqlalchemy.orm import subqueryload
 from sqlalchemy.sql.functions import concat
 
+from c2cgeoportal_admin.views.logged_views import LoggedViews
 from c2cgeoportal_commons.models.main import LayergroupTreeitem, Metadata, TreeGroup, TreeItem
 
 _list_field = partial(ListField, TreeItem)
 
 
-class TreeItemViews(AbstractViews):
+_T = TypeVar("_T", bound=TreeItem)
+
+
+class TreeItemViews(LoggedViews[_T], Generic[_T]):
+    """The admin tree item view."""
+
     _list_fields = [
         _list_field("id"),
         _list_field("name"),
@@ -50,9 +56,7 @@ class TreeItemViews(AbstractViews):
     _extra_list_fields_no_parents = [
         _list_field(
             "metadatas",
-            renderer=lambda layers_group: ", ".join(
-                ["{}: {}".format(m.name, m.value) or "" for m in layers_group.metadatas]
-            ),
+            renderer=lambda treeitem: ", ".join([f"{m.name}: {m.value}" or "" for m in treeitem.metadatas]),
             filter_column=concat(Metadata.name, ": ", Metadata.value).label("metadata"),
         )
     ]
@@ -68,22 +72,22 @@ class TreeItemViews(AbstractViews):
         )
     ] + _extra_list_fields_no_parents
 
-    @view_config(route_name="c2cgeoform_item", request_method="POST", renderer="../templates/edit.jinja2")
-    def save(self):
+    @view_config(route_name="c2cgeoform_item", request_method="POST", renderer="../templates/edit.jinja2")  # type: ignore[misc]
+    def save(self) -> SaveResponse:
         response = super().save()
         # correctly handles the validation error as if there is a validation error, cstruct is empty
-        has_to_be_registred_in_parent = (
+        has_to_be_registered_in_parent = (
             hasattr(self, "_appstruct") and self._appstruct is not None and self._appstruct.get("parent_id")
         )
-        if has_to_be_registred_in_parent:
-            parent = self._request.dbsession.query(TreeGroup).get(has_to_be_registred_in_parent)
+        if has_to_be_registered_in_parent:
+            parent = self._request.dbsession.query(TreeGroup).get(has_to_be_registered_in_parent)
             rel = LayergroupTreeitem(parent, self._obj, 100)
             self._request.dbsession.add(rel)
         return response
 
-    def _base_query(self, query):  # pylint: disable=arguments-differ
+    def _sub_query(self, query: sqlalchemy.orm.query.Query[TreeItem]) -> sqlalchemy.orm.query.Query[TreeItem]:
         return (
-            query.outerjoin("metadatas")
-            .options(subqueryload("parents_relation").joinedload("treegroup"))
-            .options(subqueryload("metadatas"))
+            query.outerjoin(TreeItem.metadatas)
+            .options(subqueryload(TreeItem.parents_relation).joinedload(LayergroupTreeitem.treegroup))
+            .options(subqueryload(TreeItem.metadatas))
         )

c2cgeoportal_admin/views/users.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-
-# Copyright (c) 2017-2020, Camptocamp SA
+# Copyright (c) 2017-2024, Camptocamp SA
 # All rights reserved.
 
 # Redistribution and use in source and binary forms, with or without
@@ -28,10 +26,18 @@
 # either expressed or implied, of the FreeBSD Project.
 
 
+import os
 from functools import partial
 
 from c2cgeoform.schema import GeoFormSchemaNode
-from c2cgeoform.views.abstract_views import AbstractViews, ListField
+from c2cgeoform.views.abstract_views import (
+    DeleteResponse,
+    GridResponse,
+    IndexResponse,
+    ListField,
+    ObjectResponse,
+    SaveResponse,
+)
 from deform.widget import FormWidget
 from passwordgenerator import pwgenerator
 from pyramid.httpexceptions import HTTPFound
@@ -39,28 +45,36 @@ from pyramid.view import view_config, view_defaults
 from sqlalchemy.orm import aliased, subqueryload
 
 from c2cgeoportal_admin.schemas.roles import roles_schema_node
+from c2cgeoportal_admin.views.logged_views import LoggedViews
 from c2cgeoportal_commons.lib.email_ import send_email_config
 from c2cgeoportal_commons.models.main import Role
-from c2cgeoportal_commons.models.static import User
+from c2cgeoportal_commons.models.static import Log, User
 
 _list_field = partial(ListField, User)
 
 base_schema = GeoFormSchemaNode(User, widget=FormWidget(fields_template="user_fields"))
-base_schema.add(roles_schema_node("roles"))
+base_schema.add(roles_schema_node(User.roles))
 base_schema.add_unique_validator(User.username, User.id)
 
 settings_role = aliased(Role)
 
+_OPENID_CONNECT_ENABLED = os.environ.get("OPENID_CONNECT_ENABLED", "false").lower() in ("true", "yes", "1")
+
 
 @view_defaults(match_param="table=users")
-class UserViews(AbstractViews):
+class UserViews(LoggedViews[User]):
+    """The admin user view."""
+
     _list_fields = [
         _list_field("id"),
-        _list_field("username"),
+        *([_list_field("username")] if not _OPENID_CONNECT_ENABLED else []),
+        _list_field("display_name"),
         _list_field("email"),
-        _list_field("last_login"),
-        _list_field("expire_on"),
-        _list_field("deactivated"),
+        *(
+            [_list_field("last_login"), _list_field("expire_on"), _list_field("deactivated")]
+            if not _OPENID_CONNECT_ENABLED
+            else []
+        ),
         _list_field(
             "settings_role",
             renderer=lambda user: user.settings_role.name if user.settings_role else "",
@@ -76,31 +90,33 @@ class UserViews(AbstractViews):
     _id_field = "id"
     _model = User
     _base_schema = base_schema
+    _log_model = Log
+    _name_field = "username"
 
     def _base_query(self):
         return (
             self._request.dbsession.query(User)
             .distinct()
             .outerjoin(settings_role, settings_role.id == User.settings_role_id)
-            .outerjoin("roles")
-            .options(subqueryload("settings_role"))
-            .options(subqueryload("roles"))
+            .outerjoin(User.roles)
+            .options(subqueryload(User.settings_role))
+            .options(subqueryload(User.roles))
         )
 
-    @view_config(route_name="c2cgeoform_index", renderer="../templates/index.jinja2")
-    def index(self):
+    @view_config(route_name="c2cgeoform_index", renderer="../templates/index.jinja2")  # type: ignore[misc]
+    def index(self) -> IndexResponse:
         return super().index()
 
-    @view_config(route_name="c2cgeoform_grid", renderer="fast_json")
-    def grid(self):
+    @view_config(route_name="c2cgeoform_grid", renderer="fast_json")  # type: ignore[misc]
+    def grid(self) -> GridResponse:
         return super().grid()
 
-    @view_config(route_name="c2cgeoform_item", request_method="GET", renderer="../templates/edit.jinja2")
-    def view(self):
+    @view_config(route_name="c2cgeoform_item", request_method="GET", renderer="../templates/edit.jinja2")  # type: ignore[misc]
+    def view(self) -> ObjectResponse:
         return super().edit()
 
-    @view_config(route_name="c2cgeoform_item", request_method="POST", renderer="../templates/edit.jinja2")
-    def save(self):
+    @view_config(route_name="c2cgeoform_item", request_method="POST", renderer="../templates/edit.jinja2")  # type: ignore[misc]
+    def save(self) -> SaveResponse:
         if self._is_new():
             response = super().save()
 
@@ -108,9 +124,11 @@ class UserViews(AbstractViews):
                 password = pwgenerator.generate()
 
                 user = self._obj
+                assert user is not None
                 user.password = password
                 user.is_password_changed = False
                 user = self._request.dbsession.merge(user)
+                assert user is not None
                 self._request.dbsession.flush()
 
                 send_email_config(
@@ -119,18 +137,20 @@ class UserViews(AbstractViews):
                     email=user.email,
                     user=user.username,
                     password=password,
+                    application_url=self._request.route_url("base"),
+                    current_url=self._request.current_route_url(),
                 )
 
             return response
 
         return super().save()
 
-    @view_config(route_name="c2cgeoform_item", request_method="DELETE", renderer="fast_json")
-    def delete(self):
+    @view_config(route_name="c2cgeoform_item", request_method="DELETE", renderer="fast_json")  # type: ignore[misc]
+    def delete(self) -> DeleteResponse:
         return super().delete()
 
-    @view_config(
+    @view_config(  # type: ignore[misc]
         route_name="c2cgeoform_item_duplicate", request_method="GET", renderer="../templates/edit.jinja2"
     )
-    def duplicate(self):
+    def duplicate(self) -> ObjectResponse:
         return super().duplicate()

c2cgeoportal_admin/widgets.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
-
-# Copyright (c) 2018-2020, Camptocamp SA
+# Copyright (c) 2018-2024, Camptocamp SA
 # All rights reserved.
 
 # Redistribution and use in source and binary forms, with or without
@@ -27,12 +25,16 @@
 # of the authors and should not be interpreted as representing official policies,
 # either expressed or implied, of the FreeBSD Project.
 
+from typing import Any
 
 import colander
+import pyramid.request
 from colander import Mapping, SchemaNode
 from deform import widget
 from deform.widget import MappingWidget, SequenceWidget
 
+from c2cgeoportal_commons.models.main import TreeItem
+
 registry = widget.default_resource_registry
 registry.set_js_resources(
     "magicsuggest", None, "c2cgeoportal_admin:node_modules/magicsuggest-alpine/magicsuggest-min.js"
@@ -52,51 +54,100 @@ widget.DateTimeInputWidget._pstruct_schema = SchemaNode(  # pylint: disable=prot
 )
 
 
-class ChildWidget(MappingWidget):
+class ChildWidget(MappingWidget):  # type: ignore
+    """
+    Extension of the widget ````deform.widget.MappingWidget``.
 
-    template = "child"
+    To be used in conjunction with ChildrenWidget, to manage n-m relationships.
 
-    def serialize(self, field, cstruct, **kw):
-        from c2cgeoportal_commons.models.main import TreeItem  # pylint: disable=import-outside-toplevel
+    Do not embed complete children forms, but just an hidden input for child primary key.
 
-        if cstruct["treeitem_id"] == colander.null:
-            kw["treeitem"] = TreeItem()
-        else:
-            kw["treeitem"] = field.schema.dbsession.query(TreeItem).get(int(cstruct["treeitem_id"]))
-        return super().serialize(field, cstruct, **kw)
+    **Attributes/Arguments**
+
+    input_name (required)
+        Form input name namely the name of the schema field identifying the child in the relation.
+
+    model (required)
+        The child model class.
+
+    label_field (required)
+        The name of the field used for display.
+
+    icon_class (optional)
+        A function which takes a child as parameter and returns a CSS class.
 
+    edit_url (optional)
+        A function taking request and child as parameter and returning
+        an URL to the corresponding resource.
 
-class ThemeOrderWidget(MappingWidget):
+    For further attributes, please refer to the documentation of
+    ``deform.widget.MappingWidget`` in the deform documentation:
+    <https://deform.readthedocs.org/en/latest/api.html>
+    """
 
     template = "child"
+    input_name = "treeitem_id"
+    model = TreeItem
+    label_field = "name"
 
-    def serialize(self, field, cstruct, **kw):
-        from c2cgeoportal_commons.models.main import TreeItem  # pylint: disable=import-outside-toplevel
+    def icon_class(self, child: Any) -> str | None:  # pylint: disable=useless-return
+        del child
+        return None
+
+    def edit_url(  # pylint: disable=useless-return
+        self, request: pyramid.request.Request, child: Any
+    ) -> str | None:
+        del request
+        del child
+        return None
 
-        if cstruct["id"] == colander.null:
-            kw["treeitem"] = TreeItem()
+    def serialize(self, field, cstruct, **kw):
+        if cstruct[self.input_name] == colander.null:
+            kw["child"] = self.model()
         else:
-            kw["treeitem"] = field.schema.dbsession.query(TreeItem).get(int(cstruct["id"]))
+            kw["child"] = field.schema.dbsession.query(self.model).get(int(cstruct[self.input_name]))
         return super().serialize(field, cstruct, **kw)
 
 
-class ChildrenWidget(SequenceWidget):
+class ChildrenWidget(SequenceWidget):  # type: ignore
+    """
+    Extension of the widget ````deform.widget.SequenceWidget``.
+
+    To be used in conjunction with ChildWidget, to manage n-m relationships.
+
+    Use Magicsuggest for searching into parent schema candidates property, which should be a list of
+    dictionaries of the form:
+    {
+        "id": "Value to be set in child identifier input (child_input_name)",
+        "label": "The text to display in MagicSuggest",
+        "icon_class": "An optional icon class for the MagisSuggest entries",
+        "edit_url": "An optional url to edit the child resource",
+        "group": "An optional group name for grouping entries in MagicSuggest",
+    }
+
+    **Attributes/Arguments**
+
+    child_input_name (required)
+        The name of the child input to fill with selected child primary key.
+
+    For further attributes, please refer to the documentation of
+    ``deform.widget.SequenceWidget`` in the deform documentation:
+    <https://deform.readthedocs.org/en/latest/api.html>
+    """
 
     template = "children"
+    category = "structural"
     add_subitem = True
+    orderable = True
+    child_input_name = "treeitem_id"
     requirements = SequenceWidget.requirements + (("magicsuggest", None),)
 
-    def __init__(self, **kw):
-        SequenceWidget.__init__(self, orderable=True, **kw)
-
     def deserialize(self, field, pstruct):
-        for i, dict_ in enumerate(pstruct):
-            dict_["ordering"] = str(i)
+        if self.orderable and pstruct != colander.null:
+            for i, dict_ in enumerate(pstruct):
+                dict_["ordering"] = str(i)
         return super().deserialize(field, pstruct)
 
     def serialize(self, field, cstruct, **kw):
-        kw["treeitems"] = [
-            {"id": item.id, "name": item.name, "item_type": item.item_type, "group": group}
-            for item, group in field.schema.treeitems
-        ]
+        kw["candidates"] = field.schema.candidates
         return super().serialize(field, cstruct, **kw)