THE BLOG

#Autorização

#CMS

#Django

#Headless

#Python

#Token

Wagtail and Django Thumbnail

A Página de Publicação

Headless CMS API com o Django Wagtail: Post model

junho de 2025

Tô animado para dividir mais com vocês sobre a criação do blog. Depois de tudo estar funcionando corretamente: back + front + infra, fico orgulhoso de ver o produto final e ter consciência de que todo o esforço até aqui, valeu a pena. Mesmo diante das dificuldades, consegui finalizar e, mesmo não possuindo muita experiência com desing, a aplicação ficou muito bonita.

Nesse post vou falar da model Post do blog, sobre como configurar corretamente a classe junto ao preview do Wagtail, permitindo acompanhar o Front-end ao editar a página no CMS. E, também, sobre como adicionar campos que compõe uma publicação como, por exemplo, imagens, código, entre outros elementos.

Django // Wagtail

Para acompanhar o conteúdo, é necessário que se tenha domínio dos conceitos básicos de Django, por isso, recomendo o tutorial oficial. Além disso, é importante entender os conceitos de uma API Rest, a comunicação entre Front-end e Back-end será feita através de requisições na API.

Já o Wagtail é um CMS que pode ser integrado a uma aplicação Django, com uma interface administrativa completa que tem suporte a funcionalidade como:

Sistema de páginas e hierarquias
Gestão de imagens e documentos
Mecanismo de busca integrada com ElasticSearch ou PostgresSQL
API nativa do framework para acessar página e recursos

E para embasamento, recomendo o blog do Michael Yin e o seu livro também, uma didática bem pratica e com bastante exemplos de código e implementações completas

Headless // CMS

Por padrão, o CMS já nos permite implementar interfaces usando html css e todo ecossistema de templates do Django, em uma solução que deixa juntos a camada de apresentação e dados. Recomendo veementemente optar por esse modelo de desenvolvimento. Ao separar o Front-end, a complexidade escala bastante e indico deixar a decisão de uma possível separação para o futuro, quando essa necessidade ficar clara.

Mesmo eu gostando de trabalhar com frameworks reativos, não recomendo o seu uso de maneira indiscriminada. O principal motivo que optei pelo uso foi pela prática e familiaridade.

class PostPage(HeadlessPreviewMixin, Page):
    header_image = models.ForeignKey(
        "wagtailimages.Image",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="+",
    )
    subtitle = models.CharField(max_length=255, default="Blog post subtitle")
    description = models.CharField(
        max_length=255,
        default="Vici consequat justo enim. Venenatis eget adipiscing luctus lorem.",
    )
    body = StreamField(BodyBlock(), blank=True)
    tags = ClusterTaggableManager(through="blog.PostPageTag", blank=True)

    def get_preview_url(self, req=None, token=None):

        if not token:
            return None
        base_url = settings.WAGTAIL_HEADLESS_PREVIEW.get("CLIENT_URLS", {}).get(
            "default", "http://localhost:3000"
        )
        page_identifier = self.slug
        locale = self.locale.language_code if hasattr(self, "locale") else "pt"
        client_url = f"{base_url}/{locale}/blog/{page_identifier}/"
        preview_url = f"{client_url}?token={token}"
        return preview_url

    class FormattedDateSerializer(serializers.Field):
        def to_representation(self, value):
            request = self.context.get("request", None)
            lang = request.GET.get("locale", "en") if request else "en"

            if lang == "pt":
                locale.setlocale(locale.LC_TIME, "pt_BR.UTF-8")
                return value.strftime("%B de %Y")  # Formato brasileiro
            locale.setlocale(locale.LC_TIME, "en_US.UTF-8")
            return value.strftime("%B of %Y")  # Formato americano

    content_panels = Page.content_panels + [
        FieldPanel("header_image"),
        FieldPanel("subtitle"),
        FieldPanel("description"),
        InlinePanel("categories", label="category"),
        # InlinePanel("post_pages", label="postpages"),
        FieldPanel("tags"),
        FieldPanel("body"),
    ]
    api_fields = [
        APIField("title"),
        APIField("body"),
        APIField("subtitle"),
        APIField("tags"),
        APIField("description"),
        APIField(
            "header_image_src",
            serializer=ImageRenditionField("fill-800x400", source="header_image"),
        ),
        APIField("first_published_at", serializer=FormattedDateSerializer()),
        APIField(
            "categories",
            serializer=PostPageBlogCategoryAPISerializer(many=True),
        ), 
    ]

from wagtail.blocks import (
    BooleanBlock,
    StructBlock,
    StreamBlock,
    CharBlock,
    RichTextBlock,
    ListBlock,
    TextBlock,
)
from wagtail.images.blocks import ImageChooserBlock
from wagtail.fields import RichTextField, StreamField
from django.db import models


class CustomImageChooserBlock(ImageChooserBlock):
    def get_api_representation(self, value, context=None):
        if value:
            return {
                "id": value.id,
                "title": value.title,
                "url": value.get_rendition("original").url,
                "thumbnail": value.get_rendition("fill-300x200").url,
                "description": value.description,
            }
        return None


