paper-streamfield 0.1.0

Implementation of the Wagtail's StreamField block picker for paper-admin.

paper-streamfield

Implementation of the Wagtail's StreamField block picker for paper-admin.

Compatibility

• python >= 3.8
• django >= 2.2
• paper-admin >= 4.3

Installation

Install the latest release with pip:

pip install paper-streamfield

Add streamfield to your INSTALLED_APPS in django's settings.py:

INSTALLED_APPS = (
    # other apps
    "streamfield",
)

How to use

1. Create some models that you want to use as blocks:

# blocks/models.py

from django.core.validators import MaxValueValidator, MinValueValidator
from django.db import models
from django.utils.text import Truncator
from django.utils.translation import gettext_lazy as _


class HeaderBlock(models.Model):
    text = models.TextField(
        _("text")
    )
    rank = models.PositiveSmallIntegerField(
        _("rank"),
        default=1,
        validators=[
            MinValueValidator(1),
            MaxValueValidator(6)
        ]
    )

    class Meta:
        verbose_name = "Header"

    def __str__(self):
        return Truncator(self.text).chars(64)


class TextBlock(models.Model):
    text = models.TextField(
        _("text")
    )

    class Meta:
        verbose_name = "Text"

    def __str__(self):
        return Truncator(self.text).chars(64)

2. Register this models using StreamBlockModelAdmin class.

# blocks/admin.py

from django.contrib import admin

from streamfield.admin import StreamBlockModelAdmin

from .models import HeaderBlock, TextBlock


@admin.register(HeaderBlock)
class HeaderBlockAdmin(StreamBlockModelAdmin):
    list_display = ["__str__", "rank"]


@admin.register(TextBlock)
class TextBlockAdmin(StreamBlockModelAdmin):
    pass

3. Create templates for each block model, named as lowercase model name or snake_cased model name.

<!-- blocks/templates/blocks/headerblock.html -->
<!-- or -->
<!-- blocks/templates/blocks/header_block.html -->
<h{{ block.rank }}>{{ block.text }}</h{{ block.rank }}>

<!-- blocks/templates/blocks/textblock.html -->
<!-- or -->
<!-- blocks/templates/blocks/text_block.html -->
<div>{{ block.text|linebreaks }}</div>

You can also use the block_template option to specify the template to use:

class HeaderBlock(models.Model):
    block_template = "blocks/header.html"
    ...

4. Add StreamField to your model:

# app/models.py

from django.db import models
from django.utils.translation import gettext_lazy as _

from streamfield.field.models import StreamField


class Page(models.Model):
    stream = StreamField(_("stream"), models=[
        "blocks.HeaderBlock",
        "blocks.TextBlock",
    ])

    class Meta:
        verbose_name = "Page"

Result:

Now you can create some blocks:

5. Use render_stream templatetag to render the stream field.

<!-- app/templates/index.html -->
{% load streamfield %}

{% render_stream page.stream %}

Result:

Special cases

Use another template engine

You can specify a template engine to render a specific block with block_template_engine option:

class HeaderBlock(models.Model):
    block_template = "blocks/header.html"
    block_template_engine = "jinja2"
    ...

Add extra context to blocks

You can add additional variables by passing keyword arguments to the render_stream templatetag:

<!-- app/templates/index.html -->
{% load streamfield %}

{% render_stream page.stream css_class="red" %}

<!-- text_block.html -->
<div class="{{ css_class }}">{{ block.text|linebreaks }}</div>

Access parent context from within a block

The parent context can be accessed via a parent_context variable:

<!-- app/templates/index.html -->
{% load streamfield %}

{% with css_class="blue" %}
  {% render_stream page.stream %}
{% endwith %}

<!-- text_block.html -->
<div class="{{ parent_context.css_class }}">{{ block.text|linebreaks }}</div>