miki-template 2.2.3 → 2.3.0

package/docs/guide/custom-tags.md

@@ -1,271 +1,542 @@
-# Custom Tags
+# Custom Tags
+
+
 
 Create your own template tags by registering a parser function. miki-template's tag API mirrors Django's — a tag is a parser that returns a Node object with a `render(context)` method.
 
+
+
 ## Table of Contents
 
+
+
 - [Register a Simple Tag](#register-a-simple-tag)
+
 - [Async Custom Tags](#async-custom-tags)
+
 - [Parsing Complex Tags](#parsing-complex-tags)
+
 - [Accessing the Parser](#accessing-the-parser)
+
 - [Tag Registration Best Practices](#tag-registration-best-practices)
 
+
+
 ---
 
+
+
 ## Register a Simple Tag
 
+
+
 === "CommonJS"
 
+
+
     ```javascript
+
     const { registerTag } = require('miki-template');
 
+
+
     registerTag('hello', (tagContent, parser) => {
+
       return {
+
         render: (context) => 'Hello World!'
+
       };
+
     });
+
     ```
 
+
+
 === "ES Modules"
 
+
+
     ```javascript
+
     import { registerTag } from 'miki-template';
 
+
+
     registerTag('hello', (tagContent, parser) => {
+
       return {
+
         render: (context) => 'Hello World!'
+
       };
+
     });
+
     ```
 
+
+
 Usage in templates:
 
+
+
 ```html
+
 {% hello %}
+
 ```
 
+
+
 ### Passing Arguments
 
+
+
 ```javascript
+
 registerTag('greet', (tagContent, parser) => {
+
   // tagContent is the full text after the tag name: "user.name"
+
   const varName = tagContent.trim();
+
   return {
+
     render: (context) => {
+
       const value = context.get(varName);
+
       return `Hello, ${value}!`;
+
     }
+
   };
+
 });
+
 ```
 
+
+
 ```html
+
 {% greet user.name %}
+
 ```
 
+
+
 ## Returning a Node Class
 
+
+
 For more complex tags, return a Node class instance:
 
+
+
 === "CommonJS"
 
+
+
     ```javascript
+
     const { registerTag } = require('miki-template');
 
+
+
     class GreetNode {
+
       constructor(varName) {
+
         this.varName = varName;
+
       }
+
       render(context) {
+
         const value = context.get(this.varName);
+
         return `Hello, ${value || 'Guest'}!`;
+
       }
+
     }
 
+
+
     registerTag('greet', (tagContent, parser) => {
+
       const varName = tagContent.trim();
+
       return new GreetNode(varName);
+
     });
+
     ```
 
+
+
 === "ES Modules"
 
+
+
     ```javascript
+
     import { registerTag } from 'miki-template';
 
+
+
     class GreetNode {
+
       constructor(varName) {
+
         this.varName = varName;
+
       }
+
       render(context) {
+
         const value = context.get(this.varName);
+
         return `Hello, ${value || 'Guest'}!`;
+
       }
+
     }
 
+
+
     registerTag('greet', (tagContent, parser) => {
+
       const varName = tagContent.trim();
+
       return new GreetNode(varName);
+
     });
+
     ```
 
+
+
 ## Async Custom Tags
 
+
+
 If your `render()` method returns a Promise, the template must be rendered with `asyncRender()`:
 
+
+
 === "CommonJS"
 
+
+
     ```javascript
+
     const { registerTag, asyncRender } = require('miki-template');
 
+
+
     registerTag('fetch_greeting', (tagContent, parser) => {
+
       const urlVar = tagContent.trim();
+
       return {
+
         async render(context) {
+
           const url = context.get(urlVar);
+
           const res = await fetch(url);
+
           const data = await res.json();
+
           return data.message;
+
         }
+
       };
+
     });
 
+
+
     // Must use asyncRender
+
     const html = await asyncRender('{% fetch_greeting api_url %}', { api_url: 'https://...' });
+
     ```
 
+
+
 === "ES Modules"
 
+
+
     ```javascript
+
     import { registerTag, asyncRender } from 'miki-template';
 
+
+
     registerTag('fetch_greeting', (tagContent, parser) => {
+
       const urlVar = tagContent.trim();
+
       return {
+
         async render(context) {
+
           const url = context.get(urlVar);
+
           const res = await fetch(url);
+
           const data = await res.json();
+
           return data.message;
+
         }
+
       };
+
     });
 
+
+
     const html = await asyncRender('{% fetch_greeting api_url %}', { api_url: 'https://...' });
+
     ```
 
+
+
 ## Parsing Complex Tags
 
+
+
 Use the `parser` object to consume tokens and build multi-part tags:
 
+
+
 === "CommonJS"
 
+
+
     ```javascript
+
     const { registerTag } = require('miki-template');
 
+
+
     registerTag('panel', (tagContent, parser) => {
+
       const classes = tagContent.trim() || '';
+
       const nodelist = parser.parse(['endpanel']);
+
       parser.skipTag(); // consume endpanel
 
+
+
       return {
+
         render: (context) => {
+
           const body = nodelist.map(n => n.render(context)).join('');
+
           return `<div class="panel ${classes}">${body}</div>`;
+
         }
+
       };
+
     });
+
     ```
 
+
+
 === "ES Modules"
 
+
+
     ```javascript
+
     import { registerTag } from 'miki-template';
 
+
+
     registerTag('panel', (tagContent, parser) => {
+
       const classes = tagContent.trim() || '';
+
       const nodelist = parser.parse(['endpanel']);
+
       parser.skipTag();
 
+
+
       return {
+
         render: (context) => {
+
           const body = nodelist.map(n => n.render(context)).join('');
+
           return `<div class="panel ${classes}">${body}</div>`;
+
         }
+
       };
+
     });
+
     ```
 
+
+
 Usage with nested content:
 
+
+
 ```html
+
 {% panel "card" %}
+
   <h2>{{ title }}</h2>
+
   <p>{{ description }}</p>
+
 {% endpanel %}
+
 ```
 
+
+
 ### Real-World Example: Cache Tag
 
+
+
 === "CommonJS"
 
+
+
     ```javascript
+
     const { registerTag } = require('miki-template');
 
+
+
     registerTag('cache_block', (tagContent, parser) => {
+
       const [key, ...rest] = tagContent.trim().split(/\s+/);
+
       const nodelist = parser.parse(['endcache_block']);
+
       parser.skipTag();
 
+
+
       return {
+
         render: (context) => {
+
           const cacheKey = key;
+
           const cache = context.get('cache') || global.__cache__;
+
           if (!cache) return nodelist.map(n => n.render(context)).join('');
+
           if (cache.has(cacheKey)) return cache.get(cacheKey);
+
           const output = nodelist.map(n => n.render(context)).join('');
+
           cache.set(cacheKey, output, rest[0] || 300);
+
           return output;
+
         }
+
       };
+
     });
+
     ```
 
+
+
 === "ES Modules"
 
+
+
     ```javascript
+
     import { registerTag } from 'miki-template';
 
+
+
     registerTag('cache_block', (tagContent, parser) => {
+
       const [key, ...rest] = tagContent.trim().split(/\s+/);
+
       const nodelist = parser.parse(['endcache_block']);
+
       parser.skipTag();
 
+
+
       return {
+
         render: (context) => {
+
           const cacheKey = key;
+
           const cache = context.get('cache') || global.__cache__;
+
           if (!cache) return nodelist.map(n => n.render(context)).join('');
+
           if (cache.has(cacheKey)) return cache.get(cacheKey);
+
           const output = nodelist.map(n => n.render(context)).join('');
+
           cache.set(cacheKey, output, rest[0] || 300);
+
           return output;
+
         }
+
       };
+
     });
+
     ```
 
+
+
 ## Tag Registration Best Practices
 
+
+
 1. **Return objects with `render(context)`** — the render signature must accept a context object.
+
 2. **Use `parser.parse([...terminators])`** for tags with bodies — this lets the parser consume nested content correctly.
+
 3. **Always call `parser.skipTag()`** after `parser.parse` to consume the end tag.
+
 4. **Handle whitespace** — `tagContent.trim()` for single-argument tags.
+
 5. **Async tags need asyncRender** — return a Promise from `render()` and use `asyncRender()` to render.
+
 6. **Access context values** — use `context.get('key')` or `context.resolve('expr')`.
 
+
+
 ## Next Steps
 
-- [Built-in Tags Reference](../api/tags)
-- [Custom Filters](./custom-filters)
-- [Guide: Tags](./tags)
+
+
+- [Built-in Tags Reference](../api/tags.md)
+
+- [Custom Filters](./custom-filters.md)
+
+- [Guide: Tags](./tags.md)
+