Marc - Sebastian Lucksch > Dotiac-0.8 > Dotiac::DTL::Filter

Download:
dotiac/Dotiac-0.8.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.8   Source   Latest Release: Dotiac-0.8_1

SEE ALSO ^

http://www.djangoproject.com, Dotiac::DTL

NAME ^

Dotiac::DTL::Filter - Filters for variables

SYNOPSIS ^

        {{ variable|add:10|upper }}
        {% cycle variable|add:10|upper variable2|add:10|upper %}
        {% include "foo.html"|cut:"o"|upper %}
        ...

DESCRIPTION ^

Filters are small functions that are applied on variables. They can be stacked by using a pipe character ( | ), without space. And they have arguments, denoted by a ":".

Some filters don't require arguments, some have optional ones and other require then.

If a filter can't use an argument or variable, it will just return it unchanged.

In this implementation, you can also apply variables as arguments to any filter and even have multiple arguments for your own filters (seperated by a ","). However this may cause trouble in some tags (like {% url %}) and is not compatible to Django. Just know it's there if you need it.

Examples:

        {{ var|upper }}

Runs the "upper" filter on the content of the variable "var"

        {{ var|add:"10" }}

Adds a 10 to the content of the variable "var". the "10" is the argument (also called parameter) to the "add" filter.

        {{ var|upper|add:"foo" }}

This construct runs the "upper" filter on the content of the variable "var" and then adds the string "foo" to the result of that.

        {{ foo|add:bar }}

In this implementation: adds the content of the variable "bar" to content of the variable "foo".

These are the filters you can use:

add :VALUE

Adds a VALUE (number or string) to the variable.

If both variable and the argument are both numbers, they are added together.

