diff --git a/jinja.html.markdown b/jinja.html.markdown new file mode 100644 index 00000000..7e5b8e96 --- /dev/null +++ b/jinja.html.markdown @@ -0,0 +1,270 @@ +--- +language: Jinja +contributors: + - ["AdaĆ­as Magdiel", "https://github.com/AdaiasMagdiel"] +filename: learn-jinja.j2 +--- + +## Getting Started with Jinja + +Jinja is a fast, expressive, and extensible templating engine for Python +applications. + +Jinja includes a lot of functionalities, such as: +- Template inheritance and inclusion; +- Defining and importing macros within templates; +- Security mechanisms to prevent XSS attacks; +- A sandboxed environment that can safely render untrusted templates; +- Extensible filters, tests, functions, and even syntax. + +A Jinja template is simply a text file. Jinja doesn't require a specific +extension, but it's common to use `.j2` or `.jinja` to make it easier for +some IDEs. + +There are a few kinds of delimiters. The default Jinja delimiters are configured +as follows: + +- `{% ... %}` for Statements +- `{{ ... }}` for Expressions to print to the template output +- `{# ... #}` for Comments not included in the template output + +```jinja +{# This is an example of a comment. #} + +{# + You can use this syntax + to write multiline comments + as well. +#} +``` + + +## VARIABLES + +```jinja +{# You have the option to access variables from the context passed to the template #} + +{{ foo }} + +{# + Additionally, you can use a dot (.) to access attributes of a variable or + use Python syntax, using [] +#} + +{{ foo.bar }} +{{ foo['bar'] }} + +{# Within the template, you can define variables as well #} + +{% set name = "Magdiel" %} +{{ name }} +``` + +## Loops + +```html +

Members

+ + + +
+{% for key, value in my_dict.items() %} +

{{ key }}

-

{{ value }}

+{% endfor %} +
+ + +
+{% for idx, url in enumerate(urls) %} + Go to url {{ idx + 1 }} +{% endfor %} +
+``` + +## Conditionals + +The if statement in Jinja is similar to the if statement in Python. It is +commonly used to check if a variable is defined, not empty, and not false in +its most basic form. + +```html +{% if users %} + +{% endif %} + + +{# For multiple branches, elif and else can be used like in Python. #} + + +{% if message.status == "error" %} +

{{ message.content }}

+{% elif message.status == "success" %} +

{{ message.content }}

+{% else %} +

{{ message.content }}

+{% endif %} +``` + +## Template Inheritance + +One of the most powerful features of Jinja is template inheritance. You can +create a base layout with predefined blocks that you can extend in another file +and override with your own content. + +```html +{# file: base.html.j2 #} + + + + + {% block head %} + + + {% block title %}{% endblock title %} - Learning Jinja + {% endblock head %} + + +
+ {% block content %}{% endblock %} + {# the endblock tag doesn't need the name of the block #} +
+ + + + + +{# file: child.html.j2 #} + +{% extends "base.html.j2" %} + +{% block head %} + {{ super() }} + +{% endblock %} + +{% block title %}Home{% endblock %} + +{% block content %} +

Index

+

Welcome to my home homepage.

+{% endblock %} + + + +{# RESULT #} + + + + + + + Home - Learning Jinja + + + +
+

Index

+

Welcome to my home homepage.

+
+ + + +``` + +### Including Content + +You can include content from another template on your current template using +the `{% include "template/path" %}` tag. + +```html + +{# file: footer.html.j2 #} + + + + + +{# file: index.html.j2 #} +... + +
+

Hi! I'm John Doe!

+
+ {% include "footer.html.j2" %} + +... + + + +{# RESULT #} + +... + +
+

Hi! I'm John Doe!

+
+ + +... +``` + +Variables passed to the main template can also be used in the include, as the +included template has access to the context of the main template. + +```html +{# file: greetings.html.j2 #} + +

I'm the {{ name }} and i like to {{ hobby }}.

+ + + +{# file: index.html.j2 #} + +{% set name = "Captain Nemo" %} +{% set hobby = "navigate through the depths of the ocean" %} + +
+ {% include "greetings.html.j2" %} +
+ + + +{# RESULT #} + +
+

I'm the Captain Nemo and i like to navigate through the depths of the ocean.

+
+``` + +## Macros + +Macros are basically like functions in another languages. You can define macros with or without arguments and reuse them in various parts of your template. + +```html +{% macro input(value="", type="text", placeholder="") -%} + +{%- endmacro %} + +

{{ input(placeholder="Your username") }}

+

{{ input(type="password") }}

+``` + +## Official Documentation + +To learn more, access the [official documentation](https://jinja.palletsprojects.com/en/).