# Template Views

URL: /docs/theming/recipes/template-views/
Section: recipes
Tags: cookbook, views, openapi, taxonomies, templates

--------------------------------------------------------------------------------

Template Views Bengal provides View objects that normalize access to complex data in templates. Instead of dealing with different data structures depending on configuration, Views give you consistent properties every time. Availability: All View filters are automatically registered and available in all template engines (Jinja2, Kida, and custom engines). Why Views? OpenAPI endpoints can come from: Individual pages (one file per endpoint) Consolidated mode (all endpoints in one section) DocElements with typed metadata Without Views, your template would need conditionals everywhere: {# Without Views - messy conditionals #} &#123;% if endpoint.typed_metadata %&#125; {{ endpoint.typed_metadata.method }} &#123;% elif endpoint.metadata %&#125; {{ endpoint.metadata.method }} &#123;% else %&#125; {{ endpoint.method }} &#123;% end %&#125; With Views, the filter handles all variations automatically: {# With Views - clean and consistent #} &#123;% for ep in section | endpoints %&#125; {{ ep.method }} {{ ep.path }} &#123;% end %&#125; The filter automatically detects whether endpoints come from consolidated mode (DocElements) or individual pages, ensuring consistent access regardless of configuration. Available Views Filter Returns Use For | endpoints EndpointView[] OpenAPI endpoints in a section | schemas SchemaView[] OpenAPI schemas in a section | tag_views TagView[] Taxonomy tags with counts | tag_view TagView | None Single tag by slug (returns None if not found) EndpointView Normalize OpenAPI endpoints for templates. Automatically handles both consolidated mode (all endpoints in one section) and individual mode (one page per endpoint). Usage &#123;% let eps = section | endpoints %&#125; &#123;% for ep in eps %&#125; &lt;div class=&quot;endpoint {{ &#x27;deprecated&#x27; if ep.deprecated else &#x27;&#x27; }}&quot;&gt; &lt;span class=&quot;method method--{{ ep.method | lower }}&quot;&gt;{{ ep.method }}&lt;/span&gt; &lt;a href=&quot;{{ ep.href }}&quot;&gt;{{ ep.path }}&lt;/a&gt; &lt;p&gt;{{ ep.summary }}&lt;/p&gt; &lt;/div&gt; &#123;% end %&#125; Properties Property Type Description method str HTTP method (GET, POST, PUT, DELETE, etc.) path str URL path with parameters (/users/{id}) summary str Short description description str Full description deprecated bool Whether endpoint is deprecated href str Link to endpoint (anchor #id in consolidated mode, page URL in individual mode). Always valid, never None. has_page bool Whether individual page exists operation_id str | None OpenAPI operationId tags tuple[str, ...] Endpoint tags typed_metadata Any Full OpenAPIEndpointMetadata (advanced) Examples API Navigation Endpoint Cards Grouped by Tag &lt;nav class=&quot;api-nav&quot;&gt; &#123;% for ep in section | endpoints %&#125; &lt;a href=&quot;{{ ep.href }}&quot; class=&quot;api-nav__link&quot;&gt; &lt;span class=&quot;badge badge--{{ ep.method | lower }}&quot;&gt;{{ ep.method }}&lt;/span&gt; {{ ep.path }} &lt;/a&gt; &#123;% end %&#125; &lt;/nav&gt; &lt;div class=&quot;api-cards&quot;&gt; &#123;% for ep in section | endpoints %&#125; &lt;a href=&quot;{{ ep.href }}&quot; class=&quot;api-card&#123;% if ep.deprecated %&#125; api-card--deprecated&#123;% end %&#125;&quot;&gt; &lt;header class=&quot;api-card__header&quot;&gt; &lt;span class=&quot;method method--{{ ep.method | lower }}&quot;&gt;{{ ep.method }}&lt;/span&gt; &lt;code&gt;{{ ep.path }}&lt;/code&gt; &lt;/header&gt; &#123;% if ep.summary %&#125; &lt;p class=&quot;api-card__summary&quot;&gt;{{ ep.summary }}&lt;/p&gt; &#123;% end %&#125; &#123;% if ep.deprecated %&#125; &lt;span class=&quot;badge badge--warning&quot;&gt;Deprecated&lt;/span&gt; &#123;% end %&#125; &lt;/a&gt; &#123;% end %&#125; &lt;/div&gt; {# Group endpoints by their first tag #} &#123;% let eps = section | endpoints %&#125; &#123;% let by_tag = eps | group_by(&#x27;tags.0&#x27;) %&#125; &#123;% for tag, tag_eps in by_tag %&#125; &lt;section&gt; &lt;h2&gt;{{ tag }}&lt;/h2&gt; &#123;% for ep in tag_eps %&#125; &lt;a href=&quot;{{ ep.href }}&quot;&gt;{{ ep.method }} {{ ep.path }}&lt;/a&gt; &#123;% end %&#125; &lt;/section&gt; &#123;% end %&#125; SchemaView Normalize OpenAPI schemas for templates. Provides consistent access to schema properties and metadata. Usage &#123;% let schs = section | schemas %&#125; &#123;% for schema in schs %&#125; &lt;div class=&quot;schema&quot;&gt; &lt;a href=&quot;{{ schema.href }}&quot;&gt;{{ schema.name }}&lt;/a&gt; &lt;span class=&quot;type&quot;&gt;{{ schema.schema_type }}&lt;/span&gt; &lt;/div&gt; &#123;% end %&#125; Properties Property Type Description name str Schema name (User, OrderRequest) schema_type str Type (object, array, string, etc.) description str Schema description href str Link to schema page or anchor (#schema-{name} if no page). Always valid, never None. has_page bool Whether individual page exists properties dict[str, Any] Property definitions required tuple[str, ...] Required property names enum tuple[Any, ...] | None Enum values (if applicable) example Any Example value (if provided) typed_metadata Any Full OpenAPISchemaMetadata (advanced) Examples Schema List Schema with Properties &lt;div class=&quot;schema-list&quot;&gt; &#123;% for schema in section | schemas %&#125; &lt;a href=&quot;{{ schema.href }}&quot; class=&quot;schema-card&quot;&gt; &lt;span class=&quot;schema-card__name&quot;&gt;{{ schema.name }}&lt;/span&gt; &lt;span class=&quot;schema-card__type&quot;&gt;{{ schema.schema_type }}&lt;/span&gt; &#123;% if schema.description %&#125; &lt;p class=&quot;schema-card__desc&quot;&gt;{{ schema.description | truncate(80) }}&lt;/p&gt; &#123;% end %&#125; &lt;/a&gt; &#123;% end %&#125; &lt;/div&gt; &#123;% for schema in section | schemas %&#125; &lt;article class=&quot;schema-doc&quot;&gt; &lt;h3&gt;{{ schema.name }}&lt;/h3&gt; &lt;p&gt;{{ schema.description }}&lt;/p&gt; &#123;% if schema.properties %&#125; &lt;table class=&quot;props-table&quot;&gt; &lt;thead&gt; &lt;tr&gt;&lt;th&gt;Property&lt;/th&gt;&lt;th&gt;Required&lt;/th&gt;&lt;/tr&gt; &lt;/thead&gt; &lt;tbody&gt; &#123;% for prop_name, prop_def in schema.properties %&#125; &lt;tr&gt; &lt;td&gt;&lt;code&gt;{{ prop_name }}&lt;/code&gt;&lt;/td&gt; &lt;td&gt;{{ &#x27;✓&#x27; if prop_name in schema.required else &#x27;&#x27; }}&lt;/td&gt; &lt;/tr&gt; &#123;% end %&#125; &lt;/tbody&gt; &lt;/table&gt; &#123;% end %&#125; &lt;/article&gt; &#123;% end %&#125; TagView Normalize taxonomy tags for templates. Provides consistent access to tag data including counts, percentages, and descriptions. Usage {# All tags #} &#123;% for tag in site | tag_views %&#125; &lt;a href=&quot;{{ tag.href }}&quot;&gt;{{ tag.name }} ({{ tag.count }})&lt;/a&gt; &#123;% end %&#125; {# With options #} &#123;% for tag in site | tag_views(limit=10, sort_by=&#x27;count&#x27;) %&#125; {{ tag.name }} &#123;% end %&#125; Properties Property Type Description name str Display name slug str URL-safe slug href str URL to tag page count int Number of posts with this tag description str Tag description (if defined) percentage float Percentage of total posts (for tag clouds) Filter Options Option Default Description limit None Maximum tags to return sort_by 'count' Sort field: 'count', 'name', or 'percentage' Examples Tag Cloud Top Tags Sidebar Single Tag Lookup Alphabetical List &lt;div class=&quot;tag-cloud&quot;&gt; &#123;% for tag in site | tag_views %&#125; {# Size based on percentage #} &#123;% let size = 0.8 + (tag.percentage / 50) %&#125; &lt;a href=&quot;{{ tag.href }}&quot; class=&quot;tag-cloud__tag&quot; style=&quot;font-size: {{ size }}em&quot;&gt; {{ tag.name }} &lt;/a&gt; &#123;% end %&#125; &lt;/div&gt; &lt;aside class=&quot;sidebar-tags&quot;&gt; &lt;h3&gt;Popular Topics&lt;/h3&gt; &lt;ul&gt; &#123;% for tag in site | tag_views(limit=10, sort_by=&#x27;count&#x27;) %&#125; &lt;li&gt; &lt;a href=&quot;{{ tag.href }}&quot;&gt; {{ tag.name }} &lt;span class=&quot;count&quot;&gt;{{ tag.count }}&lt;/span&gt; &lt;/a&gt; &lt;/li&gt; &#123;% end %&#125; &lt;/ul&gt; &lt;/aside&gt; {# Get a specific tag by slug #} {# Returns None if tag doesn&#x27;t exist, so always check #} &#123;% let python_tag = &#x27;python&#x27; | tag_view %&#125; &#123;% if python_tag %&#125; &lt;div class=&quot;featured-tag&quot;&gt; &lt;a href=&quot;{{ python_tag.href }}&quot;&gt; {{ python_tag.name }} — {{ python_tag.count }} posts &lt;/a&gt; &#123;% if python_tag.description %&#125; &lt;p&gt;{{ python_tag.description }}&lt;/p&gt; &#123;% end %&#125; &lt;/div&gt; &#123;% end %&#125; &lt;nav class=&quot;tag-index&quot;&gt; &#123;% for tag in site | tag_views(sort_by=&#x27;name&#x27;) %&#125; &lt;a href=&quot;{{ tag.href }}&quot;&gt;{{ tag.name }}&lt;/a&gt; &#123;% end %&#125; &lt;/nav&gt; When to Use Views vs Raw Data Use Views When Use Raw Data When Building reusable theme components Custom one-off queries Need consistent property access Need full page/section access Working with OpenAPI autodoc Building non-autodoc features Rendering tag clouds/lists Need raw taxonomy dict Switching between consolidation modes Accessing page metadata directly Key Benefit: Views eliminate the need for conditional logic when working with OpenAPI data that may come from different sources (consolidated vs. individual pages). Accessing Raw Data Views are filters on sections or site. You can still access raw data: {# Raw page access #} &#123;% for page in section.pages %&#125; {{ page.title }} &#123;% end %&#125; {# Raw taxonomy access #} &#123;% for tag_slug, tag_data in site.taxonomies.tags %&#125; {{ tag_data.name }}: {{ tag_data.pages | length }} posts &#123;% end %&#125; Info Seealso Template Functions — All available filters OpenAPI Autodoc — Generating API docs Taxonomy fields — Tags, categories, and custom taxonomies

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 1177
- Reading Time: 6 minutes