Installation with django-viewcomponent

Note

If your project already used django-viewcomponent, you can follow this guide to install django-lookbook.

$ pip install django-lookbook

Then add the app into INSTALLED_APPS in settings.py

INSTALLED_APPS = [
    ...,
    "django_viewcomponent",
    "django_lookbook",        # new
]

Add code below in settings.py

VIEW_COMPONENTS = {
    # we will put previews in this directory later
    "preview_base": ["previews"],
    # show_previews is True by default
    "show_previews": DEBUG,
}

# to make iframe work
X_FRAME_OPTIONS = "SAMEORIGIN"

Notes:

  1. preview_base is the base path for your previews.

  2. show_previews is a boolean value, which is used to control whether to show the previews. It is True by default, here we set it with same value of DEBUG. So the previews will only be shown in the development environment.

Update urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path("previews/", include("django_viewcomponent.urls")),      # new
    path("lookbook/", include("django_lookbook.urls")),        # new
]

Next, let’s create previews/hello_preview.py

from django.template import Context, Template
from django_viewcomponent.preview import ViewComponentPreview


class HelloComponentPreview(ViewComponentPreview):
    def hello_world(self, **kwargs):
        """
        This is a simple test for you to check how doc of the preview works
        """
        template = Template(
            """<div>Hello World</div>""",
        )
        return template.render(Context({}))

Notes:

  1. We create HelloWorldComponentPreview which inherits from ViewComponentPreview, the class name HelloComponentPreview can be seen as a group which can contains multiple previews.

  2. We define two methods hello_world and hello_world_with_name which will be used to render the preview

├── previews
│   └── hello_preview.py

Create django_viewcomponent/preview.html in the project templates directory

<!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 href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet"
        integrity="sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65" crossorigin="anonymous">
</head>
<body>

<div>
  {{ preview_html }}
</div>

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/js/bootstrap.bundle.min.js"
        integrity="sha384-kenU1KFdBIe4zVF0s0G1M5b4hcpxyD9F7jL+jjXkk+Q2h455rYXK/7HAuoJl+0I4"
        crossorigin="anonymous"></script>
</body>
</html>

  1. We import Bootstrap CSS and JS to the page.

  2. preview_html is the HTML generated by the preview method.

Now if we refresh the page and check again, the preview HTML should be rendered with Bootstrap CSS and JS.

Note

If you have other frontend assets such as Alpine.js, jQuery or CSS file, you should remember to include them in this template file django_viewcomponent/preview.html.

# create db tables and launch Django server
(venv)$ python manage.py migrate
(venv)$ python manage.py runserver

Now please check on http://127.0.0.1:8000/lookbook:

  1. The preview has been automatically detected and can be seen in the left sidebar

  2. You can see the UI of the preview on the right side and final HTML source code can also be seen

  3. The docstring of the preview has been extracted and display in the Notes tab, Markdown syntax is supported

Each time we visit a preview, the method would be called and the final result would be displayed in the top iframe.