TRMNL Tips and Tricks

https://github.com/yunruse/trmnl-tricks
Admin
A comprehensive guide and collection of tips, tricks, and best practices for creating plugins for...
Tokens:12,139
Snippets:76
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Transforming Data with Liquid Filters

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

This Liquid code example showcases the use of filters to transform data. It chains multiple filters (`default`, `prepend`, `append`) to modify a variable (`data.first_name`) for display purposes, adding a greeting. It also includes an example of displaying the original data.

```liquid
{% assign foo = data.first_name | default: "No name found" | prepend: "Hi, " | append "!" %}
<h1>Hi, {{data.first_name}}</h1>
```

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

### Liquid Operators and Control Flow

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

This Liquid example illustrates the use of operators and control flow statements within Liquid templates. It includes a `for` loop, conditional statements (`if`, `elsif`, `else`), and filters like `modulo` and `at_most`, along with the `cycle` operator for iterating through a list of strings. It also shows an alternative syntax using a `liquid` block.

```liquid
{% for i in (1..10) %}
  {% assign i2 = i | modulo: 2 %}
  {% if i < 3 %}
    {% continue %}
  {% elsif i == 5 %}
    (high five!)
  {% elsif i2 == 1 %}
    {{i | at_most: 7}} and
  {% else %}
    {% cycle 'boots and ', 'cats and ' %}
  {% endif %}
{% endfor %}
```

```liquid
{% assign numbers = (1..10) %}
{% liquid
   for i in numbers
     assign i2 = i | modulo: 2
     if i < 3
       continue
     elsif i == 5
       echo "(high five!) "
     elsif i2 == 1
       echo i | at_most: 7
       echo " and "
     else
       cycle 'boots and ', 'cats and '
     endif
   endfor
%}
```

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

### Liquid Filter and Operator Usage Examples (Liquid)

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

Illustrates the application of Liquid filters for data transformation (e.g., default values, string concatenation) and the use of operators within Liquid control flow statements for conditional logic and iteration.

```liquid
{% assign foo = data.first_name | default: "No name found" | prepend: "Hi, " | append "!" %}
<h1>Hi, {{data.first_name}}</h1>
```

```liquid
{% for i in (1..10) %}
  {% assign i2 = i | modulo: 2 %}
  {% if i < 3 %}
    {% continue %}
  {% elsif i == 5 %}
    (high five!) 
  {% elsif i2 == 1 %}
    {{i | at_most: 7}} and
  {% else %}
    {% cycle 'boots and ', 'cats and ' %}
  {% endif %}
{% endfor %}
```

```liquid
{% assign numbers = (1..10) %}
{% liquid
   for i in numbers
     assign i2 = i | modulo: 2
     if i < 3
       continue
     elsif i == 5
       echo "(high five!) "
     elsif i2 == 1
       echo i | at_most: 7
       echo " and "
     else
       cycle 'boots and ', 'cats and '
     endif
   endfor
%}
```

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

### Python: Forking TRMNL Official Plugins

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

This Python script demonstrates how to access data from official TRMNL plugins using their private API. It fetches plugin settings data via a GET request and then sends processed or augmented data to a custom plugin endpoint using a POST request. Requires the `requests` library and user authentication token.

```python
import requests
from datetime import datetime

# Fetch data from an official TRMNL plugin
PLUGIN_ID = "12345"  # Your plugin instance ID from TRMNL dashboard
USER_AUTH_TOKEN = "your_token_from_account_page"

url = f"https://usetrmnl.com/api/plugin_settings/{PLUGIN_ID}/data"
headers = {"Authorization": f"Bearer {USER_AUTH_TOKEN}"}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    official_data = response.json()

    # Manipulate or augment the data
    custom_data = {
        "original": official_data,
        "custom_field": "additional information",
        "processed_at": datetime.now().isoformat()
    }

    # Send to your custom plugin
    custom_plugin_url = "https://usetrmnl.com/api/custom_plugins/your-uuid"
    requests.post(custom_plugin_url, json={'merge_variables': custom_data})
else:
    print(f"Error fetching plugin data: {response.status_code}")
```

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

### Compress and Decompress String Data with zlib and Base64 (Python/JavaScript)

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

Demonstrates how to compress string data using Python's zlib and base64 encoding, and decompress it in JavaScript using the pako library. This is useful for reducing webhook payload sizes.

```python
def compress(string: str):
    import zlib, base64
    return base64.b64encode(
        zlib.compress(string.encode())).decode()
```

