django-cms-helpers

django-cms-helpers is a collection of helpers when working with django-cms.

Features

• templatetag for getting title extension object.

• anylink extension for cms pages.

• boilerplate code for ExtensionToolbar.

• FilerFileField extension to validate file extension and make default_alt_text required.

Requirements

django-cms-helpers supports Python 3 only and requires at least Django 3.2 and django-cms 3.9.

Prepare for development

A Python 3.8+ interpreter is required in addition to poetry.

$ poetry install

Now you’re ready to run the tests:

$ poetry run py.test

Resources

• Documentation

• Bug Tracker

• Code

Contents:

Installation

• Install with pip:

  pip install django-cms-helpers
  

• Your INSTALLED_APPS setting:

  INSTALLED_APPS = (
      # ...
      'cms',
  
      'cms_helpers',
  )
  

• To use CmsPageLink anylink extension install django-anylink and add to your settings:

  INSTALLED_APPS = (
      # ...
      'anylink',
  )
  
  ANYLINK_EXTENSIONS = (
      # ...
      'cms_helpers.anylink_extensions.CmsPageLink',
  )
  

• To use FilerFileField install django-filer and add to your settings:

  INSTALLED_APPS = (
      # ...
      'mptt',
      'easy_thumbnails',
      'filer'
  )
  

Usage

page_titleextension templatetag

To obtain cms page title extension object in template use page_titleextension templatetag. The tag requires cms page id and name of extension model.

{% load cms_helpers %}

{% page_titleextension 1 "extensionmodel" %}

The page_titleextension templatetag is cached by default if CMS_PLUGIN_CACHE is True, which is the default. You can override globally by setting CMS_HELPERS_PAGE_TITLEEXTENSION_CACHE = False. You can also override locally the template tag using the do_cache keyword argument.

{% load cms_helpers %}

{% page_titleextension 1 "extensionmodel" do_cache=False %}

anylink extension for cms pages

To create links to cms pages with anylink library use CmsPageLink extension. The extension needs to be added in settings. Details on how to use anylink can be found here.

 ANYLINK_EXTENSIONS = (
     ...

     'cms_helpers.anylink_extensions.CmsPageLink',
)

cms title extension toolbar

TitleExtensionToolbar provides boilerplate code for your ExtensionToolbar model. It includes populate function and enables setting the position of the extension in the menu through insert_after parameter.

from cms.extensions import TitleExtension
from cms.extensions.extension_pool import extension_pool
from cms.toolbar_pool import toolbar_pool
from cms_helpers.cms_toolbars import TitleExtensionToolbar


@extension_pool.register
class YourExtensionModel(TitleExtension):
    name = models.CharField(max_length=255)

    class Meta:
        verbose_name = 'yourExtension'


@toolbar_pool.register
class ExtensionToolbar(TitleExtensionToolbar):
    model = YourExtensionModel
    insert_after = 'Advanced settings'

filer field extension

FilerFileField overwrites the native filer.fields.file.FilerFileField and adds file extensions validation and sets default_alt_text to required (with alt_text_required it can be also set to not required).

from cms_helpers.filer_fields import FilerFileField
from django.db import models


class YourModel(models.Model):
    your_file = FilerFileField(
        _('Your File'),
        extensions=('png', 'jpg', 'gif'),
        alt_text_required=False
    )

Changelog

2.0.0 (2023-02-07)

• Add support for Django 4.1 and django-cms 3.11

• Drop support for Django < 3.2

• Drop support for django-cms < 3.9

1.0.0 (2022-04-29)

• Drop support for Django < 2.2

• Drop support for django-cms < 3.7

• Drop support for Python < 3.8

• Add support for Django 3.2, django-cms 3.10

0.3.0 (2020-09-29)

• Add caching for page_titleextension template tag

0.2.0 (2019-04-30)

• Add support for multiple languages to TitleExtensionToolbar

• Fix support for multi-domain links in django-cms 3.6

0.1.0 (2019-03-20)

• Add compatibility with django 2 and django-cms 3.6

0.0.1 (2019-02-07)

• Initial release of django-cms-helpers

Api documentation:

API Reference

cms_helpers package

Subpackages

cms_helpers.templatetags package

Submodules

cms_helpers.templatetags.cms_helpers module

cms_helpers.templatetags.cms_helpers.is_caching_desired(do_cache)

cms_helpers.templatetags.cms_helpers.page_titleextension(context, page_id, extension, do_cache=None)

Submodules

cms_helpers.anylink_extensions module

class cms_helpers.anylink_extensions.CmsPageLink(**kwargs)

Bases: BaseLink

name = 'page'

verbose_name = 'CMS Page'

provided_fields = ('page', 'anchor')

configure_model(model)

get_absolute_url(link)

cms_helpers.cms_toolbars module

class cms_helpers.cms_toolbars.TitleExtensionToolbar(request, toolbar, is_current_app, app_path)

Bases: ExtensionToolbar

model = None

insert_after = None

get_item_position(menu)

populate()

property media

cms_helpers.filer_fields module

class cms_helpers.filer_fields.AdminFileFormField(*args, **kwargs)

Bases: AdminFileFormField

clean(value)

Validate the given value and return its “cleaned” value as an appropriate Python object. Raise ValidationError for any errors.

class cms_helpers.filer_fields.FilerFileField(verbose_name=None, *args, **kwargs)

Bases: FilerFileField

default_form_class

alias of AdminFileFormField

formfield(**kwargs)

Pass limit_choices_to to the field being constructed.

Only passes it if there is a type that supports related fields. This is a similar strategy used to pass the queryset to the field being constructed.

Indices and tables

• Index

• Module Index

• Search Page