Catalog

The ludic.catalog module is a collection of components designed to help build applications using the Ludic framework. It serves as both a resource for building new web applications and also as a showcase of ways to implement components.

Each item in the catalog is a reusable component that generates HTML code and registers its own CSS styles.. The registered CSS are loaded using the style.load() method, as detailed in the Styles and Themes section of the documentation.

The catalog components are like Lego pieces you can assemble together to build interactive and beautiful HTML documents with minimalistic approach:

• You write HTML in pure Python, this removes any need for template engines and offers type safety as a bonus.
• The generated CSS is simple, extensible, and easy to understand. The layouts you can use for building your pages are responsive, reusable, and robust. They are based on the amazing Every Layout Book.

In order for everything to work correctly, the first thing you usually need to do is to create a Page component. This component is important for two reasons:

• It renders as a valid HTML document with (optionally) HTMX script loaded;
• It renders collected CSS styles loaded from components in the catalog.

All rendered HTML documents will have this component as a base similar to how all HTML pages in template engines like Jinja2 use the base template.

After you are done with setting up your Page component, you can use it along with all the other components in the catalog.

This component has already been mentioned throughout the documentation and can be used to create your Page component. The HtmlPage component is just for convenience so that you can quickly start and not worry about how to load e.g. CSS styles or HTMX.

Here is how you would use the HtmlPage component to create your own Page component:

from typing import override

from ludic.attrs import NoAttrs
from ludic.html import link, meta
from ludic.catalog.pages import HtmlPage, Head, Body
from ludic.catalog.layouts import Stack
from ludic.components import Component
from ludic.types import AnyChildren

class Page(Component[AnyChildren, NoAttrs]):
    @override
    def render(self) -> HtmlPage:
        return HtmlPage(
            Head(
                # add custom head elements
                meta(charset="utf-8"),
                link(rel="icon", type="image/png", href="..."),

                # here is a list of the Head's (optional) attributes
                title="My Page",        # add custom title
                favicon="favicon.ico",  # add favicon path
                load_styles=True,       # load registered styles
                htmx_config=...,        # configure HTMX
            ),
            Body(
                # here you can create a base layout where all children of
                # this Page component will be placed, more about layouts
                # in the layouts section
                Stack(*self.children),

                # here is a list of the Body's (optional) attributes
                htmx_version="1.9.10",  # loads HTMX script from CDN
                htmx_path="htmx.js",    # loads HTMX script from a path
                htmx_enabled=True,      # enable HTMX
            ),
        )

Here are the default values:

• load_styles=True
• htmx_config={"defaultSwapStyle": "outerHTML"}
• htmx_enabled=True
• htmx_version="latest"

Now that you prepared your Page component, you can use it in your code like here:

from ludic.web import LudicApp
from ludic.catalog.buttons import Button
from ludic.catalog.headers import H1
from ludic.catalog.typography import Paragraph

from your_app.pages import Page

app = LudicApp()

@app.get("/")
def index(request: Request) -> Page:
    return Page(
        H1("Hello, World!"),
        Button("Click Me", hx_get=request.url_for("clicked")),
    )

@app.get("/clicked")
def clicked(request: Request) -> Paragraph:
    return Paragraph("You clicked me!")

The HtmlPage component comes also with default styles. In fact, the following list of styles are auto-loaded whenever you import anything from the ludic.catalog module:

• ludic.catalog.pages
• ludic.catalog.layouts