APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Twig

APPNETOS extends Twig with application-aware template resolution, reusable app inclusion and integrated debugging.

Purpose

APPNETOS uses Twig to render application templates and content views. The shared rendering layer configures Twig with APPNETOS-specific functions, custom-first template lookup, an enhanced include tag and optional profiling.

Application and alias templates can be customized without changing the original template references. Standard Twig functionality remains available alongside the APPNETOS integrations.

APPNETOS Twig functions

Core\Twig\FunctionLoader explicitly registers four functions on the Twig environment.

Function Behavior
dump(...) Forwards each supplied value to Core\Debug::addDump() when the debug controller is available. Returns no output.
get_debug_bar_head() Returns the DebugBar head resources as a string, or null when unavailable.
get_debug_bar_body() Returns the DebugBar body output as a string, or null when unavailable.
include_app(id) Accepts a MongoDB ObjectId, its string representation or null; delegates inclusion to Core\Render::includeApp(). Returns no direct string value.

Debug functions are fault-tolerant and suppress errors from the optional debug infrastructure. include_app() belongs to the normal rendering pipeline and does not suppress resolution or rendering errors. Invalid ObjectId strings can also raise errors.

{% set appId = '507f1f77bcf86cd799439011' %}
{{ dump(appId) }}
{{ include_app(appId) }}

{# Use in the layout when DebugBar resources are needed #}
{{ get_debug_bar_head()|raw }}
{{ get_debug_bar_body()|raw }}

The ObjectId above is illustrative; use an existing app document ID. The debug functions return null when debugging is unavailable. Apply |raw only to trusted framework-generated DebugBar markup.

Custom-first template resolution

Core\Twig\AliasFilesystemLoader extends Twig's filesystem loader. For application templates it obtains candidate paths from ApplicationResolver::getApplicationTemplatePaths() and selects the first existing file. This supports custom overrides for the active application or alias and fallback to original application templates. Shared Core templates without an application mapping use Twig's normal filesystem lookup.

The same loader applies to direct template rendering and native Twig template operations such as include and extends. The exact directory candidates and their precedence are determined by ApplicationResolver, rather than being hard-coded in this loader.

Enhanced include tag

APPNETOS registers CustomIncludeTokenParser for the standard include tag. Its CustomIncludeNode first resolves string template names ending in .twig through Core\Files::getTemplate(). Resolved absolute paths below APPNETOS_ROOT are converted to relative loader paths. When a different template is selected and Core\Debug is available, the replacement is logged as a debug message.

The tag preserves familiar Twig options, including fallback template arrays, with variables, only and ignore missing.

{% include 'application/templates/header.html.twig' %}
{% include ['application/templates/custom.html.twig', 'application/templates/default.html.twig'] %}
{% include 'application/templates/card.html.twig' with {'title': 'Example'} only %}
{% include 'application/templates/optional.html.twig' ignore missing %}

Template candidates are attempted in order. A Twig LoaderError allows the next candidate to be tried; without ignore missing, a missing template raises a loader error. Errors from APPNETOS path resolution are not intentionally suppressed. Only string names ending in .twig receive the explicit Core\Files resolution step.

Debug mode and profiling

Core\Render configures Twig with its cache directory, debug and auto_reload according to the active debug setting; strict_variables is disabled. When debug mode is enabled, APPNETOS registers Twig's DebugExtension and ProfilerExtension, creates a Twig\Profiler\Profile and forwards that profile to StandardDebugBar::addTwigProfileCollector().

This makes Twig rendering and template profiling available to the APPNETOS DebugBar. The environment also registers Twig's StringLoaderExtension, the APPNETOS function loader and the custom include parser. Context-specific extensions can be registered through the protected initTwigExtensions() hook.

Relevant source files

  • Core\Render\Base — Twig environment, debug profiling and extension registration
  • Core\Twig\FunctionLoader — APPNETOS Twig functions
  • Core\Twig\AliasFilesystemLoader — application-aware template lookup
  • Core\Twig\TokenParser\CustomIncludeTokenParser — custom include syntax parsing
  • Core\Twig\Node\CustomIncludeNode — include resolution and rendering

Framework-neutral base templates

The shared base.html.twig and default.html.twig are Bootstrap-neutral. Bootstrap-specific components choose versioned templates in their own controllers. Dynamic HTML root attributes come from ui.html_attributes and must be HTML-attribute escaped.


<html{% if ui.html_attributes is defined %}
    {% for name, value in ui.html_attributes %
        {{ name|e('html_attr') }}="{{ value|e('html_attr') }}"
    {% endfor %}
{% endif %}>

JavaScript constants in Twig must be complete statements, including semicolons, particularly when output is compressed. For dynamic JavaScript strings, JSON-safe encoding should be reviewed rather than relying on raw output.

Next Steps

Previous

Content

Explore Content

Next

Js

Explore Js