django-renderit Documentation Release 1.2 jsoares Nov 20, 2017
Contents 1 Installation 3 2 Getting Started 5 2.1 Basic Usage............................................... 5 2.2 Extra Arguments............................................. 5 2.3 Python Objects.............................................. 8 2.4 Fallback................................................. 8 2.5 Site Specific............................................... 8 3 Template Tags 11 3.1 renderit.................................................. 11 4 Template Fallback 15 4.1 Simple Example............................................. 15 4.2 Arguments Example........................................... 16 4.3 The other arguments........................................... 20 5 Settings 21 5.1 CONCATINATION_STRING...................................... 21 5.2 ROOT_TEMPLATE_PATH....................................... 21 5.3 DEBUG................................................. 21 5.4 SITE_GROUPS............................................. 21 5.5 SITE_GET_FUNC............................................ 22 6 Contributing 23 7 Indices and tables 25 i
ii
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 what template 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 look for 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 authentication information for websites that required logged in users. We would normally have some html on our base template, 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 a variable 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 your dealing 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 look the same, for example have a image show up for DummyImage types or embdeded video player for DummyVideo types, the way we can do that is to have a bunch of if statements to check the type of object, but thats ugly, and can clutter up the template. Enstead renderit will know the type of object you are trying to render and use the appropriete 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 /renderit/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 site groups to further distingish the templates that are rendered. 8 Chapter 2. Getting Started
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_GROUPS and setting it to True This differs from groups in that they fallback to the non-site specific templates. For example, groups generate a template 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 as defaults, then we can override templates for specific sites. 2.5. Site Specific 9
10 Chapter 2. Getting Started
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 be context 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 to template 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' %} Template path built: 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=" " %} Template path built: '/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. select_template is called on the list. A list templates is created and then 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 enabled globally 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. Normally when the last group is reached, in this case 1 the template generator would just remove the 1 and try any prefix and arg combination left, but the site functionality will remove the 1 and then try all the normal groups (anything other than the 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 us the 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. When site ability is enabled we can specify a custom site value function which should yield a string. The default is renderit.templatetags.renderit_tags.default_get_site_func Change the setting SITE_GET_FUNC to a custom function to return something more friendly. For example: 18 Chapter 4. Template Fallback
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', '/renderit/default.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 has one 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 fallback to 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', '/renderit/default.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 concatination string 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', '/renderit/default.html'] 20 Chapter 4. Template Fallback
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 combine both, 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 can define 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
24 Chapter 6. Contributing
CHAPTER 7 Indices and tables genindex modindex search 25