IntelliJ Quick Jinja

A plugin for the IntelliJ platform to quickly render and review Jinja templates.

Screenshots
Requirements
Installation
Setup
Usage
License
Credits
Donate ❤️

Screenshots

Provide sample variables in a dedicated editor

View the rendered result in either plaintext or HTML mode

Quickly choose the source of the template (file, selected text, clipboard)

Requirements

- A Python interpreter has to be installed on your system. -

The Jinja2 package is also mandatory:

Jinja2

pip3 install Jinja2

Quick Jinja will try to load and use Ansible-specific filters.
So this package is optional:

Ansible

pip3 install ansible

(NOTE: ansible already includes the Jinja2 package)

Installation

Use the IDE's built-in plugin system:

File --> Settings... --> Plugins --> Marketplace
search for: Quick Jinja
click the Install-button

Or go to the plugin page on the JetBrains-website, download the archive-file and install manually.

Setup

Before actually using Quick Jinja you should check/test your Python environment by using the plugin's settings page:

The plugin does not detect or use any (virtual) environment settings of your current project.
However, you can use an individual script/executable that does the necessary/individual preparations.

Example:

create a quick-jinja folder in your home directory:
```
mkdir ~/quick-jinja
```
change into it, and create a dedicated virtual environment:
```
cd ~/quick-jinja
python3 -m venv venv
```
activate the virtual environment and install Ansible via pip:
```
source venv/bin/activate
pip install ansible
```

finally, create this script file (~/quick-jinja/run.sh):

#!/bin/bash
source ~/quick-jinja/venv/bin/activate
python3 "${@}"

don't forget to make it executable:
```
chmod +x ~/quick-jinja/run.sh
```

Reference this script in the plugin; and you should be ready to go. 👍

Usage

General

Everything should be pretty self-explanatory.
Here's a detailed description anyway. 😀

Simply open and use the new tool window to render a Jinja template.
Choose the template source:
- the complete contents of the currently edited file (automatically changes when switching tabs)
- just the selected text from the currently opened editor
- the contents of your clipboard
You can use the pin icon to disable automatic file selection and keep the currently opened document as template-source.
Enter all variables (needed for rendering) in the variables tab.
Both JSON and YAML definitions are allowed.
The status icon on the right will indicate if parsing of the entered variables was successful.
Alternatively you can choose any file where variables should be loaded from.
Pressing the green run button will try to render the template and switch to the result tab.

The rendered template (or any errors) will be shown there.
Choose the view mode:
- Plain text
- HTML (which should be more suitable when rendering HTML-templates)
The dedicated status icon will also indicate if the rendering process successfully finished.

Base-/Parent-Templates

Quick Jinja can load outsourced templates which are integrated via "extends", "include" or "import".
Jinja's FileSystemLoader is being used for this.

The loader will search in these folders (and in this order) for the referenced file:

project root directory
parent directory of the file being rendered by Quick Jinja

Custom filters/tests

Filters

You can inject your own Jinja filters by referring to an external Python script via the "Customizations" tab.

The script must contain a function named filters; which returns a dictionary with all new filters to be exposed.

e.g.: my_custom_filters.py

def swap_case(value):
    return value.swapcase()

def enclose(value, prefix='[', suffix=']'):
    return f'{prefix}{value}{suffix}'

def filters():
    return {
        'swapcase': swap_case,
        'enclose': enclose
    }

{{ "QuickJinja" | swapcase }} -> qUICKjINJA
{{ "QuickJinja" | enclose }} -> [QuickJinja]
{{ "QuickJinja" | enclose('<', '>') }} -> <QuickJinja>

(check the official Jinja documentation for more about Custom Filters)

Tests

Adding custom tests works the same way as adding custom filters; however the function tests will return all new tests in this case.

e.g. my_custom_tests.py

import re

email_regex = re.compile(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$')

def is_email_address(value):
    return True if email_regex.match(value) else False

def tests():
    return {
        'email_address': is_email_address
    }

{{ "test@test.com" is email_address }} -> True
{{ "test<at>test.com" is email_address }} -> False

(check the official Jinja documentation for more about Custom Tests)

License

Please read the license file.

Credits

Braces icon / Play icon - Bootstrap
Heart icon - FontAwesome

Donate

If you like this plugin, please consider a donation. Thank you!

4ch1m/intellij-quick-jinja