Page CMS reference API — django-page-cms 2.0.0 documentation

# Page CMS reference API

- The application model
- Placeholders
- Template tags
- Widgets
- Page Model
- Page Manager
- Page view
- Content Model
- Content Manager
- PageAlias Model
- PageAlias Manager
- Utils
- Http

## The application model

Gerbi CMS declare rather simple models: `Page` `Content` and `PageAlias`.

## Placeholders

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

class `pages.placeholders.` `ContactForm`(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None)

  Simple contact form

  `base_fields` = {'email': <django.forms.fields.EmailField object>, 'message': <django.forms.fields.CharField object>, 'subject': <django.forms.fields.CharField object>}
  `declared_fields` = {'email': <django.forms.fields.EmailField object>, 'message': <django.forms.fields.CharField object>, 'subject': <django.forms.fields.CharField object>}
  `media`

class `pages.placeholders.` `ContactPlaceholderNode`(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False, has_revision=True, section=None, shared=False, nodelist=None)

  A contact PlaceholderNode example.

  `render`(context)

    Output the content of the PlaceholdeNode as a template.

class `pages.placeholders.` `FilePlaceholderNode`(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False, has_revision=True, section=None, shared=False, nodelist=None)

  A PlaceholderNode that saves one file on disk.

  PAGE_UPLOAD_ROOT setting define where to save the file.

  `get_field`(page, language, initial=None)

    The field that will be shown within the admin.

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

    Actually save the placeholder data into the Content object.

class `pages.placeholders.` `ImagePlaceholderNode`(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False, has_revision=True, section=None, shared=False, nodelist=None)

  A PlaceholderNode that saves one image on disk.

  PAGE_UPLOAD_ROOT setting define where to save the image.

  `get_field`(page, language, initial=None)

    The field that will be shown within the admin.

class `pages.placeholders.` `JsonPlaceholderNode`(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False, has_revision=True, section=None, shared=False, nodelist=None)

  A PlaceholderNode that try to return a deserialized JSON object in the template.

  `get_render_content`(context)

class `pages.placeholders.` `MarkdownPlaceholderNode`(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False, has_revision=True, section=None, shared=False, nodelist=None)

  A PlaceholderNode that return HTML from MarkDown format

  `render`(context)

    Render markdown.

  `widget`

    alias of `django.forms.widgets.Textarea`

class `pages.placeholders.` `PlaceholderNode`(name, page=None, widget=None, parsed=False, as_varname=None, inherited=False, untranslated=False, has_revision=True, section=None, shared=False, nodelist=None)

  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 `pages.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.

  `edit_tag`()
  `field`

    alias of `django.forms.fields.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_lang`(context)
  `get_render_content`(context)
  `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 as a template.

  `render_parsed`(context, content)
  `save`(page, language, data, change, extra_data=None)

    Actually save the placeholder data into the Content object.

  `widget`

    alias of `django.forms.widgets.TextInput`

`pages.placeholders.` `get_filename`(page, content_type, data)

  Generate a stable filename using the original filename of the type.

`pages.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 `pages.templatetags.pages_tags.` `GetContentNode`(page, content_type, varname, lang, lang_filter)

  Get content node

  `render`(context)

    Return the node rendered as a string.

class `pages.templatetags.pages_tags.` `GetPageNode`(page_filter, varname)

  get_page Node

  `render`(context)

    Return the node rendered as a string.

class `pages.templatetags.pages_tags.` `LoadEditMediaNode`

  Load edit node.

  `render`(context)

    Return the node rendered as a string.

class `pages.templatetags.pages_tags.` `LoadEditNode`

  Load edit node.

  `render`(context)

    Return the node rendered as a string.

class `pages.templatetags.pages_tags.` `LoadPagesNode`

  Load page node.

  `render`(context)

    Return the node rendered as a string.

`pages.templatetags.pages_tags.` `do_contactplaceholder`(parser, token)

  Method that parse the contactplaceholder template tag.

`pages.templatetags.pages_tags.` `do_fileplaceholder`(parser, token)

  Method that parse the fileplaceholder template tag.

`pages.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

`pages.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

`pages.templatetags.pages_tags.` `do_imageplaceholder`(parser, token)

  Method that parse the imageplaceholder template tag.

`pages.templatetags.pages_tags.` `do_jsonplaceholder`(parser, token)

  Method that parse the contactplaceholder template tag.

`pages.templatetags.pages_tags.` `do_load_edit`(parser, token)

`pages.templatetags.pages_tags.` `do_load_edit_media`(parser, token)

`pages.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>

`pages.templatetags.pages_tags.` `do_markdownlaceholder`(parser, token)

  Method that parse the markdownplaceholder template tag.

`pages.templatetags.pages_tags.` `do_page_has_content`(parser, token)

  Conditional tag that only renders its nodes if the page has content for a particular content type. By default the current page is used.

  Syntax:

      {% page_has_content <content_type> [<page var name>] %}
          ...
      {%_end page_has_content %}

  Example use:

      {% page_has_content 'header-image' %}
          <img src="{{ MEDIA_URL }}{% imageplaceholder 'header-image' %}">
      {% end_page_has_content %}

