Django Basic CMS reference API

The application model

Django Basic CMS declare rather simple models: Page Content and PageAlias.

Those Django models have the following relations:

Placeholders

Placeholder module, that’s where the smart things happen.

class basic_cms.placeholders.ContactForm(data=None, files=None, auto_id=u'id_%s', prefix=None, initial=None, error_class=<class 'django.forms.util.ErrorList'>, label_suffix=u':', empty_permitted=False)

base_fields = {'email': <django.forms.fields.EmailField object at 0x487e450>, 'subject': <django.forms.fields.CharField object at 0x487e5d0>, 'message': <django.forms.fields.CharField object at 0x487e750>}

media

class basic_cms.placeholders.ContactPlaceholderNode(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False)

A contact PlaceholderNode example.

render(context)

class basic_cms.placeholders.FilePlaceholderNode(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False)

A PlaceholderNode that saves one file on disk.

PAGE_UPLOAD_ROOT setting define where to save the file.

get_field(page, language, initial=None)

save(page, language, data, change, extra_data=None)

class basic_cms.placeholders.ImagePlaceholderNode(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False)

A PlaceholderNode that saves one image on disk.

PAGE_UPLOAD_ROOT setting define where to save the image.

get_field(page, language, initial=None)

save(page, language, data, change, extra_data=None)

class basic_cms.placeholders.PlaceholderNode(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False)

This template node is used to output and save page content and dynamically generate input fields in the admin.

Parameters:

• name – the name of the placeholder you want to show/create
• page – the optional page object
• widget – the widget you want to use in the admin interface. Take a look into basic_cms.widgets to see which widgets are available.
• parsed – if the parsed word is given, the content of the placeholder is evaluated as template code, within the current context.
• as_varname – if as_varname is defined, no value will be returned. A variable will be created in the context with the defined name.
• inherited – inherit content from parent’s pages.
• untranslated – the placeholder’s content is the same for every language.

field

alias of CharField

get_content(page_obj, lang, lang_fallback=True)

get_content_from_context(context)

get_extra_data(data)

Get eventual extra data for this placeholder from the admin form. This method is called when the Page is saved in the admin and passed to the placeholder save method.

get_field(page, language, initial=None)

The field that will be shown within the admin.

get_widget(page, language, fallback=<class 'django.forms.widgets.Textarea'>)

Given the name of a placeholder return a Widget subclass like Textarea or TextInput.

render(context)

Output the content of the PlaceholdeNode in the template.

save(page, language, data, change, extra_data=None)

Actually save the placeholder data into the Content object.

widget

alias of TextInput

class basic_cms.placeholders.VideoPlaceholderNode(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False)

A youtube PlaceholderNode, just here as an example.

render(context)

widget

alias of VideoWidget

basic_cms.placeholders.get_filename(page, placeholder, data)

basic_cms.placeholders.parse_placeholder(parser, token)

Parse the PlaceholderNode parameters.

Return a tuple with the name and parameters.

Template tags

Page CMS page_tags template tags

class basic_cms.templatetags.pages_tags.FakeCSRFNode

Fake CSRF node for django 1.1.1

class basic_cms.templatetags.pages_tags.GetContentNode(page, content_type, varname, lang, lang_filter)

Get content node

class basic_cms.templatetags.pages_tags.GetPageNode(page_filter, varname)

get_page Node

class basic_cms.templatetags.pages_tags.GetPagesWithTagNode(tag, varname)

Get Pages with given tag node

class basic_cms.templatetags.pages_tags.LoadPagesNode

Load page node.

basic_cms.templatetags.pages_tags.do_contactplaceholder(parser, token)

Method that parse the contactplaceholder template tag.

basic_cms.templatetags.pages_tags.do_fileplaceholder(parser, token)

Method that parse the fileplaceholder template tag.

basic_cms.templatetags.pages_tags.do_get_content(parser, token)

Retrieve a Content object and insert it into the template’s context.

Example:

{% get_content page_object "title" as content %}

You can also use the slug of a page:

