Skip to content

HTML Jinja Web Page Structure

Jump to bottom
Saif Ur Rehman edited this page Nov 26, 2023 · 1 revision

Web Page Structure

HTML Web Pages can be created by creating files inside your app's www directory. HTML files are processed by Jinja (template engine). Python files are treated as backend scripts responsible for providing data to the HTML/Jinja files by updating context variables. Context variables can be used to generate dynamic content for the web pages.

For example to create an "About Us" page you can create the files www/about.html and www/about.py which can then be accessed by https://paralogic.io/about.

  • HTML files should extend {% extends "templates/web.html" %}
  • HTML files should have the following blocks: {% block style %}, {% block page_content %}, {% block script %}
  • Python files should contain a def get_context(context) method that will update the context dict variables to be used in the HTML/Jinja files

Create Home Page

  • Create file www/paralogic_home.html
  • Create file www/paralogic_home.py
  • Add home_page = "paralogic_home" in hooks.py (user can also change the home page in Website Settings)

Base Templates

Web pages are generated by extending templates/web.html Jinja template which in turn extends the templates/base.html Jinja template. This way header, footer, navbar are abstracted and you only need to define parts of the web page instead of writing the complete HTML page from scratch.

base.html determines the complete HTML structure including the following

  • <!DOCTYPE html> and <html>
  • <head> block with <title>, <meta>, favicon, initial JavaScript variables, google analytics, etc
  • <body> with Banner, Navbar, Footer, Base Scripts, Included Scripts, ...

web.html extends base.html to provide additional functionality

  • Hero Section
  • Breadcrumbs (if enabled)
  • Main page container
  • Page Header, Contents, Footer
  • Sidebar (if enabled)

Template Blocks

There are many blocks that be used to extend and override blocks of HTML code. You can define blocks to insert your HTML/CSS/JavaScript in different parts of the web page.

  • {% block hero %} for your hero section HTML
  • {% block page_content %} for your all your page HTML
  • {% block header %} for your page header HTML
  • {% block header_actions %} for your page header actions HTML
  • {% block page_footer %} for your page footer HTML
  • {% block style %} to add CSS and include CSS files
  • {% block script %} to add JS and include JS files
  • {% block navbar %} to override the default navbar
  • {% block page_sidebar %} to override the default sidebar
  • {% block head_include %} to add additional HTML in <head> block (for example to add additional meta tags)
  • {% block banner %} to add the top most banner even before Navbar (for news or disclaimers, etc)
  • {% block footer %} to override the default footer

Context Variables

Variables can be set or updated either from the page's Python script or by defining it in the jinja HTML files like {% set title = 'About Us' %}. Variables can be used to modify parts of the HTML code. Here are some common variables we can set to change our page.

  • title (HTML page title)
  • full_width (True by default, set as False so that container class is not defined on page container)
  • navbar_class (navbar-light by default)
  • no-breadcrumbs to disable breadcrumbs
  • show-sidebar to enable sidebar
  • no-cache to disable caching the page HTML (only enable if the page is highly dynamic)

Jinja / Frappe Filters

Jinja filters can be used to transform or format data. Here are some common useful Jinja filters.

  • striptags to strip HTML tags
  • escape to escape HTML tags
  • abs_url converts URL to absolute URL with preceding /
  • global_date_format
  • include_script to include bundled JavaScript file
  • include_style to include bundled CSS file
  • bundled_asset to get URL to bundled JS or CSS file
  • urlencode to encode URL for dynamic data
  • upper to convert string to upper case
  • title to convert string to Title Case
  • truncate to truncate a string to maximum character length
  • trim to strip leading and trailing whitespace

Overriding Base Templates

Frappe provides base templates for different components of a web page, for example, navbar, footer, sidebar, base.html, web.html. To override templates provided by frappe or any other app you can create HTML files in your app with the same directory structure and filename as in frappe.

For example the navbar HTML is defined in frappe/templates/includes/navbar/navbar.html. You can create the file paralogic_web/templates/includes/navbar/navbar.html to override it. You can start by copying the content from the original template file and making changes to your app's template.

If the template is not being overriden then make sure that your app's "Hooks Resolution Order" is higher priority than frappe and other apps by going to the "Installed Applications" page in desk view and clicking on "Update Hooks Resolution Order".

Clone this wiki locally