class NoteBlock(StructBlock):
    content = RichTextBlock(help_text="Conteúdo da nota")
    type = CharBlock(
        choices=[
            ("info", "Informação"),
            ("warning", "Aviso"),
            ("danger", "Perigo"),
            ("success", "Sucesso"),
        ],
        default="info",
        help_text="Tipo de nota",
    )

    class Meta:
        icon = "info"
        label = "Nota"
        block_api_representation = "expand"


class TableBlock(StructBlock):
    headers = ListBlock(CharBlock(), help_text="Cabeçalhos da tabela")
    rows = ListBlock(
        ListBlock(RichTextBlock(), min_num=1), help_text="Linhas da tabela"
    )

    class Meta:
        icon = "table"
        label = "Tabela"
        block_api_representation = "expand"


class CodeFileBlock(StructBlock):
    filename = CharBlock(help_text="Name of the file")
    language = CharBlock(
        choices=[
            ("bash", "Bash"),
            ("django", "Django"),
            ("dockerfile", "Dockerfile"),
            ("pgsql", "Pgsql"),
            ("shell", "Shell"),
            ("python", "Python"),
            ("makefile", "Makefile"),
            ("javascript", "JavaScript"),
            ("typescript", "TypeScript"),
            ("css", "CSS"),
            ("scss", "SCSS"),
            ("json", "JSON"),
            ("yaml", "YAML"),
            ("markdown", "Markdown"),
            ("rust", "Rust"),
            ("go", "Go"),
            ("dart", "Dart"),
            ("shell", "Shell/Bash"),
            ("sql", "SQL"),
        ],
        default="python",
    )
    code = TextBlock(help_text="Code content for the file")


class NoteBlock(StructBlock):
    content = RichTextBlock(help_text="Conteúdo da nota")
    type = CharBlock(
        choices=[
            ("info", "Informação"),
            ("warning", "Aviso"),
            ("danger", "Perigo"),
            ("success", "Sucesso"),
        ],
        default="info",
        help_text="Tipo de nota",
    )

    class Meta:
        icon = "info"
        label = "Nota"
        block_api_representation = "expand"


class TableBlock(StructBlock):
    headers = ListBlock(CharBlock(), help_text="Cabeçalhos da tabela")
    rows = ListBlock(
        ListBlock(RichTextBlock(), min_num=1), help_text="Linhas da tabela"
    )

    class Meta:
        icon = "table"
        label = "Tabela"
        block_api_representation = "expand"


class OrderedListBlock(StructBlock):
    items = ListBlock(RichTextBlock(), help_text="Lista de items")

    class Meta:
        icon = "list-ol"
        label = "Lista Ordenada"
        block_api_representation = "expand"


class UnorderedListBlock(StructBlock):
    items = ListBlock(RichTextBlock(), help_text="Lista de items")

    class Meta:
        icon = "list-ul"
        label = "Lista Não Ordenada"
        block_api_representation = "expand"


class CodeBlock(StructBlock):
    files = ListBlock(CodeFileBlock(), help_text="Multiple code files")

    class Meta:
        icon = "code"
        block_api_representation = "expand"


class Image(StructBlock):
    image = CustomImageChooserBlock()

    class Meta:
        icon = "image"
        block_api_representation = "expand"


class QuoteBlock(Image):
    quote = RichTextBlock(help_text="Texto da citação")
    attribution = CharBlock(required=False, help_text="Autor da citação")
    role = CharBlock(required=False, help_text="Cargo ou função do autor")

    class Meta:
        icon = "openquote"
        block_api_representation = "expand"


class ImageText(Image):
    reverse = BooleanBlock(required=False)
    text = RichTextBlock()

    class Meta:
        block_api_representation = "expand"


class EmbedBlock(StructBlock):
    PROVIDER_CHOICES = [
        ("youtube", "YouTube"),
        ("vimeo", "Vimeo"),
        ("instagram", "Instagram"),
        ("twitter", "Twitter"),
        ("tiktok", "TikTok"),
        ("soundcloud", "SoundCloud"),
        ("spotify", "Spotify"),
        ("other", "Outro Site"),
    ]

    provider = CharBlock(
        choices=PROVIDER_CHOICES, help_text="Selecione a plataforma de mídia"
    )

    embed_code = CharBlock(
        required=False,
        help_text="Código de incorporação fornecido pelo site (se disponível)",
    )

    url = CharBlock(help_text="URL completa do conteúdo a ser incorporado")
    caption = CharBlock(required=False, help_text="Legenda opcional para o embed")

    class Meta:
        icon = "media"
        label = "Incorporar Mídia"
        block_api_representation = "expand"


class BodyBlock(StreamBlock):
    h1 = CharBlock()
    h2 = CharBlock()
    paragraph = RichTextBlock()
    code = CodeBlock()
    quote = QuoteBlock()
    image = Image()
    image_text = ImageText()
    image_carousel = ListBlock(CustomImageChooserBlock())
    thumbnail_gallery = ListBlock(CustomImageChooserBlock())
    ordered_list = OrderedListBlock()
    unordered_list = UnorderedListBlock()
    note = NoteBlock()
    table = TableBlock()
    embed = EmbedBlock()

A página de publicação