If one or both of them are not numbers, the arguments are concatenated together.

        {{ "10"|add:"10" }} {# 20 #}
        {{ "10"|add:"-5" }} {# 5 #}
        {{ "10"|add:"foo" }} {# 10foo #}
        {{ "foo"|add:"bar" }} {# foobar #}
        {{ "bar"|add:100 }} {# 100 #}
        {% filter add:100 %}1{{ "10"|add:"20"}}{% endfilter %} {# 230 #} {# 100+1.(10+20) #}

Bugs and Differences to Django

Django only supports numbers to be added (and substracted).

addslashes

Adds backslashes before any quotes in the variable. This is useful for CSV output

If you want some more

        {{ 'Daimos "TheKing" Miller / Peter \'TheMan\' Miller'|addslashes }} {# Daimos \"TheKing\" Miller \\ Peter \'TheMan\' Miller #}

Bugs and Differences to Django

If you find any, please report them.

capfirst

Converts the first character of the value to an uppercase. Also see upper() and lower()

        {{"foo"|capfirst}} {# Foo #}
        {{"bar"|capfirst}} {# Bar #}
        {{"foo bar"|capfirst}} {# Foo bar #}

Bugs and Differences to Django

If you find any, please report them.

center :FIELDWIDTH

Centers a text in a field of FIELDWIDTH spaces.

This is not usefull for HTML (unless in <pre> like tags), but for email's from forms or other text files.

        {{ "Hello"|center:"20" }} {# "       Hello        " #}

The string is not truncated if it's larger than FIELDWIDTH

Bugs and Differences to Django

Also supports a padding parameter, if you want something other than spaces:

        {{ "Hello":center:"20";"-" }} {# "-------Hello--------" #}

cut :STRING

Removes any occurences of a STRING from the value.

        {{ "Hello World"|cut:"el" }} {# Hlo World #}
        {{ "Hello World"|cut:"l" }} {# Heo Word #}

Bugs and Differences to Django

If you find any, please report them.

date :FORMAT

Formats a time, according to a FORMAT according to a FORMAT..

        {{ "20002312"|date:"jS F Y H:i" }} {# 20th August 1970 14:11 #}
        {{ post.time|date:"jS o\f F" }} {# It is the 4th of September #}

The retured value will be safe if the FORMAT string is safe.

Format options

You can combine as many of these as you like or need:

        {{ var|date:"d. b." }}
"\"

Returns the next character, regardless if it is a format character or not.

        {{ var|date: "\H\e\l\l\o \W\o\r\l\d" }} {# =Hello World #}

This also means "\n" will in this case render an "n" and NOT a newline. Same for "\t","\f","\b","\r".

"a"

Returns whether it is AM or PM in Associated Press style: "a.m." or "p.m".

        {{ var|date: "a" }} {# a.m. on in the morning#}

This might change if a locale module is loaded.

"A"

Returns AM or PM.

        {{ var|date: "A" }} {# AM #}

This might change if a locale module is loaded.

"b"

Returns the current month in 3 lowercase letters.

        {{ var|date: "b" }} {# dec #}

This might change if a locale module is loaded.

"d"

Returns the day of the month with a leading zero.

        {{ var|date: "d" }} {# 01 #} to {# 31 #}
"D"

Returns the day of the week in 3 letters (2 letters on some locales)

        {{ var|date: "D" }} {# Sun #}

This might change if a locale module is loaded.

"f"

Returns the time with hours and minutes, but minutes are left out if they are 0.

        {{ var|date: "f" }} o'clock {# 11:30 o'clock #} {# 3 o'clock #}
"F"

Returns the month in long form.

        {{ var|date: "F" }} {# December #}

This might change if a locale module is loaded.

"g"

Returns the hour in 12-hour format without leading zeros.

        {{ var|date: "g" }} {# 1 #} to {# 12 #}
"G"

Returns the hour in 24-hour format without leading zeros.

        {{ var|date: "G" }} {# 0 #} to {# 24 #}
"h"

Returns the hour in 12-hour format with a leading zero.

        {{ var|date: "h" }} {# 01 #} to {# 12 #}
"H"

Returns the hour in 24-hour format with a leading zero.

        {{ var|date: "H" }} {# 00 #} to {# 24 #}
"i"

Returns the minutes with a leading zero.

        {{ var|date: "i" }} {# 00 #} to {# 60 #}
"j"

Returns the day of the month without leading zeros.

        {{ var|date: "j" }} {# 1 #} to {# 31 #}
"l"

Returns the day of the week as a long text.

        {{ var|date: "l" }} {# Sunday #}

This might change if a locale module is loaded.

"L"

Returns 1 or 0 whether it's a leap year.

        {{ var|date: "L" }} {# 1 #}
"m"

Returns the current month as a number with leading zeros.

        {{ var|date: "m" }} {# 01 #} to {# 12 #}
"M"

Returns the current month in 3 letters.

        {{ var|date: "M" }} {# Dec #}

This might change if a locale module is loaded.

"n"

Returns the current month as a number without leading zeros.

        {{ var|date: "m" }} {# 1 #} to {# 12 #}
"M"

Returns the current in Associated Press style notation.

        {{ var|date: "M" }} {# Jan. #} {# March #} {# July #}

This might change if a locale module is loaded.

"O"

Returns the difference to Greenwich time in hours.

        {{ var|date: "O" }} {# +0100 #}
"P"

Returns either the time in 12 hours and minutes if not zero with a.m. or p.m., midnight or noon.

        {{ var|date: "P" }} {# 1 p.m. #} {# 11:56 a.m. #} {# midnight #} {# noon #}
"r"

Returns an RFC 2822 formatted date.

        {{ var|date: "r" }} {# Sun, 28 Dec 2008 18:36:24 +0200' #}

This might change if a locale module is loaded.

"s"

Returns the seconds with a leading zero.

        {{ var|date: "s" }} {# 00 #} to {# 59 #}
"S"

Returns the ordinal suffix for the day of the month.

        {{ var|date: "S" }} {# st #} {# nd #} {# rd #} {# th #}

Defaults to english, this may change if a locale module is loaded.

"t"

Returns the number of days in the given month.

        {{ var|date: "t" }} {# 28 #} to  {# 31 #}
"T"

Returns the current timezone (needs the POSIX module)

        {{ var|date: "T" }} {# CET #} {# GMT #} {# EST #}...
"w"

Returns the day of week as a number from 0 (Sunday) to 6 (Saturday)

        {{ var|date: "w" }} {# 1 #} to {# 6 #}
"W"

Returns the ISO-8601 week number of year (uses the POSIX module), weeks start on monday.

        {{ var|date: "w" }} {# 1 #} to {# 53 #}
"y"

Returns the year in two digits (with leading zeros)

        {{ var|date: "y" }} {# 08 #}
"Y"

Returns the year in four (or more) digits (with leading zeros)

        {{ var|date: "Y" }} {# 2008 #}
"z"

Returns the day of the year without leading zeros

        {{ var|date: "z" }} {# 0 #} to {# 365 #}
"Z"

Returns the difference of the current timezone to GMT in seconds.

        {{ var|date: "Z" }} {# -43200 #} to {# 43200 #}

Bugs and Differences to Django

Since Perl has no default DateTime Object, this expects a normal unix timestamp ( result of the time() call in perl).

It also excepts the result of localtime as an array reference, this is useful for timestamps > 2038 on 32-Bit machines.

        var=>[36,31,21,2,0,109,5,1,0];
        
        {{ var|date:"jS F Y H:i" }} {# 2nd January 2009 21:31 #}

default :STRING

If the value is false (See Dotiac::DTL::Tag::if) it will return the STRING, otherwise the value.

        {{ "Hello World"|cut:"el" }} {# Hlo World #}
        {{ "Hello World"|cut:"l" }} {# Heo Word #}

Bugs and Differences to Django

Perl considers other things false as Python.

default_if_none :STRING

If the value is not defined (not found or set to undef) it will return the STRING, otherwise the value.

        {{ "Hello World"|cut:"el" }} {# Hlo World #}
        {{ "Hello World"|cut:"l" }} {# Heo Word #}

Bugs and Differences to Django

Perl considers other things false as Python.

dictsort :PROPERTY

Sorts an array of hashes, objects or arrays by a common PROPERTY. (See |dictsort for reverse sort)

        Posts=>[
                {title=>"I love food",text=>"I really do",category=>"My life"},
                {title=>"I love TV",text=>"Even more than food",category=>"My life"},
                {title=>"Simpsons",text=>"Awesome TV show",category=>"TV shows"},
                {title=>"ANTM",text=>"I love this one",category=>"TV shows"},
                {title=>"xkcd",text=>"The best webcomic",category=>"Webcomics"}
        ]

        {% for x in Posts|dictsort:"category" %}...
        {% endfor %}
        {% for x in Posts|dictsort:"title" %}...
        {% endfor %}

Bugs and Differences to Django

If PROPERTY is omitted, it just sorts by name, you can use this to sort an array of strings.

        ListofWords=>["Foo","Bar","Baz"]

        {% for x in Posts|dictsort %}
                {{x}}
        {% endfor %}

dictsortreversed :PROPERTY

Sorts an array of hashes, objects or arrays by a common PROPERTY in reverse order. (See |dictsort for normal order)

        Posts=>[
                {title=>"I love food",text=>"I really do",category=>"My life"},
                {title=>"I love TV",text=>"Even more than food",category=>"My life"},
                {title=>"Simpsons",text=>"Awesome TV show",category=>"TV shows"},
                {title=>"ANTM",text=>"I love this one",category=>"TV shows"},
                {title=>"xkcd",text=>"The best webcomic",category=>"Webcomics"}
        ]

        {% for x in Posts|dictsort:"category" %}...
        {% endfor %}
        {% for x in Posts|dictsort:"title" %}...
        {% endfor %}

Bugs and Differences to Django

If PROPERTY is omitted, it just sorts by name, you can use this to sort an array of strings.

        ListofWords=>["Foo","Bar","Baz"]

        {% for x in Posts|dictsort %}
                {{x}}
        {% endfor %}

divisibleby :NUMBER

Returns 1 (true value) if the value is divisible by NUMBER.

        {{ "21"|divisibleby:"7" }} {# 1 #}
        {{ "45"|divisibleby:"8" }} {# 0 #}

Bugs and Differences to Django

Django's divisibleby returns a True or False. There is no binary type in perl, so it will return 1 or 0

escape

Marks a string as unsafe, i.e. in need of escaping for output.

< , >, ', " and & are converted to &lt;, &gt;, &#39;, &quot; and &amp; respectively.

Beware: Escaping is done only once and only after all filters are applied. If you want to esacpe at this position in the filter pipeline use force_escape.

        {{ "<>"|escape }} {# &lt;&gt; #}
        {{ "<>"|escape|cut:"&"|escape }} {# &lt;&gt; #} {# Escaping is done only once after all filter are applied #}
        {{ "<>"|force_escape|cut:"&"|escape }} {# lt;gt; #} {# This might be what you want. #}

Bugs and Differences to Django

If you find any, please report them.

escapejs

Escapes a Javascript (JSON) String. This will not generate JSON Code out of datastructures, use Dotiac::DTL::Addon::JSON for that.

        <script>var="{{ "\""|escapejs|safe }}"</script> {# <script>var="\""</script> #} {# you will have to mark it as safe if you are generating in script tags #}
        <body onload="alert('{{ "\""|escapejs|escape }}')"> {# <body onload="alert('\&quot;')" #} {# Better escape in event handlers#}

Bugs and Differences to Django

Might escape some more characters than original Django.

On perl 5.6.2 unicode output is not really supported, you will get for example:

        \u00e3\u0093\u00b4 instead of \u4532

filesizeformat

Returns a number of bytes in bytes, Kb, Mb, Gb or Tb ... This is used to display the size of files/traffic or anything else counted this way to be read by humans

        {{ "3939232"|filesizeformat }} {# 3.76 Mb #}
        {{ "5838388588776"|filesizeformat }} {# 5.31 Tb #}
        {{ "1012"|filesizeformat }} {# 1012 bytes #} {# < 1024 #}

This will divide by 1024, not 1000.

Bugs and Differences to Django

If you find any, pleas report them

first

Returns the first element of a list.

        var=>[1,2,3,4];

        {{ var|first }} {# 1 #}
        {{ "abc"|make_list|first }} {# a #}

Bugs and Differences to Django

Also returns the first value in a hash.

fix_ampersands

Replace & with &amp;. See escape and force_escape for a better solution.

Doesn't mark the value safe.

        var=>"Tom & Jerry";

        {{ var|fix_ampersands }} {# Tom &amp;amp; Jerry #}
        {{ var|fix_ampersands|safe }} {# Tom &amp; Jerry #}

Bugs and Differences to Django

This is somewhat deprecated in Django and replaced by the autoescaping routines. Don't use this anymore.

floatformat :DIGITS

Formats a (float) value with variables with a number DIGITS after the dot. If DIGITS is negative, it will cut off trailing zeros (and the dot).

DIGITS defaults to -1

        {{ "1.001"|floatformat }} {# 1 #}
        {{ "1.001"|floatformat:"2" }} {# 1.00 #}

Bugs and Differences to Django

If you find any, please put them in the tracker or drop me a mail.

force_escape

Escapes the string at this point in the filter stack (not at the end like escape)

< , >, ', " and & are converted to &lt;, &gt;, &#39;, &quot; and &amp; respectively.

See also escape

        {{ "<>"|force_escape|escape }} {# &amp;lt;&amp;gt; #}
        {{ "<>"|force_escape|safe }} {# &lt;&gt; #}

Bugs and Differences to Django

If you find any, please report them.

get_digit :NTH

Extracts the NTH digit (from the right) of an integer value.

Just returns the value if it was not an integer.

        {{ "4893"|get_digit:"3" }} {# 8 #}
        {{ "4893"|get_digit:"2" }} {# 9 #}

Bugs and Differences to Django

If you find any, please report them.

iriencode

Encodes Unicode characters according to rfc3987, all characters above 0x7f are encoded.

You won't need this filter if the output of the script is already Unicode.

This does not replace urlencode, but should be used in conjunction with it.

The result from iriencode of an iriencoded string will not change it anymore.

        {{ "http://www.google.com/?q=\u0334%20"|iriencode }} {# http://www.google.de/?q=%CC%B4%20 #} {# %20 stayed #}
        http://www.google.com/?q={{ var|urlencode|iriencode }}&hl=en {# The best way if var contains urlunsafe chars and unicode chars #}

Bugs and Differences to Django

This won't work on EBCDIC Systems for now, sadly.

If you find anything else, please report them.

join :STRING

Joins a list-value by a STRING.

        var=>["Foo","Bar","!"];

        {{ var|join:" : " }} {# Foo : Bar : ! #}
        {{ "4893"|make_list|join:"," }} {# 4,8,9,3 #}

Bugs and Differences to Django

If you find any, please report them.

last

Returns the last element of a list. (See also first)

        var=>[1,2,3,4];

        {{ var|first }} {# 4 #}
        {{ "abc"|make_list|first }} {# c #}

Bugs and Differences to Django

Also returns the last value in a hash.

length

Returns the length of arrays, lists or strings.

The returned value is always marked safe (not that it matters for output)

        var=>[10,2,73,64];

        {{ var|length }} {# 4 #}
        {{ "abc"|length }} {# 3 #}

Bugs and Differences to Django

Tries to call count() on objects to get the length.

undef (none in python) will be counted as "".

length_is :LENGTH

Returns 1 if the length of arrays, lists or strings is equal to LENGTH, "" otherwise.

The returned value is always marked safe (not that it matters for output)

        var=>[10,2,73,64];

        {% if var|length_is:"4" %}1{% else %}0{% endif %} {# 1 #}
        {% if "abc"|length_is:"2" %}1{% else %}0{% endif %} {# 0 #}

Bugs and Differences to Django

Tries to call count() on objects to get the length.

Unknown datastructers (GLOBS, FILEHANDLES, SCALARREFS ... ) will never return true.

undef (none in python) will be counted as "".

linebreaks

Converts newlines in the value to paragraphs (<p>) and breaks <br>. The output will always be a paragraph.

Two linebreaks/newlines (\n\n) start a new paragraph, a single one gets converted into a <br /> tag.

This filter will apply escaping and return a safe string. Otherwise the <p> and <br /> tags are going to be messed up

        {{ "Hello\nWorld"|linebreaks }} {# <p>Hello<br />World</p> #}
        {{ "Hello\nWorld\n\n<b>Foo</b>"|escape|linebreaks|safe }} {# <p>Hello<br />World</p><p>&lt;b&gt;Foo&lt;/b&gt;</p>#}

Bugs and Differences to Django

This might mess up your HTML if the variable is marked safe, this will appear if you want the user to include HTML or something like BBCode.

You will have to use linebreaksbr (See below) for that.

        {{ "<b>...\n\n..</b>"|safe|linebreaks }} {# <p><b>...</p><p>..</b></p> #} {# Invalid: You can see how the <b> tag is split up #}
        <p>{{ "<b>...\n\n..</b>"|safe|linebreaksbr }}</p> {# <p><b>...<br /><br />..</b></p> #} {# Valid! #} 

Many BBCode interpreters don't replace linebreaks by themselves. (In most forums for example you can as a user switch on "Post is HTML" "Post is BBCode" "Convert linebreaks")

linebreaksbr

Converts newlines into breaks <br>.

This filter will apply escaping and return a safe string. Otherwise the <br /> tags are going to be messed up

        {{ "Hello\nWorld"|linebreaksbr }} {# Hello<br />World #}
        {{ "Hello\nWorld\n\n<b>Foo</b>"|escape|linebreaksbr|safe }} {# Hello<br />World<br /><br />&lt;b&gt;Foo&lt;/b&gt;#}

Bugs and Differences to Django

If you find any, please report them

linenumbers

Writes a linenumber before each line.

        {{ "Hello\nWorld"|linenumbers }} 
        {# 1: Hello
        2: World #}
        {{ "Hello\nWorld\n\n<b>Foo</b>"|escape|linenumbers|safe }} 
        {# 1: Hello
        2: World
        3:
        4: <b>Foo</b> #}

Bugs and Differences to Django

If you find any, please report them

ljust :FIELDWIDTH

Leftjustifies a text in a field of FIELDWIDTH spaces.

This is not usefull for HTML (unless in <pre> like tags), but for email's from forms or other text files.

        {{ "Hello"|ljust:"20" }} {# "Hello               " #}

The string is not truncated if it's larger than FIELDWIDTH

Bugs and Differences to Django

Also supports a padding parameter, if you want something other than spaces:

        {{ "Hello":ljust:"20";"-" }} {# "Hello---------------" #}

lower

Converts the value into lowercase.

        {{ "Hello, World"|lower }} {# hello, world #}

Bugs and Differences to Django

If you find any, please report them

make_list

Splits a value into a list of characters

        {% for x in "abc"|make_list %}{{ x }}{% if not forloop.last %},{% endif %}{% endfor %}{# a,b,c #}
        {{ "def"|make_list|join:"," }} {% d,e,f %}

Bugs and Differences to Django

If given a parameter it splits at the parameter:

        {{ "b,c,d"|make_list:","|join:" " }} {# b c d #}

phone2numeric

Converts a value into a phonenumber.

All this does is replace A-Y (without Q) with 2-9.

        {{ "800-FOOBAR"|phone2numeric }}{# 800-366227 #}
        {{ "Hello, World"|phone2numeric }} {% 43556, 96753 %}

Bugs and Differences to Django

This has no locale support for now, locales will have to redefine this one.

pluralize :STRING

Prints a different STRING if the value is not "1". This is very useful if you want to pluralize a value.

When STRING contains a comma ("y,ies") it will either take the first value on 1 and the other one in any other case.

The STRING defaults to "s".

        1 template{{ "1"|pluralize }}, 3 template{{ "3"|pluralize }} {# 1 template, 3 templates #}
        1 walrus{{ "1"|pluralize:"es" }}, 4 walrus{{ "4"|pluralize:"es" }} {# 1 walrus, 4 walruses #}
        1 berr{{ "1"|pluralize:"y,ies" }}, 6 berr{{ "6"|pluralize:"y,ies" }} {# 1 berry, 6 berries #}

Bugs and Differences to Django

Since Dotiac::DTL also supports multiple arguments to filters, you can also write this:

        1 cherr{{ "1"|pluralize:"y";"ies" }}, 6 cherr{{ "6"|pluralize:"y";"ies" }} {# 1 cherry, 6 cherries #}

This is useful if one of your STRINGs contains a comma.

        1 {{ "1"|pluralize:"";", and that's all" }}, 2 {{ "2"|pluralize:"";", and that's all" }} {# 1, 2, and that's all #}

pprint

For Debug

Bugs and Differences to Django

Uses Data::Dumper instead of pprint

random

Returns a random element of a list. (See also first and last)

        var=>[1,2,3,4];

        {{ var|first }} {# 3 #} {# or 1 or 2 or 4 #}
        {{ "abc"|make_list|first }} {# c #} {# or a or b #}

Bugs and Differences to Django

Also returns a random value of a hash.

removetags :TAGS

Removes HTML (XML) TAGS from the value. TAGS is a space seperated list of tags to be removed

        {{ "<p><b>Hello</b>World</p>"|removetags:"b" }} {# <p>HelloWorld</p> #}
        {{ "<p><b>H<u>el</u>lo</b><span class="w">World</span></p>"|removetags:"b span" }} {# <p>H<u>el</u>loWorld</p> #}

See striptags if you want to strip all tags from the value.

Bugs and Differences to Django

If you find any, please report them.

rjust :FIELDWIDTH

Rightjustifies a text in a field of FIELDWIDTH spaces.

This is not usefull for HTML (unless in <pre> like tags), but for email's from forms or other text files.

        {{ "Hello"|rjust:"20" }} {# "               Hello" #}

The string is not truncated if it's larger than FIELDWIDTH

Bugs and Differences to Django

Also supports a padding parameter, if you want something other than spaces:

        {{ "Hello":ljust:"20";"-" }} {# "---------------Hello" #}

safe

Marks a string as safe, i.e. in no need of escaping for output.

Also see escape.

        var="<>";

        {{ var|safe }} {# <> #}
        {{ var|escape|cut:"&"|safe }} {# <> #} {# Escaping is done only once after all filter are applied #}

Bugs and Differences to Django

If you find any, please report them.

slice :POSITION

Extracts a sublist out of a list from a POSITION. POSITION is a string of two number seperated by a ":"

See also http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice.

        var=[1,2,3,4];

        {{ var|slice:":2" }} {# [1, 2] #}
        {{ var|slice:"1:" }} {# [2, 3, 4] #}
        {{ var|slice:"1:2" }} {# [2] #}
        {{ var|slice:"-2:-1" }} {# [3] #}

Bugs and Differences to Django

Also allows you to get a single item:

        {{ var|slice:"3" }} {# 4 #} Same as: {{ var.3 }}

Also works on hashes. Then it slices the value list orderd by their keys.

slugify

Converts the value to lowercase, removes all non word characters, removes trailing and leading whitespaces and replaces all other spaces with a "-".

The resulting value is marked safe.

This is useful if you want to generate a save ID for something like a name an user entered, while keeping the original meaning.

        {{ "Hello World"|slugify }} {# hello-world #}
        {{ "<b>Foo</b>"|slugify }} {# bfoob #}

Bugs and Differences to Django

If you find any, please report them.

stringformat :FORMAT

FORMATs a value according to python's format rules. (str.format: http://docs.python.org/library/stdtypes.html#str.format)

The leading % is dropped. ("%s" = "s"),

        {{ "Hello World"|stringformat:"s" }} {# Hello World #}
        {{ "3"|stringformat:"#+05b" }} {# 0b011 #}
        {{ "3"|stringformat:"#+02d" }} {# +03 #}

Bugs and Differences to Django

This uses perl's sprintf, which is about the same as python's format. See "sprintf" in perlfunc

"r" is emulated

striptags

Removes all HTML (XML) tags from the value.

        {{ "<p><b>Hello</b>World</p>"|striptags }} {# HelloWorld #}
        {{ "<p><b>H<u>el</u>lo</b><span class="w">World</span></p>"|striptags }} {# HelloWorld #}

See removetags if you want to remove only some tags from the value.

Bugs and Differences to Django

If you find any, please report them.

time :FORMAT

Formats a time, according to a FORMAT.

This only formats for time. See date if you want to format date and time.

        {{ "20002312"|time:"H:i" }} {# 14:11 #}
        {{ post.time|time:"P" }} {# noon #}

The retured value will be safe if the FORMAT string is safe.

Format options

You can combine as many of these as you like or need:

        {{ var|time:"G:i A" }}
"\"

Returns the next character, regardless if it is a format character or not.

        {{ var|time: "\H\e\l\l\o \W\o\r\l\d" %} {# =Hello World #}

This also means "\n" will in this case render an "n" and NOT a newline. Same for "\t","\f","\b","\r".

"a"

Returns whether it is AM or PM in Associated Press style: "a.m." or "p.m".

        {{ var|time: "a" }} {# a.m. on in the morning#}

This might change if a locale module is loaded.

"A"

Returns AM or PM.

        {{ var|time: "A" }} {# AM #}

This might change if a locale module is loaded.

"f"

Returns the time with hours and minutes, but minutes are left out if they are 0.

        {{ var|time: "f" }} o'clock {# 11:30 o'clock #} {# 3 o'clock #}
"g"

Returns the hour in 12-hour format without leading zeros.

        {{ var|time: "g" }} {# 1 #} to {# 12 #}
"G"

Returns the hour in 24-hour format without leading zeros.

        {{ var|time: "G" }} {# 0 #} to {# 24 #}
"h"

Returns the hour in 12-hour format with a leading zero.

        {{ var|time: "h" }} {# 01 #} to {# 12 #}
"H"

Returns the hour in 24-hour format with a leading zero.

        {{ var|time: "H" }} {# 00 #} to {# 24 #}
"i"

Returns the minutes with a leading zero.

        {{ var|time: "i" }} {# 00 #} to {# 60 #}
"O"

Returns the difference to Greenwich time in hours.

        {{ var|time: "O" }} {# +0100 #}
"P"

Returns either the time in 12 hours and minutes if not zero with a.m. or p.m., midnight or noon.

        {{ var|time: "P" }} {# 1 p.m. #} {# 11:56 a.m. #} {# midnight #} {# noon #}
"s"

Returns the seconds with a leading zero.

        {{ var|time: "s" }} {# 00 #} to {# 59 #}
"Z"

Returns the difference of the current timezone to GMT in seconds.

        {{ var|time: "Z" }} {# -43200 #} to {# 43200 #}

Bugs and Differences to Django

Since Perl has no default DateTime Object, this expects a normal unix timestamp ( result of the time() call in perl).

It also excepts the result of localtime as an array reference, this is useful for timestamps > 2038 on 32-Bit machines.

        var=>[36,31,21,2,0,109,5,1,0];
        
        {{ var|time:"H:i" }} {# 21:31 #}

timesince :REFERNCETIME

Formats a time value and displays the time since REFERENCE TIME has passed.

REFERENCETIME is now if it is omitted

If you have a past event and want to display the time since then you can use this filter.

For any time in the future it will return 0 Minutes

        {{ post.date|timesince }} {# 3 years #}
        {{ post.date|timesince:edit.date }} {# 3 minutes #} {# after the post #}

timesince and timeuntil only differ in the order of the arguments:

        {{ date1|timeuntil:date2 }} == {{ date2|timesince:date1 }}

The generated value is always marked as safe.

Bugs and Differences to Django

Like time and date it only accepts unix timestamps.

If given any additional parameter it will print out the full time, while without it will only print useful information

        {{ post.date|timesice:edit.date;"" }} {# 2 days 3 Minutes #}
        {{ post.date|timesice:"now";"" }} {# 3 years 2 days 2 seconds #} {# compare to current time #}

If you have just a elapsed time in seconds you can use this:

        {{ "0"|timesince:"60" }} {# 1 Minute #}

timeuntil :REFERNCETIME

Formats a time value and displays the time util REFERENCE TIME.

REFERENCETIME is now if it is omitted.

If you have a funture event and want to display the time util then you can use this filter

For any time in the past it will return 0 Minutes

        {{ marriage.date|timeuntil }} {# 3 years #}
        {{ marriage.date|timeuntil:engagement.date }} {# 3 month #} {# after the engagement #}

timesince and timeuntil only differ in the order of the arguments:

        {{ date1|timesince:date2 }} == {{ date2|timeuntil:date1 }}

The generated value is always marked as safe.

Bugs and Differences to Django

Like time and date it only accepts unix timestamps.

If given any additional parameter it will print out the full time, while without it will only print useful information

        {{ post.date|timeuntil:edit.date;"" }} {# 3 month 3 Minutes #}
        {{ marriage.date|timeuntil:"now";"" }} {# 3 years 2 days 2 seconds #} {# compare to current time #}

If you have just a elapsed time in seconds you can use this:

        {{ "60"|timeuntil:"0" }} {# 1 Minute #}

title

Converts the value into titlecase.

        {{ "500 kilos of heroin found"|title }} {# 500 Kilos Of Heroin Found #}

Bugs and Differences to Django

If you find any, please report them

truncatewords :NUMBEROFWORDS

Cuts off the value after a specific NUMBER OF WORDS. Replaces the removed parts with "..."

        {{ "500 kilos of heroin found"|truncatewords:"3" }} {# 500 kilos of ... #}
        {{ "Today is monday"|truncatewords:"3" }} {# Today is monday #}

Bugs and Differences to Django

If you find any, please report them

truncatewords_html :NUMBEROFWORDS

Cuts off the value after a specific NUMBER OF WORDS. Replaces the removed parts with "..."

Same as truncatewords, but also closes every HTML/XML Tag that's left open after the cutoff.

        {{ "<b>500 kilos <u>of</u> heroin found</b>"|truncatewords:"3" }} {# <b>500 kilos <u>of</u> ...</b> #}
        {{ "Today <u>is</u> monday"|truncatewords:"3" }} {# Today <u>is</u> monday #}

This one is much slower than truncatewords, so use this only when you have HTML tags in your value.

Returns a safe string and escapes an unsafe value.

Bugs and Differences to Django

If you have a six word string and a tag after the sixth word and you truncate to six words, it will still insert a "...".

unordered_list

Converts a list-value of list into a HTML-unordered list without the surrounding <ul> Tag.

        var=>[
                "Continents",
                [
                        "North America",
                        ["USA","Kanada"],
                        "South America",
                        ["Mexico"],
                        "Europe"
                        "Australia"
                        "Asia"
                ]
                        
        ]

        {{ var|unordered_list:"3" }} 
        {#
        <li>Continents
                <ul>
                        <li>North America
                                <ul>
                                        <li>USA</li>
                                        <li>Kanada</li>
                                </ul>
                        </li>
                        <li>South America
                                <ul>
                                        <li>Mexico</li>
                                </ul>
                        </li>
                        <li>Europe</li>
                        <li>Australia</li>
                        <li>Asia</li>
                </ul>
        </li>
        #}

Also supports the old format.

The returned value is always escaped (if unsafe) and marked safe.

Bugs and Differences to Django

The old verbose format is supported, but I don't trust the implementation. (It works, I don't know why)

urlencode

Converts all characters except wordcharacters, minus, "~" and "/" to be used in an url

        http://www.google.com/?q={{ "Hello World"|urlencode }} {# http://www.google.com/?q=Hello%20World #}

Bugs and Differences to Django

If given an argument it allows for more characters to not be encoded.

        {{ "http://www.google.com/?q=Hello World"|urlencode }} {# http%3A//www.google.com/%3Fq%3DHello%20World #}
        {{ "http://www.google.com/?q=Hello World"|urlencode:":?=&" }} {# http://www.google.com/?q=Hello%20World #}

upper

Converts the value into uppercase. (Also see lower)

        {{ "Hello, World"|upper }} {# HELLO, WORLD #}

Bugs and Differences to Django

If you find any, please report them

urlize

Converts all urls in the value.

        {{ "Go to www.dotiac.com and be happy"|urlize }} {# Go to <a href="www.dotiac.com" rel="nofollow">www.dotiac.com</a> and be happy #}

The value is escaped if needed and marked safe.

Bugs and Differences to Django

This uses a regular expression, so it might find different urls than Django.

This filter is not aware of <a href="..."></a> tags so it will convert the url in that. This should be fixed in the future.

urlizetrunc :LENGTH

Converts all urls in the value and truncates the output to LENGHT. LENGTH defaults to 15.

        {{ "Go to www.dotiac.com and be happy"|urlizetrunc:8 }} {# Go to <a href="www.dotiac.com" rel="nofollow">www.doti...</a> and be happy #}

The value is escaped if needed and marked safe.

Bugs and Differences to Django

This uses a regular expression, so it might find different urls than Django.

This filter is not aware of <a href="..."></a> tags so it will convert the url in that. This should be fixed in the future.

wordcount

Counts the number of words in the value

        {{ "Hello World"|wordcount }} {# 2 #}

The returned value is always safe.

Bugs and Differences to Django

If you find any, please report them.

wordwrap :AMOUNT_OF_CHARACTERS

Wraps the valuetext after a given AMOUNT OF CHARACTERS, but doesn't rip apart words.

AMOUNT_OF_CHARACTERS defaults to 80.

        {{ "This is some text without meaning"|wordwrap:7 }}
        {# This is
        some
        text
        without
        meaning #}

Bugs and Differences to Django

If you find any, please report them.

yesno :STRINGS

Returns a different STRING depending on the value. STRINGS is a comma seperated list of 2 or 3 strings.

The first string is the content returned if the value is true, the second is the content if it's false and the third is the content if the value is null (undef in perl).

If the thrid value is not given it defaults to the second one.

        true=>1,
        false=>0,
        null=>undef

        {{ true|yesno:"do it, don't do it" }} {# do it #}
        {{ false|yesno:"do it, don't do it" }} {# don't do it #}
        {{ null|yesno:"do it, don't do it" }} {# don't do it #}

        {{ true|yesno:"yes, no, don't care" }} {# yes #}
        {{ false|yesno:"yes, no, don't care" }} {# no #}
        {{ null|yesno:"yes, no, don't care" }} {# don't care #}

Bugs and Differences to Django

You can also give it three seperate arguments, this is quite useful for variables.

        {{ var|yesno:ontrue;onfalse;onnull }}

SEE ALSO ^

http://www.djangoproject.com, Dotiac::DTL

LEGAL ^

Dotiac::DTL was built according to http://docs.djangoproject.com/en/dev/ref/templates/builtins/.

AUTHOR ^

Marc-Sebastian Lucksch

perl@marc-s.de

syntax highlighting: