sfcc-dev-mcp 1.0.15 → 1.0.19

package/dist/docs/isml/isnext.md

@@ -0,0 +1,672 @@
+# ISML isnext Element
+
+## Overview
+
+The `<isnext>` element jumps forward within a loop to the next element of an iterator. Unlike `<iscontinue>`, which breaks out of the current iteration and returns to the top of the loop, `<isnext>` advances the iterator forward one position and continues processing the next line of code.
+
+**Critical Difference:** `<isnext>` moves the iterator forward but continues executing subsequent code, while `<iscontinue>` skips all remaining code in the current iteration.
+
+## Syntax
+
+```isml
+<isnext/>
+```
+
+## Attributes
+
+This element has no attributes.
+
+## Purpose
+
+The `<isnext>` element enables:
+
+1. **Iterator Advancement:** Move to the next list element within a loop
+2. **Multi-Element Processing:** Process multiple elements in a single iteration
+3. **Skip and Continue:** Advance iterator and continue with subsequent code
+4. **Flexible Iteration:** Create custom iteration patterns beyond standard loop behavior
+5. **Paired Output:** Output elements in pairs or groups
+
+## How isnext Works
+
+### Behavior
+
+- **Advances Iterator:** Moves the iterator forward to the next element
+- **Continues Processing:** Execution continues with the next line of code (does NOT jump back to loop start)
+- **Inner Loop Only:** Only affects the iterator of the innermost loop
+- **Termination:** If iterator reaches its last element or is empty, the loop terminates instantly
+
+### Key Difference from iscontinue
+
+| Element | Iterator Movement | Code Execution |
+|---------|------------------|----------------|
+| `<isnext>` | Moves forward one position | Continues with next line of code |
+| `<iscontinue>` | Moves forward one position | Jumps back to top of loop (skips remaining code) |
+
+## Rules of Use
+
+### Loop Requirement
+
+⚠️ **CRITICAL:** `<isnext/>` can **only be used within** an `<isloop>...</isloop>` loop structure.
+
+```isml
+<!-- Good: Inside a loop -->
+<isloop items="${products}" var="product">
+  <isprint value="${product.name}"/>
+  <isnext/>
+  <isprint value="${product.name}"/>
+</isloop>
+
+<!-- Bad: Outside a loop -->
+<isif condition="${someCondition}">
+  <isnext/>  <!-- ERROR: Not in a loop -->
+</isif>
+```
+
+### Inner Loop Only
+
+In nested loops, `<isnext/>` only affects the **innermost loop**:
+
+```isml
+<isloop items="${categories}" var="category">
+  <h2>${category.name}</h2>
+  
+  <isloop items="${category.products}" var="product">
+    <isprint value="${product.name}"/>
+    <isnext/>  <!-- Only affects product loop, not category loop -->
+    <isprint value="${product.name}"/>
+  </isloop>
+</isloop>
+```
+
+### Automatic Loop Termination
+
+If the iterator has reached its last element or is empty when `<isnext/>` is processed, **the loop terminates instantly**:
+
+```isml
+<isloop items="${products}" var="product">
+  <isprint value="${product.name}"/>
+  <isnext/>  <!-- If product is last item, loop terminates here -->
+  <isprint value="${product.name}"/>  <!-- This won't execute for last item -->
+</isloop>
+```
+
+## Common Use Cases
+
+### Paired Output (Official Example)
+
+Output two products per iteration:
+
+```isml
+<isloop items="${pdict.Products}" var="product">
+  <isprint value="${product.name}"/>
+  <isnext/>
+  <isprint value="${product.name}"/> <br/>
+</isloop>
+```
+
+**How it works:**
+1. First iteration: Prints product[0], advances to product[1], prints product[1]
+2. Second iteration: Prints product[2], advances to product[3], prints product[3]
+3. Continues pairing elements until end of list
+
+**Output example:**
+```
+Product A Product B
+Product C Product D
+Product E Product F
+```
+
+### Two-Column Layout
+
+Create a two-column product grid:
+
+```isml
+<div class="product-grid">
+  <isloop items="${pdict.products}" var="product">
+    <div class="product-row">
+      <div class="product-column">
+        <h3>${product.name}</h3>
+        <img src="${product.images.small[0].url}" alt="${product.name}"/>
+      </div>
+      
+      <isnext/>
+      
+      <div class="product-column">
+        <h3>${product.name}</h3>
+        <img src="${product.images.small[0].url}" alt="${product.name}"/>
+      </div>
+    </div>
+  </isloop>
+</div>
+```
+
+**Result:** Products displayed in pairs, two per row.
+
+### Comparison Display
+
+Display products side-by-side for comparison:
+
+```isml
+<div class="comparison-table">
+  <isloop items="${pdict.compareProducts}" var="product">
+    <div class="comparison-item">
+      <h3>${product.name}</h3>
+      <div class="price">${product.price}</div>
+      <div class="rating">${product.rating}</div>
+    </div>
+    
+    <isnext/>
+    
+    <div class="comparison-item">
+      <h3>${product.name}</h3>
+      <div class="price">${product.price}</div>
+      <div class="rating">${product.rating}</div>
+    </div>
+  </isloop>
+</div>
+```
+
+### Before/After Pairs
+
+Display before and after images or states:
+
+```isml
+<div class="before-after-gallery">
+  <isloop items="${pdict.images}" var="image">
+    <div class="comparison-set">
+      <div class="before">
+        <h4>Before</h4>
+        <img src="${image.url}" alt="Before"/>
+      </div>
+      
+      <isnext/>
+      
+      <div class="after">
+        <h4>After</h4>
+        <img src="${image.url}" alt="After"/>
+      </div>
+    </div>
+  </isloop>
+</div>
+```
+
+### Skip Specific Elements
+
+Skip certain elements and continue processing:
+
+```isml
+<isloop items="${pdict.products}" var="product">
+  <isif condition="${product.custom.hideFromList}">
+    <isnext/>  <!-- Skip this product and move to next -->
+  </isif>
+  
+  <div class="product-tile">
+    ${product.name}
+  </div>
+</isloop>
+```
+
+**Note:** For this use case, `<iscontinue/>` would be more appropriate as it's clearer in intent.
+
+### Grouped Output
+
+Output products in groups of three:
+
+```isml
+<isloop items="${pdict.products}" var="product">
+  <div class="product-group">
+    <div class="product-1">${product.name}</div>
+    
+    <isnext/>
+    <div class="product-2">${product.name}</div>
+    
+    <isnext/>
+    <div class="product-3">${product.name}</div>
+  </div>
+</isloop>
+```
+
+**Output:** Products grouped in sets of three per container.
+
+### Q&A Pairs
+
+Display question and answer pairs:
+
+```isml
+<div class="faq-list">
+  <isloop items="${pdict.faqItems}" var="item">
+    <div class="faq-item">
+      <div class="question">
+        <strong>Q:</strong> ${item.text}
+      </div>
+      
+      <isnext/>
+      
+      <div class="answer">
+        <strong>A:</strong> ${item.text}
+      </div>
+    </div>
+  </isloop>
+</div>
+```
+
+### Dual Language Display
+
+Show content in two languages side-by-side:
+
+```isml
+<div class="bilingual-content">
+  <isloop items="${pdict.contentBlocks}" var="block">
+    <div class="content-pair">
+      <div class="language-primary">
+        <h3>${block.title}</h3>
+        <p>${block.body}</p>
+      </div>
+      
+      <isnext/>
+      
+      <div class="language-secondary">
+        <h3>${block.title}</h3>
+        <p>${block.body}</p>
+      </div>
+    </div>
+  </isloop>
+</div>
+```
+
+## Difference from iscontinue
+
+### Visual Comparison
+
+```isml
+<!-- Using isnext: Advances and continues processing -->
+<isloop items="${products}" var="product">
+  <isprint value="${product.name}"/>
+  
+  <isif condition="${product.price > 100}">
+    <isnext/>  <!-- Moves to next product, continues below -->
+  </isif>
+  
+  <!-- This code WILL execute after isnext -->
+  <div class="product-footer">Processed</div>
+</isloop>
+
+<!-- Using iscontinue: Advances and jumps to loop start -->
+<isloop items="${products}" var="product">
+  <isprint value="${product.name}"/>
+  
+  <isif condition="${product.price > 100}">
+    <iscontinue/>  <!-- Moves to next product, jumps to loop start -->
+  </isif>
+  
+  <!-- This code WILL NOT execute after iscontinue -->
+  <div class="product-footer">Processed</div>
+</isloop>
+```
+
+### Execution Flow Diagram
+
+**isnext flow:**
+```
+Loop Start
+  ↓
+Code before isnext
+  ↓
+<isnext/> (iterator advances)
+  ↓
+Code after isnext (EXECUTES)
+  ↓
+Loop End → Back to Loop Start
+```
+
+**iscontinue flow:**
+```
+Loop Start
+  ↓
+Code before iscontinue
+  ↓
+<iscontinue/> (iterator advances)
+  ↓
+Back to Loop Start (code after iscontinue SKIPPED)
+```
+
+### When to Use Which
+
+**Use `<isnext/>`:**
+- Process multiple elements in single iteration
+- Create paired/grouped outputs
+- Advance iterator but continue processing subsequent code
+- Build custom iteration patterns
+
+**Use `<iscontinue/>`:**
+- Skip current item and jump to next iteration
+- Filter items from loop output
+- Early exit from current iteration
+- Standard skip/filter behavior
+
+```isml
+<!-- isnext: Process two products together -->
+<isloop items="${products}" var="product">
+  <div class="pair">
+    <div>${product.name}</div>
+    <isnext/>
+    <div>${product.name}</div>
+  </div>
+</isloop>
+
+<!-- iscontinue: Skip unavailable products -->
+<isloop items="${products}" var="product">
+  <isif condition="${!product.available}">
+    <iscontinue/>
+  </isif>
+  <div>${product.name}</div>
+</isloop>
+```
+
+## Edge Cases and Gotchas
+
+### Last Element Behavior
+
+When `<isnext/>` is called on the last element, the loop terminates immediately:
+
+```isml
+<isloop items="${products}" var="product">
+  <div>Product: ${product.name}</div>
+  <isnext/>
+  <div>Next: ${product.name}</div>  <!-- Not executed if first product was last -->
+</isloop>
+```
+
+**With 3 products:**
+1. Iteration 1: Shows product[0], advances, shows product[1]
+2. Iteration 2: Shows product[2], advances → **loop terminates** (no product[3])
+
+**Result:** Product[2] appears only once (not paired).
+
+### Empty Iterator
+
+If the iterator is empty when `<isnext/>` is processed, loop terminates:
+
+```isml
+<isloop items="${emptyArray}" var="item">
+  <div>This won't display</div>
+  <isnext/>  <!-- Loop terminates immediately -->
+  <div>Neither will this</div>
+</isloop>
+```
+
+### Nested Loops
+
+`<isnext/>` only affects the innermost loop:
+
+```isml
+<isloop items="${categories}" var="category">
+  <h2>${category.name}</h2>
+  
+  <isloop items="${category.products}" var="product">
+    <div>${product.name}</div>
+    <isnext/>  <!-- Advances product iterator only -->
+    <div>${product.name}</div>
+  </isloop>
+  
+  <!-- category iterator not affected -->
+</isloop>
+```
+
+### Odd Number of Elements
+
+With paired output, odd-numbered lists will have unpaired last element:
+
+```isml
+<!-- 5 products: A, B, C, D, E -->
+<isloop items="${products}" var="product">
+  <div class="pair">
+    <span>${product.name}</span>
+    <isnext/>
+    <span>${product.name}</span>
+  </div>
+</isloop>
+
+<!-- Output:
+  Pair 1: A B
+  Pair 2: C D
+  Pair 3: E (alone, loop terminates after isnext)
+-->
+```
+
+**Solution:** Handle odd case explicitly:
+
+```isml
+<isloop items="${products}" var="product" status="loopStatus">
+  <div class="pair">
+    <span>${product.name}</span>
+    
+    <isif condition="${!loopStatus.last}">
+      <isnext/>
+      <span>${product.name}</span>
+    </isif>
+  </div>
+</isloop>
+```
+
+## Best Practices
+
+### Document Non-Standard Iteration
+
+```isml
+<iscomment>
+  This loop processes products in pairs for side-by-side comparison display.
+  Uses isnext to advance iterator within iteration.
+</iscomment>
+<isloop items="${products}" var="product">
+  <div class="comparison">
+    <div class="left">${product.name}</div>
+    <isnext/>
+    <div class="right">${product.name}</div>
+  </div>
+</isloop>
+```
+
+### Handle Odd-Numbered Collections
+
+```isml
+<isloop items="${products}" var="product" status="status">
+  <div class="product-pair">
+    <div class="product-left">${product.name}</div>
+    
+    <!-- Check if not last element before isnext -->
+    <isif condition="${!status.last}">
+      <isnext/>
+      <div class="product-right">${product.name}</div>
+    <iselse>
+      <div class="product-right empty"><!-- Placeholder --></div>
+    </isif>
+  </div>
+</isloop>
+```
+
+### Use Status Object for Safe Iteration
+
+```isml
+<isloop items="${products}" var="product" status="loopStatus">
+  <div class="item">${product.name}</div>
+  
+  <!-- Safe: Check if there's a next element -->
+  <isif condition="${loopStatus.index + 1 < loopStatus.count}">
+    <isnext/>
+    <div class="item">${product.name}</div>
+  </isif>
+</isloop>
+```
+
+### Prefer iscontinue for Simple Filtering
+
+```isml
+<!-- Less clear: Using isnext to skip -->
+<isloop items="${products}" var="product">
+  <isif condition="${!product.available}">
+    <isnext/>
+    <!-- What happens here? -->
+  </isif>
+  <div>${product.name}</div>
+</isloop>
+
+<!-- Better: Using iscontinue for filtering -->
+<isloop items="${products}" var="product">
+  <isif condition="${!product.available}">
+    <iscontinue/>
+  </isif>
+  <div>${product.name}</div>
+</isloop>
+```
+
+### Avoid Complex Logic with isnext
+
+```isml
+<!-- Avoid: Complex logic makes behavior unclear -->
+<isloop items="${items}" var="item">
+  <isif condition="${condition1}">
+    <div>Thing 1</div>
+    <isnext/>
+    <isif condition="${condition2}">
+      <div>Thing 2</div>
+      <isnext/>
+      <div>Thing 3</div>
+    </isif>
+  </isif>
+</isloop>
+
+<!-- Better: Simplify or restructure -->
+<isloop items="${items}" var="item" begin="0" step="2">
+  <div>${item.name}</div>
+  <div>${items[loopStatus.index + 1].name}</div>
+</isloop>
+```
+
+## Performance Considerations
+
+### Iterator Access
+
+`<isnext/>` advances the iterator in-place, which is efficient:
+
+```isml
+<!-- Efficient: isnext advances iterator directly -->
+<isloop items="${products}" var="product">
+  <div>${product.name}</div>
+  <isnext/>
+  <div>${product.name}</div>
+</isloop>
+
+<!-- Less efficient: Manual index tracking -->
+<isloop items="${products}" var="product" status="status">
+  <div>${product.name}</div>
+  <isif condition="${status.index + 1 < products.length}">
+    <div>${products[status.index + 1].name}</div>
+  </isif>
+</isloop>
+```
+
+### Loop Step Alternative
+
+For evenly-spaced iteration, consider using `step` attribute:
+
+```isml
+<!-- Using isnext for pairs -->
+<isloop items="${products}" var="product">
+  <div>${product.name}</div>
+  <isnext/>
+  <div>${product.name}</div>
+</isloop>
+
+<!-- Alternative: Using step (if just iterating pairs) -->
+<isloop items="${products}" var="product" step="2">
+  <div>${product.name}</div>
+  <div>${products[loopStatus.index + 1].name}</div>
+</isloop>
+```
+
+## Troubleshooting
+
+### Unexpected Loop Termination
+
+**Problem:** Loop terminates before processing all items.
+
+**Solution:** Check if `<isnext/>` is advancing beyond the last element:
+
+```isml
+<!-- Problem: Last element causes early termination -->
+<isloop items="${products}" var="product">
+  <div>${product.name}</div>
+  <isnext/>  <!-- Terminates on last element -->
+  <div>${product.name}</div>
+</isloop>
+
+<!-- Solution: Check for last element -->
+<isloop items="${products}" var="product" status="status">
+  <div>${product.name}</div>
+  <isif condition="${!status.last}">
+    <isnext/>
+    <div>${product.name}</div>
+  </isif>
+</isloop>
+```
+
+### Code Not Executing After isnext
+
+**Problem:** Expected code after `<isnext/>` doesn't execute.
+
+**Solution:** Remember `<isnext/>` terminates loop if at last element:
+
+```isml
+<!-- This code won't execute if isnext reaches end -->
+<isloop items="${products}" var="product">
+  <isnext/>
+  <div>${product.name}</div>  <!-- May not execute -->
+</isloop>
+
+<!-- Check iterator position first -->
+<isloop items="${products}" var="product" status="status">
+  <isif condition="${status.index + 1 < status.count}">
+    <isnext/>
+    <div>${product.name}</div>
+  </isif>
+</isloop>
+```
+
+### Using Outside Loop
+
+**Problem:** Error when using `<isnext/>` outside loop.
+
+**Solution:** Ensure `<isnext/>` is always inside `<isloop>`:
+
+```isml
+<!-- Wrong: Outside loop -->
+<isnext/>  <!-- ERROR -->
+
+<!-- Correct: Inside loop -->
+<isloop items="${items}" var="item">
+  <isnext/>  <!-- OK -->
+</isloop>
+```
+
+## Related Elements
+
+- **`<isloop>`**: Loop structure that contains `<isnext>`
+- **`<iscontinue>`**: Skips to next iteration (different behavior than `<isnext>`)
+- **`<isbreak>`**: Exits loop entirely
+- **`<isif>`**: Conditional statements often used with `<isnext>`
+
+## Summary
+
+The `<isnext>` element is useful for:
+
+- ✅ Processing multiple elements in single iteration
+- ✅ Creating paired or grouped output (two-column layouts, comparisons)
+- ✅ Advancing iterator while continuing code execution
+- ✅ Building custom iteration patterns
+- ✅ Side-by-side displays (before/after, Q&A, bilingual content)
+- ✅ Efficient iterator advancement without manual index tracking
+
+**Key Distinction:** `<isnext/>` advances the iterator and **continues processing** subsequent code, unlike `<iscontinue/>` which **jumps back** to the loop start.
+
+Use `<isnext>` when you need to process multiple elements together in a single iteration, but be mindful of loop termination when reaching the last element.