{% get_content "my-page-slug" "title" as content %}

Syntax:

{% get_content page type [lang] as name %}

Parameters:

• page – the page object, slug or id
• type – content_type used by a placeholder
• name – name of the context variable to store the content in
• lang – the wanted language

basic_cms.templatetags.pages_tags.do_get_page(parser, token)

Retrieve a page and insert into the template’s context.

Example:

{% get_page "news" as news_page %}

Parameters:

• page – the page object, slug or id
• name – name of the context variable to store the page in

basic_cms.templatetags.pages_tags.do_get_pages_with_tag(parser, token)

Return Pages with given tag

Syntax:

{% get_pages_with_tag <tag name> as <varname> %}

Example use:

{% get_pages_with_tag “footer” as pages %}

basic_cms.templatetags.pages_tags.do_imageplaceholder(parser, token)

Method that parse the imageplaceholder template tag.

basic_cms.templatetags.pages_tags.do_load_pages(parser, token)

Load the navigation pages, lang, and current_page variables into the current context.

Example:

<ul>
    {% load_pages %}
    {% for page in pages_navigation %}
        {% pages_menu page %}
    {% endfor %}
</ul>

basic_cms.templatetags.pages_tags.do_placeholder(parser, token)

Method that parse the placeholder template tag.

Syntax:

{% placeholder <name> [on <page>] [with <widget>] [parsed] [as <varname>] %}

Example usage:

{% placeholder about %}
{% placeholder body with TextArea as body_text %}
{% placeholder welcome with TextArea parsed as welcome_text %}
{% placeholder teaser on next_page with TextArea parsed %}

basic_cms.templatetags.pages_tags.do_videoplaceholder(parser, token)

Method that parse the imageplaceholder template tag.

basic_cms.templatetags.pages_tags.get_page_from_string_or_id(page_string, lang=None)

Return a Page object from a slug or an id.

basic_cms.templatetags.pages_tags.has_content_in(page, language)

Fitler that return True if the page has any content in a particular language.

Parameters:

• page – the current page
• language – the language you want to look at

basic_cms.templatetags.pages_tags.language_content_up_to_date(page, language)

Tell if all the page content has been updated since the last change of the official version (settings.LANGUAGE_CODE)

This is approximated by comparing the last modified date of any content in the page, not comparing each content block to its corresponding official language version. That allows users to easily make “do nothing” changes to any content block when no change is required for a language.

basic_cms.templatetags.pages_tags.pages_admin_menu(context, page)

Render the admin table of pages.

basic_cms.templatetags.pages_tags.pages_breadcrumb(context, page, url='/')

Tags

basic_cms.templatetags.pages_tags.pages_dynamic_tree_menu(context, page, url='/')

Render a “dynamic” tree menu, with all nodes expanded which are either ancestors or the current page itself.

Override pages/dynamic_tree_menu.html if you want to change the design.

Parameters:

• page – the current page
• url – not used anymore

basic_cms.templatetags.pages_tags.pages_menu(context, page, url='/')

Render a nested list of all the descendents of the given page, including this page.

Parameters:

• page – the page where to start the menu from.
• url – not used anymore.

basic_cms.templatetags.pages_tags.pages_siblings_menu(context, page, url='/')

Get the parent page of the given page and render a nested list of its child pages. Good for rendering a secondary menu.

Parameters:

• page – the page where to start the menu from.
• url – not used anymore.

basic_cms.templatetags.pages_tags.pages_sub_menu(context, page, url='/')

Get the root page of the given page and render a nested list of all root’s children pages. Good for rendering a secondary menu.

Parameters:

• page – the page where to start the menu from.
• url – not used anymore.

basic_cms.templatetags.pages_tags.show_absolute_url(context, page, lang=None)

Show the url of a page in the right language

Example

{% show_absolute_url page_object %}

You can also use the slug of a page:

{% show_absolute_url "my-page-slug" %}

Keyword arguments: :param page: the page object, slug or id :param lang: the wanted language (defaults to settings.PAGE_DEFAULT_LANGUAGE)

