Restructure the example to describe creating a form

Author: evilkermit

README.md

@@ -18,9 +18,8 @@ We use the MVVM framework for NOVA applications. With this in mind, each example
 1. view.py - Sets up a Trame GUI for the example.
 2. model.py - Sets up a Pydantic model and any business logic needed by the application.
 3. view_model.py - Sets up a view model that binds the model and view.
-4. mvvm_factory.py - Entrypoint for creating the model and view model.
-5. main.py - Runs the Trame GUI.
+4. main.py - Entrypoint for the Trame GUI.
 
 ## List of Examples
 
-1. [Binding Trame parameters](examples/trame_bindings)
+1. [Creating a form for a Pydantic model](examples/pydantic_form)

examples/trame_bindings/main.py examples/pydantic_form/main.pyexamples/trame_bindings/main.py renamed to examples/pydantic_form/main.py

@@ -1,6 +1,6 @@
-"""Runs the Trame bindings example."""
+"""Runs the Pydantic form example."""
 
-from examples.trame_bindings.view import App
+from examples.pydantic_form.view import App
 
 
 def main() -> None:

examples/pydantic_form/model.py

@@ -0,0 +1,46 @@
+"""Model implementation for Pydantic form example."""
+
+from pydantic import BaseModel, Field, computed_field, field_validator
+
+
+class FormData(BaseModel):
+    """Pydantic model."""
+
+    user_name: str = Field(default="", title="User Name")
+    domain_name: str = Field(default="", title="Domain Name")
+    submitted: bool = Field(default=False)
+
+    @computed_field
+    @property
+    def submit_disabled(self) -> bool:
+        if "@" not in self.email:
+            return True
+        return False
+
+    @computed_field
+    @property
+    def email(self) -> str:
+        if not self.user_name or not self.domain_name:
+            return ""
+        return f"{self.user_name}@{self.domain_name}"
+
+    @field_validator("domain_name", mode="after")
+    @classmethod
+    def validate_domain_name(cls, value: str) -> str:
+        if value and "." not in value:
+            raise ValueError("Invalid domain name.")
+
+        return value
+
+
+class Model:
+    """Model implementation for Pydantic form example."""
+
+    def __init__(self) -> None:
+        self.form = FormData()
+
+    def submit(self) -> None:
+        self.form.submitted = True
+
+    def unsubmit(self) -> None:
+        self.form.submitted = False

examples/pydantic_form/view.py

@@ -0,0 +1,66 @@
+"""View for Pydantic form example."""
+
+from nova.mvvm.trame_binding import TrameBinding
+from nova.trame import ThemedApp
+from nova.trame.view.components import InputField
+from nova.trame.view.layouts import GridLayout
+from trame.widgets import html
+from trame.widgets import vuetify3 as vuetify
+
+from .model import Model
+from .view_model import ViewModel
+
+
+class App(ThemedApp):
+    """View for Pydantic form example."""
+
+    def __init__(self) -> None:
+        super().__init__()
+
+        self.create_vm()
+        # If you forget to call connect, then the application will crash when you attempt to update the view.
+        self.view_model.form_bind.connect("form")
+        # Generally, we want to initialize the view state before creating the UI for ease of use. If initialization
+        # is expensive, then you can defer it. In this case, you must handle the view state potentially being
+        # uninitialized in the UI via v_if statements.
+        self.view_model.update_view()
+
+        self.create_ui()
+
+    def create_ui(self) -> None:
+        with super().create_ui() as layout:
+            with layout.content:
+                with vuetify.VCard(classes="mx-auto my-4", max_width=600):
+                    with GridLayout(columns=2, gap="0.5em"):
+                        # The GUI must bind the Pydantic model fields to elements.
+                        # Most bindings use the tuple syntax: (parameter_name, default_value).
+                        # If you don't have a default value, then you can use: (parameter_name,).
+                        InputField(v_model=("form.user_name",))
+
+                        # v_model allows you to just pass the parameter_name as a string.
+                        # This typically does not work when binding other parameters.
+                        InputField(v_model="form.domain_name")
+
+                        # Try just passing a string to model_value, and see what happens here!
+                        InputField(
+                            model_value=("form.email",), column_span=2, label="Computed Email Address", readonly=True
+                        )
+
+                        # If you need to trigger some Python code on an event, then you can call view model functions
+                        # directly.
+                        vuetify.VBtn(
+                            "Submit",
+                            column_span=2,
+                            disabled=("form.submit_disabled",),
+                            click=self.view_model.submit,
+                        )
+
+                    # This is less common, but you can use handlebars expressions to display the form data inside of
+                    # a string.
+                    html.Span("You've submitted the following email address: {{ form.email }}", v_if="form.submitted")
+
+    def create_vm(self) -> None:
+        binding = TrameBinding(self.state)
+
+        model = Model()
+        self.view_model = ViewModel(model, binding)

examples/pydantic_form/view_model.py

@@ -0,0 +1,38 @@
+"""View model implementation for Pydantic form example."""
+
+from typing import Any
+
+from nova.mvvm.interface import BindingInterface
+
+from .model import Model
+
+
+class ViewModel:
+    """View model implementation for Pydantic form example."""
+
+    def __init__(self, model: Model, binding: BindingInterface) -> None:
+        self.model = model
+        # self.on_update is called any time the view updates the binding.
+        self.form_bind = binding.new_bind(self.model.form, callback_after_update=self.on_update)
+
+    def on_update(self, results: Any) -> None:
+        print("The user has modified the form:", results)
+
+        # If you need to detect that a specific field in the Pydantic model was updated, you can do so with:
+        updated = results.get("updated", [])
+        for update in updated:
+            match update:
+                case "user_name" | "domain_name":
+                    self.model.unsubmit()
+                    # In these cases, our computed field will update, and we need to communicate that update to the
+                    # front-end. Try commenting this out and see what happens!
+                    self.update_view()
+
+    def submit(self) -> None:
+        self.model.submit()
+        # Now, the Pydantic model has the new value, but the view doesn't until we call update_view.
+        self.update_view()
+
+    def update_view(self) -> None:
+        # This will fail if you haven't called connect on the binding!
+        self.form_bind.update_in_view(self.model.form)