{
"info": {
"author": "Yury Lapshinov",
"author_email": "y.raagin@gmail.com",
"bugtrack_url": null,
"classifiers": [
"License :: OSI Approved :: BSD License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3"
],
"description": "# Django StreamField\n\nThis is a simple realisation of StreamField's idea of Wagtail CMS for plain Django admin or with Grappelli skin.\n\n## Highlights\nYou can build your page with different kind of blocks. \nSort them and sort the lists inside the blocks.\n\nFor editing content inside the blocks, it use native popup mechanism in Django admin interface.\nThis allow you to use other field's widgets inside the blocks as is.\nFor example, if you want to use in your blocks FileBrowseField\nfrom django-filebrowser, it will perfectly working \nwithout any additional settings.\n\nModule also working with [Grappelli Interface](https://github.com/sehmaschine/django-grappelli) (Optional)\n\n\n\n## Contents\n\n- [Installation](#installation)\n- [How to use](#how-to-use)\n- [Admin](#admin)\n - [Custom admin class for block's models](#custom-admin-class-for-blocks-models)\n - [Custom templates for render block models in admin](#custom-templates-for-render-block-models-in-admin)\n - [Override how to render block's fields in admin](#override-how-to-render-blocks-fields-in-admin)\n - [Override list of blocks for your StreamField in admin.py](#override-list-of-blocks-for-your-streamfield-in-adminpy)\n- [Block options](#block-options)\n- [Special cases](#special-cases)\n - [Complex Blocks](#complex-blocks) \n - [Blocks without data in database. Only templates](#blocks-without-data-in-database-only-templates)\n - [Add extra context to blocks](#add-extra-context-to-blocks)\n - [Cache for reduce the number of database requests](#cache-for-reduce-the-number-of-database-requests)\n- [Settings](#settings)\n\n## Installation\n\nRequirements: `django>=2.*`\n\n`pip install django-streamfield`\n\n## How to use\n\n**1. Create new app called `streamblocks`**\n\n**2. Put to `streamblocks/models.py` some models**\n\n...that you want to use in your stream field.\nAnd add this models in STREAMBLOCKS_MODELS list.\nFor example:\n\n```python\n# streamblocks/models.py\n\n# one object\nclass RichText(models.Model):\n text = models.TextField(blank=True, null=True) \n\n class Meta:\n # This will use as name of block in admin\n verbose_name=\"Text\"\n\n# list of objects\nclass ImageWithText(models.Model):\n image = models.ImageField(upload_to=\"folder/\")\n text = models.TextField(null=True, blank=True)\n\n # StreamField option for list of objects\n as_list = True\n\n class Meta:\n verbose_name=\"Images with text\"\n\n# Register blocks for StreamField as list of models\nSTREAMBLOCKS_MODELS = [\n RichText,\n ImageWithText\n]\n```\n\n**3. Create templates for each models above, named as lowercase names of the models:**\n\n1. streamblocks/templates/streamblocks/richtext.html\n2. streamblocks/templates/streamblocks/imagewithtext.html\n\nAnd use `block_content` as context.\n\n> Note: block_content will be single object \nif no 'as_list' property in your model, \nand will be a list of objects if there is.\n\n```html\n\n
\n {{ block_content.text|safe }}\n
\n```\n```html\n\n
\n {% for block in block_content %}\n
\n \n
{{ block.text }}
\n
\n {% endfor %}\n
\n```\n\n**4. Add apps to settings.py**\n\nAdd to INSTALLED_APPS\n\n```python\nINSTALLED_APPS = [\n ...\n 'streamblocks',\n 'streamfield',\n ...\n```\n\n**5. Add streamfield.urls to main urls.py**\n```python\nurlpatterns += [\n path('streamfield/', include('streamfield.urls'))\n]\n```\n\n**6. Add StreamField to your model in your application**\n\nAnd add the models that you want to use in this stream as model_list\n```python\n# models.py\nfrom streamfield.fields import StreamField\nfrom streamblocks.models import RichText, ImageWithText\n\nclass Page(models.Model):\n stream = StreamField(\n model_list=[ \n RichText,\n ImageWithText\n ],\n verbose_name=\"Page blocks\"\n )\n```\n\nThen if you have your 'page' in context, \nyou can get content by field cached property page.stream.render\n```html\n...\n
\n {{ page.stream.render }}\n
\n...\n```\n\nOr, if you need extra context in blocks, you may use template tag:\n```html\n{% load streamfield_tags %}\n...\n
\n...\n```\n\n\n## Admin\n### Custom admin class for block's models\nModels will automaticaly register in admin.\nIf you want provide custom admin class, \nfirst unregister models and register again, using `StreamBlocksAdmin` class.\n\n```python\n# streamblocks/admin.py\n\nfrom django.contrib import admin\nfrom streamfield.admin import StreamBlocksAdmin\n\nfrom streamblocks.models import RichText\n\nadmin.site.unregister(RichText)\n@admin.register(RichText)\nclass RichTextBlockAdmin(StreamBlocksAdmin, admin.ModelAdmin):\n pass\n```\n\n### Custom templates for render block models in admin\nIf you need to customize admin templates for block models wich you are using, you need to put templates named as \ndescribed in section 3 (above). but put it inside \"admin\" folder.\n\nFor example for RichText block it will be:\n\n`streamblocks/templates/streamblocks/admin/richtext.html`\n\nAs context use \"form\":\n```html\n{{ form.text.value }}\n```\n### Override how to render block's fields in admin\nCreate custom template for field with name as lowercased field widget name, and put it inside `.../streamblocks/admin/fields/` folder.\n\nFor example for TextField widget (Textarea) of RichText block, it will be:\n\n`streamblocks/templates/streamblocks/admin/fields/textarea.html`\n\nAs context use \"field\":\n```html\n{{ field.value|default:\"\"|safe }}\n```\n\n### Override list of blocks for your StreamField in admin.py\nTypicaly you set the blocks in your models as `model_list` attribute of StreamField field.\nBut if you want to change blocks, for example depending on object, you can do it in admin site\nof your model. Suppose you want to use only `RichText` on page with id=1.\n\n```python\n# admin.py\nfrom streamfield.fields import StreamFieldWidget\nfrom streamblocks.models import RichText\nfrom .models import Page\n\nclass PageAdmin(models.Admin):\n\n def get_form(self, request, obj=None, **kwargs):\n form = super().get_form(request, obj, **kwargs)\n if obj and obj.id == 1:\n form.base_fields['stream'].widget = StreamFieldWidget(attrs={\n 'model_list': [ RichText ]\n })\n return form\n```\nBe careful with already existing blocks in db. If you remove them from admin, it produce error.\n\n## Block options\nYou may use `options` property in your streamblocks models to add some additional options to your block.\nThis is useful with `as_list` property when you need to add some options to whole block not separatly to each object of this list.\n\nFor example:\n```python\n# streamblocks/models.py\n\n# list of objects as slider\nclass Slide(models.Model):\n image = models.ImageField(upload_to=\"folder/\")\n text = models.TextField(null=True, blank=True)\n\n # StreamField option for list of objects\n as_list = True\n\n options = {\n \"autoplay\": {\n \"label\": \"Autoplay slider\",\n \"type\": \"checkbox\",\n \"default\": False\n }\n }\n\n class Meta:\n verbose_name=\"Slide\"\n verbose_name_plural=\"Slider\"\n```\nIn block template you can use this options as `options.autoplay`\nIn page admin you will see it on the bottom of this block.\n> Note: Now only \"checkbox\" type is working.\nYou may apply options for all blocks with `STREAMFIELD_BLOCK_OPTIONS` (See [Settings](#settings))\n\n## Special cases\n### Complex Blocks\nYou may use StreamField as part of blocks and create with that way complex structure\nand use `{{ block_content..render }}`\n\n### Blocks without data in database. Only templates.\nYou may use it for widgets or separators or for whatever you want...\nJust make the block model `abstract`.\n```python\nclass EmptyBlock(models.Model):\n class Meta:\n abstract = True\n verbose_name='Empty space'\n```\nand use `streamblocks/templates/streamblocks/emptyblock.html` for your content.\n> Note: Don't forget to register a block in STREAMBLOCKS_MODELS\n\n### Add extra context to blocks\nSupose, you need to add some data to blocks from global context.\nInstead of using render property in template `{{ page.stream.render }}`,\nyou need to use template tag `stream_render` from `streamfield_tags` with keywords arguments.\n\nFor example, if you have in page template `request` and `page` objects and want to use it in blocks:\n```html\n{% load streamfield_tags %}\n...\n