How to use placeholders outside the CMS¶

Admin Integration¶

Your model with PlaceholderFields can still be edited in the admin. However, any PlaceholderFields in it will only be available for editing from the frontend. PlaceholderFields must not be present in any fieldsets, fields, form or other ModelAdmin field’s definition attribute.

To provide admin support for a model with a PlaceholderField in your application’s admin, you need to use the mixin PlaceholderAdminMixin along with the ModelAdmin. Note that the PlaceholderAdminMixin must precede the ModelAdmin in the class definition:

from django.contrib import admin
from cms.admin.placeholderadmin import PlaceholderAdminMixin
from myapp.models import MyModel

class MyModelAdmin(PlaceholderAdminMixin, admin.ModelAdmin):
    pass

admin.site.register(MyModel, MyModelAdmin)

I18N Placeholders¶

Out of the box PlaceholderAdminMixin supports multiple languages and will display language tabs. If you extend your model admin class derived from PlaceholderAdminMixin and overwrite change_form_template have a look at admin/placeholders/placeholder/change_form.html to see how to display the language tabs.

If you need other fields translated as well, django CMS has support for django-hvad. If you use a TranslatableModel model be sure to not include the placeholder fields amongst the translated fields:

class MultilingualExample1(TranslatableModel):
    translations = TranslatedFields(
        title=models.CharField('title', max_length=255),
        description=models.CharField('description', max_length=255),
    )
    placeholder_1 = PlaceholderField('placeholder_1')

    def __unicode__(self):
        return self.title

Be sure to combine both hvad’s TranslatableAdmin and PlaceholderAdminMixin when registering your model with the admin site:

from cms.admin.placeholderadmin import PlaceholderAdminMixin
from django.contrib import admin
from hvad.admin import TranslatableAdmin
from myapp.models import MultilingualExample1

class MultilingualModelAdmin(TranslatableAdmin, PlaceholderAdminMixin, admin.ModelAdmin):
    pass

admin.site.register(MultilingualExample1, MultilingualModelAdmin)

Templates¶

To render the placeholder in a template you use the render_placeholder tag from the cms_tags template tag library:

{% load cms_tags %}

{% render_placeholder mymodel_instance.my_placeholder "640" %}

The render_placeholder tag takes the following parameters:

• PlaceholderField instance

• width parameter for context sensitive plugins (optional)

• language keyword plus language-code string to render content in the specified language (optional)

The view in which you render your placeholder field must return the request object in the context. This is typically achieved in Django applications by using RequestContext:

from django.shortcuts import get_object_or_404, render

def my_model_detail(request, id):
    object = get_object_or_404(MyModel, id=id)
    return render(request, 'my_model_detail.html', {
        'object': object,
    })

If you want to render plugins from a specific language, you can use the tag like this:

{% load cms_tags %}

{% render_placeholder mymodel_instance.my_placeholder language 'en' %}

Options¶

If you need to change ?edit to a custom string (say, ?admin_on) you may set CMS_TOOLBAR_URL__EDIT_ON variable in your settings.py to "admin_on".

You may also change other URLs with similar settings:

• ?edit_off (CMS_TOOLBAR_URL__EDIT_OFF)

• ?build (CMS_TOOLBAR_URL__BUILD)

• ?toolbar_off (CMS_TOOLBAR_URL__DISABLE)

When changing these settings, please be careful because you might inadvertently replace reserved strings in system (such as ?page). We recommended you use safely unique strings for this option (such as secret_admin or company_name).

Permissions¶

To be able to edit a placeholder user must be a staff member and needs either edit permissions on the model that contains the PlaceholderField, or permissions for that specific instance of that model. Required permissions for edit actions are:

• to add: require add or change permission on related Model or instance.

• to change: require add or change permission on related Model or instance.

• to delete: require add or change or delete permission on related Model or instance.

With this logic, an user who can change a Model’s instance but can not add a new Model’s instance will be able to add some placeholders or plugins to existing Model’s instances.

Model permissions are usually added through the default Django auth application and its admin interface. Object-level permission can be handled by writing a custom authentication backend as described in django docs

For example, if there is a UserProfile model that contains a PlaceholderField then the custom backend can refer to a has_perm method (on the model) that grants all rights to current user only based on the user’s UserProfile object:

def has_perm(self, user_obj, perm, obj=None):
    if not user_obj.is_staff:
        return False
    if isinstance(obj, UserProfile):
        if user_obj.get_profile()==obj:
            return True
    return False