basic_cms.templatetags.pages_tags.show_content(context, page, content_type, lang=None, fallback=True)

Display a content type from a page.

Example:

{% show_content page_object "title" %}

You can also use the slug of a page:

{% show_content "my-page-slug" "title" %}

Or even the id of a page:

{% show_content 10 "title" %}

Parameters:

• page – the page object, slug or id
• content_type – content_type used by a placeholder
• lang – the wanted language (default None, use the request object to know)
• fallback – use fallback content from other language

basic_cms.templatetags.pages_tags.show_revisions(context, page, content_type, lang=None)

Render the last 10 revisions of a page content with a list using the pages/revisions.html template

basic_cms.templatetags.pages_tags.show_slug_with_level(context, page, lang=None, fallback=True)

Display slug with level by language.

Widgets

Django CMS come with a set of ready to use widgets that you can enable in the admin via a placeholder tag in your template.

class basic_cms.widgets.CKEditor(language=None, attrs=None, **kwargs)

CKEditor widget.

class Media

js = ['Nonepages/ckeditor/ckeditor.js', 'filebrowser/js/FB_CKEditor.js']

CKEditor.media

CKEditor.render(name, value, attrs=None, **kwargs)

class basic_cms.widgets.EditArea(language=None, attrs=None, **kwargs)

EditArea is a html syntax coloured widget.

class Media

js = ['Nonepages/edit_area/edit_area_full.js']

path = 'edit_area/edit_area_full.js'

EditArea.media

EditArea.render(name, value, attrs=None, **kwargs)

class basic_cms.widgets.FileInput(page=None, language=None, attrs=None, **kwargs)

media

render(name, value, attrs=None, **kwargs)

class basic_cms.widgets.ImageInput(page=None, language=None, attrs=None, **kwargs)

media

render(name, value, attrs=None, **kwargs)

class basic_cms.widgets.LanguageChoiceWidget(language=None, attrs=None, **kwargs)

media

render(name, value, attrs=None, **kwargs)

class basic_cms.widgets.RichTextarea(language=None, attrs=None, **kwargs)

A RichTextarea widget.

class Media

css = {'all': ['Nonepages/css/rte.css']}

js = ['Nonepages/javascript/jquery.js']

path = 'css/rte.css'

RichTextarea.media

RichTextarea.render(name, value, attrs=None, **kwargs)

class basic_cms.widgets.VideoWidget(attrs=None, page=None, language=None, video_url=None, weight=None, height=None)

A youtube Widget for the admin.

decompress(value)

format_output(rendered_widgets)

Given a list of rendered widgets (as strings), it inserts an HTML linebreak between them.

Returns a Unicode string representing the HTML for the whole lot.

media

value_from_datadict(data, files, name)

class basic_cms.widgets.WYMEditor(language=None, attrs=None, **kwargs)

WYMEditor widget.

class Media

js = ['Nonepages/javascript/jquery.js', 'Nonepages/javascript/jquery.ui.js', 'Nonepages/javascript/jquery.ui.resizable.js', 'Nonepages/wymeditor/jquery.wymeditor.js', 'Nonepages/wymeditor/plugins/resizable/jquery.wymeditor.resizable.js']

path = 'wymeditor/plugins/resizable/jquery.wymeditor.resizable.js'

WYMEditor.media

WYMEditor.render(name, value, attrs=None, **kwargs)

class basic_cms.widgets.markItUpHTML(attrs=None)

markItUpHTML widget.

class Media

css = {'all': ['Nonepages/markitup/skins/simple/style.css', 'Nonepages/markitup/sets/default/style.css']}

js = ['Nonepages/javascript/jquery.js', 'Nonepages/markitup/jquery.markitup.js', 'Nonepages/markitup/sets/default/set.js']

path = 'markitup/sets/default/style.css'

markItUpHTML.media

markItUpHTML.render(name, value, attrs=None, **kwargs)

class basic_cms.widgets.markItUpMarkdown(attrs=None)

markItUpMarkdown widget.

class Media

