Templates utils

↑ Parent: Utils

← Previous: Python utils

Utility functions in templates

MagiCircles provides a set of utility functions for templates. You can load them using tools:

{% load tools %}

Note that using template tags, either provided ones below or your own, adds a significant loading cost. See "Avoid calling functions in templates" in ⎡Coding style⎦.

Name	Description	Parameters	Return value
addint	Concatenate an integer at the end of a string	string, int	string
anon_format	Same than format but parameters that are not named. Equivalent of 'hello {}'.format('Deby')	string, **kwargs	string
call	Call a function	function, parameter	returns the returned value after the function has been called
callWithContext	Takes a dict that contains a function, calls it with the current context, up to 3 parameters and stores the returned value in result_of_callwithcontext in the context	dict, function (= string name key in dict), p1=None, p2=None, p3=None	None
format	Format a string with the given dictionary. Equivalent of: 'hello {name}!'.format(name='Deby')	string, **kwargs	string
getattribute	Gets an attribute of an object dynamically from a string name	value, arg	the attribute
isList	Is thing a list?	thing	bool
isnone	Return True if the value is None	value	bool
mod	Is a divisible by b?	a, b	a % b == 0
modelName	Takes an instance of a django model and returns the string name	thing	string
orcallable	Will check if a variable is callable and call it, or just return it if it's not. Will also translate it if needed.	var_or_callable	value
padzeros	Pad an integer with zeros	value, length	string
split	Returns a list of strings from a string	string, splitter=',')	list
startswith	Check if a string starts with another string	string, string	bool
t	Translated string for terms in django_translated, see ⎡Avoid generating translation terms for terms already available in Django framework⎦	string	localized string
times	Create a range from 0 to value	value	list of integers
trans_anon_format	Same than trans_format but parameters that are not named. Equivalent of _('hello {}').format('Deby')	string, **kwargs	string
trans_format	Same than format but with a translated string. Equivalent of _('hello {name}!').format(name='Deby')	string, **kwargs	string

Available templates

MagiCircles provides 2 kinds of templates you can use:

• Base templates: For Single pages
• Includes: included in your own templates in Single pages, or used in collections whenever templates can be provided (example: before_template in list view).

Base templates

base.html

Should be used as a base when you create single pages.

Available blocks:

Name	Available as variable?	Description
title	page_title	What's in the HTML <title> in the header.
extracss	extracss	Inclusion of other CSS files.
shareimage	share_image	Preview image used when the URL to this page is shared on social media (Facebook, Twitter, etc).
shareimagetwitter	share_image	Preview image used when the URL to this page is shared to Twitter.
content	❌	The main block that contains the content of your page.
js	js	Inclusion of other Javascript files. Loaded after the external dependencies (jQuery, Bootstrap, etc) and before MagiCircles Javascript files (commons, magi_main, main)
js2	js2	Another block for inclusion of other Javascript files if the first block/variable has already been set and you don't want to overwrite it.
afterjs	afterjs	Inclusion of other Javascript files. Loaded after MagiCircles Javascript files.

Variables you can set:

Name	Value	Default	Example
hidenavbar	Show or hide the navbar at the top of the website. Should only be used if it needs to be forced to True, as a GET parameter hidenavbar is available for all pages.	False
corner_popups	It's already in your global context, but you can add some popups if needed. See Corner popups.	[]
js_files	List of Javascript files, as full URLs or as file names in your static folder, without the .js extension at the end.	None	`['https://s.co/a.js', 'bower/github-wiki/js/githubwiki', 'wiki']
js_variables	A dictionary of variables to be made available in Javascript for your own scripts. You should use jsv available in Python Utils to ensure your variables will be loaded correctly.	None	{ 'is_happy': jsv(is_happy) }
cuteform_fields	Should always be added by cuteFormFieldsForContext (in Python Utils)
ajax_callback	A single Javascript function that will be called when the page is loaded, before afterjs.	None	'loadURLs'

ajax.html

It's essentially the equivalent of base.html but without the HTML boilerplate: HTML <head>, <body>, and the nav bar.

Should be used as a base when you create single pages available in Ajax.

Available blocks:

Name	Available as variable?	Description
content	include_template	The main block that contains the content of your page.
js	❌	Inclusion of Javascript files. Will be loaded when the Ajax page is included in your page, so all the Javascript files from the base template will have been loaded already.
js2	❌	Another block for inclusion of other Javascript files if the first block/variable has already been set and you don't want to overwrite it.
afterjs	❌	Inclusion of Javascript files. Will be loaded after js_variables and cuteform fields have been loaded.

Variables you can set:

Name	Value	Default	Example
below_item	Template included after the include_template, when content block is not overridden.	None	'alert'
js_files	List of Javascript files, as full URLs or as file names in your static folder, without the .js extension at the end.
js_variables	A dictionary of variables to be made available in Javascript for your own scripts. You should use jsv available in Python Utils to ensure your variables will be loaded correctly.	None	{ 'is_happy': jsv(is_happy) }
ajax_callback	A single Javascript function that will be called when the page is loaded. Can't be used if afterjs is overridden.	None	'loadURLs'

form.html

Your go-to template to load pages that contain forms!

For a single form, you can provide the variable form in the context, and if you want multiple, you can provide forms as a dictionary.

The variable extends is always required. You can set it to base.html or ajax.html depending on your page.

Available blocks:

Name	Available as a variable?	Variable per form?	Description
beforeforms	beforeforms	❌	Shown at the top of the page, before any form.
beforeform	beforeform	Dict*, Property*	Shown at the top of the form, before the title.
imagetitle	image or icon	Property*	An image or icon that shows up before the title of the form as decoration.
title	form_title	Property*	Title of the form, shows up at the top of the form. Defaults to the page's title
beforefields	beforefields	Dict*, Property*	Shown before the form fields, after the form's title.
form	❌	❌	How the form(s) gets displayed.
afterfields	afterfields	Dict*, Property*	Shown after the form fields, before the submit button.
otherbuttons	otherbuttons	Dict*, Property*	Additional buttons to be shown before the main submit button.
submit	❌	Property*	Title of the submit button. Defaults to "Apply changes"
belowform	belowform	Dict*, Property*	Shown after the form, after the submit button.
belowforms	belowforms	❌	Shown at the end of the page, after the form(s).

*Dict: You can provide a dictionary in the context. Keys correspond to the form name.

*Property: You can set that value within the form itself, as a property.

Variables you can set:

Name	Value	Default	Example
extends	base.html or ajax.html	Required
multipart	Should the form(s) allow files upload?	False

Variables you can set as form's properties:

Name	Value	Default	Example
action	The URL to which the form should be submitted.	Same page with anchor to form (if multiple forms)	'/onsubmit/'

sidebar.html

You can use this template base if you would like a side bar on your page, similar to the side bars used to filter list views or the side bar of the wiki and help pages.

It extends base.html, so blocks and variables from base.html are also available.

Available blocks:

Name	Available as a variable?	Description
sidebar	❌	Content shown in the side bar itself.
`sidebar_content	❌	Content of the page.

Variables you can set:

Name	Value	Default	Example
hide_side_bar	Will not show the side bar at all. Makes it look just like any page extending base.html.	False
side_bar_no_padding	If set to True , the side bar will not have any padding.	False
small_container	If set to True, makes the page container smaller.	False
no_container	If set to True, the page will not be in a container, making it full width.	False

simpleForm.html

A simpler version of form.html.

Available blocks:

Name	Available as a variable?	Description
beforefields	❌	Shown before the form fields, under the title.
afterfields	❌	Shown after the form fields, before the submit button.
submit	❌	Title of the submit button. Defaults to 'Apply changes'.
belowform	❌	Shown after the form, below the submit button.

Variables you can set:

Name	Value	Default	Example
title	Title of the form.	Required	_('Settings')

emails/base.html

Should be used as a base for any HTML email. See send_email in Python Utils for more details about how to send emails.

Available blocks:

Name	Available as a variable?	Description
subject	❌	Subject of the email. Defaults to t_site_name (from email context)
headersubject	❌	Visible subject of the email. Defaults to t_site_name (from email context)
content	❌	Content of the email.
actionbutton	❌	Full HTML of an action button shown in the footer. Defaults to a button you can configure with actionlink and actionbuttontitle.
actionlink	❌	The URL to which you want your action button to point to. Defaults to the website's homepage.
actionbuttontitle	❌	The title of the action button. Defaults to the name of the website.
footersentence	❌	A sentence at the end of the email. Defaults to "Thanks for using our site!".

Common

include/alert.html

A Bootstrap alert.

Variables you can set:

Name	Value	Default	Example
alert_message	The message of the alert.	Required.	_('Permission denied.')
alert_type	success, info, warning, danger, main, secondary, and any value in COLOR (see Website Settings)	warning
alert_flaticon	Flaticon	about
alert_button_link	A button will show up which will point to this URL.	None	'/activities/'
alert_button_string	If alert_button_link, this is required and should be the title of the button.	None	_('Home')

include/avatar.html

Shows the avatar of a user. This is the recommended way to show an avatar, anywhere.

Variables you can set:

Name	Value	Default	Example
av_user	User instance, with preselected preferences.	Required	request.user
av_size	Font size of the heart displayed next to the avatar when the user is premium.	Required	30
av_image_size	Size of the avatar (width and height will be equal).	Required	200
av_link	Should the avatar link to the profile of the user?	False
av_account_id	If av_link is True, it will link this specific account within the profile with an anchor	None
av_class	Extra classes to be added to the avatar.	None	'btn'
av_external	If av_link is True, should the link open in a new tab?	False
av_username	Should the username be displayed under the avatar?	False
av_button	Should the avatar be in a button? (Classes: btn, btn-main)	False
av_fixed	Should the avatar be of fixed size? Otherwise, will have a max-width of 100%. Often useful considering the default avatar is never resized.	False
av_inline	Should the avatar be displayed inline? Defaults to a responsive block.	False
av_align	Align the avatar to the right, left or center.	Will follow the parent's css

include/disqus.html

Adds a comment section to any page. Mostly useful for Single pages.

Variables you can set:

Name	Value	Default	Example
disqus_identifier	The identifier of your page.	Required	about

include/share.html

Shows share buttons.

Variables you can set:

Name	Value	Default	Example
share_url	The URL to be shared.	Required	item.http_item_url
share_sentence	The sentence to be shared.	Required	_('Check out my profile!')
share_btn_class	Class of the button (btn-something).	main

emails/donation_footer.html

Can be included in footersentence when using emails/base.html. Will show a link to encourage users to donate. Should only be used when sending nice, positive emails.

→ Next: Javascript utils