Add help text to adapter_help management command; specify optional ke…

…yword arguments

wagtail_fedit/adapters/base.py

@@ -70,9 +70,10 @@ def loads(self, data):
 class BaseAdapter(FeditIFrameMixin):
     identifier              = None
     signer: Signer          = Signer()
-    # wrapper_template        = None
-    # run_context_processors  = True
-    required_kwargs         = [] # Required keyword arguments for the adapter
+    # Required keyword arguments for the adapter
+    required_kwargs         = []
+    # Optional keyword arguments for the adapter, these are only used to print the help example.
+    optional_kwargs         = []
     # Tokens which should be resolved absolutely (no parser.compile_filter)
     # These are NOT required.
     absolute_tokens         = [
@@ -105,6 +106,18 @@ def usage_string(cls) -> str:
             s.append(f"{kwarg}=value")
             if i < len(cls.required_kwargs) - 1:
                 s.append(" ")
+
+        if (
+            cls.required_kwargs and cls.optional_kwargs or\
+            not cls.required_kwargs and cls.absolute_tokens and cls.optional_kwargs
+        ):
+            s.append(" ")
+
+        for i, kwarg in enumerate(cls.optional_kwargs):
+            s.append(f"[{kwarg}=value]")
+            if i < len(cls.optional_kwargs) - 1:
+                s.append(" ")
+
         return "".join(s)
 
     @property

wagtail_fedit/adapters/block.py

@@ -39,20 +39,27 @@ class BlockAdapter(BlockFieldReplacementAdapter):
     on successful form submission.
     """
     identifier = "block"
-    required_kwargs = ["block"]
+    required_kwargs = [
+        "block",
+    ]
+    optional_kwargs = [
+        "block_id",
+    ]
     absolute_tokens = [ # override; remove "inline"
-        "admin" # allows for displaying admin URLs
+        "admin", # allows for displaying admin URLs
     ]
 
     def __init__(self, object: models.Model, field_name: str, request: HttpRequest, **kwargs):
         super().__init__(object, field_name, request, **kwargs)
 
         self.block = self.kwargs.pop("block", None)
         if self.block:
-            if not isinstance(self.block, BoundBlock):
-                raise AdapterError("Invalid block type")
+            if not hasattr(self.block, "id") and not "block_id" in self.kwargs:
+                raise AdapterError("Invalid block type, block must have an `id` attribute or provide a `block_id`")
+
+            if hasattr(self.block, "id"):
+                self.kwargs["block_id"] = self.block.id
 
-            self.kwargs["block_id"] = self.block.id
         else:
             block_id = self.kwargs.get("block_id", None)
             if block_id is None:

wagtail_fedit/management/commands/adapter_help.py

@@ -1,4 +1,4 @@
-from django.core.management.base import BaseCommand, CommandError
+from django.core.management.base import BaseCommand
 from django.core.management.color import color_style, supports_color
 from wagtail_fedit.adapters import adapter_registry
 from wagtail_fedit.utils import TEMPLATE_TAG_NAME
@@ -9,19 +9,30 @@ class Command(BaseCommand):
 
     def handle(self, *args, **options):
         s = [
-            "Registered Adapters:",
+            " Registered Adapters",
+            "====================",
+            " * The first argument is the identifier of the adapter.",
+            " * The second argument is the model and field to edit. instance.modelfield",
+            " * Absolute arguments (missing an equal sign) are optional and treated as booleans.",
+            " * Keyword arguments wrapped in square brackets are optional. [key=value]",
+            " * The value of the adapter is the value of the field.",
+            "====================",
+            "",
         ]
 
         for identifier, adapter_class in adapter_registry.adapters.items():
             s.append(
-                f"\t{{% {TEMPLATE_TAG_NAME} {identifier} instance.modelfield {adapter_class.usage_string()} %}}",
+                f"    {{% {TEMPLATE_TAG_NAME} {identifier} instance.modelfield {adapter_class.usage_string()} %}}",
             )
 
         if supports_color():
             style = color_style()
-            s = style.SUCCESS("\n".join(s))
+            s = "\n|".join(s)
+            s = style.SUCCESS(f'|{s}')
         else:
-            s = "\n".join(s)
+            s = "\n|".join(s)
+            s = f'|{s}'
+        self.stdout.write("\n")
         self.stdout.write(s)
         self.stdout.write("\n")
 

wagtail_fedit/utils.py

@@ -452,27 +452,6 @@ def lock_info(object, user) -> _lock_info:
     return _lock_info(lock, locked_for_user)
 
 
-def get_hooks(hook_name):
-    """
-        Return the hooks for a given hook name in the wagtail_fedit namespace.
-    """
-    for hook in hooks.get_hooks(f"wagtail_fedit.{hook_name}"):
-        yield hook
-
-
-def _resolve_expressions(context, *expressions):
-    """
-        Resolve a list of possible templatetag filterexpressions.
-    """
-    def _map(expression):
-        if isinstance(expression, FilterExpression):
-            return expression.resolve(context)
-        return expression
-
-    return tuple(map(_map, expressions))
-
-
-
 def wrap_adapter(request: HttpRequest, adapter: "BaseAdapter", context: dict, run_context_processors: bool = False) -> str:
     if not context:
         context = {}