Customizing FeinCMS Part 1

Update: We can now use a list of our Template instances instead of a list of dicts whilst registering a template.

pages.models:

from feincms.models import Base, Template as FeinCMSTemplate
from feincms.module.page.models import Page


class Template(FeinCMSTemplate):
    def __init__(
        self, title, path, regions, key=None, preview_image=None, unique=False
    ):
        super(Template, self).__init__(
            title, path, regions, key=key, preview_image=preview_image
        )
        self.unique = unique


Page.register_templates(
    Template(
        key='internalpage',
        title='Internal Page',
        path='pages/internal.html',
        regions=(
            ('main', 'Main Content'),
        )
    ), Template(
        key='homepage',
        title='Home Page',
        path='pages/home_page.html',
        regions=(
            ('home_main', 'Main Content'),
        ),
        unique=True
    )
)

So far so easy.

The next step is to hide unique templates from admin forms when they have already been assigned to other pages, we do this by changing PageAdminForm.

But first of all we have to stop and think about what we are doing.

We are going to write a generic check_template function which checks if a template is valid given a particular set of arguments and raises an exception if it doesn't. Why an Exception? Just because it's flexible. If we want to add a new feature all we have to do is create a new Exception and write a few lines of code for validating a page.

So create a new file called pages.exceptions.py with the definition of a new Exception in it:

pages.exceptions:

class UniqueTemplateException(Exception):
    pass

Now we can finally add our validation.

pages.admin:

from django.contrib import admin
from django.conf import settings as django_settings
from django.utils.translation import ugettext_lazy as _
from django.utils.safestring import mark_safe
from django.forms.util import ErrorList
from django.http import HttpResponse

from feincms.module.page.models import Page, PageAdmin as PageAdminOld
from feincms.module.page.models import PageAdminForm as PageAdminFormOld


from pages.exceptions import UniqueTemplateException


def check_template(model, template, instance=None, parent=None):
    if template.unique and model.objects.filter(
                                template_key=template.key
                            ).exclude(id=instance.id if instance else -1).count():
        raise UniqueTemplateException()


def is_template_valid(model, template, instance=None, parent=None):
    try:
        check_template(model, template, instance=instance, parent=parent)
        return True
    except UniqueTemplateException:
        pass

    return False


class PageAdminForm(PageAdminFormOld):
    def __init__(self, *args, **kwargs):
        super(PageAdminForm, self).__init__(*args, **kwargs)

        instance = kwargs.get('instance')
        parent = kwargs.get('initial', {}).get('parent')
        if not parent and instance:
            parent = instance.parent
        templates = self.get_valid_templates(instance, parent)

        choices = []
        for key, template in templates.items():
            if template.preview_image:
                choices.append(
                    (template.key, mark_safe(
                        u'<img src="%s" alt="%s" /> %s' % (
                            template.preview_image, template.key, template.title
                        )
                    ))
                )
            else:
                choices.append((template.key, template.title))

        self.fields['template_key'].choices = choices
        if choices:
            self.fields['template_key'].default = choices[0][0]

    def clean(self):
        cleaned_data = super(PageAdminForm, self).clean()

        # No need to think further, let the user correct errors first
        if self._errors:
            return cleaned_data

        parent = cleaned_data.get('parent')
        if parent:
            template_key = cleaned_data['template_key']
            template = self.Meta.model._feincms_templates[template_key]

            try:
                check_template(
                    self.Meta.model, template, instance=self.instance, parent=parent
                )
            except UniqueTemplateException:
                self._errors['parent'] = ErrorList(
                    [_('Template already used somewhere else.')]
                )
                del cleaned_data['parent']
        return cleaned_data

    def get_valid_templates(self, instance=None, parent=None):
        """
            @return dict: dict containing all the templates valid for this instance
                (excluding unique ones already used etc.)
        """
        templates = self.Meta.model._feincms_templates.copy()

        return dict(
            filter(
                lambda (key, template): is_template_valid(
                    self.Meta.model, template, instance=instance, parent=parent
                ), templates.items()
            )
        )


class PageAdmin(PageAdminOld):
    form = PageAdminForm


# We have to unregister the default configuration, and register ours
admin.site.unregister(Page)
admin.site.register(Page, PageAdmin)

It might seem tricky but it's really straightforward. There are just a few new things:

• check_template: raises an exception if the template isn't valid given a particular set of params
• is_template_valid: shortcut. It returns True if the template is valid given a particular set of params
• PageAdminForm.clean: checks if the template assigned can be used
• PageAdminForm.get_valid_templates: returns all the valid templates for the current instance we are adding/changing
• PageAdminForm.__init__: reinitialize the template_key field by excluding unique templates which have already been assigned to other pages

Conclusions

As you can see, with a few lines of code we have added our new unique template feature.

Most importantly, we haven't changed the main code and we can still upgrade feinCMS or implement extra custom validation.

Next

Customizing FeinCMS Part 2: First-Level-Only templates