Skip to main content

StreamField for native Django Admin or with Grappelli

Project description

Django StreamField

This is a simple realisation of StreamField's idea from Wagtail CMS for plain Django admin or with Grappelli skin.

Does not work with sqlite DB yet.

For editing content we use native popup mechanism in Django admin interface. This allow us to use other field's widgets inside the blocks as is.

For example, if you want to use in your blocks FileBrowseField from django-filebrowser, it will perfectly working without any additional settings.


pip install django-streamfield

How to use

Create new app called streamblocks

Put to streamblocks/ some models

that you want to use in your stream field. For example:

# streamblocks/

# one object
class RichText(models.Model):
    text = models.TextField(blank=True, null=True)   

    class Meta:
        # This will use as name of block in admin

# list of objects
class ImageWithText(models.Model):
    image = models.ImageField(upload_to="folder/")
    text = models.TextField(null=True, blank=True)

    # StreamField option for list of objects
    as_list = True

    class Meta:
        verbose_name="Images with text"

In streamblocks/ register blocks

for StreamField as list of your block models

# streamblocks/



Create templates for each models above, named as lowercase names of the models:

  1. streamblocks/templates/streamblocks/richtext.html
  2. streamblocks/templates/streamblocks/imagewithtext.html

And use block_content as context.

Note: block_content will be single object if no 'as_list' property in your model, and will be a list of objects if there is.

<div class="rich-text-block">
    {{ block_content|safe }}

<ul class="image-with-text-block">
    {% for block in block_content %}
        <img src="{{ block.image.url }}" alt="">
        <p>{{ block.text }}</p>
    {% endfor %}

Add apps to



Add streamfield.urls to main

urlpatterns += [
    path('streamfield/', include('streamfield.urls'))

Add StreamField to your model in your application

And add the models that you want to use in this stream as model_list

from streamfield.fields import StreamField

class Page(models.Model):
    stream = StreamField(
        verbose_name="Page blocks"

Then if you have your 'page' in context, you can get content by calling method

<div class="content">
    {{ }}


Models will automaticaly register in admin If you want provide custom admin class, first unregister models and register again, using StreamBlocksAdmin class.

from django.contrib import admin
from streamfield.admin import StreamBlocksAdmin

from streamblocks.models import RichText
class RichTextBlockAdmin(StreamBlocksAdmin, admin.ModelAdmin):

Complex Blocks

You may use StreamField as part of blocks and create with that way complex structure and use {{ block_content.<field_name>.render }}

Cache for reduce the number of database requests

There is two ways of caching:

  • Simple cache view with django cache
  • Create additional field, for example: 'stream_rendered' and render to this field html in save method
def save(self, *args, **kwargs):
    self.stream_rendered =
    super().save(*args, **kwargs)

...and use this field in your html


You may use STREAMFIELD_BLOCK_OPTIONS in to add some options to block For example:

    "margins": {
        "label": "Margins",
        "type": "checkbox",
        "default": True

Note: Now only type "checkbox" is working, the other options in plan.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-streamfield, version 1.0.3
Filename, size File type Python version Upload date Hashes
Filename, size django_streamfield-1.0.3-py3-none-any.whl (186.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size django-streamfield-1.0.3.tar.gz (171.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page