css = {'all': ['Nonepages/markitup/skins/simple/style.css', 'Nonepages/markitup/sets/markdown/style.css']}

js = ['Nonepages/javascript/jquery.js', 'Nonepages/markitup/jquery.markitup.js', 'Nonepages/markitup/sets/markdown/set.js']

path = 'markitup/sets/markdown/style.css'

markItUpMarkdown.media

markItUpMarkdown.render(name, value, attrs=None, **kwargs)

class basic_cms.widgets.markItUpRest(attrs=None)

markItUpRest widget.

class Media

css = {'all': ['Nonepages/markitup/skins/simple/style.css', 'Nonepages/markitup/sets/rst/style.css']}

js = ['Nonepages/javascript/jquery.js', 'Nonepages/markitup/jquery.markitup.js', 'Nonepages/markitup/sets/rst/set.js']

path = 'markitup/sets/rst/style.css'

markItUpRest.media

markItUpRest.render(name, value, attrs=None, **kwargs)

Page Model

class basic_cms.models.Page(*args, **kwargs)

This model contain the status, dates, author, template. The real content of the page can be found in the Content model.

creation_date

When the page has been created.

publication_date

When the page should be visible.

publication_end_date

When the publication of this page end.

last_modification_date

Last time this page has been modified.

status

The current status of the page. Could be DRAFT, PUBLISHED,

EXPIRED or HIDDEN. You should the property :attr:`calculated_status` if

you want that the dates are taken in account.

template

A string containing the name of the template file for this page.

calculated_status

Get the calculated status of the page based on Page.publication_date, Page.publication_end_date, and Page.status.

content_by_language(language)

Return a list of latest published Content for a particluar language.

Parameters:language – wanted language,

dump_json_data()

Return a python dict representation of this page for use as part of a JSON export.

expose_content()

Return all the current content of this page into a string.

This is used by the haystack framework to build the search index.

get_absolute_url(*moreargs, **morekwargs)

Alias for get_url_path.

This method is only there for backward compatibility and will be removed in a near futur.

Parameters:language – the wanted url language.

get_children_for_frontend()

Return a QuerySet of published children page

get_complete_slug(language=None, hideroot=True)

Return the complete slug of this page by concatenating all parent’s slugs.

Parameters:language – the wanted slug language.

get_content(language, ctype, language_fallback=False)

Shortcut method for retrieving a piece of page content

Parameters:

• language – wanted language, if not defined default is used.
• ctype – the type of content.
• fallback – if True, the content will also be searched in other languages.

get_date_ordered_children_for_frontend()

Return a QuerySet of published children page ordered by publication date.

get_languages()

Return a list of all used languages for this page.

get_template()

Get the template of this page if defined or the closer parent’s one if defined or pages.settings.PAGE_DEFAULT_TEMPLATE otherwise.

get_template_name()

Get the template name of this page if defined or if a closer parent has a defined template or pages.settings.PAGE_DEFAULT_TEMPLATE otherwise.

get_url(language=None)

Alias for get_complete_slug.

This method is only there for backward compatibility and will be removed in a near futur.

Parameters:language – the wanted url language.

get_url_path(language=None)

Return the URL’s path component. Add the language prefix if PAGE_USE_LANGUAGE_PREFIX setting is set to True.

Parameters:language – the wanted url language.

has_broken_link()

Return True if the page have broken links to other pages into the content.

invalidate()

Invalidate cached data for this page.

is_first_root()

Return True if this page is the first root pages.

margin_level()

Used in the admin menu to create the left margin.

save(*args, **kwargs)

Override the default save method.

slug(language=None, fallback=True)

Return the slug of the page depending on the given language.

Parameters:

• language – wanted language, if not defined default is used.
• fallback – if True, the slug will also be searched in other languages.

slug_with_level(language=None)

Display the slug of the page prepended with insecable spaces equal to simluate the level of page in the hierarchy.

title(language=None, fallback=True)

Return the title of the page depending on the given language.

Parameters:

• language – wanted language, if not defined default is used.
• fallback – if True, the slug will also be searched in other languages.

