@modyo/mcp 0.1.0

package/docs/channels/liquid/best-practices.md

@@ -0,0 +1,471 @@
+# Liquid Best Practices for Modyo MCP
+
+> **Critical Guide**: This document addresses the most common and impactful mistakes when working with Liquid templates in Modyo. Read this before creating widgets or templates.
+
+---
+
+## Table of Contents
+
+1. [Field Name Notation (CRITICAL)](#field-name-notation-critical)
+2. [Conditional Rendering](#conditional-rendering)
+3. [Empty State Handling](#empty-state-handling)
+4. [Content Access Patterns](#content-access-patterns)
+5. [Menu Access Patterns](#menu-access-patterns)
+6. [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Field Name Notation (CRITICAL)
+
+### ⚠️ The Problem
+
+**This is the #1 most common error** causing widgets to appear empty even when content exists.
+
+### ✅ CORRECT - Use Bracket Notation with Exact Field Names
+
+```liquid
+{{ entry.fields['Product Name'] }}
+{{ banner.fields['Title'] }}
+{{ banner.fields['CTA Text'] }}
+{{ banner.fields['CTA Link'] }}
+{{ product.fields['Icon'] }}
+```
+
+### ❌ WRONG - Do NOT Use Dot Notation or Snake Case
+
+```liquid
+{{ entry.fields.product_name }}     <!-- WILL NOT WORK -->
+{{ banner.fields.title }}            <!-- WILL NOT WORK -->
+{{ banner.fields.cta_text }}         <!-- WILL NOT WORK -->
+{{ product.fields.icon }}            <!-- WILL NOT WORK -->
+```
+
+### Why This Matters
+
+- **Field names in Modyo Content UI**: Use title case with spaces (e.g., "Product Name")
+- **Liquid access pattern**: Must use **exact match** with bracket notation
+- **Never convert to snake_case** or use dot notation
+- **Case-sensitive**: "Product Name" ≠ "product name" ≠ "product_name"
+
+### Discovery Pattern
+
+When you create a content type with `type-create` or `type-update`, use `type-get` to see the exact field names:
+
+```bash
+# Get content type schema
+mcp__modyo-mcp__type-get({ platformSlug, spaceId, typeId })
+
+# Response will show:
+{
+  "fields": [
+    {
+      "id": 123,
+      "name": "Product Name",  ← THIS IS THE EXACT NAME TO USE
+      "type": "string"
+    }
+  ]
+}
+```
+
+Then in your widget Liquid code:
+
+```liquid
+{% assign entries = spaces['public-content'].types['product_card'].entries %}
+{% for product in entries %}
+  <h3>{{ product.fields['Product Name'] }}</h3>  ← EXACT MATCH
+{% endfor %}
+```
+
+---
+
+## Conditional Rendering
+
+### Always Check Field Existence Before Rendering
+
+Optional fields should be conditionally rendered to prevent empty elements and improve UX.
+
+### ✅ CORRECT Pattern
+
+```liquid
+{% if banner.fields['CTA Text'] and banner.fields['CTA Link'] %}
+  <a href="{{ banner.fields['CTA Link'] }}" class="btn btn-primary">
+    {{ banner.fields['CTA Text'] }}
+  </a>
+{% endif %}
+```
+
+### ❌ WRONG Pattern
+
+```liquid
+<!-- This will render empty button if no CTA data -->
+<a href="{{ banner.fields['CTA Link'] }}" class="btn btn-primary">
+  {{ banner.fields['CTA Text'] }}
+</a>
+```
+
+### Complex Conditional Example
+
+```liquid
+{% if product.fields['Featured Image'] %}
+  <img src="{{ product.fields['Featured Image'].url }}"
+       alt="{{ product.fields['Image Alt Text'] | default: product.fields['Product Name'] }}">
+{% else %}
+  <div class="placeholder-image">
+    <i class="bi bi-image" aria-hidden="true"></i>
+  </div>
+{% endif %}
+```
+
+### Checking Multiple Conditions
+
+```liquid
+{% if entry.fields['Published'] and entry.fields['Visible'] %}
+  {% if entry.fields['Start Date'] %}
+    {% assign start_date = entry.fields['Start Date'] | date: '%s' %}
+    {% assign now = 'now' | date: '%s' %}
+    {% if start_date <= now %}
+      <!-- Render entry -->
+    {% endif %}
+  {% else %}
+    <!-- Render entry (no date restriction) -->
+  {% endif %}
+{% endif %}
+```
+
+---
+
+## Empty State Handling
+
+### Always Provide Feedback When No Content Exists
+
+Widgets should gracefully handle empty states to improve UX.
+
+### ✅ CORRECT Pattern
+
+```liquid
+{% assign entries = spaces['public-content'].types['news_article'].entries %}
+
+{% if entries.size > 0 %}
+  <div class="news-grid">
+    {% for article in entries limit: 3 %}
+      <article class="news-card">
+        <h3>{{ article.fields['Headline'] }}</h3>
+        <p>{{ article.fields['Summary'] }}</p>
+      </article>
+    {% endfor %}
+  </div>
+{% else %}
+  <div class="empty-state text-center py-5">
+    <i class="bi bi-newspaper" style="font-size: 3rem; color: #ccc;" aria-hidden="true"></i>
+    <p class="mt-3 text-muted">No news articles available at this time.</p>
+  </div>
+{% endif %}
+```
+
+### Empty State Best Practices
+
+1. **Use semantic HTML**: `<div class="empty-state">` not generic `<div>`
+2. **Provide helpful icon**: Bootstrap Icons, Font Awesome, or SVG
+3. **Clear message**: Tell users why nothing is showing
+4. **Suggest action**: "Check back soon" or "Browse our products"
+5. **Style appropriately**: Muted colors, centered, adequate spacing
+
+---
+
+## Content Access Patterns
+
+### Accessing Content from Spaces
+
+```liquid
+<!-- Access all entries of a type -->
+{% assign products = spaces['public-content'].types['product_card'].entries %}
+
+<!-- Access by UUID (stable identifier) -->
+{% assign entry = spaces['public-content'].types['product_card'].entries | by_uuid: '1234-5678-abcd' %}
+
+<!-- Access by slug (for published entries) -->
+{% assign entry = spaces['public-content'].types['product_card'].entries | by_slug: 'premium-account' %}
+
+<!-- Filter entries -->
+{% assign featured = spaces['public-content'].types['product_card'].entries | where: "fields['Featured']", true %}
+
+<!-- Sort entries -->
+{% assign sorted = spaces['public-content'].types['product_card'].entries | sort: "fields['Order']" %}
+
+<!-- Limit results -->
+{% assign top_three = spaces['public-content'].types['product_card'].entries | limit: 3 %}
+```
+
+### Widget Variables for Dynamic Content
+
+Widgets should use variables to be reusable across different content:
+
+```liquid
+<!-- Widget variables (set when adding widget to page) -->
+{% assign space_uid = widget.variables.space_uid | default: 'public-content' %}
+{% assign type_uid = widget.variables.type_uid | default: 'product_card' %}
+{% assign limit = widget.variables.limit | default: 6 %}
+
+<!-- Access content dynamically -->
+{% assign entries = spaces[space_uid].types[type_uid].entries | limit: limit %}
+```
+
+### Filtering with Variables
+
+```liquid
+{% assign category_filter = widget.variables.category_filter %}
+{% assign entries = spaces[space_uid].types[type_uid].entries %}
+
+{% if category_filter and category_filter != 'all' %}
+  {% assign entries = entries | where: "fields['Category']", category_filter %}
+{% endif %}
+
+{% assign show_featured = widget.variables.show_featured_only | default: false %}
+{% if show_featured %}
+  {% assign entries = entries | where: "fields['Featured']", true %}
+{% endif %}
+```
+
+---
+
+## Menu Access Patterns
+
+### Accessing Navigation Menus
+
+Menus are accessed by their **slug** (case-sensitive):
+
+```liquid
+<!-- Access menu by slug -->
+{% assign main_menu = menus['main'] %}
+{% assign footer_menu = menus['footer-te-puede-interesar'] %}
+
+<!-- WRONG - menus don't have IDs in Liquid -->
+{% assign menu = menus[123] %}  <!-- WILL NOT WORK -->
+```
+
+### Always Check Menu Existence
+
+```liquid
+{% if menus['footer-informate'] %}
+  <nav aria-label="{{ menus['footer-informate'].name }}">
+    <h6>{{ menus['footer-informate'].name }}</h6>
+    <ul>
+      {% for item in menus['footer-informate'].items | visible_items %}
+        <li>
+          <a href="{{ item.url }}">{{ item.label }}</a>
+        </li>
+      {% endfor %}
+    </ul>
+  </nav>
+{% endif %}
+```
+
+### Filter Menu Items
+
+```liquid
+<!-- Only visible items -->
+{% assign items = menus['main'].items | visible_items %}
+
+<!-- Top-level items only (no children) -->
+{% assign top_items = menus['main'].items | visible_items | where: "parent_id", nil %}
+
+<!-- Items with children (for dropdowns) -->
+{% for item in menus['main'].items | visible_items %}
+  {% if item.children.size > 0 %}
+    <li class="dropdown">
+      <a href="{{ item.url }}">{{ item.label }}</a>
+      <ul class="dropdown-menu">
+        {% for child in item.children | visible_items %}
+          <li><a href="{{ child.url }}">{{ child.label }}</a></li>
+        {% endfor %}
+      </ul>
+    </li>
+  {% else %}
+    <li><a href="{{ item.url }}">{{ item.label }}</a></li>
+  {% endif %}
+{% endfor %}
+```
+
+### Menu Item Properties
+
+```liquid
+{% for item in menus['main'].items | visible_items %}
+  <a href="{{ item.url }}"
+     {% if item.target %}target="{{ item.target }}"{% endif %}
+     {% if item.target == '_blank' %}rel="noopener noreferrer"{% endif %}>
+    {{ item.label }}
+  </a>
+{% endfor %}
+```
+
+---
+
+## Common Pitfalls
+
+### 1. ❌ Using `.name` Instead of `['Name']` on Content Fields
+
+```liquid
+<!-- WRONG -->
+{{ entry.fields.name }}
+
+<!-- CORRECT -->
+{{ entry.fields['Name'] }}
+```
+
+**Exception**: Menu properties DO use dot notation:
+```liquid
+{{ menus['main'].name }}  <!-- Correct: menu property -->
+{{ item.label }}           <!-- Correct: menu item property -->
+```
+
+### 2. ❌ Not Filtering Visible Menu Items
+
+```liquid
+<!-- WRONG - shows hidden items -->
+{% for item in menus['main'].items %}
+
+<!-- CORRECT - only visible items -->
+{% for item in menus['main'].items | visible_items %}
+```
+
+### 3. ❌ Hardcoding Menu Names in Snippets
+
+```liquid
+<!-- LESS FLEXIBLE -->
+<h6>Te puede interesar</h6>
+
+<!-- MORE FLEXIBLE - uses actual menu name -->
+<h6>{{ menus['footer-te-puede-interesar'].name }}</h6>
+```
+
+**Note**: If menu name rendering fails (returns blank), hardcode as fallback. This was discovered in Iteration 10.
+
+### 4. ❌ Not Handling Asset URLs Properly
+
+```liquid
+<!-- WRONG - asset field is an object, not a string -->
+<img src="{{ product.fields['Image'] }}">
+
+<!-- CORRECT - access the url property -->
+<img src="{{ product.fields['Image'].url }}"
+     alt="{{ product.fields['Image Alt Text'] }}">
+```
+
+### 5. ❌ Forgetting CSP Nonce in Inline Styles/Scripts
+
+```liquid
+<!-- WRONG - will be blocked by CSP -->
+<style>
+  .custom { color: blue; }
+</style>
+
+<!-- CORRECT - includes CSP nonce -->
+<style nonce="{{csp_nonce}}">
+  .custom { color: blue; }
+</style>
+```
+
+### 6. ❌ Using Inline Event Handlers
+
+```liquid
+<!-- WRONG - CSP blocks inline event handlers -->
+<button onclick="doSomething()">Click</button>
+
+<!-- CORRECT - use event listeners in script -->
+<button id="myButton">Click</button>
+<script nonce="{{csp_nonce}}">
+  document.getElementById('myButton').addEventListener('click', function() {
+    // doSomething
+  });
+</script>
+```
+
+### 7. ❌ Not Using Site-Relative URLs
+
+```liquid
+<!-- WRONG - hardcodes domain -->
+<a href="https://mysite.modyo.cloud/products">Products</a>
+
+<!-- CORRECT - site-relative -->
+<a href="/products">Products</a>
+```
+
+### 8. ❌ Not Escaping User-Generated Content
+
+```liquid
+<!-- POTENTIALLY UNSAFE -->
+<div>{{ entry.fields['User Comment'] }}</div>
+
+<!-- SAFER - escape HTML -->
+<div>{{ entry.fields['User Comment'] | escape }}</div>
+
+<!-- OR use strip_html for plain text -->
+<div>{{ entry.fields['User Comment'] | strip_html }}</div>
+```
+
+---
+
+## Quick Reference Checklist
+
+Before publishing a widget or template, verify:
+
+- [ ] ✅ Using bracket notation for ALL content fields: `fields['Name']`
+- [ ] ✅ Field names match exactly (case-sensitive, including spaces)
+- [ ] ✅ Optional fields have conditional rendering (`{% if %}`)
+- [ ] ✅ Empty states provided for collections (`{% if entries.size > 0 %}`)
+- [ ] ✅ Menu items filtered by visibility (`| visible_items`)
+- [ ] ✅ Asset URLs accessed via `.url` property
+- [ ] ✅ CSP nonce included in inline `<style>` and `<script>` tags
+- [ ] ✅ No inline event handlers (`onclick`, etc.)
+- [ ] ✅ Site-relative URLs used (`/path` not `https://domain.com/path`)
+- [ ] ✅ Widget variables used for reusability
+- [ ] ✅ Accessibility attributes included (ARIA labels, alt text)
+
+---
+
+## Related Documentation
+
+- [CSS Organization Guide](./CSS_ORGANIZATION.md) - CSS templates vs snippets
+- [Template Workflows Guide](./TEMPLATE_WORKFLOWS.md) - Safe template editing patterns
+- [Widget Workflows Guide](./WIDGET_WORKFLOWS.md) - Widget ID stability and publishing
+- [Modyo Liquid Documentation](https://docs.modyo.com/en/platform/channels/liquid-markup.html)
+
+---
+
+## Testing Your Liquid Code
+
+### Local Testing Pattern
+
+1. **Create content entries first** - Liquid won't show anything if content doesn't exist
+2. **Publish content** - Draft entries aren't accessible to widgets
+3. **Test with varied data** - Some entries with optional fields, some without
+4. **Test empty states** - Remove all entries to see empty state
+5. **Test filtering** - Verify category/featured filters work correctly
+
+### Common Debug Steps
+
+```liquid
+<!-- Debug: Show all available spaces -->
+{% for space in spaces %}
+  <p>Space: {{ space.uid }}</p>
+{% endfor %}
+
+<!-- Debug: Show all types in a space -->
+{% for type in spaces['public-content'].types %}
+  <p>Type: {{ type.uid }}</p>
+{% endfor %}
+
+<!-- Debug: Show entry count -->
+<p>Entries: {{ spaces['public-content'].types['product_card'].entries.size }}</p>
+
+<!-- Debug: Show first entry's fields -->
+{% assign first = spaces['public-content'].types['product_card'].entries | first %}
+{% if first %}
+  <pre>{{ first.fields | json }}</pre>
+{% endif %}
+```
+
+---
+
+**Last Updated**: October 23, 2025
+**Source**: Iteration 9 findings from mcp-improvements.md