TRMNL Plugin Templates

The TRMNL Salah Prayer Times Plugin leverages a set of custom HTML/Liquid templates to render prayer times and related information on TRMNL e-ink devices. These templates are specifically designed to adhere to TRMNL's design system guidelines↗, ensuring optimal display and user experience across various screen sizes.

The plugin-markup-handler dynamically selects and renders the appropriate template based on the view size requested by the TRMNL device, fetching user-specific settings and prayer data to populate the content.

Template Overview

The plugin includes four primary templates, each tailored for a specific display size on TRMNL devices:

Full View Template (src/templates/full/index.ts)

This template utilizes the entire screen real estate to display a comprehensive overview of daily prayer times. It presents the Gregorian and Hijri dates, the next upcoming prayer with its time, and a detailed list of all six prayer times (Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha) in a table format. Metadata like the calculation method and last sync time are also included.

Half Horizontal View Template (src/templates/half-horizontal/index.ts)

Designed for a wider, shorter display area, this template arranges prayer times into two columns to efficiently use space. It maintains the display of Gregorian and Hijri dates, the next prayer, and the six prayer times. The two-column layout ensures readability for a broader view.

Half Vertical View Template (src/templates/half-vertical/index.ts)

Optimized for a taller, narrower display, this template prioritizes a single-column table layout for prayer times. It displays the Gregorian and Hijri dates, the next prayer, and a list of all prayer times, ensuring legibility in a vertical orientation.

Quadrant View Template (src/templates/quadrant/index.ts)

This template is built for the smallest display area, typically a quarter of the screen. It provides a condensed view, focusing on essential information: Gregorian and Hijri dates, the next prayer with its time, and a two-column layout for the six prayer times to maximize space.

LiquidJS Rendering and Data

The templates are rendered using LiquidJS, a JavaScript implementation of Shopify's Liquid templating language. The src/controllers/plugin-markup/processTemplate.ts file orchestrates this rendering process.

The processTemplate function takes a Liquid template string and a context object as input. This context object is constructed from two key interfaces:

• TemplateData: This interface encapsulates the data extracted from the Aladhan API response, including formatted prayer times (formattedTimings), raw timings (timings), Hijri date details, and meta-information such as the calculation method. It also includes enhancedData derived from calculations, such as the next prayer's name and time, time until the next prayer, formatted Hijri and Gregorian dates, current time, last sync time, and the currently active prayer.

• PrayerTimesResult: This interface holds the raw prayer times data and metadata, primarily used to populate the TemplateData before rendering.

LiquidJS uses this data to dynamically populate placeholders and control the display logic within the HTML templates. Custom filters, such as slice, are registered to enhance data manipulation capabilities directly within the templates.

TRMNL Design System Adherence

All templates are meticulously crafted to adhere to TRMNL's design system, ensuring consistency and readability on e-ink displays. Key aspects of this adherence include:

• Semantic Structure: Use of .environment, .screen, and .view classes to define the overall display context.
• Layout Components: Extensive use of layout (e.g., layout--col, layout--stretch-x) and flex (e.g., flex, flex--col, gap--space-between) classes for responsive and organized content arrangement. The grid class (e.g., grid--cols-2) is used for multi-column layouts where applicable.
• Typography Hierarchy: Clear differentiation of information using title (e.g., title--small), label (e.g., label--large), value (e.g., value--xsmall), and description classes for headings, prayer names, times, and supplementary text.
• Visual Elements: Use of utility classes like p--1 for padding, w--full for width, and text--right for text alignment.
• E-ink Optimization: High-contrast elements and minimal graphics are chosen. Background colors like bg--gray-6 and bg--gray-7 are used for highlighting the next or current prayer, providing visual cues optimized for monochrome displays.

Illustrative Snippet

This snippet, demonstrating how prayer times are looped through and conditionally highlighted, is common across multiple templates:

This loop iterates through each prayer name. The {% if prayer == IDX_0.enhancedData.currentPrayer %} condition dynamically applies the bg--gray-7 class to the current prayer row, visually highlighting it on the e-ink screen. The label class ensures proper text styling, and text--right aligns the prayer times for better readability.

For more details on the architecture, refer to the [Technical Architecture] documentation, and for specific API endpoints, see the [API Reference: Handlers] page.