@modyo/mcp 0.1.0

package/docs/channels/liquid/field-access.md

@@ -0,0 +1,340 @@
+# Liquid Field Access in Modyo Channels
+
+## Overview
+
+When accessing content fields in Liquid templates (widgets, pages, snippets, layouts), field names **must match exactly** as they are defined in the Content Type schema.
+
+## Critical Rule: Exact Field Name Matching
+
+**Field names in Liquid must preserve:**
+- ✅ **Spaces**: Characters remain as spaces
+- ✅ **Accents**: á, é, í, ó, ú, ñ, etc.
+- ✅ **Capitalization**: Title Case, UPPERCASE, lowercase
+- ✅ **Special Characters**: All characters exactly as defined
+
+### Why This Matters
+
+Unlike many CMS platforms that normalize field names (converting to snake_case, removing accents, etc.), Modyo preserves the exact field names as entered in the Content Type definition. This allows for:
+- Better internationalization support
+- More descriptive field names with natural language
+- Consistency between UI and API
+
+However, it requires **exact matching** when accessing fields in Liquid.
+
+## Common Mistakes
+
+### ❌ Wrong Approaches
+
+```liquid
+<!-- ❌ WRONG: Using snake_case when field has spaces -->
+{{ product.fields['icono_svg'] }}
+
+<!-- ❌ WRONG: Missing accent -->
+{{ product.fields['titulo'] }}
+
+<!-- ❌ WRONG: Wrong capitalization -->
+{{ product.fields['url'] }}
+
+<!-- ❌ WRONG: Using dot notation (doesn't work for fields with spaces/accents) -->
+{{ product.fields.Título }}
+
+<!-- ❌ WRONG: Without quotes -->
+{{ product.fields[titulo] }}
+
+<!-- ❌ WRONG: Hyphen instead of space -->
+{{ product.fields['icono-svg'] }}
+```
+
+### ✅ Correct Approach
+
+```liquid
+<!-- ✅ CORRECT: Exact match with Content Type -->
+{{ product.fields['Icono SVG'] }}     <!-- Space preserved -->
+{{ product.fields['Título'] }}        <!-- Accent preserved -->
+{{ product.fields['URL'] }}           <!-- Capitalization preserved -->
+{{ product.fields['Descripción'] }}   <!-- Accent and capital preserved -->
+```
+
+## Workflow: Getting Exact Field Names
+
+### Step 1: Get Content Type Schema
+
+Use the `type-get` tool to retrieve the exact field definitions:
+
+```typescript
+const type = await type-get({
+  platformSlug: "your-platform",
+  spaceId: 2516,
+  typeId: 5759
+});
+```
+
+### Step 2: Check Field Names in Response
+
+Look at the `fields` array in the response:
+
+```json
+{
+  "id": 5759,
+  "name": "Product",
+  "fields": [
+    {
+      "id": 31354,
+      "name": "Título",           // ← Use this EXACT name
+      "type": "string"
+    },
+    {
+      "id": 31355,
+      "name": "Descripción",      // ← Use this EXACT name
+      "type": "text"
+    },
+    {
+      "id": 31356,
+      "name": "Icono SVG",        // ← Use this EXACT name (with space)
+      "type": "text"
+    },
+    {
+      "id": 31357,
+      "name": "URL",              // ← Use this EXACT name (uppercase)
+      "type": "string"
+    }
+  ]
+}
+```
+
+### Step 3: Copy Exact Names to Liquid
+
+**DO NOT type manually** - copy the exact field names from the schema:
+
+```liquid
+{%- assign products = spaces['my-space'].types['product'].entries -%}
+{%- for product in products -%}
+  <h3>{{ product.fields['Título'] }}</h3>
+  <p>{{ product.fields['Descripción'] }}</p>
+  <div>{{ product.fields['Icono SVG'] }}</div>
+  <a href="{{ product.fields['URL'] }}">Link</a>
+{%- endfor -%}
+```
+
+## Examples by Language
+
+### Spanish Fields
+
+```liquid
+<!-- Content Type fields defined as: -->
+<!-- "Título", "Descripción", "Año de Publicación" -->
+
+{%- for book in spaces['biblioteca'].types['book'].entries -%}
+  <h2>{{ book.fields['Título'] }}</h2>
+  <p>{{ book.fields['Descripción'] }}</p>
+  <span>{{ book.fields['Año de Publicación'] }}</span>
+{%- endfor -%}
+```
+
+### English Fields with Spaces
+
+```liquid
+<!-- Content Type fields defined as: -->
+<!-- "Product Name", "Short Description", "Main Image" -->
+
+{%- for item in spaces['catalog'].types['product'].entries -%}
+  <h2>{{ item.fields['Product Name'] }}</h2>
+  <p>{{ item.fields['Short Description'] }}</p>
+  <img src="{{ item.fields['Main Image'].url }}">
+{%- endfor -%}
+```
+
+### Mixed Case Fields
+
+```liquid
+<!-- Content Type fields defined as: -->
+<!-- "SKU", "URL", "API Key" -->
+
+{%- for config in spaces['settings'].types['config'].entries -%}
+  SKU: {{ config.fields['SKU'] }}
+  URL: {{ config.fields['URL'] }}
+  API Key: {{ config.fields['API Key'] }}
+{%- endfor -%}
+```
+
+## Testing Field Access
+
+### 1. Test in Simple Template First
+
+Before using in complex widgets, test field access in a simple snippet:
+
+```liquid
+{%- assign test_entry = spaces['my-space'].types['my-type'].entries | first -%}
+
+<h3>Testing Field Access:</h3>
+<ul>
+  <li>Title: {{ test_entry.fields['Título'] }}</li>
+  <li>Description: {{ test_entry.fields['Descripción'] }}</li>
+</ul>
+```
+
+### 2. Check for Empty Output
+
+If a field returns empty:
+1. Verify field name matches exactly (case, spaces, accents)
+2. Check field exists in Content Type (`type-get`)
+3. Verify entry has value for that field (`entry-get`)
+4. Confirm entry is accessible (published or draft depending on context)
+
+### 3. Debug with Field List
+
+List all available fields to verify exact names:
+
+```liquid
+{%- assign entry = spaces['my-space'].types['my-type'].entries | first -%}
+
+<h3>Available Fields:</h3>
+{% for field in entry.fields %}
+  <li>{{ field[0] }}: {{ field[1] }}</li>
+{% endfor %}
+```
+
+## Best Practices
+
+### 1. Always Check Schema First
+
+```typescript
+// ALWAYS start by checking the Content Type schema
+const type = await type-get({ platformSlug, spaceId, typeId });
+
+// Review field names before writing Liquid
+type.fields.forEach(field => {
+  console.log(`Field: "${field.name}" (ID: ${field.id})`);
+});
+```
+
+### 2. Copy, Don't Type
+
+**Never manually type field names** - always copy from schema to avoid typos:
+```liquid
+<!-- ❌ BAD: Typed manually (risk of typos) -->
+{{ product.fields['Descripcion'] }}  <!-- Missing accent -->
+
+<!-- ✅ GOOD: Copied from schema -->
+{{ product.fields['Descripción'] }}  <!-- Exact match -->
+```
+
+### 3. Document Field Names
+
+In widget code, document the required field names:
+
+```liquid
+<!--
+  Required Content Type Fields (exact names):
+  - "Título" (string)
+  - "Descripción" (text)
+  - "Icono SVG" (text)
+  - "URL" (string)
+-->
+
+{%- for product in products -%}
+  {{ product.fields['Título'] }}
+{%- endfor -%}
+```
+
+### 4. Use Consistent Naming in Content Types
+
+When creating Content Types, consider:
+- Using consistent naming patterns
+- Avoiding overly complex names
+- Documenting field names in type description
+
+## Troubleshooting
+
+### Field Returns Empty/Null
+
+**Problem**: Field access returns nothing
+
+**Checklist**:
+1. ✅ Field name matches exactly (spaces, accents, case)?
+2. ✅ Field exists in Content Type schema?
+3. ✅ Entry has a value for this field?
+4. ✅ Entry is accessible (published/draft)?
+5. ✅ Using bracket notation with quotes: `['Field Name']`?
+
+**Solution**:
+```typescript
+// 1. Check Content Type schema
+const type = await type-get({ platformSlug, spaceId, typeId });
+console.log('Available fields:', type.fields.map(f => f.name));
+
+// 2. Check specific entry
+const entry = await entry-get({ platformSlug, spaceId, entryId });
+console.log('Entry field values:', entry.field_values);
+
+// 3. Use exact field name in Liquid
+{{ entry.fields['Exact Field Name'] }}
+```
+
+### Field Name Has Special Characters
+
+**Problem**: Field has parentheses, slashes, or other special characters
+
+**Solution**: Use bracket notation with quotes (same as spaces):
+```liquid
+{{ entry.fields['Price (USD)'] }}
+{{ entry.fields['Start/End Date'] }}
+{{ entry.fields['Contact Email'] }}
+```
+
+### Multiple Entries with Same Pattern
+
+**Problem**: Need to access same fields across many entries
+
+**Solution**: Create a reusable snippet:
+```liquid
+<!-- _includes/product-card.liquid -->
+<div class="product-card">
+  <h3>{{ product.fields['Título'] }}</h3>
+  <p>{{ product.fields['Descripción'] }}</p>
+  <a href="{{ product.fields['URL'] }}">Ver más</a>
+</div>
+
+<!-- In main template -->
+{%- for product in products -%}
+  {% snippet 'product-card', product: product %}
+{%- endfor -%}
+```
+
+## Content API vs Liquid
+
+### Important Difference
+
+**Content API** (JavaScript fetch):
+- Field values accessed via `field_id` (numeric ID)
+- Example: `entry.field_values.find(f => f.field_id === 31354).value`
+
+**Liquid Templates**:
+- Field values accessed via exact `field name` (string)
+- Example: `entry.fields['Título']`
+
+### When to Use Each
+
+**Use Content API** when:
+- Building external applications
+- Need published content only
+- Client-side dynamic loading
+
+**Use Liquid** when:
+- Building widgets/pages in Modyo
+- Need access to draft content
+- Server-side rendering
+- Better performance (no extra HTTP request)
+
+## Related Documentation
+
+- [Modyo Snippets Architecture](/docs/MODYO_SNIPPETS_ARCHITECTURE.md)
+- [Editing Published Widgets](/docs/EDITING_PUBLISHED_WIDGETS.md)
+- [Modyo Liquid Markup](https://docs.modyo.com/en/platform/channels/liquid-markup.html)
+- [Content Type Schema Tool](/docs/tools/TYPE_TOOLS.md)
+
+---
+
+**Document Version**: 1.0.0
+**Last Updated**: 2025-01-09
+**Purpose**: Guide for accessing content fields in Liquid templates with exact name matching