Feature/preview (#3)

* add component preview
* add preview doc

Author: michael-yin

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
-## 1.0.1
+## 1.0.3
+
+1. Add component `Preview` support
+
+## 1.0.2
 
 1. Initial release

docs/source/images/preview-index.png

@@ -15,4 +15,5 @@ Topics
    slot.md
    templates.md
    context.md
+   preview.md
    testing.md

docs/source/images/small-modal-preview.png

@@ -0,0 +1,93 @@
+# Previews
+
+We can create previews for our components, and check the result in the browser, just like Storybook.
+
+## Config
+
+Add below config to your Django settings
+
+```python
+VIEW_COMPONENTS = {
+    "preview_base": ["django_app/tests/previews"],
+}
+```
+
+`preview_base` is the base path for your previews. You can add multiple paths to it.
+
+Add below url path to your Django urls
+
+```python
+path("previews/", include("django_viewcomponent.urls")),
+```
+
+So all the previews will work on the `/previews` path, I'd like to do that when `DEBUG` is `True`.
+
+## Create a preview
+
+```bash
+django_app/tests/
+├── previews
+│   ├── modal_preview.py
+│   └── tab_preview.py
+```
+
+Notes:
+
+1. I'd like to put all previews under the `tests` directory, but you can put them anywhere you like.
+
+```python
+from django.template import Context, Template
+from django_viewcomponent.preview import ViewComponentPreview
+
+
+class ModalComponentPreview(ViewComponentPreview):
+    def small_modal(self, **kwargs):
+        template = Template(
+            """
+            {% load viewcomponent_tags %}
+
+            {% component 'modal' size="sm" as component %}
+              {% call component.trigger %}
+                <button class="btn btn-blue" data-action="click->modal#open:prevent">Open Small Modal</button>
+              {% endcall %}
+
+              {% call component.body %}
+                <h2 class="mb-4 text-xl">Small Modal Content</h2>
+                <p class="mb-4">This is an example modal dialog box.</p>
+              {% endcall %}
+
+              {% call component.actions %}
+                <button class="btn btn-white" data-action="click->modal#close:prevent">Cancel</button>
+                <button class="btn btn-blue" data-action="click->modal#close:prevent">Close</button>
+              {% endcall %}
+            {% endcomponent %}
+        """,
+        )
+
+        return template.render(Context({}))
+```
+
+Notes:
+
+1. We create a `ModalComponentPreview`, which inherits from `ViewComponentPreview`.
+2. We defined a public method `small_modal`, which will be used to render the preview, and `small_modal` is the name of the preview.
+3. We can get `request.GET` from the `kwargs` parameter, and use it to render the preview.
+4. In most cases, we can create one preview class for one component, and create multiple public method for one preview.
+
+That is it!
+
+## Check the preview
+
+If we check [http://127.0.0.1:8000/previews/](http://127.0.0.1:8000/previews/), all previews will be listed there.
+
+![](./images/preview-index.png)
+
+If we check the `small_modal` preview, we will see the result in the browser.
+
+![](./images/small-modal-preview.png)
+
+The great thing is, we can also see the source code of the preview, which helps us to understand how to use the component.
+
+## Override Templates
+
+You can also override the templates to fit your needs, please check the template files under `django_viewcomponent/templates/django_viewcomponent` to learn more.

docs/source/index.rst

@@ -5,11 +5,10 @@
 from pathlib import Path
 
 from django.template.engine import Engine
-
 from django_viewcomponent.loaders import ComponentLoader
 
 
-def autodiscover():
+def autodiscover_components():
     # Autodetect a <component>.py file in a components dir
     current_engine = Engine.get_default()
     loader = ComponentLoader(current_engine)
@@ -19,6 +18,14 @@ def autodiscover():
             import_component_file(path)
 
 
+def autodiscover_previews():
+    from django_viewcomponent.app_settings import app_settings
+    preview_base_ls = [Path(p) for p in app_settings.PREVIEW_BASE]
+    for directory in preview_base_ls:
+        for path in glob.iglob(str(directory / "**/*.py"), recursive=True):
+            import_component_file(path)
+
+
 def import_component_file(path):
     MODULE_PATH = path
     MODULE_NAME = Path(path).stem

docs/source/preview.md

@@ -3,7 +3,11 @@
 
 class AppSettings:
     def __init__(self):
-        self.settings = getattr(settings, "COMPONENTS", {})
+        self.settings = getattr(settings, "VIEW_COMPONENTS", {})
+
+    @property
+    def PREVIEW_BASE(self):
+        return self.settings.setdefault("preview_base", [])
 
 
 app_settings = AppSettings()

src/django_viewcomponent/__init__.py

@@ -5,5 +5,5 @@ class ComponentsConfig(AppConfig):
     name = "django_viewcomponent"
 
     def ready(self):
-        # autodiscover components
-        self.module.autodiscover()
+        self.module.autodiscover_components()
+        self.module.autodiscover_previews()

src/django_viewcomponent/app_settings.py

@@ -0,0 +1,51 @@
+import re
+import inspect
+from django.urls import reverse
+from urllib.parse import urljoin
+
+pattern = re.compile(r'(?<!^)(?=[A-Z])')
+
+
+def public_instance_methods(cls):
+    return [name for name in cls.__dict__.keys() if not name.startswith('__') and callable(getattr(cls, name))]
+
+
+def camel_to_snake(name):
+    # https://stackoverflow.com/questions/1175208/elegant-python-function-to-convert-camelcase-to-snake-case
+    name = pattern.sub('_', name).lower()
+    return name
+
+
+class ViewComponentPreview:
+
+    previews = {}
+    preview_name = None
+    preview_view_component_path = None
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __init_subclass__(cls, **kwargs):
+        name = cls.__name__
+        name = name.replace("Preview", "")
+        new_name = camel_to_snake(name)
+        ViewComponentPreview.previews[new_name] = cls
+        cls.preview_name = new_name
+        cls.preview_view_component_path = inspect.getfile(cls)
+        cls.url = urljoin(reverse('django_viewcomponent:preview-index'), cls.preview_name + '/')
+
+    @classmethod
+    def examples(cls):
+        public_methods = public_instance_methods(cls)
+        return public_methods
+
+    def preview_source(self, method_name):
+        method = getattr(self, method_name)
+        raw_source_code = inspect.getsource(method)
+
+        # remove 4 spaces from the beginning of each line
+        lines = raw_source_code.split('\n')
+        modified_lines = [line[4:] for line in lines]
+        modified_string = '\n'.join(modified_lines)
+
+        return modified_string

src/django_viewcomponent/apps.py

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/themes/prism.min.css">
+</head>
+<body>
+{% block content %}
+{% endblock %}
+
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/prism.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/components/prism-python.min.js"></script>
+</body>
+</html>