django-renderit Documentation - Read the Docs · django-renderit Documentation, Release 1.2 django-renderit is a easy way to render objects. Contents: Contents 1

django-renderit DocumentationRelease 1.2

jsoares

Nov 20, 2017

Contents

1 Installation 3

2 Getting Started 52.1 Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Extra Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3 Python Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.4 Fallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.5 Site Specific . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3 Template Tags 113.1 renderit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4 Template Fallback 154.1 Simple Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.2 Arguments Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.3 The other arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5 Settings 215.1 CONCATINATION_STRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.2 ROOT_TEMPLATE_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.3 DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.4 SITE_GROUPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.5 SITE_GET_FUNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6 Contributing 23

7 Indices and tables 25

i

ii

django-renderit Documentation, Release 1.2

django-renderit is a easy way to render objects.

Contents:

Contents 1


2 Contents

CHAPTER 1

Installation

Installation is easy using pip or easy_install.

pip install django-renderit

or

easy_install django-renderit

Add renderit to your installed apps:

INSTALLED_APPS = (...'renderit',...

)

3


4 Chapter 1. Installation

CHAPTER 2

Getting Started

The idea here is to take a object and render it based off of its content type.

django-renderit is one template tag called renderit and it takes a bunch of different parameters to determine whattemplate to render.

2.1 Basic Usage

{% load renderit %}

{% renderit object %}

This will render object using the default template, which is:

'/renderit/default.html'

You can then create a template that is object specific, for example, if the object is a‘‘auth.user‘‘ instance, it will lookfor this template:

'/renderit/auth_user.html'

2.2 Extra Arguments

We can add extra arguments to further make this template unique, for example, lets say we want to render the au-thentication information for websites that required logged in users. We would normally have some html on our basetemplate, such as

<html><head>MySite</head><body>

<div class="auth">

5


Welcome,{% if request.user.is_authenticated %}

{{ request.user.username }}, <a href="/profile/">Profile</a> <a href=→˓"/logout/">Logout</a>

{% else %}Guest, <a href="/login/">Login</a> or <a href="/register/">Register</

→˓a>{% endif %}

</div><div class="content">

...</div>

</body></html>

renderit‘s goal is to take these little blocks of code and seperate them out in there own specific, resuable templates,and to clean up the main templates.

{% load renderit %}<html>

<head>MySite</head><body>

{% renderit request.user auth %}<div class="content">

...</div>

</body></html>

The above example takes an extra argument auth, this can be a context variable or taken literally. If auth not avariable in the template then renderit will take is as a string:

'/renderit/auth_user_auth.html'

Any arguments specified after the object, will be appended to the end of the template name.

While the above example can be used with django’s include tag in the same way, a better use case would be when yourdealing with a list of gerneric objects.

Lets take the following models:

class DummyEntry(models.Model):title = models.CharField(max_length=200)body = models.TextField()publish_date = models.DateTimeField(default=datetime.datetime.now)author = models.CharField(max_length=200)

def __unicode__(self):return self.title

class DummyBookmark(models.Model):url = models.URLField()name = models.CharField(max_length=200)

class DummyVideo(models.Model):url = models.URLField()

6 Chapter 2. Getting Started


name = models.CharField(max_length=200)

class DummyImage(models.Model):url = models.URLField()name = models.CharField(max_length=200)

class RelatedContent(models.Model):entry = models.ForeignKey(DummyEntry)content_type = models.ForeignKey(ContentType)object_id = models.IntegerField()content_object = generic.GenericForeignKey('content_type', 'object_id')add_date = models.DateTimeField(default=datetime.datetime.now)

Lets create and add the content to a generic list:

bm_ctype = ContentType.objects.get_for_model(DummyBookmark)vi_ctype = ContentType.objects.get_for_model(DummyVideo)im_ctype = ContentType.objects.get_for_model(DummyImage)en_ctype = ContentType.objects.get_for_model(DummyEntry)

entry = DummyEntry.objects.create(title="This is an example entry",body="This is only an example entry",author="John Smith")

bm = DummyBookmark.objects.create(url="http://google.com",name="Google")