`pages.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 %}

`pages.templatetags.pages_tags.` `get_page_from_string_or_id`(page_string, lang=None)

  Return a Page object from a slug or an id.

`pages.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

`pages.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.

`pages.templatetags.pages_tags.` `pages_admin_menu`(context, page)

  Render the admin table of pages.

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

  Tags

`pages.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

`pages.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.

`pages.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.

`pages.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.

`pages.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)

`pages.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

`pages.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

## 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 `pages.widgets.` `FileInput`(page=None, language=None, attrs=None, **kwargs)
  `delete_msg` = 'Delete file'
  `media`
  `please_save_msg` = 'Please save the page to show the file field'
  `render`(name, value, attrs=None, **kwargs)

    Render the widget as an HTML string.

class `pages.widgets.` `ImageInput`(page=None, language=None, attrs=None, **kwargs)
  `delete_msg` = 'Delete image'
  `media`
  `please_save_msg` = 'Please save the page to show the image field'

class `pages.widgets.` `LanguageChoiceWidget`(language=None, attrs=None, **kwargs)
  `media`
  `render`(name, value, attrs=None, **kwargs)

    Render the widget as an HTML string.

class `pages.widgets.` `PageLinkWidget`(attrs=None, page=None, language=None, video_url=None, linkedpage=None, text=None)

  A page link Widget for the admin.

  `decompress`(value)

    Return a list of decompressed values for the given compressed value. The given value can be assumed to be valid, but not necessarily non-empty.

  `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)

    Given a dictionary of data and this widget’s name, return the value of this widget or None if it’s not provided.

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

  A RichTextarea widget.

  class `Media`
    `css` = {'all': ['/static/pages/css/rte.css', '/static/pages/css/font-awesome.min.css']}
    `js` = ['/static/pages/javascript/jquery.js', '/static/pages/javascript/jquery.rte.js']
  `media`
  `render`(name, value, attrs=None, **kwargs)

    Render the widget as an HTML string.

## Page Model

class `pages.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.`
  exception `DoesNotExist`
  exception `MultipleObjectsReturned`
  `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,

  `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`(language=None)

    Alias for get_url_path.

    Parameters: | language – the wanted url language.

  `get_children`()

    Cache superclass result

  `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_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.

  `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.

  `move_to`(target, position='first-child')

    Invalidate cache when moving

  `published_children`()

    Return a `QuerySet` of published children page

  `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 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.

  `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 `pages.managers.` `PageManager`

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

  `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.

  `from_slug`(slug)
  `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.

  `published`()

    Creates a `QuerySet` of published `Page`.

  `root`()

    Return a `QuerySet` of pages without parent.

## Page view

class `pages.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 `pages.models.` `Content`(*args, **kwargs)

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

  exception `DoesNotExist`
  exception `MultipleObjectsReturned`
  `body`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `creation_date`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `get_next_by_creation_date`(*, field=<django.db.models.fields.DateTimeField: creation_date>, is_next=True, **kwargs)
  `get_previous_by_creation_date`(*, field=<django.db.models.fields.DateTimeField: creation_date>, is_next=False, **kwargs)
  `id`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `language`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `objects` = <pages.managers.ContentManager object>
  `page`

    Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

    In the example:

        class Child(Model):
            parent = ForeignKey(Parent, related_name='children')

    `Child.parent` is a `ForwardManyToOneDescriptor` instance.

  `page_id`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `type`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

## Content Manager

class `pages.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.

  `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 `pages.models.` `PageAlias`(*args, **kwargs)

  URL alias for a `Page`

  exception `DoesNotExist`
  exception `MultipleObjectsReturned`
  `id`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `objects` = <pages.managers.PageAliasManager object>
  `page`

    Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

    In the example:

        class Child(Model):
            parent = ForeignKey(Parent, related_name='children')

    `Child.parent` is a `ForwardManyToOneDescriptor` instance.

  `page_id`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

  `save`(*args, **kwargs)

    Save the current instance. Override this in a subclass if you want to control the saving process.

    The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

  `url`

    A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

## PageAlias Manager

class `pages.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

`pages.utils.` `get_now`()

`pages.utils.` `get_placeholders`(template_name)

  Return a list of PlaceholderNode found in the given template.

  Parameters: | template_name – the name of the template file

`pages.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'

`pages.utils.` `slugify`(value, allow_unicode=False)

  Convert to ASCII if ‘allow_unicode’ is False. Convert spaces to hyphens. Remove characters that aren’t alphanumerics, underscores, or hyphens. Convert to lowercase. Also strip leading and trailing whitespace. Copyright: https://docs.djangoproject.com/en/1.9/_modules/django/utils/text/#slugify TODO: replace after stopping support for Django 1.8

## Http

Page CMS functions related to the `request` object.

`pages.phttp.` `get_language_from_request`(request)

  Return the most obvious language according the request.

`pages.phttp.` `get_request_mock`()

  Build a `request` mock up for tests

`pages.phttp.` `get_slug`(path)

  Return the page’s slug

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

`pages.phttp.` `get_template_from_request`(request, page=None)

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

`pages.phttp.` `remove_slug`(path)

  Return the remainin part of the path

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