Metadata-Version: 2.4
Name: jinja-super-macros
Version: 0.2.0
Summary: Improved macros for Jinja
Author: Maxime Bouroumeau-Fuseau
Author-email: Maxime Bouroumeau-Fuseau <maxime.bouroumeau@gmail.com>
License-Expression: MIT
Requires-Dist: jinja2>=3.0.0,<4.0.0
Requires-Python: >=3.10
Project-URL: Repository, https://github.com/hyperflask/jinja-super-macros
Description-Content-Type: text/markdown

# Jinja Super Macros

Jinja Super Macros introduces a new syntax to call macros as well as an automatic macro loader.

```jinja
{% macro Form(action) %}
    <form action="{{ action }}" method="post">
        {{ caller() }}
    </form>
{% endmacro %}

{% macro FormInput(name) %}
    <input type="text" name="{{ name }}">
{% endmacro %}

<{Form action="/" }>
    <{FormInput name="email" }/>
</{Form}>
```

## Installation

    pip install jinja-super-macros

## Usage

To start using super macros, configure the environment with additional
extensions and settings and register your macros:

```py
from jinja2 import Environment, PackageLoader
from jinja_super_macros import configure_environment

env = Environment(loader=PackageLoader(__name__, 'templates'))
configure_environment(env)

env.macros.register_from_template("macros.html")
```

You can register macros from templates available through your loader:

 - `register_from_template(template)`: register all macros defined in the template
 - `register(name, template)`: register the specified macro located in the template
 - `register_from_env()`: look for macros in all templates:
    - by default, only look in templates named `__macros__.html`
    - pass `filter_func=False` to register from ALL templates
    - provide a custom `filter_func` (will receive the template name as argument)

You can also register macros using templates not accessible from your environment loader:

 - `register_file(filename)`
 - `register_directory(path)`
 - `register_package(package_name, package_path='macros')`

## New macro tags syntax

Macro tags allow you to use Jinja's macros with a syntax similar
to html tags. There are two types of macro tags: inline and block.
Inline is the equivalent of calling the macro using `{{ macro_name() }}`
and block is equivalent to the `{% call %}` directive.

Inline directives are enclosed in `<{` and `}/>`. Arguments
can be provided the same was as html attributes but their values are
Jinja expressions.

Inline tag example:

    <{macro_name arg1=value1 arg2=value2 arg-with-dashes=value3 }/>

is equivalent to:

    {{ macro_name(arg1=value1, arg2=value2, arg_with_dashes=value3) }}

Block tags, start with an opening directive enclosed in `<{` and `}>`
and must be closed with a closing directive `</{macro_name}>` (note
that the macro name is optional in the closing directive).

Block tag example:

    <{macro_name arg1=value1 arg2=value2 }>
        my macro content
    </{macro_name}>

is equivalent to:

    {% call macro_name(arg1=value1, arg2=value2) %}
        my macro content
    {% endcall %}

The list of attributes acts almost the same as a function call but with spaces instead of comma. This means that values can be single expressions with no operators or a full expression enclosed in parentheses.

    <{macro_name arg1 arg2 kw-arg1=single_value kw-arg2=("a" if True else "b") **kwargs }/>

By default, when a macro tag is used but no macro is found matching the name,
it will fallback to rendering the html tag:

    <{input type="checkbox" checked=is_checked() }/>

## New ways to define macros

Jinja Super Macros registry's also gives you the possibility to create macros from new sources.

- `create_from_file(filename)`: wrap the content of the file in a macro directive and register it
- `create_from_directory(path)`: create macros from all files in the directory (recursively):
    - by default, only files with the extension `.macro.html`
    - pass `filter_func=False` to register fromm ALL files
    - provide a custom `filter_func` (will receive the template name as argument)
    - files starting with a dot or un underscore are always ignored
- `create_from_global(global_name, macro_name)`: create a macro that calls a context variable
- `create_from_func(func)`: create a macro from a function
- `@env.macros.macro` decorator: create using the decorated function

When creating from files, use `kwargs.something` to access keyword arguments passed to the macro.  
Use `caller()` as usual for inner content.

When creating from function, pass `receive_caller=True` to receive the `caller` argument.