vid = DummyVideo.objects.create(url="http://www.youtube.com/watch?v=K24mFGlJij0&playnext=1&list=PL4A64BDBA5F9629AE

→˓",name="Django's Caravan - Gypsy Jazz Guitar - Leigh Jackson")

img1 = DummyImage.objects.create(url="http://www.flickr.com/photos/alisonlyons/5678882139/",name="Fair Exchange From alison lyons photography")

RelatedContent.objects.create(entry=entry,content_type=bm_ctype,object_id=bm.pk)

RelatedContent.objects.create(entry=entry,content_type=vi_ctype,object_id=vid.pk)

RelatedContent.objects.create(entry=entry,content_type=im_ctype,object_id=img.pk)

RelatedContent.objects.create(entry=entry,

2.2. Extra Arguments 7


content_type=en_ctype,object_id=entry.pk)

related_objects = RelatedContent.objects.all()

When related_content is used in your template, there will be 4 different types of objects. If we dont want they all to lookthe same, for example have a image show up for DummyImage types or embdeded video player for DummyVideotypes, the way we can do that is to have a bunch of if statements to check the type of object, but thats ugly, andcan clutter up the template. Enstead renderit will know the type of object you are trying to render and use theappropriete template.

{% for obj in related_content %}{% renderit obj %}

{% endfor %}

When we output the template list that is created for each item in the loop above, it will look something like this:

[u'renderit/sample_app_dummybookmark.html', 'renderit/default.html'][u'renderit/sample_app_dummyvideo.html', 'renderit/default.html'][u'renderit/sample_app_dummyimage.html', 'renderit/default.html'][u'renderit/sample_app_dummyentry.html', 'renderit/default.html']

We can then create the templates and make them custom to the type of object.

2.3 Python Objects

While the examples shown are specific to django models, we can pass in any object and its type will be used (slugified)to build the template. If we have a python dictionary, the template will be:

'/renderit/dict.html'

Of course this is rather broad, so we should pass in extra arguments to ensure its specific to what we use it for

{% renderit dict_obj top10 %}

The template that will be looked for first would be:

'/renderit/dict_top10.html'

Read more about Template Tags

2.4 Fallback

Fallback template paths are generated based on the arguments supplied, which the last possbiel template being ‘/ren-derit/default.html’. Read more about Template Fallback

2.5 Site Specific

In the event you are using sites, and the templates you need rendered are structurally different, you can enable sitegroups to further distingish the templates that are rendered.



This is similar to how groups are parsed, but they fallback to the non-site specific templates if not found.

Here is an example of the template difference between site and non-site:

'renderit/section/sample_app_video.html'

And want to create a site specific template:

'renderit/1/section/sample_app_video.html'

We need to either specify site=True in the template tag or enable sites for all templates using the setting SITE_GROUPSand setting it to True

This differs from groups in that they fallback to the non-site specific templates. For example, groups generate atemplate list like the following:

['renderit/<group1>/<group2>/<template_name>','renderit/<group1>/<template_name>','renderit/<template_name>']

When sites are enabled for the same scenario produces the following template list:

['renderit/<site>/<group1>/<group2>/<template_name>','renderit/<site>/<group1>/<template_name>','renderit/<site>/<template_name>','renderit/<group1>/<group2>/<template_name>','renderit/<group1>/<template_name>','renderit/<template_name>']

Key thing to take away from this, is that we can create templates without any care for sites initially, which may act asdefaults, then we can override templates for specific sites.

2.5. Site Specific 9



CHAPTER 3

Template Tags

Contents

• Template Tags

– renderit

* Syntax

* Examples

* arguments

3.1 renderit

3.1.1 Syntax

{% renderit [object] [arg] [arg] ... [with] [group=S] [prefix=S] [concat=S]→˓[context=True|False] [site=True|False] [as] [varname] %}

3.1.2 Examples

Simplest Form:

{% renderit request.user %}

Multiple Arguments:

{% renderit request.user auth custom %}

11


With Prefix

{% renderit request.user auth custom with prefix=header %}

Change concatination string to be __ (double under score)

{% renderit request.user auth custom with prefix=header concat="__" %}

3.1.3 arguments

object

Only required argument, can be any python object.

args

Anything specified after [object] and before [with] will be treated as extra concatination strings. These can also becontext variables.

Note: If an object is resolved and contains a space, the argument will be slugified, using django.template.defaultfilters.slugify

with

Required only if [group], [prefix] or [concat] is used.

group

This value is used to better structure the template location. A folder with the supplied value will be preprened totemplate path.

Example

{% renderit auth.user with group='users' %}

Template path built:

'/renderit/users/auth_user.html'

prefix

Prefixes the template with supplied value.

Example

{% renderit auth.user with prefix='users' %}


12 Chapter 3. Template Tags


'/renderit/users_auth_user.html'

concat

Change the default concatination string when building templates, default is _ (underscore)

Example

{% renderit auth.user with concat="__" %}


'/renderit/auth__users.html'

Note: The default concatination string can be changed using CONCATINATION_STRING

context

If True (default) the template context will be passed into the template.

site

If True the site will be used to add additional possible templates on a per site basis

Example

{% renderit auth.user with site=True %}

as

Only required if a return variable is used.

varname

Store the rendered template into a context varaible.

Example

{% renderit auth.user as auth_var %}

{{ auth_var }}

3.1. renderit 13


14 Chapter 3. Template Tags

CHAPTER 4

Template Fallback

Contents

• Template Fallback

– Simple Example

– Arguments Example

* Single Argument

* Mulitple Arguments

* Prefix

* Group

* Site

* Combined

– The other arguments

* concat

Fallback template paths are generated based on the arguments supplied. A list templates is created and thenselect_template is called on the list.

4.1 Simple Example

{% renderit auth.user %}

Generated List:

15


['/renderit/auth_user.html','/renderit/default.html']

Note: The default template root path can be changed via ROOT_TEMPLATE_PATH

4.2 Arguments Example

4.2.1 Single Argument

{% renderit auth.user auth %}

Generated list:

['/renderit/auth_user_auth.html','/renderit/auth_user.html','/renderit/default.html']

4.2.2 Mulitple Arguments

{% renderit auth.user auth homepage %}

Generated list:

['/renderit/auth_user_auth_homepage.html','/renderit/auth_user_auth.html','/renderit/auth_user.html','/renderit/default.html']

4.2.3 Prefix

Suppling a prefix will gerernate two sets of templates, one set with the prefix and one set without the prefix

{% renderit auth.user with prefix=userinfo %}

Generated List:

['/renderit/userinfo_auth_user.html','/renderit/auth_user.html','/renderit/default.html']

With Arguments

{% renderit auth.user homepage custom with prefix=userinfo %}

Generated List:

16 Chapter 4. Template Fallback


['/renderit/userinfo_auth_user_homapage_custom.html','/renderit/userinfo_auth_user_homepage.html','/renderit/userinfo_auth_user.html',

'/renderit/auth_user_homepage_custom.html','/renderit/auth_user_homapage.html','/renderit/auth_user.html',

'/renderit/default.html']

4.2.4 Group

Changed in version ‘1.1‘

Group will append the string and act like a directory rather then a extra template path string.

{% renderit auth.user with group=users %}

Generated List:

['/renderit/users/auth_user.html','/renderit/auth_user.html','/renderit/default.html']

The group argument can also be a path i.e. users/homepage

New in version ‘1.1‘

{% renderit auth.user with group=users/homepage %}

Generated List:

['/renderit/users/homepage/auth_user.html','/renderit/users/auth_user.html','/renderit/auth_user.html','/renderit/default.html']

4.2.5 Site

New in version ‘1.2‘

We can group templates by the current site. This option can be supplied via the template tag as site=True or enabledglobally using the SITE_GROUPS setting.

{% renderit auth.user with site=True %}

Generated List:

['/renderit/1/auth_user.html','/renderit/auth_user.html','/renderit/default.html']

The example above will automatically apply the site id as part of the group.

4.2. Arguments Example 17


Note: While this looks like just another group i.e. 1/a/b, it acts slightly different when the site is reached. Normallywhen the last group is reached, in this case 1 the template generator would just remove the 1 and try any prefix and argcombination left, but the site functionality will remove the 1 and then try all the normal groups (anything other thanthe site) all over again.

Here is an example without sites:

.. code-bloack:: django

{% renderit test with groups=1/a/b %}

Generated List:

['renderit/1/a/b/test.html',

'renderit/1/a/test.html',

'renderit/1/test.html',

'renderit/test.html',

'renderit/default.html']

Here is an example with sites (notice the removal of 1 in the groups):

.. code-bloack:: django

{% renderit test with groups=a/b sites=True %}

Generated List:

['renderit/1/a/b/test.html',

'renderit/1/a/test.html',

'renderit/1/test.html',

'renderit/a/b/test.html',

'renderit/a/test.html',

'renderit/testhtml',

'renderit/default.html']

As shown, the site id is used first, but when the site id is removed, it will reset the groups with no site id. This gives usthe ability to have defaults and site overrides.

Site value generation

The above examples showed the default value used, the pk of the site, but this isn’t very developer friendly. Whensite ability is enabled we can specify a custom site value function which should yield a string. The default is ren-derit.templatetags.renderit_tags.default_get_site_func

Change the setting SITE_GET_FUNC to a custom function to return something more friendly. For example:



RENDERIT_SETTINGS = {'SITE_GET_FUNC': 'example.sample_app.utils.get_site_name'

}

def get_site_name():site_map = {

1: 'white',2: 'black',3: 'red',4: 'blue'

}return site_map.get(Site.objects.get_current().pk)

4.2.6 Combined

The list of generated template paths can get rather large when using multiple arguments, a prefix and a group together

{% renderit auth.user hompage custom with prefix=logininfo group=users %}

Generated List:

['/renderit/users/logininfo_auth_user_admins_custom.html','/renderit/users/logininfo_auth_user_admin.html','/renderit/users/logininfo_auth_user.html',

'/renderit/users/logininfo_auth_user_admin_custom.html','/renderit/users/logininfo_auth_user_homepage.html','/renderit/users/auth_user.html',

'/renderit/logininfo_auth_user_homepage_custom.html','/renderit/logininfo_auth_user_homepage.html','/renderit/logininfo_auth_user.html',

'/renderit/auth_user_homepage_custom.html','/renderit/auth_user_homepage.html','/renderit/auth_user.html',


What we have here is 2 sets with 2 inner sets of templates, one set has the group users one without, the inner set hasone set with prefix logininfo and one set without.

Note: This is just the generated template path list, these templates do not have to exist, this is simply a way to fallbackto other templates in case a template does not exist.

With the update to group argument to allow a path, the generate list gets even larger.

{% renderit auth.user admins custom with prefix=logininfo group=users/homepage %}

Generated List:

['/renderit/users/homepage/logininfo_auth_user_admins_custom.html','/renderit/users/homepage/logininfo_auth_user_admins.html','/renderit/users/homepage/logininfo_auth_user.html',

4.2. Arguments Example 19


'/renderit/users/homepage/auth_user_admins_custom.html','/renderit/users/homepage/auth_user_admins.html','/renderit/users/homepage/auth_user.html',

'/renderit/users/logininfo_auth_user_admins_custom.html','/renderit/users/logininfo_auth_user_admins.html','/renderit/users/logininfo_auth_user.html',

'/renderit/users/auth_user_admins_custom.html','/renderit/users/auth_user_admins.html','/renderit/users/auth_user.html',

'/renderit/logininfo_auth_user_admins_custom.html','/renderit/logininfo_auth_user_admins.html','/renderit/logininfo_auth_user.html',

'/renderit/auth_user_admins_custom.html','/renderit/auth_user_admins.html','/renderit/auth_user.html',


This is similar to the previous example, except that now we have users/homepage as one set and users as another set

4.3 The other arguments

4.3.1 concat

This argumennt is taken literally and will not create any extra sets. If we take the last example and add concatinationstring to be __ (double underscore) we would get:

{% renderit auth.user hompage custom with prefix=logininfo group=users concat="__" %}

Generated List:

['/renderit/users/logininfo__auth__user__homepage__custom.html','/renderit/users/logininfo__auth__user__homepage.html','/renderit/users/logininfo__auth__user.html',

'/renderit/users/auth__user__homepage__custom.html','/renderit/users/auth__user__homepage.html','/renderit/users/auth__user.html',

'/renderit/logininfo__auth__user__homepage__custom.html','/renderit/logininfo__auth__user__homepage.html','/renderit/logininfo__auth__user.html',

'/renderit/auth__user__homepage__custom.html','/renderit/auth__user__homepage.html','/renderit/auth__user.html',



CHAPTER 5

Settings

All settings are grouped in the RENDERIT_SETTINGS dictionary, below are all the possible options

Note: You can also use individual settings by prepending RENDERIT_ in front of the names below. If you combineboth, the individual settings will act as defaults, and the dictionary will override the setting if supplied

5.1 CONCATINATION_STRING

Change the default concatination strings, default is _ (underscore)

5.2 ROOT_TEMPLATE_PATH

Change the default root template path to look for the templates, default is /renderit/

5.3 DEBUG

Outputs some debugging information to the console, defaults to the value of DEBUG

5.4 SITE_GROUPS

Boolean value indicated if renderit should care about sites

21


5.5 SITE_GET_FUNC

By default when site groups are enabled, it will use the pk of the site. However if we want cleaner names, you candefine your own function to get the value. Defaults to renderit.templatetags.renderit_tags.default_get_site_func

22 Chapter 5. Settings

CHAPTER 6

Contributing

• Source

• Issues

23

https://github.com/jsoa/django-renderit

https://github.com/jsoa/django-renderit/issues


24 Chapter 6. Contributing

CHAPTER 7

Indices and tables

• genindex

• modindex

• search

25

Documents

django-renderit Documentation - Read the Docs · django-renderit Documentation, Release 1.2 django-renderit is a easy way to render objects. Contents: Contents 1