addd meta for template_name

template_html
form_class
component_key

Author: JohananOppongAmoateng

docs/source/validation.md

@@ -20,10 +20,11 @@ class BookForm(forms.Form):
     publish_date = forms.DateField(required=True)
 
 class BookView(UnicornView):
-    form_class = BookForm
-
     title = ""
     publish_date = ""
+
+    class Meta:
+        form_class = BookForm
 ```
 
 ```html
@@ -35,7 +36,11 @@ class BookView(UnicornView):
 </div>
 ```
 
-Because of the `form_class = BookForm` defined on the `UnicornView` above, `Unicorn` will automatically validate that the title has a value and is less than 100 characters. The `publish_date` will also be converted into a `datetime` from the string representation in the text input.
+Because of the `Meta.form_class = BookForm` defined on the `UnicornView` above, `Unicorn` will automatically validate that the title has a value and is less than 100 characters. The `publish_date` will also be converted into a `datetime` from the string representation in the text input.
+
+```{note}
+Setting `form_class` directly as a class attribute also works and is supported for backwards compatibility.
+```
 
 ### Validate the entire component
 
@@ -60,10 +65,11 @@ class BookForm(forms.Form):
     title = forms.CharField(max_length=6, required=True)
 
 class BookView(UnicornView):
-    form_class = BookForm
-
     text = "hello"
 
+    class Meta:
+        form_class = BookForm
+
     def set_text(self):
         self.text = "hello world"
         self.validate()
@@ -80,10 +86,11 @@ class BookForm(forms.Form):
     title = forms.CharField(max_length=6, required=True)
 
 class BookView(UnicornView):
-    form_class = BookForm
-
     text = "hello"
 
+    class Meta:
+        form_class = BookForm
+
     def set_text(self):
         if self.is_valid():
             self.text = "hello world"

docs/source/views.md

@@ -125,26 +125,32 @@ Never put sensitive data into a public property because that information will pu
 
 ### template_name
 
-By default, the component name is used to determine what template should be used. For example, `hello_world.HelloWorldView` would by default use `unicorn/hello-world.html`. However, you can specify a particular template by setting `template_name` in the component.
+By default, the component name is used to determine what template should be used. For example, `hello_world.HelloWorldView` would by default use `unicorn/hello-world.html`. Set `template_name` inside `Meta` to override it.
 
 ```python
 # hello_world.py
 from django_unicorn.components import UnicornView
 
 class HelloWorldView(UnicornView):
-    template_name = "unicorn/hello-world.html"
+    class Meta:
+        template_name = "unicorn/hello-world.html"
+```
+
+```{note}
+Setting `template_name` directly as a class attribute also works and is supported for backwards compatibility.
 ```
 
 ### template_html
 
-Template HTML can be defined inline on the component instead of using an external HTML file.
+Template HTML can be defined inline on the component instead of using an external HTML file. Set it inside `Meta`.
 
 ```python
 # hello_world.py
 from django_unicorn.components import UnicornView
 
 class HelloWorldView(UnicornView):
-    template_html = """<div>
+    class Meta:
+        template_html = """<div>
     <div>
         Count: {{ count }}
     </div>
