Frontend Templates & UI Reuse

Developer guide for the Enezaframework. Part of the Developer documentation.

Table of Contents

1. Overview
2. Generic Templates Shipped by the Framework
3. Reuse the Vristo Template
4. Static CSS and JS
5. HTMX and Alpine.js
6. Icons
7. When to Create a Template
8. Change History
9. Related Guides

Overview

Enezaframework's UI is built on a purchased HTML template (Vristo) plus Tailwind CSS, HTMX, and Alpine.js. The framework ships generic templates for CRUD flows, so frontend work is mostly about reusing existing markup and components rather than writing new UI.

flowchart LR
    BASE[Base layout / template] --> COMP[Reusable components]
    BASE --> CRUD[Generic CRUD templates]
    BASE --> WIDGETS[Dashboard and chart widgets]
    CRUD --> PAGES[App pages]
    PAGES --> HTMX[HTMX partial swaps]
    PAGES --> ALPINE[Alpine.js reactivity]

Generic Templates Shipped by the Framework

Base views resolve their templates automatically, so most apps never reference these paths directly. They are listed here so you know where to look and what to override:

Override a template only by pointing the view's template_name / partial_template_name (or the create/detail template attributes) at your own file — do not edit the framework templates.

Reuse the Vristo Template

The reference design lives in the vristo-html-template folder at the project root. Before building any screen:

• Look for an existing page that already does something similar and reuse its structure and classes.
• Reuse the dashboard and chart widgets that ship with the template instead of introducing new chart widgets.
• Reuse existing HTML components and elements (buttons, cards, tables, modals, dropdowns) rather than recreating them.
• Keep the visual language consistent with the rest of the ERP.

Static CSS and JS

• Always reuse the CSS and JS that come with the template. They live under vristo-html-template/assets.
• Do not pull in a second copy of a library the template already bundles.
• Ensure the Django static files configuration points at the same assets the template uses.

HTMX and Alpine.js

The framework uses HTMX for server-driven partial updates and Alpine.js for client-side state.

• HTMX — inline tabs, list updates, and action responses are loaded by swapping partial templates into a container (for example #detail-container) rather than reloading the page. The list and detail base views return partial templates when the HX-Request header is present.
• Alpine.js — reactive widgets such as image uploads and field toggles update the DOM without a round trip.

POST requests require HTMX. BaseDetailView.post, BaseCreateView.post, and BaseParameter.post return HTTP 400 when the request is not an HTMX request. If you build a custom form submission, send it through HTMX (for example with hx-post).

When adding interactivity, prefer the patterns already used by the framework templates over bespoke JavaScript.

Icons

Icons are SVG files in a static icons/ folder (for example static/icons/). They are rendered with load_icon(name, width=24, height=24), which resolves icons/{name}.svg. Use the same helper in menus and in detail_ui_view tab/action definitions so the icon key matches a real file. See Menu & Navigation Configuration.

When to Create a Template

Create an app-specific template only when the generic framework templates cannot express the requirement:

1. Confirm no generic template or existing component covers it.
2. Place it under templates/<app_name>/.
3. Reuse the base layout and existing components.
4. Load app static assets consistently with the rest of the project.

Most CRUD apps should ship zero custom templates.

The user is solely responsible for testing and validating the rendered UI; the developer/agent does not run the application.

Change History

Dated changes that affect this guide, taken from docs/Release note/CHANGELOG.md and the release notes. For the complete history, see the changelog.

Related Guides

• Migrating Templates to the EZ Surface Style
• Standardized App Structure
• Model Field Conventions
• CRUD Base Views
• Back to the Developer index