API Reference¶

Complete reference for all Django IncludeContents template tags, template engine features, and configuration options.

Template Tags¶

`{% includecontents %}`¶

Include a template with content blocks.

Syntax:

{% includecontents template_name [context_vars] %}
    [content]
    [{% contents block_name %}content{% endcontents %}]
{% endincludecontents %}

Parameters: - template_name: String or variable containing the template path - context_vars: Optional keyword arguments to pass to the template

Example:

{% includecontents "components/card.html" title="Hello" count=5 %}
    Main content
    {% contents footer %}Footer content{% endcontents %}
{% endincludecontents %}

`{% contents %}`¶

Define named content blocks within {% includecontents %}.

Syntax:

{% contents block_name %}content{% endcontents %}

Parameters: - block_name: Name of the content block (available as contents.block_name)

`{% wrapif %}`¶

Conditionally wrap content with HTML elements.

Syntax:

{% wrapif condition %}
    <wrapper>
        {% contents %}content{% endcontents %}
    </wrapper>
{% endwrapif %}

Shorthand syntax:

{% wrapif condition then "tag" attr=value %}
    content
{% endwrapif %}

Parameters: - condition: Boolean expression to evaluate - tag: HTML tag name (in shorthand syntax) - attr=value: HTML attributes (in shorthand syntax)

Conditional variants: - {% wrapelif condition %} - Else-if condition - {% wrapelse %} - Else block

`{% attrs %}`¶

Render component attributes with defaults and class handling.

Syntax:

{% attrs [attr=default_value] [class="classes"] [class:condition_class=condition] %}

Features: - Default values: {% attrs class="default" %} - Class extension: {% attrs class="& additional" %} (append) - Class prepending: {% attrs class="base &" %} (prepend) - Conditional classes: {% attrs class:active=is_active %} - Grouped attributes: {% attrs.group attr=value %}

`{% icon %}`¶

Render an icon from the configured icon sprite.

Syntax:

{% icon icon_name [attr=value] [use.attr=value] [as variable_name] %}

Parameters: - icon_name: Name of the icon (string or variable) - attr=value: Attributes for the SVG element - use.attr=value: Attributes for the USE element (prefixed with use.) - as variable_name: Store the SVG in a context variable instead of rendering

Example:

{% load icons %}
{% icon "home" class="w-6 h-6" %}
{% icon "user" class="avatar" use.role="img" use.aria-label="Profile" %}