@@ -157,6 +163,10 @@ class HelloWorldView(UnicornView):
     ...
 ```
 
+```{note}
+Setting `template_html` directly as a class attribute also works and is supported for backwards compatibility.
+```
+
 ## Instance properties
 
 ### component_args
@@ -532,6 +542,80 @@ data, modifying records) should still verify `self.request.user.is_authenticated
 inside the relevant component methods.
 ```
 
+### template_name
+
+Override the template path used to render the component.
+
+```python
+# hello_world.py
+from django_unicorn.components import UnicornView
+
+class HelloWorldView(UnicornView):
+    class Meta:
+        template_name = "unicorn/hello-world.html"
+```
+
+### template_html
+
+Define the component template as an inline HTML string instead of a separate file.
+
+```python
+# hello_world.py
+from django_unicorn.components import UnicornView
+
+class HelloWorldView(UnicornView):
+    count = 0
+
+    class Meta:
+        template_html = """<div>
+    <div>Count: {{ count }}</div>
+    <button unicorn:click="increment">+</button>
+</div>"""
+```
+
+### component_key
+
+Set a default key for the component class. This is applied when the template tag
+does not supply a `key=` argument and is useful when you always want a specific
+component to be keyed the same way.
+
+```python
+# signup.py
+from django_unicorn.components import UnicornView
+
+class SignupView(UnicornView):
+    class Meta:
+        component_key = "signup"
+```
+
+```{note}
+A `key=` value provided in the template tag always takes precedence over
+`Meta.component_key`.
+```
+
+### form_class
+
+Attach a Django form for validation. Errors from the form are merged into the
+component's `errors` dict.
+
+```python
+# book_form.py
+from django_unicorn.components import UnicornView
+from .forms import BookForm
+
+class BookFormView(UnicornView):
+    title = ""
+    year = None
+
+    class Meta:
+        form_class = BookForm
+```
+
+```{note}
+Setting `form_class` directly as a class attribute also works and is supported for
+backwards compatibility.
+```
+
 ## Pickling and Caching
 
 Components are pickled and cached for the duration of the AJAX request. This means that any instance variable on the component must be pickleable.

src/django_unicorn/components/unicorn_view.py

@@ -237,21 +237,38 @@ def __init__(self, component_args: list | None = None, **kwargs):
         self._init_script: str = ""
         self._validate_called = False
         self.errors: dict[Any, Any] = {}
+
+        # Apply Meta.component_key as a class-level default when the template
+        # tag has not provided a key (i.e. self.component_key is still empty).
+        if not self.component_key and hasattr(self, "Meta") and hasattr(self.Meta, "component_key"):
+            self.component_key = self.Meta.component_key
+
         self._set_default_template_name()
         self._set_caches()
 
     @timed
     def _set_default_template_name(self) -> None:
         """Sets a default template name based on component's name if necessary.
 
-        Also handles `template_html` if it is set on the component which overrides `template_name`.
+        Also handles `template_html` (via Meta or direct attribute) which overrides
+        `template_name`. Meta attributes take precedence over direct class attributes.
         """
 
-        if hasattr(self, "template_html"):
+        # Resolve template_html — Meta takes precedence over direct attribute
+        template_html = None
+        if hasattr(self, "Meta") and hasattr(self.Meta, "template_html"):
+            template_html = self.Meta.template_html
+        elif hasattr(self, "template_html"):
+            template_html = self.template_html
+
+        if template_html:
             try:
-                self.template_name = create_template(self.template_html)  # type: ignore
+                self.template_name = create_template(template_html)  # type: ignore
             except AssertionError:
                 pass
+        elif hasattr(self, "Meta") and hasattr(self.Meta, "template_name"):
+            # Meta.template_name overrides a direct class attribute when set
+            self.template_name = self.Meta.template_name
 
         get_template_names_is_valid = False
 
@@ -578,9 +595,15 @@ def get_frontend_context_variables(self) -> str:
 
     @timed
     def _get_form(self, data):
-        if hasattr(self, "form_class"):
+        form_class = None
+        if hasattr(self, "Meta") and hasattr(self.Meta, "form_class"):
+            form_class = self.Meta.form_class
+        elif hasattr(self, "form_class"):
+            form_class = self.form_class
+
+        if form_class:
             try:
-                form = cast(Callable, self.form_class)(data=data)
+                form = cast(Callable, form_class)(data=data)
                 form.is_valid()
 
                 return form
@@ -871,13 +894,26 @@ def _is_public(self, name: str) -> bool:
             "calling",
             "called",
             "login_not_required",
+            "form_class",
         )
         excludes = []
 
         if hasattr(self, "Meta") and hasattr(self.Meta, "login_not_required"):
             if not isinstance(self.Meta.login_not_required, bool):
                 raise AssertionError("Meta.login_not_required should be a bool")
 
+        if hasattr(self, "Meta") and hasattr(self.Meta, "template_name"):
+            if not isinstance(self.Meta.template_name, str):
+                raise AssertionError("Meta.template_name should be a str")
+
+        if hasattr(self, "Meta") and hasattr(self.Meta, "template_html"):
+            if not isinstance(self.Meta.template_html, str):
+                raise AssertionError("Meta.template_html should be a str")
+
+        if hasattr(self, "Meta") and hasattr(self.Meta, "component_key"):
+            if not isinstance(self.Meta.component_key, str):
+                raise AssertionError("Meta.component_key should be a str")
+
         if hasattr(self, "Meta") and hasattr(self.Meta, "exclude"):
             if not is_non_string_sequence(self.Meta.exclude):
                 raise AssertionError("Meta.exclude should be a list, tuple, or set")