Renderers

Renderers#

Overview#

To build HTML for a page or section object a renderer class is used. While a section renderer produces a html snippet representing the section object, a page renderer provides a full html document for a page. Including all its sections.

Nevertheless, both renderers are based on the same concept, using the proven triad of get_template_name, get_context and render methods.

There is a default renderer for pages as well as for sections. Which are probably sufficient for most use cases. Still you are free to write your own renderer classes and register() them for your page and section models. The only thing a renderer class has to provide is a render method returning valid HTML.

Renderer classes using django’s MediaDefiningClass as metaclass. They can be equipped with a Media classes like django’s forms and widgets:

from simple_page import renderers

class FancySectionRenderer(renderers.SectionRenderer):
    class Media:
        css = dict(all=['fancy_section.css'])
        js = ['fancy_section.js']

It is the responsibility of the page renderer to merge the media definitions of all renderers involved and provide them as a media template variable. For more details see get_media_assets().

Api Reference#

Registry#

simple_page.renderers.register(model_cls, renderer_cls=None, context=None)#

Register a renderer class for a page or section model. This function can also be used as a decorator for your renderer class:

@renderers.register(FancyPage)
class FancyPageRenderer(renderers.PageRenderer):
    ...

Section renderer can be applied context specific. A context can be a page type, a region name or a tuple of page type and region name:

@renderers.register(FancySection, context='main')
class MainRegionFancySectionRenderer(renderers.SectionRenderer):
    ...

or:

@renderers.register(FancySection, context=(FancyPage, 'main'))
class FancyPageMainRegionFancySectionRenderer(renderers.SectionRenderer):
    ...

This allows you to use different renderers depending on where a section appears. See get_section_renderer() for more details about how a renderer will be choosen.

Parameters:

  • model_cls (Page or Section) – model to be rendered

  • renderer_cls (PageRenderer or SectionRenderer) – renderer class

  • context (Page or str or tuple of both, optional) – context where a section renderer should be applied

simple_page.renderers.get_page_renderer(page)#

Return the registered renderer for the page or PageRenderer.

Parameters:

page (Page) – page instance to be rendered

Returns:

renderer class

Return type:

PageRenderer

simple_page.renderers.get_section_renderer(section, page=None, region=None)#

Return a renderer instance for the section.

We look for a registered renderer in this order:

  • page-type and region specific

  • region specific

  • page-type specific

  • neither page-type nor region specific

The first one found will be returned. Otherwise the SectionRenderer is used as fallback.

Parameters:

  • obj (Section) – section instance

  • page (Page) – page the section will be rendered for

  • region (str) – region the section will be rendered in

Returns:

renderer class

Return type:

SectionRenderer

Renderer Classes#

class simple_page.renderers.SectionRenderer(obj, request=None, **kwargs)#

Bases: BaseRenderer

Renderer for Section instances.

Initialize the renderer.

Parameters:

  • obj (Page or Section) – object to be rendered

  • request (HttpRequest) – request object (default: None)

  • kwargs – Additional data as keyword arguments (default: dict())

get_template_name()#

Return template name. If template_name is set it will be returned. Otherwise the template name will be constructed as follows:

“sections/<section_class_name_in_snake_case>.html”

get_context()#

Build and return rendering context:

  • section: section object

Returns:

rendering context

Return type:

dict

render()#

Return the rendered HTML using the template and context returned by get_template_name() and get_context() methods.

template_name = None#

Template name. Default is None. See get_template_name().

class simple_page.renderers.PageRenderer(obj, request=None, **kwargs)#

Bases: BaseRenderer

Renderer for Page instances.

Initialize the renderer.

Parameters:

  • obj (Page or Section) – object to be rendered

  • request (HttpRequest) – request object (default: None)

  • kwargs – Additional data as keyword arguments (default: dict())

get_template_name()#

Return template name. If template_name is set it will be returned. Otherwise the template name will be constructed as follows:

“pages/<page_class_name_in_snake_case>.html”

get_section_data(section, region)#

Build and return a dictionary holding the section’s data:

  • obj: section object itself

  • renderer: renderer object for this section

  • html: section’s html build by the renderer returned by get_section_renderer()

Parameters:

  • section (Section) – section object

  • region (str) – region name

Returns:

section data holding the section object and the rendered html

Return type:

dict

get_region_data(region, title)#

Build and return a dictionary holding the region’s data:

  • name: region name

  • title: region title

  • sections: list of section data build by get_section_data()

Parameters:

  • region (str) – region name

  • tilte (str) – region title

Returns:

region data holding title, name and sections for this region

Return type:

dict

get_media_assets(context)#

Merge media definitions of the page’s and all sections’ renderers. Return them as string.

Return str:

merged media assets

get_context()#

Build rendering context:

As a shortcut each region data will also be added using the region’s name as an own context variable.

Returns:

rendering context

Return type:

dict

render()#

Return the rendered HTML using the template and context returned by get_template_name() and get_context() methods.

template_name = None#

Template name. Default is None. See get_template_name().