JinjaX

In Jinjax, any content placed between the opening and closing tags of a component is automatically passed to that component as an implicit content variable. This is known as a slot. The component is responsible for the outer structure, while the user provides the inner content.

Example of a component definition:

<button class="fancy-btn">
  {{ content }}
</button>

Example of using the component:

<FancyButton>
  <i class="icon"></i> Click me!
</FancyButton>

When a component is placed inside a subfolder, its name is constructed by joining the subfolder names and the filename with dots, converted to PascalCase.

• Structure: components/Person/Form.jinja $\rightarrow$ Name: Person.Form
• Structure: components/password-reset/form.jinja $\rightarrow$ Name: PasswordReset.Form (Note: the kebab-case folder is converted to PascalCase).

You call these using the dot notation in both Python and HTML tags.

# Calling a nested component from Python
catalog.render("Person.Form")

<!-- Calling a nested component from another component -->
<Person.Form> some content </Person.Form>

Jinja macros are template snippets that function similarly to Python functions. They accept positional or keyword arguments and return rendered text.

To pass child content (blocks of HTML) into a macro, you must use the {% call %} syntax in conjunction with the {{ caller() }} function inside the macro definition. Without {% call %}, macros behave like standard functions.

{# Macro definition #}
{% macro button(type="button") -%}
  <button type="{{ type }}" class="btn-blue">
    {{ caller() }}
  </button>
{%- endmacro %}

{# Usage with child content #}
{% from 'forms.html' import button %}

{% call button("submit") %}Submit{% endcall %}

If you pass arguments to a component that were not declared in its {#def #} block, they are collected into a special attrs object. You can render these collected attributes onto an HTML element using {{ attrs.render() }}.

Warning: You cannot pass attrs to another component using <Component {{ attrs.render() }} /> because components are translated to function calls before rendering. Instead, you must pass the attrs object itself using the special _attrs argument.

{# Correct way to pass extra attributes to a child component #}
<MyButton _attrs={{ attrs }} />
<MyButton :_attrs="attrs" />

JinjaX is designed to bring the component-based development model (familiar to React or Vue users) to server-side rendered (SSR) applications using Jinja.

While standard Jinja templates often suffer from 'HTML soup' (long methods, deep nesting, and scattered variables), JinjaX aims to provide a way to organize markup, logic, and styles into modular, reusable packages. It seeks to bridge the gap between the power of Jinja macros and the ergonomic, JSX-like syntax of modern frontend frameworks.

If a subfolder contains a file named index.jinja, that file is treated as the primary component for that folder name. This allows you to call the component using only the folder name instead of the full path.

Example Structure:

└ components/
    └─ Tab/
        ├─ index.jinja
        └─ Panel.jinja

• Tab/index.jinja is called as Tab.
• Tab/Panel.jinja is called as Tab.Panel.

# Using the index component
catalog.render("Tab")

# Using a sibling component in the same folder
catalog.render("Tab.Panel")

You can organize components into nested directories. To reference a component located in a subfolder, use a dot (.) between each directory name in the component call.

For example, a component at form/Button.jinja is called as form.Button, and a component at product/items/Header.jinja is called as product.items.Header.

<form.Button> ... </form.Button>

<product.items.Header> ... </product.items.Header>

To use components from an installed library, add the library's component path to your catalog using catalog.add_folder(). The path provided by the library must be an absolute path.

import jinjax_ui
...
catalog.add_folder(jinjax_ui.components_path)

To use components inside a standard Jinja template, add the catalog instance to your Jinja environment's globals. Then, use catalog.irender("ComponentName", ...) to render the component. This is useful for embedding small components like buttons or forms within larger templates.

# Register catalog as a global in your Jinja environment
app.jinja_env.globals["catalog"] = catalog

{# Inside a template #}
<div>
  {{ catalog.irender("LikeButton", title="Like and subscribe!", post=post) }}
</div>
<p>Lorem ipsum</p>
{{ catalog.irender("CommentForm", post=post) }}