```javascript
const decompress = blob => window.pako.inflate(
    Uint8Array.from(atob(blob), c => c.charCodeAt(0)),
    { to: 'string' });

  // document.querySelector('#myElement').innerText
  //   = decompress({{lyrics}})
```

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

### Generate QR Codes with HTML and JavaScript

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

This snippet demonstrates how to implement QR code generation on a webpage. It includes script tags for the QRCode.js library and a custom QR.js script, along with basic styling for the QR code images. It supports various data types like URLs, emails, phone numbers, SMS, Wi-Fi credentials, and Apple Shortcuts via custom attributes on the `<qr>` element.

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/qrcodejs/1.0.0/qrcode.min.js" integrity="sha512-CNgIRecGo7nphbeZ04Sc13ka07paqdeTu0WR1IM4kNcpmBAUSHSQX0FslNhTDadL4O5SAGapGt4FodqL8My0mA==" crossorigin="anonymous" referrerpolicy="no-referrer" defer></script>
<script src="https://cdn.jsdelivr.net/gh/yunruse/trmnl-tricks/QR.js" defer></script>
<style>
  qr img {
    border: 10px solid white;
    display: inline;
  }
  qr img {
    display: inline !important;
  }
</style>
```

```html
<qr>HTTPS://TINYURL.COM/TRMNL-QR-EXAMPLE</qr>
<qr qr-apple-shortcut="Toggle Orthanc Doors"></qr>
<qr qr-telephone="+1310-807-3956"></qr>
<qr qr-sms-number="+1310-807-3956"
  qr-sms-message="can you open up the door"
  ></qr>
<qr qr-wifi-ssid="Moria"
  qr-wifi-password="mellon"
  ></qr>
<qr qr-email-address="gwaihir@eagles.manwe.vlr"></qr>
```

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

### Compress String Data using Python and Decompress in JavaScript

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

This snippet demonstrates how to compress a string using Python's zlib and base64 encoding, and then decompress the resulting blob in JavaScript using the pako library. It's useful for reducing data size for transfer or storage, especially for JSON or English text. Ensure pako.min.js is loaded for decompression.

```python
def compress(string: str):
    import zlib, base64
    return base64.b64encode(
        zlib.compress(string.encode())).decode()
```

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/pako/2.1.0/pako.min.js"></script>
<script>
  const decompress = blob => window.pako.inflate(
      Uint8Array.from(atob(blob), c => c.charCodeAt(0)),
      { to: 'string' });
  document.querySelector('#myElement').innerText = decompress({{myText | json}})
</script>
```

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

### Generate QR Codes with Text or Attributes

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

Demonstrates how to create QR codes using the `<qr>` element. Content can be provided directly as text within the element, or by using specific attributes for structured data like phone numbers, SMS messages, Wi-Fi credentials, and email addresses. All-caps text can reduce QR code size.

```html
<qr>HTTPS://TINYURL.COM/TRMNL-QR-EXAMPLE</qr>
<qr qr-apple-shortcut="Toggle Orthanc Doors"></qr>
<qr qr-telephone="+1310-807-3956"></qr>
<qr qr-sms-number="+1310-807-3956"
  qr-sms-message="can you open up the door"
  ></qr>
<qr qr-wifi-ssid="Moria"
  qr-wifi-password="mellon"
  ></qr>
<qr qr-email-address="gwaihir@eagles.manwe.vlr"></qr>
```

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

### Include QR Code Scripts and Styles

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

This snippet includes the necessary JavaScript libraries (qrcodejs and TRMNL Tricks QR.js) and basic CSS for displaying QR codes. Ensure these are placed at the bottom of your HTML body for proper execution. The QR code element itself is represented by `<qr>`.

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/qrcodejs/1.0.0/qrcode.min.js" integrity="sha512-CNgIRecGo7nphbeZ04Sc13ka07paqdeTu0WR1IM4kNcpmBAUSHSQX0FslNhTDadL4O5SAGapGt4FodqL8My0mA==" crossorigin="anonymous" referrerpolicy="no-referrer" defer></script>
<script src="https://cdn.jsdelivr.net/gh/yunruse/trmnl-tricks/QR.js" defer></script>
<style>
  qr img {
    border: 10px solid white;
    display: inline;
  }
  qr img {
    display: inline !important;
  }