update_redirect_to_from_json(redirect_to_complete_slugs)

The second pass of PageManager.create_and_update_from_json_data used to update the redirect_to field.

Returns a messages list to be appended to the messages from the first pass.

valid_targets()

Return a QuerySet of valid targets for moving a page into the tree.

Parameters:perms – the level of permission of the concerned user.

visible

Return True if the page is visible on the frontend.

Page Manager

class basic_cms.managers.PageManager

Page manager provide several filters to obtain pages QuerySet that respect the page attributes and project settings.

create_and_update_from_json_data(d, user)

Create or update page based on python dict d loaded from JSON data. This applies all data except for redirect_to, which is done in a second pass after all pages have been imported,

user is the User instance that will be used if the author can’t be found in the DB.

returns (page object, created, messages).

created is True if this was a new page or False if an existing page was updated.

messages is a list of strings warnings/messages about this import

drafts()

Creates a QuerySet of drafts using the page’s Page.publication_date.

expired()

Creates a QuerySet of expired using the page’s Page.publication_end_date.

filter_published(queryset)

Filter the given pages QuerySet to obtain only published page.

from_path(complete_path, lang, exclude_drafts=True)

Return a Page according to the page’s path.

hidden()

Creates a QuerySet of the hidden pages.

navigation()

Creates a QuerySet of the published root pages.

on_site(site_id=None)

Return a QuerySet of pages that are published on the site defined by the SITE_ID setting.

Parameters:site_id – specify the id of the site object to filter with.

populate_pages(parent=None, child=5, depth=5)

Create a population of Page for testing purpose.

published()

Creates a QuerySet of published Page.

root()

Return a QuerySet of pages without parent.

Page view

class basic_cms.views.Details

This class based view get the root pages for navigation and the current page to display if there is any.

All is rendered with the current page’s template.

choose_language(lang, request)

Deal with the multiple corner case of choosing the language.

extra_context(request, context)

Call the PAGE_EXTRA_CONTEXT function if there is one.

get_navigation(request, path, lang)

Get the pages that are at the root level.

get_template(request, context)

Just there in case you have special business logic.

is_user_staff(request)

Return True if the user is staff.

resolve_page(request, context, is_staff)

Return the appropriate page according to the path.

resolve_redirection(request, context)

Check for redirections.

Content Model

class basic_cms.models.Content(*args, **kwargs)

A block of content, tied to a Page, for a particular language

exception DoesNotExist

exception Content.MultipleObjectsReturned

Content.get_next_by_creation_date(*moreargs, **morekwargs)

Content.get_previous_by_creation_date(*moreargs, **morekwargs)

Content.objects = <basic_cms.managers.ContentManager object at 0x4878b10>

Content.page

Content Manager

class basic_cms.managers.ContentManager

Content manager methods

PAGE_CONTENT_DICT_KEY = 'page_content_dict_%d_%s_%d'

create_content_if_changed(page, language, ctype, body)

Create a Content for a particular page and language only if the content has changed from the last time.

Parameters:

• page – the concerned page object.
• language – the wanted language.
• ctype – the content type.
• body – the content of the Content object.

get_content(page, language, ctype, language_fallback=False)

Gets the latest content string for a particular page, language and placeholder.

Parameters:

• page – the concerned page object.
• language – the wanted language.
• ctype – the content type.
• language_fallback – fallback to another language if True.

get_content_object(page, language, ctype)

Gets the latest published Content for a particular page, language and placeholder type.

get_content_slug_by_slug(slug)

Returns the latest Content slug object that match the given slug for the current site domain.

Parameters:slug – the wanted slug.

get_page_ids_by_slug(slug)

Return all page’s id matching the given slug. This function also returns pages that have an old slug that match.

Parameters:slug – the wanted slug.

sanitize(content)

Sanitize a string in order to avoid possible XSS using html5lib.

set_or_create_content(page, language, ctype, body)

Set or create a Content for a particular page and language.

Parameters:

