Using HTML Templates in JavaScript in Frappe Framework (v15)

Introduction: Why Use HTML Templates in JavaScript?

HTML templates allow developers to separate presentation logic from JavaScript code, making client-side UI development cleaner and more maintainable.
In Frappe Framework v15, HTML templates are first-class citizens and integrate seamlessly with JavaScript using built-in rendering utilities.

What Are HTML Templates in Frappe?

HTML templates in Frappe are Jinja-style template files (.html) that can be rendered:

• On the server (Python)
• On the client (JavaScript)

When used in JavaScript, these templates enable dynamic UI rendering without hardcoding HTML strings.

Why Use HTML Templates in Client-Side Code?

Using HTML templates in JavaScript helps you:

• Avoid inline HTML strings
• Reuse UI components
• Improve readability and maintainability
• Maintain consistency across Desk, dialogs, and pages

This approach is widely used in ERPNext desk customizations.

Technical Prerequisites

Before using HTML templates in JavaScript, ensure:

• Frappe Framework v15 is installed
• Your app has a /templates directory
• You are writing client-side JavaScript (Desk, Page, or Dialog)

Where Are HTML Templates Stored?

In Frappe v15, HTML templates used in JavaScript are typically stored under:

your_app/
└── your_app/
└── templates/
└── includes/
└── your_template.html

Templates placed inside templates/includes are automatically available for client-side rendering.

How Does Frappe Render HTML Templates in JavaScript?

Frappe provides the global JavaScript utility:

frappe.render_template(template_name, context)

This function:

• Loads the HTML template
• Applies the provided context
• Returns rendered HTML as a string

Basic Example: Rendering an HTML Template in JavaScript

Step 1: Create an HTML Template

File: your_app/templates/includes/user_card.html
<div class="user-card">
<h4>{{ user_name }}</h4>
<p>{{ user_email }}</p>
</div>

Step 2: Render Template in JavaScript

const html = frappe.render_template("user_card", {
user_name: "John Doe",
user_email: "john@example.com"
});

The returned html variable contains fully rendered markup.

How to Inject Rendered HTML into the DOM

Once rendered, you can insert the HTML anywhere:

$(html).appendTo(".page-body");

This pattern is commonly used in:

• Custom Pages
• Dialogs
• Dashboards
• Sidebar widgets

Using HTML Templates Inside Frappe Pages

Example: Custom Page Script

frappe.pages['my-page'].on_page_load = function(wrapper) {
const html = frappe.render_template("user_card", {
user_name: "Jane Smith",
user_email: "jane@example.com"
});
$(wrapper).find(".layout-main-section").html(html);
};

Using HTML Templates in Dialogs

HTML templates are ideal for dialog content:

let dialog = new frappe.ui.Dialog({
title: "User Info",
fields: [
{
fieldtype: "HTML",
fieldname: "content"
}
]
});
dialog.fields_dict.content.$wrapper.html(
frappe.render_template("user_card", {
user_name: "Admin",
user_email: "admin@example.com"
})
);
dialog.show();

Context Data: What Can Be Passed?

You can pass:

• Strings
• Numbers
• Arrays
• Objects

Example:

frappe.render_template("list_template", {
items: ["Item A", "Item B"]
});

Templates support standard Jinja control structures like loops and conditions.

Best Practices for HTML Templates in JavaScript

• Keep templates logic-light
• Avoid inline CSS or JS
• Use semantic HTML
• Place templates in templates/includes
• Reuse templates across features

Common Mistakes and How to Avoid Them

Template Not Found Error

Cause:
Template not inside templates/includes.

Fix:
Move the file to the correct directory.

Undefined Variables in Template

Cause:
Context key missing in render_template.

Fix:
Ensure all variables are passed explicitly.

Overusing Templates for Simple UI

Cause:
Templates used where plain JS is enough.

Fix:
Use templates for repeatable or complex UI only.

Advanced Usage: Looping and Conditions

Example: Loop in Template

<ul>
{% for item in items %}
<li>{{ item }}</li>
{% endfor %}
</ul>

Rendered using:

frappe.render_template("item_list", {
items: ["Cement", "Clinker", "Fly Ash"]
});

Integration Patterns

HTML templates in JavaScript are commonly used with:

• Custom Pages
• Dialogs
• Report UI enhancements
• ERPNext Desk customizations

Target Audience

• Frappe Developers
• ERPNext Consultants
• Frontend Customization Experts
• System Integrators

Industry Relevance

This approach is widely used in:

• Manufacturing ERP dashboards
• Accounting UI customizations
• CRM extensions
• Industry-specific ERPNext apps

Cross-References (Recommended Internal Links)

• Custom Pages in Frappe
• Dialogs in Frappe Framework
• Client Scripts Best Practices
• Jinja Templates in Frappe

Summary: Clean UI with HTML Templates

Using HTML templates in JavaScript in Frappe Framework v15 enables clean separation of UI and logic.
It improves maintainability, readability, and scalability—making it a best practice for professional ERPNext and Frappe applications.