Other Integrations

This guide will walk you through the process of integrating the Ludic framework with other projects (aside from Starlette integration, which is covered in the Web Framework section of the documentation). Here is the list of currently supported integrations:

• FastAPI
• Django

This guide will walk you through integrating the Ludic framework with a FastAPI project. We will cover the necessary setup steps and provide examples of how to use Ludic in your FastAPI application.

To install Ludic with FastAPI support, use the following command:

1   pip install "ludic[fastapi]"

Integrating Ludic with FastAPI is straightforward. Simply configure the LudicRoute route class:

1   from fastapi import FastAPI
2   from ludic.contrib.fastapi import LudicRoute
3   
4   app = FastAPI()
5   app.router.route_class = LudicRoute

You can return Ludic components directly from FastAPI endpoints:

 1   from fastapi import FastAPI
 2   from ludic.html import html, head, body, div, h1, p, title, b
 3   from ludic.contrib.fastapi import LudicRoute
 4   
 5   app = FastAPI()
 6   app.router.route_class = LudicRoute
 7   
 8   @app.get("/")
 9   def index() -> html:
10       return html(
11           head(title("My Page")),
12           body(
13               div(
14                   h1("My Homepage"),
15                   p(f"Hello {b('World!')}"),
16                   id="container",
17               )
18           )
19       )

You can also use predefined components from Ludic's catalog:

 1   import json
 2   from fastapi import FastAPI, Request
 3   from ludic.catalog.pages import HtmlPage, Head, Body
 4   from ludic.catalog.headers import H1
 5   from ludic.catalog.typography import Code, CodeBlock, Link, Paragraph
 6   from ludic.catalog.layouts import Center, Stack
 7   from ludic.components import Component
 8   from ludic.types import AnyChildren
 9   from ludic.contrib.fastapi import LudicRoute
10   
11   app = FastAPI()
12   app.router.route_class = LudicRoute
13   
14   class MyPage(Component[AnyChildren, GlobalAttrs]):
15       def render(self) -> HtmlPage:
16           return HtmlPage(
17               Head(title="My Page"),
18               Body(
19                   Center(
20                       Stack(*self.children, **self.attrs),
21                       style={"padding-block": "xxl"},
22                   ),
23                   htmx_version="2.0.0",
24               ),
25           )
26   
27   @app.get("/")
28   async def index_with_components(request: Request) -> MyPage:
29       query_params = dict(request.query_params)
30       return MyPage(
31           H1("Demo Using The Catalog"),
32           Paragraph(
33               "This page is using components from "
34               f"{Link('Ludic framework.', to='https://getludic.dev')}"
35           ),
36           Paragraph(f"Here is the content of {Code('request.query_params')}"),
37           CodeBlock(json.dumps(query_params, indent=4), language="json"),
38       )

If you need more control, use LudicResponse explicitly:

 1   from fastapi import FastAPI
 2   from ludic.html import p
 3   from ludic.contrib.fastapi import LudicResponse, LudicRoute
 4   
 5   app = FastAPI()
 6   app.router.route_class = LudicRoute
 7   
 8   @app.get("/custom")
 9   def custom_response() -> LudicResponse:
10       return LudicResponse(
11           p("Hello, World!"),
12           status_code=201,
13           headers={"X-Custom-Header": "Ludic"}
14       )

You can check a working FastAPI example:

• in the examples section
• source code on GitHub

This guide wil walk you through integration of the Ludic framework with a Django project. We will cover the necessary setup steps, how to configure middleware, and provide examples of how to use Ludic in your Django views.

First, you need to install Ludic. You can do this using pip:

pip install "ludic[django]"

To use Ludic with Django, you need to add the Ludic middleware to your Django settings. This middleware helps manage the Ludic elements during the request-response cycle, clean up cache, and so on.

1. Open your settings.py file.
2. Add LudicMiddleware to the MIDDLEWARE list:

1   MIDDLEWARE = [
2       # other middlewares...
3       "ludic.contrib.django.LudicMiddleware",
4   ]

Let's create a simple HTML page using Ludic elements in a Django view. Here is the content of the views.py file rendering a valid HTML page:

 1   from django.http import HttpRequest
 2   from ludic.contrib.django import LudicResponse
 3   from ludic.html import html, head, body, div, h1, p, title, b
 4   
 5   
 6   def index(request: HttpRequest) -> LudicResponse:
 7       return LudicResponse(
 8           html(
 9               head(
10                   title("My Page"),
11               ),
12               body(
13                   div(
14                       h1("My Homepage"),
15                       p(f"Hello {b("World!")}"),
16                       id="container",
17                   )
18               )
19           )
20       )

However, you are not limited to ludic.html module. You can build your own components or use the ones available in the catalog. Here is a simple example creating a page component and using it in a view:

 1   import json
 2   
 3   from django.http import HttpRequest
 4   from ludic.attrs import GlobalAttrs
 5   from ludic.catalog.layouts import Center, Stack
 6   from ludic.catalog.pages import HtmlPage, Head, Body
 7   from ludic.catalog.headers import H1
 8   from ludic.catalog.typography import Code, CodeBlock, Link, Paragraph
 9   from ludic.components import Component
10   from ludic.contrib.django import LudicResponse
11   from ludic.types import AnyChildren
12   
13   
14   class MyPage(Component[AnyChildren, GlobalAttrs]):
15       def render(self) -> HtmlPage:
16           return HtmlPage(
17               Head(title="My Page"),
18               Body(
19                   Center(
20                       Stack(*self.children, **self.attrs),
21                       style={"padding-block": self.theme.sizes.xxl},
22                   ),
23                   htmx_version="2.0.0",
24               ),
25           )
26   
27   
28   def index_with_components(request: HttpRequest) -> LudicResponse:
29       return LudicResponse(
30           MyPage(
31               H1("Demo Using The Catalog"),
32               Paragraph(
33                   "This page is using components from "
34                   f"{Link("Ludic framework.", to="https://getludic.dev")}"
35               ),
36               Paragraph(f"Here is the content of {Code("request.GET")}:"),
37               CodeBlock(
38                   json.dumps(request.GET.dict(), indent=4),
39                   language="json",
40               ),
41           )
42       )