Extra help text for each individual adapter

Nigel2392 · Apr 20, 2024 · b688faa · b688faa
1 parent c40958a
commit b688faa
Show file tree

Hide file tree

Showing 5 changed files with 43 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -60,9 +60,9 @@ Getting Started
    </head>
    <body>
        {# Adress the model.field or model.my.related.field you wish to edit. #}
-       {# Editable fields get a special `inline` argument. #}
-       {# if True the button is not placed with an absolute CSS position. #}
-       <h1>{% fedit field self.title inline=True or False %}</h1>
+       {# For help on arguments for the adapters please run the adapter_help command. #}
+       {# Example: `python3 ./manage.py adapter_help` #}
+       <h1>{% fedit field self.title inline %}</h1>
 
        <main class="my-streamfield-content">
            {% fedit field self.content %}

diff --git a/wagtail_fedit/adapters/base.py b/wagtail_fedit/adapters/base.py
@@ -119,6 +119,20 @@ def usage_string(cls) -> str:
                 s.append(" ")
 
         return "".join(s)
+
+    @classmethod
+    def usage_help_text(cls) -> list[str]:
+        """
+        Return a help text which describes how to use the adapter.
+        This might be a good time to exalain the kwargs.
+        """
+        if "inline" in cls.absolute_tokens:
+            s = [
+                "This adapter is used to edit a field of a model instance.",
+                "inline: if passed; the adapter will be rendered with inline styles.",
+            ]
+            return s
+        return []
 
     @property
     def field_value(self):

diff --git a/wagtail_fedit/adapters/block.py b/wagtail_fedit/adapters/block.py
@@ -49,6 +49,15 @@ class BlockAdapter(BlockFieldReplacementAdapter):
         "admin", # allows for displaying admin URLs
     ]
 
+    @classmethod
+    def usage_help_text(cls) -> list[str]:
+        return [
+            "This adapter is used to edit a block of a streamfield.",
+            "block: the block instance to edit. This can be a regular block isntance or a BoundBlock.",
+            "block_id: the block ID to edit, required if block is not a BoundBlock.",
+            "admin: if passed; the adapter will display admin URLs.",
+        ]
+
     def __init__(self, object: models.Model, field_name: str, request: HttpRequest, **kwargs):
         super().__init__(object, field_name, request, **kwargs)
 

diff --git a/wagtail_fedit/adapters/misc.py b/wagtail_fedit/adapters/misc.py
@@ -31,6 +31,14 @@ class BackgroundImageFieldAdapter(BaseFieldFuncAdapter):
     absolute_tokens = []
     js_constructor = "wagtail_fedit.editors.WagtailFeditFuncEditor"
 
+    @classmethod
+    def usage_help_text(cls) -> list[str]:
+        return [
+            "This adapter is used to edit a field of a model instance.",
+            "target: the target element to apply the background-image to.",
+            "css_variable_name: the CSS variable name to apply the background-image to. element.style.setProperty(css_variable_name, url);",
+        ]
+
     def __init__(self, object, field_name: str, request: HttpRequest, **kwargs):
         kwargs["name"] = "wagtail_fedit.funcs.backgroundImageFunc"
         super().__init__(object, field_name, request, **kwargs)

diff --git a/wagtail_fedit/management/commands/adapter_help.py b/wagtail_fedit/management/commands/adapter_help.py
@@ -24,14 +24,19 @@ def handle(self, *args, **options):
             s.append(
                 f"    {{% {TEMPLATE_TAG_NAME} {identifier} instance.modelfield {adapter_class.usage_string()} %}}",
             )
+            help_text = adapter_class.usage_help_text()
+            if help_text:
+                help_text = "\n      * ".join(help_text)
+                s.append(f"      * {help_text}")
+                s.append("")
+            else:
+                s.append("")
 
         if supports_color():
             style = color_style()
-            s = "\n|".join(s)
-            s = style.SUCCESS(f'|{s}')
+            s = style.SUCCESS("\n".join(s))
         else:
-            s = "\n|".join(s)
-            s = f'|{s}'
+            s = "\n".join(s)
         self.stdout.write("\n")
         self.stdout.write(s)
         self.stdout.write("\n")