</style>
```

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

### Fetching Official Plugin Data (Python)

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

This Python code illustrates how to fetch data from an official TRMNL plugin. It outlines the necessary URL format for the polling request and the authorization header required, using placeholder variables for plugin ID and user authentication token.

```python
# In Polling URL
https://usetrmnl.com/api/plugin_settings/{{plugin_id}}/data
# In the Polling Headers:
authorization=bearer {{user_auth_token}}

```

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

### Customizing Forms with HTML

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

Allows the use of a limited subset of HTML tags within form descriptions and help text for enhanced formatting and user guidance.

```APIDOC
## Customizing Forms with HTML

### Description
You can use a limited subset of HTML tags within the `description` and `help_text` fields of form elements to add formatting, links, and emphasis. This is useful for decorating mandatory fields, adding implementation details, or linking to reference documents.

### Allowed HTML Elements
- `<br>`: Line break.
- `<strong>` or `<b>`: Bold text.
- `<a>`: Anchor tag for links. Supports `href` and `target="_blank"` attributes.

### Usage Example
```yaml
- keyname: desc1
  field_type: description
  name: Welcome to the Orthanc Door Controls
  description: >
    <b class="text-red-600">Warning: not suitable for non-wizards!</b>
    <br/>
    Please see <a class="underline" href="https://en.wikipedia.org/wiki/Isengard">Isengard Documentation</a> for more.
    <br/>
    If <b class="text-blue-800">Saruman</b> keeps undoing your decisions, go to <a class="bg-emerald-100">Settings -> Saruman -> Draw As If Poison From A Wound</a>.

- keyname: my_bool
  field_type: select
  name: Let Balrog in?
  options:
  - "You shall pass": true
  - "YOU SHALL NOT PASS": false
  help_text: Make sure you are a servant of the <b class="text-red-400">Secret Fire</b>, wielder of the <b class="text-red-400">flame of Anor</b> first.
```
```

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

### TRMNL Widget Sizing with Liquid Templating

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

Defines widget sizes using Liquid templating for responsive layouts in TRMNL plugins. Allows dynamic setting of width and height attributes based on predefined widget configurations (full, half-horizontal, half-vertical, quadrant).

```html
<style>
/* Widget size definitions for responsive layouts */
/* Full widget */
{% assign width=780 %}
{% assign height=460 %}

/* Half-horizontal widget */
{% assign width=780 %}
{% assign height=225 %}

/* Half-vertical widget */
{% assign width=400 %}
{% assign height=460 %}

/* Quadrant widget */
{% assign width=400 %}
{% assign height=235 %}
</style>

<div style="width: {{width}}px; height: {{height}}px;">
  <!-- Plugin content here -->
</div>
```

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

### Fetching Plugin Content API

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

Retrieves data from official TRMNL plugins. Requires a user authentication token.

```APIDOC
## Fetching Plugin Content API

### Description
This endpoint allows you to fetch data from official TRMNL plugins. You need to provide the plugin ID and a user authentication token.

### Method
GET

### Endpoint
`https://usetrmnl.com/api/plugin_settings/{plugin_id}/data`

### Parameters
#### Path Parameters
- **plugin_id** (string) - Required - The unique identifier of the plugin instance.

#### Headers
- **Authorization** (string) - Required - Bearer token for user authentication. Format: `bearer {{user_auth_token}}`.

### Request Example
```python
# In Polling URL
https://usetrmnl.com/api/plugin_settings/{{plugin_id}}/data

# In the Polling Headers:
authorization=bearer {{user_auth_token}}
```