{# Store in variable for conditional rendering #}
{% icon "optional-icon" class="w-4 h-4" as my_icon %}
{% if my_icon %}{{ my_icon }}{% endif %}

Generated output:

<svg class="w-6 h-6"><use href="#home"></use></svg>
<svg class="avatar"><use role="img" aria-label="Profile" href="#user"></use></svg>

Behavior: - Invalid/non-existent icons render nothing (empty string) - With as variable: invalid icons store empty string in the variable

`{% icons_inline %}`¶

Output the entire SVG sprite sheet inline in the page.

Syntax:

{% icons_inline %}

Usage: - Use in development mode for immediate icon updates - Place before closing </body> tag for best performance - Not needed in production when sprites are served as static files

Example:

{% load icons %}
<!DOCTYPE html>
<html>
<body>
    <!-- Page content -->
    {% icons_inline %}
</body>
</html>

`{% icon_sprite_url %}`¶

Get the URL to the generated sprite file.

Syntax:

{% icon_sprite_url %}

Usage: - Returns the URL in production mode when sprites are on disk - Returns empty string in development mode - Useful for preloading or custom sprite loading

Example:

{% icon_sprite_url as sprite_url %}
{% if sprite_url %}
    <link rel="preload" href="{{ sprite_url }}" as="image" type="image/svg+xml">
{% endif %}

Template Filters¶

`|not`¶

Negate boolean values, useful for conditional classes.

Syntax:

{{ value|not }}

Example:

<include:button class:disabled="{{ enabled|not }}">
    Click me
</include:button>

HTML Component Syntax¶

Component Tags¶

Syntax:

<include:component-name [attributes]>
    [content]
    [<content:block-name>content</content:block-name>]
</include:component-name>

Self-closing:

<include:component-name [attributes] />

Component Discovery¶

Components are discovered from templates/components/ directory:

File Path	Component Tag
`components/card.html`	`<include:card>`
`components/forms/field.html`	`<include:forms:field>`
`components/ui/button.html`	`<include:ui:button>`

Icon Tags¶

Syntax:

<icon:icon-name [attributes] [use.attributes] />

Parameters: - icon-name: Name of the configured icon - attributes: Attributes for the SVG element - use.attributes: Attributes for the USE element (prefixed with use.)

Examples:

<!-- Basic icon -->
<icon:home class="w-6 h-6" />

<!-- With accessibility attributes -->
<icon:user class="avatar" use.role="img" use.aria-label="User profile" />

<!-- With dynamic classes -->
<icon:star class="icon" class:filled="{{ is_favorite }}" />

Generated output:

<svg class="w-6 h-6"><use href="#mdi-home"></use></svg>
<svg class="avatar"><use role="img" aria-label="User profile" href="#tabler-user"></use></svg>
<svg class="icon filled"><use href="#lucide-star"></use></svg>

Attribute Syntax¶

String attributes:

<include:card title="Hello" class="my-card" />

Variable attributes:

<include:card title="{{ title }}" user="{{ user }}" />

Shorthand attributes:

<include:card {title} {user} />
<!-- Equivalent to: title="{{ title }}" user="{{ user }}" -->

Template expressions:

<include:card 
    title="{% if user %}Welcome {{ user.name }}{% else %}Welcome{% endif %}"
    href="{% url 'profile' user.pk %}"
    class="card {% if featured %}featured{% endif %}"
/>

Conditional classes:

<include:button class:active="{{ is_active }}" class:disabled="{{ is_disabled }}">
    Click me
</include:button>

Content Blocks¶

HTML content syntax:

<include:card>
    Main content
    <content:header>Header content</content:header>
    <content:footer>Footer content</content:footer>
</include:card>

Mixed syntax:

<include:card>
    Main content
    <content:header>HTML syntax header</content:header>
    {% contents footer %}Traditional syntax footer{% endcontents %}
</include:card>

Component Props System¶

Props Definition¶

Define component props in template comments:

Syntax:

{# props prop1, prop2=default, prop3=value #}

Types of props: - Required: title (no default value) - Optional with default: visible=True, count=0, text="default" - Optional without default: description="", callback=None

Example:

{# props title, subtitle="", priority="normal", show_meta=True #}
<div class="article priority-{{ priority }}">
    <h1>{{ title }}</h1>
    {% if subtitle %}<h2>{{ subtitle }}</h2>{% endif %}
    <div>{{ contents }}</div>
    {% if show_meta %}
        <footer>Priority: {{ priority }}</footer>
    {% endif %}
</div>

Enum Props¶

Define props with allowed values:

Syntax:

{# props variant=primary,secondary,danger #}

Optional enums (start with empty value):

{# props size=,small,medium,large #}

Usage:

<!-- Single value -->
<include:button variant="primary">Click me</include:button>

<!-- Multiple values (space-separated) -->
<include:button variant="primary large">Big Primary Button</include:button>

Generated variables for single value (variant="primary"): - variant - The prop value ("primary") - variantPrimary - Boolean (True) - variantSecondary - Boolean (False)

Generated variables for multiple values (variant="primary large"): - variant - The full value ("primary large") - variantPrimary - Boolean (True) - variantLarge - Boolean (True) - Other boolean flags remain False

Attrs Variable¶

Undefined attributes are collected in attrs:

Access methods: - {{ attrs }} - Render all attributes as HTML - {{ attrs.attrName }} - Access individual attribute (camelCase) - {% attrs %} - Render with defaults and class handling - {% attrs.group %} - Render grouped attributes

Kebab-case conversion:

<!-- Usage -->
<include:card data-user-id="123" my-custom-attr="value" />

<!-- In component -->
{# props #}
<div data-id="{{ attrs.dataUserId }}" custom="{{ attrs.myCustomAttr }}">
    {{ contents }}
</div>

Template Engine Features¶

Multi-line Template Tags¶

The custom template engine supports multi-line template tags:

{% if 
    user.is_authenticated 
    and user.is_staff 
    and user.has_perm('myapp.view_admin')
%}
    Admin content
{% endif %}

{% includecontents "complex-component.html"
    title="Long Title Here"
    description="A very long description that spans multiple lines"
    data=complex_data_structure
%}
    Content
{% endincludecontents %}

Auto-loaded Template Tags¶

When using the custom template engine, these tags are automatically available: - includecontents - contents
- wrapif, wrapelif, wrapelse - attrs - not filter - icon, icons_inline, icon_sprite_url (icon tags)

No need to use {% load includecontents %} or {% load icons %}.

Configuration¶

Template Engine Settings¶

Replace Django's default template backend:

TEMPLATES = [
    {
        'BACKEND': 'includecontents.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Traditional Setup¶

Without the custom engine, add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ... other apps
    'includecontents',
]

Then load tags in templates:

{% load includecontents %}

Icons Configuration¶

Configure the icons system in your settings:

INCLUDECONTENTS_ICONS = {
    # Required: List of icons to include
    'icons': [
        'mdi:home',                      # Iconify icons
        'tabler:user',
        ('custom-name', 'mdi:house'),    # Custom names with tuples
        'icons/logo.svg',                # Local SVG files from static files
        ('brand', 'logos/company.svg'),
    ],

    # Optional: Development mode (default: DEBUG)
    'dev_mode': True,

    # Optional: Cache timeout in seconds (default: 3600)
    'cache_timeout': 3600,

    # Optional: Iconify API base URL (default: 'https://api.iconify.design')
    'api_base': 'https://api.iconify.design',
}

Icon sources: - Iconify icons: Use prefix notation like mdi:home, tabler:calendar - Local SVG files: Place in static directories, reference by path (must end with .svg) - Custom names: Use tuples for custom component names

Context Variables¶

Available in Components¶

Components have access to these automatic context variables:

contents - Main content block
contents.block_name - Named content blocks
attrs - Undefined attributes object
Any explicitly passed props/attributes

Context processor variables are automatically available: - request - HTTP request object (from context_processors.request) - user - Current user (from context_processors.auth) - csrf_token - CSRF token (from Django's CSRF middleware) - Any custom context processor variables

Context Isolation¶

Components run in isolated context: - Parent template variables are NOT inherited - Only explicitly passed variables are available - Exception: Context processor variables are always available - Ensures predictable, reusable components

Error Handling¶

Common Errors¶

TemplateDoesNotExist:

Template 'components/nonexistent.html' does not exist

TemplateSyntaxError (missing required prop):

Missing required prop 'title' for component 'card'

TemplateSyntaxError (invalid enum value):

Invalid value 'invalid' for enum prop 'variant'. Must be one of: primary, secondary, danger

TemplateSyntaxError (malformed component):

Invalid component syntax: unclosed tag 'include:card'

Debug Tips¶

Check component file exists in templates/components/
Verify required props are provided
Check enum values match defined options
Validate HTML syntax in component usage
Use Django's template debugging for detailed error info

Performance Notes¶

Template caching: Components benefit from Django's template caching
Context isolation: Minimal overhead for creating isolated contexts
Attribute parsing: Parsed once during template compilation
Content rendering: Similar performance to standard {% include %} tags

Compatibility¶

Django: 3.2+ (LTS), 4.0+, 4.1+, 4.2+ (LTS), 5.0+
Python: 3.8+, 3.9+, 3.10+, 3.11+, 3.12+
Template engines: Works with Django's template system

The custom template engine is fully compatible with Django's standard template features and can be used as a drop-in replacement.

API Reference¶

Template Tags¶

{% includecontents %}¶

{% contents %}¶

{% wrapif %}¶

{% attrs %}¶

{% icon %}¶

{% icons_inline %}¶

{% icon_sprite_url %}¶

Template Filters¶

|not¶

HTML Component Syntax¶

Component Tags¶

Component Discovery¶

Icon Tags¶

Attribute Syntax¶

Content Blocks¶

Component Props System¶

Props Definition¶

Enum Props¶

Attrs Variable¶

Template Engine Features¶

Multi-line Template Tags¶

Auto-loaded Template Tags¶

Configuration¶

Template Engine Settings¶

Traditional Setup¶

Icons Configuration¶

Context Variables¶

Available in Components¶

Context Isolation¶

Error Handling¶

Common Errors¶

Debug Tips¶

Performance Notes¶

Compatibility¶

`{% includecontents %}`¶

`{% contents %}`¶

`{% wrapif %}`¶

`{% attrs %}`¶

`{% icon %}`¶

`{% icons_inline %}`¶

`{% icon_sprite_url %}`¶

`|not`¶