sfcc-dev-mcp 1.0.15 → 1.0.19

package/dist/docs/isml/isbreak.md

@@ -0,0 +1,687 @@
+# ISML isbreak Element
+
+## Overview
+
+The `<isbreak>` element unconditionally terminates loop execution in ISML templates. It provides flow control to exit loops early when a specific condition is met, similar to the `break` statement in JavaScript, Java, and other programming languages. When used in nested loops, it only terminates the innermost loop in which it appears.
+
+## Syntax
+
+```isml
+<isbreak/>
+```
+
+## Attributes
+
+**None** - This is a self-closing tag with no attributes.
+
+## Purpose
+
+The `<isbreak>` element serves to:
+
+1. **Early Loop Termination:** Exit a loop before iterating through all items
+2. **Performance Optimization:** Stop processing when desired result is found
+3. **Conditional Exit:** Combine with `<isif>` to exit based on conditions
+4. **Limit Results:** Display only a specific number of items from a collection
+5. **Error Prevention:** Exit loop when invalid state is detected
+
+### Scope
+
+- **Works within:** `<isloop>` elements
+- **Terminates:** Only the innermost loop containing the `<isbreak>`
+- **Does not affect:** Outer loops in nested loop structures
+
+## Common Use Cases
+
+### Limit Number of Items Displayed
+
+```isml
+<!-- Display only the first 3 products -->
+<isloop items="${pdict.products}" var="product" status="loopStatus">
+    <div class="product">
+        <h3>${product.name}</h3>
+        <p>${product.price}</p>
+    </div>
+    
+    <isif condition="${loopStatus.count >= 3}">
+        <isbreak/>
+    </isif>
+</isloop>
+```
+
+### Exit When Condition is Met
+
+```isml
+<!-- Find the first available product and stop -->
+<isloop items="${pdict.products}" var="product">
+    <isif condition="${product.available && product.inStock}">
+        <div class="first-available">
+            <h3>Featured: ${product.name}</h3>
+            <p>In Stock Now!</p>
+        </div>
+        <isbreak/>
+    </isif>
+</isloop>
+```
+
+### Prevent Excessive Processing
+
+```isml
+<!-- Process up to 10 items to prevent performance issues -->
+<isloop items="${pdict.searchResults}" var="result" status="status">
+    <div class="search-result">
+        ${result.name}
+    </div>
+    
+    <isif condition="${status.count >= 10}">
+        <div class="more-results">
+            <a href="${URLUtils.url('Search-ShowMore')}">View All Results</a>
+        </div>
+        <isbreak/>
+    </isif>
+</isloop>
+```
+
+### Error Detection and Exit
+
+```isml
+<!-- Exit loop if invalid data is encountered -->
+<isloop items="${pdict.orderItems}" var="item" status="status">
+    <isif condition="${!item.product || !item.quantity}">
+        <div class="error">Invalid order item detected</div>
+        <isbreak/>
+    </isif>
+    
+    <div class="order-item">
+        <span>${item.product.name}</span>
+        <span>Qty: ${item.quantity}</span>
+    </div>
+</isloop>
+```
+
+### Display "Top N" Items
+
+```isml
+<!-- Show top 5 best sellers -->
+<h2>Top 5 Best Sellers</h2>
+<ol class="bestsellers">
+    <isloop items="${pdict.bestSellers}" var="product" status="loop">
+        <li>
+            <a href="${URLUtils.url('Product-Show', 'pid', product.ID)}">
+                ${product.name}
+            </a>
+        </li>
+        
+        <isif condition="${loop.count >= 5}">
+            <isbreak/>
+        </isif>
+    </isloop>
+</ol>
+```
+
+### Category Navigation Limit
+
+```isml
+<!-- Show first 8 categories, then "More" link -->
+<ul class="category-nav">
+    <isloop items="${pdict.categories}" var="category" status="catStatus">
+        <li>
+            <a href="${URLUtils.url('Search-Show', 'cgid', category.ID)}">
+                ${category.displayName}
+            </a>
+        </li>
+        
+        <isif condition="${catStatus.count >= 8}">
+            <li class="more-categories">
+                <a href="${URLUtils.url('Category-ShowAll')}">More Categories...</a>
+            </li>
+            <isbreak/>
+        </isif>
+    </isloop>
+</ul>
+```
+
+### Search and Stop
+
+```isml
+<!-- Find specific item and exit -->
+<isset name="targetFound" value="${false}" scope="page" />
+
+<isloop items="${pdict.products}" var="product">
+    <isif condition="${product.ID == pdict.searchPID}">
+        <div class="found-product">
+            <h3>Found: ${product.name}</h3>
+            <p>Price: ${product.price}</p>
+        </div>
+        <isset name="targetFound" value="${true}" scope="page" />
+        <isbreak/>
+    </isif>
+</isloop>
+
+<isif condition="${!targetFound}">
+    <p>Product not found in current results</p>
+</isif>
+```
+
+## Nested Loops
+
+### Inner Loop Break Only
+
+```isml
+<!-- isbreak only terminates the inner loop -->
+<isloop items="${pdict.categories}" var="category" status="outerLoop">
+    <h3>${category.displayName}</h3>
+    <ul>
+        <isloop items="${category.products}" var="product" status="innerLoop">
+            <li>${product.name}</li>
+            
+            <!-- This breaks only the inner loop (products) -->
+            <isif condition="${innerLoop.count >= 5}">
+                <isbreak/>
+            </isif>
+        </isloop>
+    </ul>
+    <!-- Outer loop continues here -->
+</isloop>
+```
+
+### Breaking Both Inner and Outer Loops
+
+```isml
+<!-- Use a flag to break outer loop -->
+<isset name="shouldBreak" value="${false}" scope="page" />
+
+<isloop items="${pdict.categories}" var="category" status="outerLoop">
+    <h3>${category.displayName}</h3>
+    
+    <isloop items="${category.products}" var="product" status="innerLoop">
+        <isif condition="${product.specialCondition}">
+            <isset name="shouldBreak" value="${true}" scope="page" />
+            <isbreak/>
+        </isif>
+        
+        <div>${product.name}</div>
+    </isloop>
+    
+    <!-- Check flag and break outer loop -->
+    <isif condition="${shouldBreak}">
+        <isbreak/>
+    </isif>
+</isloop>
+```
+
+### Multiple Nested Levels
+
+```isml
+<!-- Three levels of nesting -->
+<isloop items="${pdict.departments}" var="dept">
+    <h2>${dept.name}</h2>
+    
+    <isloop items="${dept.categories}" var="category" status="catLoop">
+        <h3>${category.name}</h3>
+        
+        <isloop items="${category.products}" var="product" status="prodLoop">
+            <p>${product.name}</p>
+            
+            <!-- Breaks only the product loop -->
+            <isif condition="${prodLoop.count >= 3}">
+                <isbreak/>
+            </isif>
+        </isloop>
+        
+        <!-- Breaks only the category loop -->
+        <isif condition="${catLoop.count >= 5}">
+            <isbreak/>
+        </isif>
+    </isloop>
+</isloop>
+```
+
+## Best Practices
+
+1. **Always Use with Conditions:**
+   ```isml
+   <!-- Good: Conditional break -->
+   <isloop items="${products}" var="product" status="loop">
+       <isif condition="${loop.count >= 10}">
+           <isbreak/>
+       </isif>
+       ${product.name}
+   </isloop>
+   
+   <!-- Bad: Unconditional break (pointless) -->
+   <isloop items="${products}" var="product">
+       ${product.name}
+       <isbreak/>  <!-- Will always break after first item -->
+   </isloop>
+   ```
+
+2. **Use Loop Status for Counting:**
+   ```isml
+   <!-- Good: Use status.count -->
+   <isloop items="${products}" var="product" status="status">
+       <isif condition="${status.count >= 5}">
+           <isbreak/>
+       </isif>
+       ${product.name}
+   </isloop>
+   
+   <!-- Avoid: Manual counter (unnecessary) -->
+   <isset name="counter" value="${0}" scope="page" />
+   <isloop items="${products}" var="product">
+       <isset name="counter" value="${counter + 1}" scope="page" />
+       <isif condition="${counter >= 5}">
+           <isbreak/>
+       </isif>
+       ${product.name}
+   </isloop>
+   ```
+
+3. **Consider Using begin/end Instead:**
+   ```isml
+   <!-- Using isbreak -->
+   <isloop items="${products}" var="product" status="loop">
+       <div>${product.name}</div>
+       <isif condition="${loop.count >= 5}">
+           <isbreak/>
+       </isif>
+   </isloop>
+   
+   <!-- Better: Use end attribute -->
+   <isloop items="${products}" var="product" end="4">
+       <div>${product.name}</div>
+   </isloop>
+   ```
+
+4. **Provide User Feedback:**
+   ```isml
+   <!-- Good: Show there are more items -->
+   <isloop items="${products}" var="product" status="loop">
+       <div>${product.name}</div>
+       <isif condition="${loop.count >= 10}">
+           <div class="more-items-indicator">
+               <a href="${URLUtils.url('Product-ShowAll')}">
+                   View All ${products.length} Products
+               </a>
+           </div>
+           <isbreak/>
+       </isif>
+   </isloop>
+   ```
+
+5. **Use Meaningful Conditions:**
+   ```isml
+   <!-- Good: Clear intent -->
+   <isloop items="${products}" var="product" status="loop">
+       <isif condition="${loop.count >= pdict.maxDisplayItems}">
+           <isbreak/>
+       </isif>
+       ${product.name}
+   </isloop>
+   
+   <!-- Less clear: Magic number -->
+   <isloop items="${products}" var="product" status="loop">
+       <isif condition="${loop.count >= 7}">
+           <isbreak/>
+       </isif>
+       ${product.name}
+   </isloop>
+   ```
+
+6. **Document Complex Break Logic:**
+   ```isml
+   <!-- Break early for performance on large datasets -->
+   <isloop items="${pdict.searchResults}" var="result" status="status">
+       <div class="result">${result.name}</div>
+       
+       <!-- Limit to 20 results to maintain page performance -->
+       <isif condition="${status.count >= 20}">
+           <div class="pagination-link">
+               <a href="${URLUtils.url('Search-Show', 'start', 20)}">Next Page</a>
+           </div>
+           <isbreak/>
+       </isif>
+   </isloop>
+   ```
+
+7. **Handle Edge Cases:**
+   ```isml
+   <!-- Check if collection exists and has items -->
+   <isif condition="${pdict.products && pdict.products.length > 0}">
+       <isloop items="${pdict.products}" var="product" status="loop">
+           <div>${product.name}</div>
+           
+           <isif condition="${loop.count >= 5}">
+               <isbreak/>
+           </isif>
+       </isloop>
+   <iselse>
+       <p>No products available</p>
+   </isif>
+   ```
+
+## Performance Considerations
+
+### When to Use isbreak for Performance
+
+```isml
+<!-- Good: Large collection, need only first few items -->
+<isloop items="${pdict.allProducts}" var="product" status="loop">
+    <div>${product.name}</div>
+    
+    <!-- Stop after 10 to avoid processing thousands of items -->
+    <isif condition="${loop.count >= 10}">
+        <isbreak/>
+    </isif>
+</isloop>
+```
+
+### When begin/end is Better
+
+```isml
+<!-- Better: Use begin/end for simple range -->
+<isloop items="${pdict.products}" var="product" begin="0" end="9">
+    <div>${product.name}</div>
+</isloop>
+
+<!-- Instead of: -->
+<isloop items="${pdict.products}" var="product" status="loop">
+    <div>${product.name}</div>
+    <isif condition="${loop.count >= 10}">
+        <isbreak/>
+    </isif>
+</isloop>
+```
+
+### Avoid Unnecessary Processing
+
+```isml
+<!-- Good: Break immediately when found -->
+<isloop items="${products}" var="product">
+    <isif condition="${product.ID == targetID}">
+        <isset name="foundProduct" value="${product}" scope="page" />
+        <isbreak/>
+    </isif>
+</isloop>
+
+<!-- Bad: Process all items even after finding target -->
+<isloop items="${products}" var="product">
+    <isif condition="${product.ID == targetID}">
+        <isset name="foundProduct" value="${product}" scope="page" />
+    </isif>
+</isloop>
+```
+
+## Common Patterns
+
+### Pagination Preview
+
+```isml
+<!-- Show first page of results with "More" link -->
+<div class="search-results">
+    <isloop items="${pdict.searchResults}" var="result" status="loop">
+        <div class="result-item">
+            <h4>${result.name}</h4>
+            <p>${result.description}</p>
+        </div>
+        
+        <isif condition="${loop.count >= pdict.resultsPerPage}">
+            <isif condition="${pdict.searchResults.length > pdict.resultsPerPage}">
+                <div class="more-results">
+                    <a href="${URLUtils.url('Search-Show', 'showAll', 'true')}">
+                        View All ${pdict.searchResults.length} Results
+                    </a>
+                </div>
+            </isif>
+            <isbreak/>
+        </isif>
+    </isloop>
+</div>
+```
+
+### Featured Items Section
+
+```isml
+<!-- Show featured items until section is full -->
+<div class="featured-products">
+    <h2>Featured Products</h2>
+    <div class="product-grid">
+        <isloop items="${pdict.products}" var="product" status="loop">
+            <isif condition="${product.featured}">
+                <div class="featured-product-tile">
+                    <img src="${product.imageURL}" alt="${product.name}" />
+                    <h3>${product.name}</h3>
+                    <span>${product.price}</span>
+                </div>
+                
+                <!-- Stop after 4 featured products -->
+                <isif condition="${loop.count >= 4}">
+                    <isbreak/>
+                </isif>
+            </isif>
+        </isloop>
+    </div>
+</div>
+```
+
+### Carousel with Limit
+
+```isml
+<!-- Carousel showing limited items -->
+<div class="product-carousel">
+    <isloop items="${pdict.recommendedProducts}" var="product" status="carouselLoop">
+        <div class="carousel-item">
+            <a href="${URLUtils.url('Product-Show', 'pid', product.ID)}">
+                <img src="${product.images.small[0].url}" alt="${product.name}" />
+                <p>${product.name}</p>
+            </a>
+        </div>
+        
+        <!-- Carousel shows max 6 items -->
+        <isif condition="${carouselLoop.count >= 6}">
+            <isbreak/>
+        </isif>
+    </isloop>
+</div>
+```
+
+### Conditional Data Processing
+
+```isml
+<!-- Process until specific condition met -->
+<isset name="totalPrice" value="${0}" scope="page" />
+<isset name="budgetExceeded" value="${false}" scope="page" />
+
+<isloop items="${pdict.cart.items}" var="item" status="itemLoop">
+    <isset name="totalPrice" value="${totalPrice + item.price}" scope="page" />
+    
+    <div class="cart-item">
+        <span>${item.name}</span>
+        <span>${item.price}</span>
+    </div>
+    
+    <!-- Stop if budget limit reached -->
+    <isif condition="${totalPrice > pdict.budgetLimit}">
+        <div class="budget-warning">Budget limit reached</div>
+        <isset name="budgetExceeded" value="${true}" scope="page" />
+        <isbreak/>
+    </isif>
+</isloop>
+```
+
+## Comparison with Alternatives
+
+### isbreak vs end attribute
+
+```isml
+<!-- Using isbreak (dynamic condition) -->
+<isloop items="${products}" var="product" status="loop">
+    <div>${product.name}</div>
+    <isif condition="${product.price > 1000}">
+        <isbreak/>  <!-- Stop at first expensive item -->
+    </isif>
+</isloop>
+
+<!-- Using end attribute (fixed range) -->
+<isloop items="${products}" var="product" end="9">
+    <div>${product.name}</div>  <!-- Always shows first 10 -->
+</isloop>
+```
+
+**Use `<isbreak>` when:**
+- Breaking condition is dynamic
+- Exit depends on item properties
+- Condition is complex
+
+**Use `end` attribute when:**
+- Fixed number of items needed
+- Simpler and more readable
+- No conditional logic required
+
+### isbreak vs isnext
+
+```isml
+<!-- isbreak: Exit loop completely -->
+<isloop items="${products}" var="product" status="loop">
+    <div>${product.name}</div>
+    <isif condition="${loop.count >= 5}">
+        <isbreak/>  <!-- Stop loop entirely -->
+    </isif>
+</isloop>
+
+<!-- isnext: Skip current iteration, continue loop -->
+<isloop items="${products}" var="product">
+    <isif condition="${!product.available}">
+        <isnext/>  <!-- Skip unavailable, continue with next -->
+    </isif>
+    <div>${product.name}</div>
+</isloop>
+```
+
+**Use `<isbreak>` to:**
+- Exit loop completely
+- Stop all further processing
+
+**Use `<isnext>` to:**
+- Skip current item
+- Continue with remaining items
+
+## Debugging and Testing
+
+### Add Debug Output
+
+```isml
+<!-- Debug: Show when break occurs -->
+<isloop items="${products}" var="product" status="loop">
+    <div>${product.name}</div>
+    
+    <isif condition="${loop.count >= 10}">
+        <!-- Debug output (remove in production) -->
+        <iscomment>
+            Breaking loop at count: ${loop.count}
+            Total items: ${products.length}
+        </iscomment>
+        <isbreak/>
+    </isif>
+</isloop>
+```
+
+### Validate Break Conditions
+
+```isml
+<!-- Ensure break condition is valid -->
+<isif condition="${pdict.maxItems && pdict.maxItems > 0}">
+    <isloop items="${products}" var="product" status="loop">
+        <div>${product.name}</div>
+        
+        <isif condition="${loop.count >= pdict.maxItems}">
+            <isbreak/>
+        </isif>
+    </isloop>
+<iselse>
+    <!-- Fallback: show all items -->
+    <isloop items="${products}" var="product">
+        <div>${product.name}</div>
+    </isloop>
+</isif>
+```
+
+## Related Elements
+
+- `<isloop>` - Creates the loop that `<isbreak>` terminates
+- `<isnext>` - Skips to next iteration instead of breaking
+- `<isif>` - Provides conditional logic for break decisions
+- `<isset>` - Sets flags for break conditions
+
+## Notes
+
+- `<isbreak>` is a self-closing tag with no attributes
+- Must be used within an `<isloop>` element
+- In nested loops, only breaks the innermost loop
+- Always used with `<isif>` for conditional breaking
+- Has no visible output; only affects loop control
+- Consider using `end` attribute for simple fixed ranges
+- Use `<isnext>` to skip items instead of breaking
+- Performance benefit when processing large collections
+- Useful for "show first N items" patterns
+
+## Error Prevention
+
+### Check Loop Context
+
+```isml
+<!-- Bad: isbreak outside of loop (error) -->
+<div>Some content</div>
+<isbreak/>  <!-- ERROR: Not in a loop -->
+
+<!-- Good: isbreak inside loop -->
+<isloop items="${products}" var="product">
+    <div>${product.name}</div>
+    <isif condition="${condition}">
+        <isbreak/>
+    </isif>
+</isloop>
+```
+
+### Validate Conditions
+
+```isml
+<!-- Bad: Condition might be undefined -->
+<isloop items="${products}" var="product" status="loop">
+    <isif condition="${loop.count >= maxItems}">
+        <isbreak/>
+    </isif>
+    <div>${product.name}</div>
+</isloop>
+
+<!-- Good: Validate condition exists -->
+<isloop items="${products}" var="product" status="loop">
+    <isif condition="${!empty(maxItems) && loop.count >= maxItems}">
+        <isbreak/>
+    </isif>
+    <div>${product.name}</div>
+</isloop>
+```
+
+## Migration Notes
+
+### SiteGenesis to SFRA
+
+```isml
+<!-- SiteGenesis -->
+<isloop iterator="${pdict.Basket.products}" alias="product" status="status">
+    <isif condition="${status.count >= 3}">
+        <isbreak/>
+    </isif>
+    ${product.name}
+</isloop>
+
+<!-- SFRA (same syntax, updated attributes) -->
+<isloop items="${pdict.cart.items}" var="item" status="status">
+    <isif condition="${status.count >= 3}">
+        <isbreak/>
+    </isif>
+    ${item.productName}
+</isloop>
+```
+
+The `<isbreak>` syntax remains the same; only loop attributes and data structure change.