### Notes
- `{{plugin_id}}` is the defined ID of your plugin instance.
- `{{user_auth_token}}` can be fetched from the [account tab](https://usetrmnl.com/account).
```

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

### Setting Widget Dimensions in Liquid (Liquid)

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

Provides Liquid assignments for common widget dimension presets (full, half-horizontal, half-vertical, quadrant). These can be used to control the layout and size of plugin elements.

```liquid
<!-- Full -->
{% assign width=780 %}
{% assign height=460 %}
<!-- Half-horizontal -->
{% assign width=780 %}
{% assign height=225 %}
<!-- Half-vertical -->
{% assign width=400 %}
{% assign height=460 %}
<!-- Quadrant -->
{% assign width=400 %}
{% assign height=235 %}
```

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

### Customizing Plugin Forms with HTML (YAML)

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

This snippet demonstrates how to use custom HTML elements within plugin form descriptions and help text. It allows for rich text formatting, links, and conditional display of information using standard HTML tags within YAML configuration.

```yaml
- keyname: desc1
  field_type: description
  name: Welcome to the Orthanc Door Controls
  description: >
    <b class="text-red-400">Warning: not suitable for non-wizards!</b>
    <br/>
    Please see <a class="underline" href="https://en.wikipedia.org/wiki/Isengard">Isengard Documentation</a> for more.
    <br/>
    If <b class="text-blue-400">Saruman</b> keeps undoing your decisions, go to <a class="bg-blue-100">Settings -&gt; Saruman -&gt; Draw As If Poison From A Wound</a>.

- keyname: my_bool
  field_type: select
  name: Let Balrog in?
  options:
  - "You shall pass": true
  - "YOU SHALL NOT PASS": false
  help_text: Make sure you are a servant of the Secret Fire, wielder of the flame of Anor first.

```

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

### POST /api/custom_plugins/{your_plugin_uuid}

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

Sends data to a custom plugin via a POST request. Supports JSON payloads and specific merge strategies for updating variables.

```APIDOC
## POST /api/custom_plugins/{your_plugin_uuid}

### Description
Sends data to a custom plugin endpoint. The `merge_variables` field in the request body contains the data to be sent. The `merge_strategy` can be used to control how the data is merged with existing variables.

### Method
POST

### Endpoint
`/api/custom_plugins/{your_plugin_uuid}`

### Parameters
#### Path Parameters
- **your_plugin_uuid** (string) - Required - The unique identifier for your custom plugin.

#### Request Body
- **merge_variables** (object) - Required - The data payload to send. This is a JSON object that will be merged with the existing variables.
- **merge_strategy** (string) - Optional - The strategy to use for merging data. Can be `deep_merge` for objects or `stream` for arrays. Defaults to replacing existing variables.
- **stream_limit** (integer) - Optional - Used with `stream` merge strategy to limit the number of items appended to an array.

### Request Example
```python
import requests

URL = f"https://usetrmnl.com/api/custom_plugins/{your_plugin_uuid}"
data = {
  "my_data": {"a": 1, "b": [1, 2, 3]},
  "foo": "long string",
}

# Example with deep_merge
response_deep_merge = requests.post(URL, json={'merge_variables': {"a": {"b": {"second": 2}}}, "merge_strategy": "deep_merge"})

# Example with stream
response_stream = requests.post(URL, json={'merge_variables': {"a": [3, 4, 5, 6, 7]}, "merge_strategy": "stream"})

# Example with stream and limit
response_stream_limit = requests.post(URL, json={'merge_variables': {"a": [8, 9]}, "merge_strategy": "stream", "stream_limit": 4})
```

### Response
#### Success Response (200)
- **message** (string | null) - A confirmation message or null if the operation was successful.

#### Error Response
- **429 Too Many Requests** - Returned if data is sent more frequently than every five minutes.

#### Response Example
```json
{
  "message": null
}
```
```

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

### Fetching Plugin Data with TRMNL API

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

This snippet shows how to fetch data from official TRMNL plugins using their API. It specifies the polling URL and required headers, including authorization, for accessing plugin settings and data.

```python
# In Polling URL
https://usetrmnl.com/api/plugin_settings/{{plugin_id}}/data
# In the Polling Headers:
authorization=bearer {{user_auth_token}}
```

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

### QR Code Generation with Custom Attributes

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

The QR.js library allows for declarative HTML-based QR code generation within TRMNL plugins. It automatically detects content types and renders optimized QR codes for e-ink displays.

```APIDOC
## QR Code Generation with Custom Attributes

### Description
This section details how to use the QR.js library to generate QR codes in TRMNL plugins using HTML attributes. The library supports various content types including URLs, WiFi credentials, SMS, email, telephone numbers, and Apple Shortcuts.

### Method
Client-side rendering via JavaScript and HTML.

### Endpoint
N/A (Client-side library)

### Parameters
#### HTML Attributes
- **`qr`** (Element) - The main element for QR code generation.
- **`qr-wifi-ssid`** (string) - Optional - The SSID for WiFi QR codes.
- **`qr-wifi-password`** (string) - Optional - The password for WiFi QR codes.
- **`qr-wifi-encryption`** (string) - Optional - The encryption type for WiFi QR codes (e.g., WPA, WEP, WPA2).
- **`qr-sms-number`** (string) - Optional - The phone number for SMS QR codes.
- **`qr-sms-message`** (string) - Optional - The message content for SMS QR codes.
- **`qr-email-address`** (string) - Optional - The email address for email QR codes.
- **`qr-telephone`** (string) - Optional - The phone number for telephone QR codes.
- **`qr-apple-shortcut`** (string) - Optional - The name of the Apple Shortcut for Apple Shortcut QR codes.
- **`qr-correction`** (string) - Optional - The error correction level (L, M, Q, H). Defaults to M.

### Request Example
```html
<!-- Plain URL QR code -->
<qr>HTTPS://TINYURL.COM/TRMNL-QR-EXAMPLE</qr>

<!-- WiFi credentials QR code -->
<qr qr-wifi-ssid="MyNetwork"
    qr-wifi-password="secretpassword123"
    qr-wifi-encryption="WPA"></qr>

<!-- SMS message QR code -->
<qr qr-sms-number="+13108073956"
    qr-sms-message="Hello from TRMNL!"></qr>

<!-- Email QR code -->
<qr qr-email-address="user@example.com"></qr>

<!-- Telephone QR code -->
<qr qr-telephone="+13108073956"></qr>

<!-- Apple Shortcut QR code -->
<qr qr-apple-shortcut="Toggle Smart Lights"></qr>

<!-- Custom QR code with error correction -->
<qr qr-correction="H">IMPORTANT-DATA-HERE</qr>
```

### Response
N/A (Renders directly in the HTML page)
```

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

### TRMNL Framework CSS for E-ink Displays

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

Provides CSS utility classes for styling TRMNL e-ink displays. Includes styles for vertical text orientation and word-based text clamping to improve readability on e-ink screens. These classes can be applied directly in HTML or within style tags.

```css
/* Vertical text for rotated index labels */
.index {
  writing-mode: vertical-rl;
  text-orientation: mixed;
}

/* Word-based clamping instead of character-based */
.clamp--nicely {
  word-break: normal !important;
}
```

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

### Generate QR Codes with QR.js for TRMNL Plugins

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

This snippet demonstrates how to use the QR.js library to generate various types of QR codes (URL, WiFi, SMS, Email, Phone, Apple Shortcut) within TRMNL plugins. It shows basic HTML inclusion and attribute-based configuration for different QR code content types and error correction.

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/qrcodejs/1.0.0/qrcode.min.js"
        integrity="sha512-CNgIRecGo7nphbeZ04Sc13ka07paqdeTu0WR1IM4kNcpmBAUSHSQX0FslNhTDadL4O5SAGapGt4FodqL8My0mA=="
        crossorigin="anonymous" referrerpolicy="no-referrer" defer></script>
<script src="https://cdn.jsdelivr.net/gh/yunruse/trmnl-tricks/QR.js" defer></script>
<style>
  qr img {
    border: 10px solid white;
    display: inline !important;
  }
</style>

<!-- Plain URL QR code (use all-caps for smaller QR codes) -->
<qr>HTTPS://TINYURL.COM/TRMNL-QR-EXAMPLE</qr>

<!-- WiFi credentials QR code -->
<qr qr-wifi-ssid="MyNetwork"
    qr-wifi-password="secretpassword123"
    qr-wifi-encryption="WPA"></qr>

<!-- SMS message QR code -->
<qr qr-sms-number="+13108073956"
    qr-sms-message="Hello from TRMNL!"></qr>

<!-- Email QR code -->
<qr qr-email-address="user@example.com"></qr>

<!-- Telephone QR code -->
<qr qr-telephone="+13108073956"></qr>

<!-- Apple Shortcut QR code -->
<qr qr-apple-shortcut="Toggle Smart Lights"></qr>

<!-- Custom QR code with error correction -->
<qr qr-correction="H">IMPORTANT-DATA-HERE</qr>
```

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

### Adding Custom HTML to Forms with TRML

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

This snippet demonstrates how to inject custom HTML, including <br>, <strong>, <b>, and <a> tags, into form fields like 'description' and 'help_text' within the TRML framework. It allows for enhanced formatting and linking directly within form elements.

```yaml
- keyname: desc1
  field_type: description
  name: Welcome to the Orthanc Door Controls
  description: >
    <b class="text-red-600">Warning: not suitable for non-wizards!</b>
    <br/>
    Please see <a class="underline" href="https://en.wikipedia.org/wiki/Isengard">Isengard Documentation</a> for more.
    <br/>
    If <b class="text-blue-800">Saruman</b> keeps undoing your decisions, go to <a class="bg-emerald-100">Settings -> Saruman -> Draw As If Poison From A Wound</a>.

- keyname: my_bool
  field_type: select
  name: Let Balrog in?
  options:
  - "You shall pass": true
  - "YOU SHALL NOT PASS": false
  help_text: Make sure you are a servant of the <b class="text-red-400">Secret Fire</b>, wielder of the <b class="text-red-400">flame of Anor</b> first.
```

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

### Liquid Templating: Dynamic Content and Logic

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

TRMNL uses Shopify's Liquid templating engine to process variables from webhooks, form inputs, and system data. It supports accessing data, iterating over arrays, formatting dates with timezone awareness, and implementing conditional logic. The `json` and `escape` filters are used to safely pass Liquid variables to JavaScript.

```liquid
<!-- Accessing webhook data -->
{% assign temp = data.temperature | default: "N/A" %}
<div class="weather">Temperature: {{temp}}°F</div>

<!-- Iterating over arrays -->
{% for day in data.forecast %}
  <div class="forecast-item">
    {{day.day}}: {{day.high}}°/{{day.low}}°
  </div>
{% endfor %}

<!-- Timezone-aware date formatting -->
{% assign current_time = trmnl.system.timestamp_utc | plus: trmnl.user.utc_offset | date: "%I:%M %p" %}
<div>Current time: {{current_time}}</div>

<!-- Conditional logic and filters -->
{% assign name = data.user_name | default: "Guest" | capitalize %}
{% if name == "Guest" %}
  <h1>Welcome, Guest!</h1>
{% else %}
  <h1>Hello, {{name}}!</h1>
{% endif %}

<!-- Complex iteration with modulo and cycle -->
{% for i in (1..10) %}
  {% assign i2 = i | modulo: 2 %}
  {% if i < 3 %}
    {% continue %}
  {% elsif i2 == 1 %}
    <span class="odd">{{i}}</span>
  {% else %}
    <span class="even">{{i}}</span>
  {% endif %}
{% endfor %}

<!-- Passing Liquid variables to JavaScript -->
<script>
  const weatherData = JSON.parse(`{{data.forecast | json}}`);
  const userName = "{{data.user_name | escape}}";
  const NOW = new Date(new Date().valueOf() + {{trmnl.user.utc_offset}} * 1000);

  console.log(`Weather for ${userName}:`, weatherData);
  console.log(`Current time in user timezone: ${NOW}`);
</script>
```

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

### TRMNL Webhook Data Merging Strategies

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

This snippet illustrates how to use 'deep_merge' and 'stream' strategies for merging data into TRMNL webhooks. 'deep_merge' recursively merges dictionaries by key, while 'stream' appends to top-level arrays, with an optional 'stream_limit'.

```python
# Using deep_merge to extend objects
# state: {"a": {"b": {"first": 1}}}
requests.post(URL, json={'merge_variables': {"a": {"b": {"second": 2}}}, "merge_strategy": "deep_merge"})
# state: {"a": {"b": {"first": 1, "second": 2}}}
requests.post(URL, json={'merge_variables': {"xyz": "true"}, "merge_strategy": "deep_merge"})
# state: {"a": {"b": {"first": 1, "second": 2}}, "xyz": "true"}

# Using streaming to extend arrays
# state: {"a": [1, 2]}
requests.post(URL, json={'merge_variables': {"a": [3, 4, 5, 6, 7]}, "merge_strategy": "stream"})
# state: {"a": [1, 2, 3, 4, 5, 6, 7]}
requests.post(URL,json={'merge_variables': {"a": [8, 9]}, "merge_strategy": "stream", "stream_limit": 4})
# state: {"a": [6, 7, 8, 9]}
```

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

### YAML: Custom Plugin Form Configuration

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

This YAML configuration defines custom fields for TRMNL plugins, allowing users to input values through a structured form. It supports various field types like text, select, checkbox, and description, with options for validation and help text. These form variables can be directly embedded into plugin settings URLs and headers using double-brace syntax (e.g., `{{api_key}}`).

```yaml
# Plugin custom form definition
custom_fields:
  - keyname: api_key
    field_type: text
    name: API Key
    description: Enter your API key from the provider dashboard
    required: true

  - keyname: refresh_rate
    field_type: select
    name: Refresh Rate
    options:
      - "5 minutes": 5
      - "15 minutes": 15
      - "1 hour": 60
    help_text: How often to fetch new data

  - keyname: show_icons
    field_type: checkbox
    name: Show weather icons
    description: Display icons next to weather data

  - keyname: desc1
    field_type: description
    name: Setup Instructions
    description: >
      <b class="text-red-600">Important:</b> Get your API key from
      <a href="https://example.com/api" target="_blank" class="underline">example.com/api</a>.
      <br/>
      See <a href="https://docs.example.com" class="text-blue-600">documentation</a> for details.

# Using form variables in plugin settings
p-o-l-l-i-n-g_url: https://api.example.com/data?key={{api_key}}&interval={{refresh_rate}}

p-o-l-l-i-n-g_headers:
  Authorization: Bearer {{api_key}}
  User-Agent: TRMNL-Plugin/1.0
```

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

### Send Data to TRMNL API via Webhook (Python)

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

This Python snippet shows how to send data to TRMNL custom plugins using POST requests. It covers basic JSON payloads, different merge strategies (standard, deep_merge, stream), handling rate limits, and data compression for large payloads using zlib and base64.

```python
import requests
import json
import zlib
import base64

# Basic webhook POST to TRMNL custom plugin
URL = "https://usetrmnl.com/api/custom_plugins/abc123-your-plugin-uuid-here"

data = {
    "temperature": 72,
    "weather": "Sunny",
    "forecast": [
        {"day": "Mon", "high": 75, "low": 62},
        {"day": "Tue", "high": 73, "low": 60}
    ]
}

# Standard merge (replaces all variables)
response = requests.post(URL, json={'merge_variables': data})

if response.status_code == 200:
    result = response.json()
    if result.get('message') is None:
        print("Data sent successfully")
    else:
        print(f"Error: {result['message']}")
elif response.status_code == 429:
    print("Rate limited: wait 5 minutes between requests")

# Deep merge strategy (merges nested objects)
nested_data = {"user": {"settings": {"theme": "dark"}}}
requests.post(URL, json={
    'merge_variables': nested_data,
    'merge_strategy': 'deep_merge'
})

# Stream strategy (appends to arrays with optional limit)
stream_data = {"events": [{"time": "10:00", "title": "Meeting"}]}
requests.post(URL, json={
    'merge_variables': stream_data,
    'merge_strategy': 'stream',
    'stream_limit': 10  # Keep only last 10 items
})

# Data compression for large payloads

def compress(string: str):
    return base64.b64encode(zlib.compress(string.encode())).decode()

large_text = "Very long text content that needs compression..."
compressed_data = {"content": compress(large_text)}
requests.post(URL, json={'merge_variables': compressed_data})
```

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

### Sending Data to Webhook (Python)

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

This Python snippet shows how to send JSON data to a TRMNL webhook using the `requests` library. It includes the target URL format and demonstrates constructing a POST request with a JSON payload containing merge variables. It also mentions potential response codes and their meanings.

```python
import requests
URL = "https://usetrmnl.com/api/custom_plugins/{your_plugin_uuid}"
data = {
  "my_data": {"a": 1, "b": 2},
  "foo": "long string",
}

requests.post(URL, json={'merge_variables': data})

```

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

### Adjusting Timezone in Liquid and JavaScript

Source: https://github.com/yunruse/trmnl-tricks/blob/main/README.md

These snippets show how to adjust for timezone differences in Liquid and JavaScript. Liquid provides UTC time and user's UTC offset, allowing for custom time formatting. JavaScript also assumes UTC and requires manual offset adjustment for accurate local time representation. Both methods aim to display user-specific local time.

```liquid
{% assign time = trmnl.system.timestamp_utc | plus: trmnl.user.utc_offset | date: "%F %T%z" %}
```

```javascript
const NOW = new Date(new Date().valueOf() + {{trmnl.user.utc_offset}} * 1000);
```

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

### Decompress zlib Data in JavaScript with pako

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

Decompresses zlib-compressed data received via webhooks using the pako library. This is useful for sending more data within webhook size limits. It handles both plain text and JSON data. The function relies on the pako library and browser's built-in `atob` function.

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/pako/2.1.0/pako.min.js"></script>
<script>
  // Decompression helper function
  const decompress = blob => window.pako.inflate(
    Uint8Array.from(atob(blob), c => c.charCodeAt(0)),
    { to: 'string' }
  );

  // Decompress text data from Liquid variable
  const compressedText = "{{data.compressed_content | json}}";
  const decompressedText = decompress(compressedText);
  document.getElementById('content').innerText = decompressedText;

  // Decompress and parse JSON data
  const compressedJson = "{{data.compressed_json}}";
  const decompressedData = JSON.parse(decompress(compressedJson));

  console.log("Decompressed data:", decompressedData);

  // Process and render decompressed data
  decompressedData.items.forEach(item => {
    const div = document.createElement('div');
    div.className = 'item';
    div.textContent = item.title;
    document.getElementById('container').appendChild(div);
  });
</script>

<div id="content"></div>
<div id="container"></div>
```

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

### Improved Word Wrapping for Clamped Text (CSS)

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

Modifies default text clamping behavior to prioritize word boundaries over letter boundaries, preventing awkward line breaks within words. Requires adding `clamp--nicely` class and including the provided CSS.

```css
.clamp--nicely {
  word-break: normal !important;
}
```

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

### Webhook Data Transmission to TRMNL API

Source: https://context7.com/yunruse/trmnl-tricks/llms.txt

This API endpoint allows external sources to send data to TRMNL plugins via POST requests with JSON payloads. It supports different merge strategies and data compression.

```APIDOC
## Webhook Data Transmission to TRMNL API

### Description
Send data from external sources to TRMNL plugins using POST requests with JSON payloads. The API enforces a 2KB limit on `merge_variables` content and rate limits requests to once every five minutes per plugin.

### Method
POST

### Endpoint
`https://usetrmnl.com/api/custom_plugins/<plugin_uuid>`

### Parameters
#### Path Parameters
- **`plugin_uuid`** (string) - Required - The unique identifier for the TRMNL plugin.

#### Query Parameters
None

#### Request Body
- **`merge_variables`** (object) - Required - A JSON object containing the data to be merged into the plugin's variables. Maximum size is 2KB.
- **`merge_strategy`** (string) - Optional - The strategy for merging variables. Options: `standard` (default, replaces all variables), `deep_merge` (merges nested objects), `stream` (appends to arrays).
- **`stream_limit`** (integer) - Optional - When using `stream` strategy, limits the number of items to keep in the array.

### Request Example
```python
import requests
import json
import zlib
import base64

URL = "https://usetrmnl.com/api/custom_plugins/abc123-your-plugin-uuid-here"

# Standard merge
data_standard = {
    "temperature": 72,
    "weather": "Sunny",
    "forecast": [
        {"day": "Mon", "high": 75, "low": 62},
        {"day": "Tue", "high": 73, "low": 60}
    ]
}
response = requests.post(URL, json={'merge_variables': data_standard})

# Deep merge strategy
nested_data = {"user": {"settings": {"theme": "dark"}}}
requests.post(URL, json={
    'merge_variables': nested_data,
    'merge_strategy': 'deep_merge'
})

# Stream strategy
stream_data = {"events": [{"time": "10:00", "title": "Meeting"}]}
requests.post(URL, json={
    'merge_variables': stream_data,
    'merge_strategy': 'stream',
    'stream_limit': 10  # Keep only last 10 items
})

# Data compression for large payloads
def compress(string: str):
    return base64.b64encode(zlib.compress(string.encode())).decode()

large_text = "Very long text content that needs compression..."
compressed_data = {"content": compress(large_text)}
requests.post(URL, json={'merge_variables': compressed_data})
```

### Response
#### Success Response (200)
- **message** (string) - Indicates success, e.g., "Data sent successfully".

#### Error Response (4xx/5xx)
- **message** (string) - Describes the error, e.g., "Rate limited: wait 5 minutes between requests".

#### Response Example (Success)
```json
{
  "message": "Data sent successfully"
}
```

#### Response Example (Rate Limited)
```json
{
  "message": "Rate limited: wait 5 minutes between requests"
}
```
```

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

### Passing JSON Data to JavaScript from Liquid (JavaScript)

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

Shows how to securely pass JSON data from a Liquid template to a JavaScript variable by utilizing the `json` filter. This avoids manual string manipulation and potential parsing errors.

```javascript
let some_list = JSON.parse(`{{data.my_list | json}}`)
```

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

### Vertical Text Orientation with writing-mode (CSS)

Source: https://github.com/yunruse/trmnl-tricks/wiki/Home

Applies CSS to display text vertically, suitable for rotated labels on elements like TRMNL's `.item`. It uses `writing-mode` and `text-orientation` properties.

```css
.index {
  writing-mode: vertical-rl;
  text-orientation: mixed;
}
```
Tokens:
Raw