• page – the concerned page object.
• language – the wanted language.
• ctype – the content type.
• body – the content of the Content object.

PageAlias Model

class basic_cms.models.PageAlias(*args, **kwargs)

URL alias for a Page

exception DoesNotExist

exception PageAlias.MultipleObjectsReturned

PageAlias.objects = <basic_cms.managers.PageAliasManager object at 0x487e150>

PageAlias.page

PageAlias.save(*args, **kwargs)

PageAlias Manager

class basic_cms.managers.PageAliasManager

PageAlias manager.

from_path(request, path, lang)

Resolve a request to an alias. returns a PageAlias if the url matches no page at all. The aliasing system supports plain aliases (/foo/bar) as well as aliases containing GET parameters (like index.php?page=foo).

Parameters:

• request – the request object
• path – the complete path to the page
• lang – not used

Utils

A collection of functions for Page CMS

basic_cms.utils.export_po_files(path='poexport', stdout=None)

Export all the content from the published pages into po files. The files will be automatically updated with the new content if you run the command again.

basic_cms.utils.get_placeholders(template_name)

Return a list of PlaceholderNode found in the given template.

Parameters:template_name – the name of the template file

basic_cms.utils.import_po_files(path='poexport', stdout=None)

Import all the content updates from the po files into the pages.

basic_cms.utils.json_to_pages(json, user, preferred_lang=None)

Attept to create/update pages from JSON string json. user is the user that will be used when creating a page if a page’s original author can’t be found. preferred_lang is the language code of the slugs to include in error messages (defaults to settings.PAGE_DEFAULT_LANGUAGE).

Returns (errors, pages_created) where errors is a list of strings and pages_created is a list of: (page object, created bool, messages list of strings) tuples.

If any errors are detected there the error list will contain information for the user and no pages will be created/updated.

basic_cms.utils.normalize_url(url)

Return a normalized url with trailing and without leading slash.

>>> normalize_url(None)
'/'
>>> normalize_url('/')
'/'
>>> normalize_url('/foo/bar')
'/foo/bar'
>>> normalize_url('foo/bar')
'/foo/bar'
>>> normalize_url('/foo/bar/')
'/foo/bar'

basic_cms.utils.now_utc()

basic_cms.utils.pages_to_json(queryset)

Return a JSON string export of the pages in queryset.

basic_cms.utils.validate_pages_json_data(d, preferred_lang)

Check if an import of d will succeed, and return errors.

errors is a list of strings. The import should proceed only if errors is empty.

Http

Page CMS functions related to the request object.

basic_cms.http.get_language_from_request(request)

Return the most obvious language according the request.

basic_cms.http.get_request_mock()

Build a request mock up that is used in to render the templates in the most fidel environement as possible.

This fonction is used in the get_placeholders method to render the input template and search for the placeholder within.

basic_cms.http.get_slug(path)

Return the page’s slug

>>> get_slug('/test/function/')
function

basic_cms.http.get_template_from_request(request, page=None)

Gets a valid template from different sources or falls back to the default template.

basic_cms.http.pages_view(view)

Make sure the decorated view gets the essential pages variables.

basic_cms.http.remove_slug(path)

Return the remainin part of the path

>>> remove_slug('/test/some/function/')
test/some

Admin views

Pages admin views

basic_cms.admin.views.change_status(request, *args, **kwargs)

Switch the status of a page.

basic_cms.admin.views.delete_content(request, *args, **kwargs)

basic_cms.admin.views.get_content(request, *args, **kwargs)

Get the content for a particular page

basic_cms.admin.views.list_pages_ajax(request, *args, **kwargs)

Render pages table for ajax function.

basic_cms.admin.views.modify_content(request, *args, **kwargs)

Modify the content of a page.

basic_cms.admin.views.move_page(*args, **kwargs)

Move the page to the requested target, at the given position.

basic_cms.admin.views.sub_menu(request, *args, **kwargs)

Render the children of the requested page with the sub_menu template.

basic_cms.admin.views.traduction(request, *args, **kwargs)

Traduction helper.