Install¶

Install package in your environment :

pip install cmsplugin-blocks

For development install see Install for development, this is also a good way to quick start a demonstration since development install have a demonstration site ready to run.

Configuration¶

Hint

Your project will need to be correctly configured for DjangoCMS, this document won’t treat about it.

Add it to your installed Django apps in settings :

INSTALLED_APPS = (
    ...
    "sorl.thumbnail",
    "smart_media",
    "cmsplugin_blocks",
)

Note

cmsplugin_blocks need to be added after DjangoCMS;
If your project use easy_thumbnails, you will have to put Sorl and SmartMedia before it, see SmartMedia configuration documentation.

Then import the default settings:

from smart_media.settings import *
from cmsplugin_blocks.defaults import *

You may not import these defaults but you will have to define them all in your project settings.

Note

Instead, if your project use django-configuration, your settings class can inherits from from cmsplugin_blocks.contrib.django_configuration import CmsBlocksDefaultSettings and the settings class from SmartMedia see SmartMedia configuration documentation.

Finally you will have to apply database migrations.

Settings¶

These are the default settings you can override in your project settings.

Hint

All feature choices are list of tuple. First choice item is a valid CSS class name (not a selector, only alphanumeric, - and _), second item is the label for select option. As an exemple:

BLOCKS_ALBUM_FEATURES = [
    ("foo", "Foo"),
    ("text-center", "Centered text"),
]

cmsplugin_blocks.defaults.BLOCKS_ENABLED_PLUGINS = ['AlbumPlugin', 'CardPlugin', 'ContainerPlugin', 'HeroPlugin', 'SliderPlugin']¶: Enabled plugins to register. Unregistered plugin models are still created but not available anymore in DjangoCMS.

cmsplugin_blocks.defaults.BLOCKS_ALBUM_FEATURES = []¶: Available feature classes for Album model.

cmsplugin_blocks.defaults.BLOCKS_ALBUMITEM_FEATURES = []¶: Available feature classes for AlbumItem model.

cmsplugin_blocks.defaults.BLOCKS_CARD_FEATURES = []¶: Available feature classes for Card model.

cmsplugin_blocks.defaults.BLOCKS_CONTAINER_FEATURES = []¶: Available feature classes for Container model.

cmsplugin_blocks.defaults.BLOCKS_HERO_FEATURES = []¶: Available feature classes for Hero model.

cmsplugin_blocks.defaults.BLOCKS_SLIDER_FEATURES = []¶: Available feature classes for Slider model.

cmsplugin_blocks.defaults.BLOCKS_SLIDERITEM_FEATURES = []¶: Available feature classes for SliderItem model.

cmsplugin_blocks.defaults.BLOCKS_ALBUM_TEMPLATES = [('cmsplugin_blocks/album/default.html', 'Default')]¶: Available template choices to render an Album object and its items.

cmsplugin_blocks.defaults.BLOCKS_CARD_TEMPLATES = [('cmsplugin_blocks/card/default.html', 'Default')]¶: Available template choices to render an Card object.

cmsplugin_blocks.defaults.BLOCKS_CONTAINER_TEMPLATES = [('cmsplugin_blocks/container/default.html', 'Default')]¶: Available template choices to render an Container object.

cmsplugin_blocks.defaults.BLOCKS_HERO_TEMPLATES = [('cmsplugin_blocks/hero/default.html', 'Default')]¶: Available template choices to render an Hero object.

cmsplugin_blocks.defaults.BLOCKS_SLIDER_TEMPLATES = [('cmsplugin_blocks/slider/default.html', 'Default')]¶: Available template choices to render a Slider object and its items.

cmsplugin_blocks.defaults.BLOCKS_ALLOWED_IMAGE_EXTENSIONS = ['jpg', 'jpeg', 'svg', 'gif', 'png']¶

Allowed image file extensions for images. This is used in plugin form with image field for validation and also for allowed formats in media_thumb template tag (smart format).

Note that image field validation is naively based on file extension, not on the real image format so this could be tricked.

You should accord this list with setting SMART_FORMAT_AVAILABLE_FORMATS.

cmsplugin_blocks.defaults.BLOCKS_MODEL_TRUNCATION_LENGTH = 4¶

Word length limit for model string representation truncation.

This is used in every model string which are displayed in their plugin resume in DjangoCMS placeholder menu.

With a length of 4 words, an object title “Foo bar Lorem ipsum ping” will be cutted to “Foo bar Lorem ipsum”.

cmsplugin_blocks.defaults.BLOCKS_MODEL_TRUNCATION_CHR = '...'¶

Truncation string added to the end of an object title when it have been truncated when over the word limit.

Use an empty string if you don’t want any character at the end of truncation.

cmsplugin_blocks.defaults.BLOCKS_MASSUPLOAD_FILESIZE_LIMIT = 42991616¶

Maximum file size allowed for mass upload feature. Maximum file size (in bytes) allowed for ZIP archive for mass upload.

This is a limit at Django level so files are still stored until post validation.

You should mind to configure a limit on your webserver to avoid basic attacks with very big files.

Value could be something like:

5242880 for ~5MiO;
10485760 for ~10MiO;
42991616 for ~50MiO.

See:

https://stackoverflow.com/questions/2472422/django-file-upload-size-limit

About CKEditor settings¶

djangocms-text-ckeditor get configurations from CKEDITOR_SETTINGS["toolbar_HTMLField"] when used from external plugin but use CKEDITOR_SETTINGS["toolbar_CMS"] for internal plugin like its basic TextPlugin.

You will have to copy toolbar_CMS config to toolbar_HTMLField if you want to share the same configuration for every plugins:

CKEDITOR_SETTINGS["toolbar_HTMLField"] = CKEDITOR_SETTINGS["toolbar_CMS"]