pongo2 1.0-RC1 released back to frontpage

One month after releasing pongo2 beta to the public I’m happy to announce that I’ve released the first release candidate of pongo2 1.0, the first stable release.

pongo2 1.0-RC1 includes almost any filters and tags which are being shipped with Django 1.7 (there are only a few exceptions which are caused by the different languages used (Python vs. Go) and by some slightly different escape-handling in pongo2; see README.md in the repository for more about the caveats).

You find a complete list of supported filters and tags at the end of this blog post.

Any help in testing of pongo2 1.0-RC1 would be really appreciated. I hope to get a first stable version of pongo2 soon.

Update: Try pongo2 out in the pongo2 playground.

Django-templates vs. pongo2-templates

I want to use this blog post to point out which features pongo2 is shipping with and how it differs from Django-templates.

Complex function calls

pongo2 allows complex function calls (in any expression) which means calling functions with arbitrary arguments (even nested function calls). It’s really straight-forward so I only will bring up one example:

{{ myobject.myfunction(ctxfunction(variable1, "string", 42))|intcomma }}

You can either call functions on objects or provide functions (even variadic ones) through pongo2.Context.

Expressions

pongo2 ships with arithmetic and boolean expression support. One example:

{% with good_karma_threshold=42 %}
    {% for user in users %}
        {% if user.karma >= good_karma_threshold %}
            {{ user }} got good karma!
        {% else %}
            {{ user }} is missing {{ good_karma_threshold-user.karma }} 
                karma points for a good karma.
        {% endif %}
    {% endfor %}
{% endwith %}

The following operators are supported:

Operator Meaning Example Remarks
+ addition -3 + 7 *1
- (unary) negative -42
- (binary) subtraction 4 - 5 *1
* multiplication 4 * 15 *1
/ division 4 / 15 *1
!, not (unary) negation !(4==5)
<, >, <=, =>, == value comparison 5 < 6 *2
||, or disjunction (2 > 3) || (1 < -5)
&&, and conjunction (2 > 3) && (1 < -5)
% remainder 4 % 3 *3
^ exponentiation 3 ^ 7 *4
in contains mykey in mymap *5

Remarks:

  1. Returns a float64 if any of these two operands is float, otherwise it returns int.
  2. Returns a boolean (true or false).
  3. Only works on integers (floats are being converted to integer before doing this operation).
  4. Result will always be a float64.
  5. Checks whether a map/struct/string contains a key/field/substring. Returns a boolean (true or false).

The common operator precedences apply. It’s allowed to use parenthesis to enforce other precedencens.

Macros

pongo2 ships with the ability of defining macros. You can wrap a part of your template (which can itself include filters and tags) and make it available as a callable function for later and repetitive use in the same template:

A macro definition looks like this:

{% macro user_profile_info(profile_object, name=default_name, admin=false) %}
<div class="profile">
    <p>The user #{{ profile_object.ID }} is called {{ name }}.</p>
    {% if admin %}<p>This user is an admin!</p>{% endif %}
</div>
{% endmacro %}

Macros are supporting an arbitrary amount of parameters and even supporting default values. You can use these macros in the following way:

{% for user in users %}
    {{ macro(user) }}
{% endfor %}

<p>Admin 'flosch':</p>
{{ macro(user_flosch_obj, "flosch", true) }}

<p>Moderator 'fred':</p>
{{ macro(user_fred_obj, "fred") }}

pongo2-addons

I’ve created an addons-package, pongo2-addons, which ships even more tags and filters like

  • filesizeformat
  • slugify
  • truncatesentences
  • markdown
  • and some humanization-filters like intcomma, ordinal, naturalday and timesince/timeuntil/naturalday.

Most of them are depending on 3rd-party-libraries (this is why I created a separated package; pongo2 itself does not depend on any 3rd-party-library), but thanks to nice Go dependency model it’s hassle-free to install the whole package:

go get -u github.com/flosch/pongo2-addons

As I pointed out in my first pongo2 blog post, it’s simple to activate more filters and tags. Therefore to activate these tags/filters all you have to do is to import this package (after importing pongo2):

_ "github.com/flosch/pongo2-addons"

That’s all. As always, any feedback on this package would be very appreciated as well.

Supported (built-in) filters and tags in pongo2

The complete list of currently supported and built-in filters and tags (package pongo2) is following.

Filters

  • add
  • addslashes
  • capfirst
  • center
  • cut
  • date
  • default
  • default_if_none
  • divisibleby
  • escape
  • escapejs
  • first
  • floatformat
  • get_digit
  • iriencode
  • join
  • last
  • length
  • length_is
  • linebreaks
  • linebreaksbr
  • linenumbers
  • ljust
  • lower
  • make_list
  • phone2numeric
  • pluralize
  • random
  • removetags
  • rjust
  • safe
  • slice
  • stringformat
  • sriptags
  • time
  • title
  • truncatechars
  • truncatechars_html
  • truncatewords
  • truncatewords_html
  • upper
  • urlencode
  • urlize
  • urlizetrunc
  • wordcount
  • wordwrap
  • yesno

Two special pongo2-filters:

  • float
  • integer

Tags

  • autoescape
  • block
  • comment
  • cycle
  • extends
  • filter
  • firstof
  • for
  • if
  • ifchanged
  • ifequal
  • ifnotequal
  • include
  • lorem
  • now
  • spaceless
  • ssi
  • templatetag
  • verbatim
  • widthratio
  • with

One special pongo2-tag:

  • macro

New comment

Comments are moderated and therefore are not published instantly.





Comments

  • Aug 22 2014 18:59:27 +0200 CEST

    blocks are supported by Florian

    Hi Philippe,

    blocks are supported in any template (and template inheritance through the extends/block-tag is supported as well). Are you missing something?

    Ciao, Florian

  • Aug 20 2014 19:04:03 +0200 CEST

    FR by Philippe

    Should it support blocks inside includes?