Django Template Filter Replace

May 9, 2012 - Custom template tags and filters must live inside a Django app. Machine without enabling access to all of them for every Django installation. If you're writing a template filter that only expects a string as the first argument,.

Chapter 3 lists a number of the most useful built-in template tags and filters. However, Django ships with many more built-in tags and filters.

This appendix provides a summary of all template tags and filters in Django. For more detailed information and use cases, see the Django Project. Butel arc 125 registration code. Built-in Tags autoescape Controls the current auto-escaping behavior.

This tag takes either on or off as an argument and that determines whether auto-escaping is in effect inside the block. The block is closed with an endautoescape ending tag. When auto-escaping is in effect, all variable content has HTML escaping applied to it before placing the result into the output (but after any filters have been applied). This is equivalent to manually applying the escape filter to each variable. The only exceptions are variables that are already marked as safe from escaping, either by the code that populated the variable, or because it has had the safe or escape filters applied.

Sample usage.

Django filters are designed toformat template variables. The syntax to apply Django filters isthe vertical bar character also known as 'pipe' inUnix environments (e.g.{{variable filter}}). It'sworth mentioning that it's possible to use multiple filters on thesame variable (e.g.{{variable filter filter}}).

I'll classify each built-inDjango filter into functional sections so it's easier to identifythem. The functional classes I'll use are: Dates, Strings, Lists,Numbers, Dictionaries, Spacing and special characters, Developmentand Testing & Urls.

Dates

• date.- The date filter formats Pythondatetime objects and only works if the variable isthis type of Python object. The date filter uses astring to specify a format. For example, if a variable contains adatetime object with the date 01/01/2018, the filterstatement {{variable date:'F jS o'}} outputs January1st 2018. The string syntax for the date filter is based on thecharacters described in table 3-3.

Note The date filter can also acceptpredefined date variables {{variable date:'DATE_FORMAT'}},{{variable date:'DATETIME_FORMAT'}},{{variable date:'SHORT_DATE_FORMAT' %} or{{variable date:'SHORT_DATETIME_FORMAT'}}.

The predefined datevariables in themselves are also composed of date strings based onthe syntax in table 3-3. For example DATE_FORMAT default's to 'N j,Y' (e.g. Jan 1, 2018), DATETIME_FORMAT defaults to 'N j, Y, P'(e.g. Jan 1, 2018, 12 a.m.), SHORT_DATE_FORMAT defaults to 'm/d/Y'(e.g. 01/01/2018) and SHORT_DATETIME_FORMAT defaults to 'm/d/Y P'(e.g. 01/01/2018 12 a.m.). Each date variable can be overriddenwith different date strings in a project's settings.pyfile.

Table 3-3. Django date & time format characters

Standards based characters	Description
c	Outputs ISO 8601 format (e.g.2015-01-02T10:30:00.000123+02:00 or 2015-01-02T10:30:00.000123 ifthe datetime has no timezone [i.e.naive datetime])
r	Outputs RFC 2822 formatted date (e.g.'Thu, 21 Dec 200016:01:07 +0200')
U	Outputs seconds since Unix epoch date--January 1 197000:00:00 UTC
I (Uppercase i)	Outputs whether daylight savings time is in effect(e.g.'1' or '0')
Hour based characters	Description
a	Outputs 'a.m.' or 'p.m.'
A	Outputs 'AM' or 'PM'
f	Outputs time, 12-hour hours and minutes, with minutesleft off if they're zero (e.g.'1', '1:30')
g	Outputs hour, 12-hour format without leading zeros(e.g.'1' to '12')
G	Outputs hour, 24-hour format without leading zeros(e.g.'0' to '23')
h	Outputs hour, 12-hour format (e.g.'01' to'12')
H	Outputs hour, 24-hour format (e.g.'00' to'23')
i	Outputs minutes (e.g.'00' to '59')
P	Outputs time, 12-hour hours, minutes and 'a.m.'/'p.m.',with minutes left off if they're zero and the special-case strings'midnight' and 'noon' if appropriate (e.g.'1 a.m.', '1:30 p.m.','midnight', 'noon', '12:30 p.m.')
s	Outputs seconds, 2 digits with leading zeros (e.g.'00' to'59')
u	Outputs microseconds (e.g.000000 to 999999)
Timezone characters	Description
e	Outputs timezone name. Can be in any format, or mightreturn an empty string, depending datetime definition (e.g. ','GMT', '-500', 'US/Eastern')
O	Outputs difference in timezone to Greenwich time in hours(e.g.'+0200')
T	Outputs datetime time zone (e.g.'EST', 'MDT')
Z	Outputs time zone offset in seconds. The offset fortimezones west of UTC is always negative, and for those east of UTCis always positive (e.g.-43200 to 43200)
Day and week characters	Description
D	Outputs day of the week, textual, 3 letters(e.g.'Thu','Fri')
l (Lowercase L)	Outputs day of the week, textual, long(e.g.'Thursday','Friday')
S	Outputs English ordinal suffix for day of the month, 2characters (e.g.'st', 'nd', 'rd' or 'th')
w	Outputs day of the week, digits without leading zeros(e.g.'0' for Sunday to '6' for Saturday)
z	Outputs day of the year (e.g.0 to 365)
W	Outputs the week number of the year, with weeks startingon Monday based on ISO-8601 (e.g.1, 53)
o	Outputs week-numbering year, corresponding to theISO-8601 week number (W)(e.g.'1999')
Month characters	Description
b	Outputs textual month, 3 letters, lowercase(e.g.'jan','feb')
d	Outputs day of the month, 2 digits with leading zeros(e.g.'01' to '31')
j	Outputs day of the month without leading zeros (e.g. '1'to '31')
E	Outputs month, locale specific alternative representationusually used for long date representation (e.g. 'listopada' forPolish locale, as opposed to 'Listopad')
F	Outputs month, textual, long (e.g.'January','February')
m	Outputs month, 2 digits with leading zeros (e.g.'01' to'12')
M	Outputs month, textual, 3 letters(e.g.'Jan','Feb')
n	Outputs month without leading zeros (e.g.'1' to'12')
N	Outputs month abbreviation in Associated Press style(e.g.'Jan', 'Feb', 'March', 'May')
t	Outputs number of days in the given month (e.g. 28 to31)
Year characters	Description
L	Outputs boolean for whether it's a leap year (e.g.True orFalse)
y	Outputs year, 2 digits (e.g.'99')
Y	Outputs year, 4 digits (e.g.'1999')

To literally output a date character in a string statement youcan use the backslash character (e.g. {{variable date:'jSof F o'}} outputs 1st of January 2018, note the escapedof)

• time.- The time filter formats thetime component of a Python datetime object. Thetime filter is similar to the date filterwhich uses a string to specify a time format. For example, if avariable contains a datetime object with a time ofnoon the filter statement {{variable time:'g:i'}}outputs 12:00. The time filter uses the same format charactersillustrated in table 3-3 related to the time of day.

• timesince.- The timesince filteroutputs the time that's passed between a datetimeobject and the current time. The timesince filteroutput is expressed in seconds, minutes, hours, days or weeks. Forexample, if a variable contains the datetime object01/01/2018 12:00pm and the current time is 01/01/2018 3:30pm thestatement {{variable timesince}} outputs 3 hours 30minutes. The timesince filter can also calculate thetime that's passed between two datetime objectvariables -- instead of the default current time -- by appending asecond datetime object argument (e.g.{{variable timesince:othervariable}}).
• timeuntil.-The timeuntil filter outputs the time that needs toelapse from the current time to a datetime object. Thetimeuntil filter output is expressed in seconds,minutes, hours, days or weeks. For example, if a variable containsthe datetime object 01/01/2018 10:00pm and the currenttime is 01/01/2018 9:00pm the statement{{variable timeuntil}} outputs 1 hour. Thetimeuntil filter can also calculate the time thatneeds to elapse between two datetime object variables-- instead of the default current time -- by appending a seconddatetime object argument (e.g.{{variable timeuntil:othervariable}}).

Strings, lists and numbers

• add.- The add filter adds values. Theadd filter can add two variables or a hardcoded valueand a variable. For example, if a variable contains 5 the filterstatement {{variable add:'3'}} outputs 8. If valuescan be coerced to integers -- like the last example -- theadd filter performs a sum, if not the add filterconcatenates. For a string variable that contains 'Hello' thefilter statement {{variable add:' World'}} outputsHello World. For a list variable that contains ['a','e','i'] andanother list variable that contains ['o','u'] the filter statement{{variable add:othervariable}} outputs['a','e','i','o','u'].
• default.- The default filter is used to specify a default value if avariable is false, doesn't exist or is empty. For example, if avariable doesn't exist in a template, contains False or is an emptystring (') the filter statement {{variable default:'novalue'}} outputs novalue.
• default_if_none.- The default filter isused to specify a default value if a variable is None.For example, if a variable contains None the filterstatement {{variable default_if_none:'No value'}}outputs No value. Note if a variable contains an emptystring (') this is not considered Noneand the default_if_none filter does not output itsargument value.
• length.- The length filteris used to obtain the length of a value. For example, if a variablecontains the string latte the filter statement{{variable length}} outputs 5. For a list variablethat contains ['a','e','i'] the filter statement{{variable length}} outputs 3.
• length_is.- The length_is filter is used to evaluate if the lengthof a value is the size of a given argument. For example, if avariable contains latte the tag and filter statement{% if variable length_is:'7' %} evaluates to false.For a list variable that contains ['a','e','i'] thetag and filter statement {% if variable length_is:'3'%} evaluates to true.
• make_list.- The make_list filter creates a list from a string ornumber. For example, for the filter and tag statement {% withmycharlist='mocha' make_list %} the mycharlist variable isassigned the list ['m', 'o', 'c', 'h', 'a']. For an integervariable that contains 724 the filter and tag statement {%with myintlist=variable make_list %} the myintlist isassigned the list ['7', '2', '4'].
• yesno.- The yesno filter maps the value of a variable fromTrue,False and None to thestrings yes,no,maybe. For example, if a variable evaluates toTrue the filter statement{{variable yesno}} outputs yes, if the variableevaluates to False the same statement outputs no andif the variable evaluates to None the same statementoutputs maybe. The yesno filter also accepts custommessages as arguments. For example, if a variable evaluates toTrue the filter statement{{variable yesno:'yea,nay,novote'}} outputs yea, ifthe variable evaluates to False the same statementoutputs nay and if the variable evaluates to None thesame statement outputs novote.

Numbers

• divisibleby.- The divisibleby filterreturns a boolean value if a variable is divisible by a givenvalue. For example, if a variable contains 20 the filter statement{{variable divisibleby:'5'}} returnsTrue.
• filesizeformat.-The filesizeformat filter converts a number of bytes intoa friendly file size string. For example, if a variable contains250 the filter statement {{variable filesizeformat}}outputs 250 bytes, if it contains 2048 the output is 2 KB, if itcontains 2000000000 the output is 1.9 GB.
• floatformat.- The floatformat filter rounds a floating-point numbervariable. The floatformat filter can accept a positiveor negative integer argument to round a variable a specific numberof decimals. If no argument is used, the floatformatfilter rounds to one decimal place, as if the argument where -1.For example, if a variable contains 9.33253 the filter statement{{variable floatformat}} outputs 9.3, for the samevariable {{variable floatformat:3}} outputs 9.333 andfor {{variable floatformat:-3}} the output is 9.333;if a variable contains 9.00000 the filter statement{{variable floatformat}} outputs 9,{{variable floatformat:3}} outputs 9.000 and{{variable floatformat:-3}} outputs 9; and if avariable contains 9.37000 the filter statement{{variable floatformat}} outputs 9.4,{{variable floatformat:3}} outputs 9.370 and{{variable floatformat:-3}} outputs9.370.
• get_digit.- The get_digit filteroutputs the digit of a number variable, where 1 is the last digit,2 is the second to last digit and so on. For example, if a variablecontains 10257, the filter statement{{variable get_digit:'1'}} outputs 7 and the filterstatement {{variable get_digit:'3'}} outputs 2. If thevariable or argument is not an integer or if the argument is lessthan 1, the get_digit filter output's the originalvariable value.
• phone2numeric.- The phone2numeric filter converts mnemonic letters inphone numbers to digits. For example, if a variable contains1-800-DJANGO the filter statement{{variable phone2numeric}} outputs 1-800-352646. Aphone2numeric filter value doesn't necessarily need toprocess valid phone numbers, the filter simply converts letters totheir equivalent telephone keypad numbers.

Strings

• capfirst.- The capfirst filter capitalizes the first character of astring variable. For example, if a variable contains helloworld the filter statement{{variable capfirst}} outputs Helloworld.
• cut.- The cut filter removes allvalues of a given argument from a string variable. For example, ifa variable contains mocha latte the filter statement{{variable filter:'mocha'}} outputslatte. For the same variable the filter statement is{{variable filter:' '}} outputsmochalatte.
• linenumbers.- The linenumbers filter adds line numbers to each stringvalue separated by a new line. Listing 3-15 illustrates an exampleof the linenumbers filter.

Listing 3-15 Django linenumbers filter

• lower.- The lower filter converts all values of a string variableto lowercase. For example, if a variable contains HelloWorld the filter statement {{variable lower}}outputs hello world.
• stringformat.- The stringformat filter formats a value with Python stringformatting syntax^[4]. For example, if a variablecontains 7 the filter statement{{variable stringformat:'03d'}} outputs007. Note the stringformat filter doesnot require the leading % used in Python stringformatting syntax.
• pluralize.- The pluralize filter returns a plural suffix based on thevalue of an argument. For example, if the variabledrink_count contains 1 the filter statement 'Youhave {{drink_count}} drink{{pluralize drink_count}}' outputs'You have 1 drink', if the variable contains 2 thesame filter statement outputs 'You have 2 drinks'. Bydefault, the pluralize filter uses the letter s which is the mostcommon plural suffix. However, you can specify different singularand plural suffixes with additional arguments. For example, thefilter statement 'We have {{store_count}}business{{store_count pluralize:'es'}}' outputs 'Wehave 1 business' if store_count is 1 or'We have 5 businesses' if store_count is5. Another example is the filter statement 'We have{{resp_number}}responsibilit{{resp_number pluralize:'y','ies'}}' whichoutputs 'We have 1 responsibility' ifresp_number is 1 or 'We have 3responsibilities' if resp_number is 3.
• slugify.- The slugify filter converts a string to an ASCII-typestring. This means a string in converted to lowercase, removesnon-word characters (alphanumerics and underscores), strips leadingand trailing white space, as well as converts spaces to hyphens.For example, if a variable contains Welcome to the #1Coffeehouse! the filter statement{{variable slugify}} outputswelcome-to-the-1-coffeehouse. The slugifyfilter is typically used to normalize strings for urls and filepaths.
• title.- The title filter converts all first character values of astring variable to uppercase. For example, if a variable containshello world the filter statement{{variable title}} outputs HelloWorld.
• truncatechars.- The truncatechars filter truncates a string to a givennumber of characters and appends an ellipsis sequence. For example,if a variable contains Coffeehouse started as a smallstore the filter statement{{variable truncatechars:20}} outputsCoffeehouse started...
• truncatechars_html.- The truncatechars_html filter is similar to thetruncatechars filter but is aware of HTML tags. Thisfilter is designed for HTML content, so content isn't left withopen HTML tags. For example, if a variable contains<b>Coffeehouse started as a smallstore</b> the filter statement{{variable truncachars_html:20}} outputs<b>Coffeehouse start..</b>.
• truncatewords.- The truncatewords filter truncates a string to a givennumber of words and appends an ellipsis sequence. For example, if avariable contains Coffeehouse started as a small storethe filter statement {{variable truncatwords:3}}outputs Coffeehouse started as...
• truncatewords_html.- The truncatewords_html filter is similar to thetruncatewords filter but is aware of HTML tags. Thisfilter is designed for HTML content, so content isn't left withopen HTML tags. For example, if a variable contains<b>Coffeehouse started as a smallstore</b> the filter statement{{variable truncatwords_html:3}} outputs<b>Coffeehouse started as..</b>.
• upper.- The upper filter converts all values of a string variableto uppercase. For example, if a variable contains HelloWorld the filter statement {{variable lower}}outputs HELLO WORLD.
• wordcount.- The wordcount filter counts the words in a string. Forexample, if a variable contains Coffeehouse started as a small store the filter statement{{variable wordcount}} outputs 6.

Lists and dictionaries

• dictsort.- The dictsort filter sorts a list of dictionaries andreturns new list sorted by a given key argument. For example, if avariable contains [{'name':'Downtown','city':'San Diego'},{'name':'Uptown','city':'San Diego'},{'name':'Midtown','city':'SanDiego'}] the filter and tag statement {% withnewdict=variable dictsort:'name' %} the newdictvariable is assigned the list [{'name':'Downtown','city':'SanDiego'},{'name':'Midtown','city':'SanDiego'},{'name':'Uptown','city':'San Diego'}]. Thedictsort filter can also operate on lists of tuples orlists by specify an index number (e.g. {% withotherlist=listoftuples dictsort:0 %}) to sort by the firstelement of each tuple in the list).
• dictsortreversed.-The dictsortreversed filter sorts a list ofdictionaries and returns new list sorted in reverse by a given keyargument. The dictsortreversed filter works likedictsort except it returns the list in reverseorder.
• join.- Thejoin filter joins a list with a string. The joinfilter works just like Python's str.join(list). Forexample, for a list variable that contains ['a','e','i','o','u']the filter statement {{variable join:'--'}} outputsa--e--i--o--u.
• first.- Thefirst filter returns the first item in a list. Forexample, for a list variable that contains ['a','e','i','o','u']the filter statement {{variable first}} outputs a.
• last.- Thelast filter returns the last item in a list. Forexample, for a list variable that contains ['a','e','i','o','u']the filter statement {{variable last}} outputs u.
• random.- Therandom filter returns a random item in a list. Forexample, for a list variable that contains ['a','e','i','o','u']the filter statement {{variable random}} could outputa, e, i, o or u.
• slice.- Theslice filter returns the slice of a list. For example,for a list variable that contains ['a','e','i','o','u'] the filterstatement {{variable slice:':3'}} outputs['a','e','i'].
• unordered_list.- Theunordered_list outputs an HTML unordered list from alist variable. Listing 3-16 illustrates an example of theunordered_list filter.

Listing 3-16. Django unordered_list filter

Spacing and special characters

• addslashes.- Theaddslashes filter adds slashes to all quotes (i.e. itescapes quotes). The addslashes filter is useful whenDjango templates are used to export data to other systems thatrequire to escape quotes (e.g. CSV files). For example, if avariable contains Today's news the filter statement{{variable addslashes}} outputs Today'snews.
• center.- Thecenter filter center aligns a value and pads it withadditional white space characters until it reaches the givenargument of characters. For example, if a variable containsmocha the filter statement{{variable center:'15'}} outputs
• ' mocha '. (i.e. 5spaces to the left of mocha, 5 spaces for mocha, 5 spaces to theright of mocha.
• ljust.- Theljust filter left aligns a value and pads it withadditional white space characters until it reaches the givenargument of characters. For example, if a variable containsmocha the filter statement{{variable ljust:'15'}} outputs
• 'mocha '.(i.e. 5spaces for mocha, 10 space padding).
• rjust.- Therjust filter right aligns a value and pads it withadditional white space characters until it reaches the givenargument of characters. For example, if a variable containslatte the filter statement{{variable rjust:'10'}} outputs
• 'latte'.'(i.e. 5 space padding, 5 spaces forlatte).
• escape.- Theescape filter escapes HTML characters from a value.Specifically with the escape filter: <is converted to < ,> isconverted to > ,' (single quote)is converted to ' ,' (doublequote) is converted to " and& is converted to &amp.

Tip If you use the escape filter on contiguousvariables, it's easier to wrap the variables with the {% autoescape%} tag to achieve the same results.

• escapejs.- Theescapejs filter escapes characters into unicodestrings which are often used for JavaScript strings. Though theescapejs filter does not make a string HTML safe, itdoes protect against syntax errors when using templates to generateJavaScript/JSON. For example, if a variable contains'mocharn 'price:2.25' the filter statement{{variable escapejs}} outputsu0022mochau000Du000A u0027price:2.25u0022.
• force_escape.- Theforce_escape filter escapes HTML characters from avalue just like the escape filter. The difference isforce_escape is applied immediately and returns a newand escaped string. This is useful when you need multiple escapingor want to apply other filters to the escaped results. Normally,you'll use the escape filter.
• linebreaks.- Thelinebreaks filter replaces plain text line breaks withHTML tags, a single newline becomes an HTML line break(<br/>) and a new line followed by a blank linebecomes a paragraph break (</p>). For example,if a variable contains 385 MainnSan Diego, CA thefilter statement {{variable linebreaks}} outputs<p>385 Main<br/>San Diego,CA</p>.
• linebreaksbr.- Thelinebreaksbr filter converts all text variable newlines to HTML line breaks (<br/>). For example,if a variable contains 385 MainnSan Diego, CA thefilter statement {{variable linebreaksbr}} outputs385 Main<br/>San Diego, CA.
• striptags.- Thestriptags filter removes all HTML tags from a value.For example, if a variable contains<b>Coffee</b>house, the <i>best</i><span>drinks</span> the filter statement{{variable striptags}} outputs Coffeehouse, thebest drinks.

Caution The striptags filter uses very basic logicto strip HTML tags. This means there's a possibility a convolutedpiece of HTML isn't fully stripped of tags. This is why content invariables passed through the striptags filter is automaticallyescaped and should never be marked as safe.

• safe.- The safefilter marks a string as not requiring HTML escaping.
• safeseq.- Thesafeseq applies the safe filter to eachelement of a list. It's useful in conjunction with other filtersthat operate on a list, such as the join filter(e.g.{{stores safeseq join:', '}}). You wouldn't usethe safe filter directly on list variables, as itwould first convert the variable to a string, rather than workingwith the individual elements of a list.
• wordwrap.- Thewordwrap filter wraps words at a given character linelength argument. Listing 3-17 illustrates an example of thewordwrap filter.

Listing 3-17. Django wordwrap filter

Development and testing

• pprint.- Thepprint filter is a wrapper for Python'spprint.pprint(). The pprint filter isuseful during development and testing because it outputs theformatted representation of an object.

Urls

• iriencode.- Theiriencode filter converts an InternationalizedResource Identifier (IRI) to a string that is suitable forinclusion in a URL. This is necessary if you're trying to usestrings containing non-ASCII characters in a URL. For example, if avariable contains ?type=cold&size=large the filterstatement {{variable iriencode}} outputs?type=cold&size=large.
• urlencode.- Theurlencode filter escapes a value for use in a URL. Forexample, if a variable containshttp://localhost/drinks?type=cold&size=large thefilter statement {{variable urlencode}} outputshttp%3A//localhost/drinks%3Ftype%3Dcold%26size%3Dlarge.The urlenconde filter assumes the /character is safe. The urlencode filter can accept anoptional argument with the characters that should not be escaped.An empty string can be provided when all characters should beescaped (e.g.{{variable urlencode:'}} outputshttp%3A%2F%2Flocalhost%2Fdrinks%3Ftype%3Dcold%26size%3Dlarge).
• urlize.- Theurlize filter converts text URLs or email addressesinto clickable HTML links. This urlize filter works onlinks prefixed with http://, https://, or www. Links generated bythe urlize filter have a rel='nofollow' attributeadded to them. For example, if a variable contains Visithttp://localhost/drinks the filter statement{{variable urlize}} outputs Visit <ahref='http://localhost/drinks'rel='nofollow'>http://localhost/drinks</a>; if avariables contains Contact support@coffeehouse.com thefilter statement {{variable urlize}} outputsContact <ahref='mailto:support@coffeehouse.com'>support@coffeehouse.com</a>.
• urlizetrunc.- Theurlizetrunc filter converts text URLs and emails intoclickable HTML links -- just like the urlize filter --except it truncates the url to a given number of characters thatinclude an ellipsis sequence. For example, if a variable containsVisit http://localhost/drinks the filter statement{{variable urlizetrunc:20}} outputs Visit <ahref='http://localhost/drinks'rel='nofollow'>http://localhost/..</a>.