sfcc-dev-mcp 1.0.19 → 1.0.21

package/docs/isml/iscomment.md

@@ -1,794 +0,0 @@
-# ISML iscomment Element
-
-## Overview
-
-The `<iscomment>` element allows you to add documentation, reminders, and instructions within ISML templates that are completely removed during template processing. Unlike HTML comments, content within `<iscomment>` tags is never sent to the browser and cannot be viewed in page source, making it ideal for internal documentation, sensitive notes, and developer comments that should remain private.
-
-**Key Difference from HTML Comments:** `<iscomment>` content is stripped during server-side processing; HTML comments (`<!-- -->`) are sent to the browser and visible in page source.
-
-## Syntax
-
-```isml
-<iscomment>
-  ... your comments here ...
-</iscomment>
-```
-
-### Deprecated Syntax
-
-⚠️ **DEPRECATED (since March 6, 2009):**
-```isml
-<!---  your comments here  --->
-```
-
-**Note:** While this deprecated syntax doesn't cause failures, the standard `<iscomment>` syntax is strongly recommended.
-
-## Attributes
-
-**None** - This element has no attributes.
-
-## Purpose
-
-The `<iscomment>` element serves several critical purposes:
-
-1. **Internal Documentation:** Document template logic, business rules, and implementation details
-2. **Developer Notes:** Leave reminders and instructions for yourself and team members
-3. **Confidentiality:** Hide sensitive information that should never reach the browser
-4. **Code Organization:** Add section headers and explanatory notes
-5. **Debugging Aids:** Temporarily comment out code or add debug notes
-6. **Maintenance Instructions:** Document why specific code exists and how to maintain it
-
-### Processing Behavior
-
-**Server-Side Removal:**
-- Content is **not parsed** by the template processor
-- Content **does not appear** in the generated HTML sent to browser
-- Content **cannot be viewed** using "View Source" in browsers
-- No performance impact on client-side rendering
-
-**Security Benefit:** Unlike HTML comments, `<iscomment>` prevents information leakage to end users.
-
-## Comparison: iscomment vs HTML Comments
-
-| Feature | `<iscomment>` | `<!-- HTML Comment -->` |
-|---------|---------------|-------------------------|
-| **Visible in Page Source** | ❌ No | ✅ Yes |
-| **Sent to Browser** | ❌ No | ✅ Yes |
-| **Server-Side Processing** | Removed | Passed through |
-| **Confidentiality** | ✅ High | ❌ None |
-| **Use Case** | Internal docs, sensitive notes | Public documentation, SEO |
-| **Security** | ✅ Safe for internal notes | ⚠️ Never put sensitive data |
-
-```isml
-<!-- HTML comment: visible in page source -->
-<div>This is content</div>
-
-<iscomment>
-ISML comment: NOT visible in page source
-Never sent to browser
-</iscomment>
-```
-
-## Common Use Cases
-
-### Template Documentation
-
-```isml
-<iscomment>
-    Template: product/productDetails.isml
-    Purpose: Display product detail page with pricing, availability, and add-to-cart
-    Author: Development Team
-    Last Updated: 2025-10-03
-    
-    Dependencies:
-    - Product model from controller
-    - URLUtils helper
-    - Product availability service
-</iscomment>
-
-<div class="product-detail">
-    <h1>${pdict.Product.name}</h1>
-    <!-- Product details -->
-</div>
-```
-
-### Business Logic Explanation
-
-```isml
-<iscomment>
-    Complex pricing logic:
-    1. Start with base price
-    2. Apply customer-specific price book
-    3. Apply active promotions
-    4. Calculate volume discounts
-    5. Apply employee discount if applicable
-    
-    DO NOT change this order - promotions must apply before employee discount
-</iscomment>
-
-<div class="pricing">
-    <span class="price">${pdict.Product.price}</span>
-</div>
-```
-
-### Developer Reminders
-
-```isml
-<iscomment>
-    TODO: Refactor this section to use product factory
-    FIXME: This logic duplicates code in productTile.isml - consolidate
-    NOTE: Be careful with performance - this loops through all variants
-</iscomment>
-
-<isloop items="${pdict.Product.variants}" var="variant">
-    <div>${variant.name}</div>
-</isloop>
-```
-
-### Code Sections and Organization
-
-```isml
-<iscomment>
-    ========================================
-    SECTION: Product Images
-    ========================================
-</iscomment>
-
-<div class="product-images">
-    <!-- Image gallery code -->
-</div>
-
-<iscomment>
-    ========================================
-    SECTION: Product Pricing
-    ========================================
-</iscomment>
-
-<div class="product-pricing">
-    <!-- Pricing code -->
-</div>
-
-<iscomment>
-    ========================================
-    SECTION: Add to Cart
-    ========================================
-</iscomment>
-
-<div class="add-to-cart">
-    <!-- Add to cart code -->
-</div>
-```
-
-### Sensitive Configuration Notes
-
-```isml
-<iscomment>
-    Payment Integration Notes:
-    - Payment processor: XYZ Payments
-    - Merchant ID stored in site preferences
-    - Test mode enabled in sandbox environments
-    - Production credentials in Business Manager
-    
-    IMPORTANT: Never hardcode credentials in templates
-</iscomment>
-
-<div class="payment-options">
-    <!-- Payment integration code -->
-</div>
-```
-
-### Debugging Information
-
-```isml
-<iscomment>
-    Debug info:
-    - pdict.Product type: ${typeof pdict.Product}
-    - Product ID: ${pdict.Product.ID}
-    - Available: ${pdict.Product.available}
-    - In Stock: ${pdict.Product.availabilityModel.inStock}
-    
-    This output only visible in ISML file, never in browser
-</iscomment>
-
-<div class="product">
-    ${pdict.Product.name}
-</div>
-```
-
-### Commenting Out Code Blocks
-
-```isml
-<div class="product-actions">
-    <button type="submit" class="add-to-cart">Add to Cart</button>
-    
-    <iscomment>
-        Temporarily disabled for A/B test - re-enable after test completes
-        
-        <isapplepay 
-            sku="${pdict.Product.ID}" 
-            class="dw-apple-pay-logo-black" 
-        />
-    </iscomment>
-</div>
-```
-
-### Version History and Change Log
-
-```isml
-<iscomment>
-    Change Log:
-    
-    2025-10-03 - Added Einstein recommendations section
-    2025-09-15 - Refactored pricing logic for promotion stacking
-    2025-08-20 - Implemented lazy loading for product images
-    2025-07-10 - Initial implementation
-</iscomment>
-
-<div class="product-detail-page">
-    <!-- Page content -->
-</div>
-```
-
-### API and Integration Notes
-
-```isml
-<iscomment>
-    Inventory Service Integration:
-    
-    Endpoint: /inventory/check
-    Method: GET
-    Params: productId, storeId
-    Response: { available: boolean, quantity: number }
-    
-    Error Handling:
-    - Service timeout: Show "Check in Store" message
-    - Service unavailable: Fall back to default availability
-    - Invalid product: Show out of stock
-</iscomment>
-
-<div class="availability">
-    <isif condition="${pdict.Product.available}">
-        <span class="in-stock">In Stock</span>
-    </isif>
-</div>
-```
-
-### Data Structure Documentation
-
-```isml
-<iscomment>
-    Expected pdict structure:
-    
-    pdict.Product = {
-        ID: String,
-        name: String,
-        price: Money,
-        available: Boolean,
-        images: {
-            large: [{ url: String, alt: String }],
-            small: [{ url: String, alt: String }]
-        },
-        variants: Array<Variant>
-    }
-</iscomment>
-
-<h1>${pdict.Product.name}</h1>
-```
-
-### Maintenance Instructions
-
-```isml
-<iscomment>
-    IMPORTANT MAINTENANCE NOTE:
-    
-    This template uses a custom product availability service.
-    If availability checks fail:
-    1. Check service status in Business Manager
-    2. Verify service credentials in site preferences
-    3. Review service logs in Operations > Services
-    4. Contact Platform team if issues persist
-    
-    Escalation: platform-team@company.com
-</iscomment>
-
-<div class="product-info">
-    <!-- Product information -->
-</div>
-```
-
-## Best Practices
-
-1. **Use for Internal Documentation:**
-   ```isml
-   <iscomment>
-       Internal note: This section implements custom pricing logic
-       approved by Business team on 2025-09-01
-   </iscomment>
-   ```
-
-2. **Never Use for Public Content:**
-   ```isml
-   <!-- Good: Public documentation using HTML comments -->
-   <!-- Product carousel - 4 items per slide -->
-   
-   <iscomment>
-       Good: Internal documentation using iscomment
-       Carousel implementation uses Slick library v1.8.1
-       Custom configuration in product.js
-   </iscomment>
-   ```
-
-3. **Document Complex Logic:**
-   ```isml
-   <iscomment>
-       Promotion stacking logic:
-       1. Order-level promotions apply first
-       2. Product-level promotions apply second
-       3. If conflict, best discount wins
-       4. Maximum 3 promotions per order
-   </iscomment>
-   ```
-
-4. **Add TODO/FIXME Notes:**
-   ```isml
-   <iscomment>
-       TODO: Optimize this loop - currently iterates all variants
-       FIXME: Race condition when multiple users add last item
-       NOTE: This code will be refactored in next sprint
-   </iscomment>
-   ```
-
-5. **Explain "Why" Not Just "What":**
-   ```isml
-   <iscomment>
-       Bad: Loops through products
-       
-       Good: Loops through products in reverse order because
-       newest products should display first per Marketing requirements
-       (Jira ticket: STORE-1234)
-   </iscomment>
-   ```
-
-6. **Use for Temporary Debugging:**
-   ```isml
-   <iscomment>
-       Debug: Product object structure
-       ${JSON.stringify(pdict.Product)}
-       
-       Remove before deploying to production
-   </iscomment>
-   ```
-
-7. **Document Template Dependencies:**
-   ```isml
-   <iscomment>
-       This template depends on:
-       - Product model from Product-Show controller
-       - URLUtils for link generation
-       - Resource bundle: product.properties
-       - CSS: product.css
-       - JS: productDetail.js
-   </iscomment>
-   ```
-
-8. **Add Section Dividers for Long Templates:**
-   ```isml
-   <iscomment>
-       ================================================
-       PRODUCT IMAGES SECTION
-       ================================================
-   </iscomment>
-   
-   <!-- Image code -->
-   
-   <iscomment>
-       ================================================
-       PRODUCT DETAILS SECTION
-       ================================================
-   </iscomment>
-   
-   <!-- Details code -->
-   ```
-
-## When to Use iscomment vs HTML Comments
-
-### Use `<iscomment>` for:
-
-- ✅ Internal developer notes
-- ✅ Business logic explanations
-- ✅ Sensitive information references
-- ✅ TODO/FIXME/NOTE annotations
-- ✅ Code that's temporarily disabled
-- ✅ Debugging information
-- ✅ Maintenance instructions
-- ✅ API documentation
-- ✅ Version history
-
-### Use HTML Comments `<!-- -->` for:
-
-- ✅ Public documentation
-- ✅ SEO-related notes
-- ✅ Browser compatibility notes
-- ✅ Content sectioning visible to frontend developers
-- ✅ Conditional IE comments
-- ✅ Third-party integration documentation
-
-```isml
-<iscomment>
-    Internal: This section implements Einstein recommendations
-    Service endpoint: /einstein/recommendations
-    Fallback: Show best sellers if service unavailable
-</iscomment>
-
-<!-- Einstein Product Recommendations Section -->
-<div class="recommendations">
-    <!-- Public HTML comment for frontend developers -->
-    <h2>You May Also Like</h2>
-    <!-- Recommendation tiles render here -->
-</div>
-```
-
-## Multi-Line Comments
-
-```isml
-<iscomment>
-    Long, detailed explanation spanning multiple lines.
-    
-    This can include:
-    - Bullet points
-    - Code examples (in comments)
-    - Complex explanations
-    - References to documentation
-    
-    Everything within the iscomment tags is removed
-    during template processing and never sent to browser.
-</iscomment>
-```
-
-## Nested Comments (Not Supported)
-
-⚠️ **Warning:** You cannot nest `<iscomment>` tags:
-
-```isml
-<!-- Bad: Nested comments not supported -->
-<iscomment>
-    Outer comment
-    <iscomment>
-        Inner comment - THIS WON'T WORK
-    </iscomment>
-</iscomment>
-
-<!-- Good: Single level comments -->
-<iscomment>
-    First comment
-</iscomment>
-
-<div>Some content</div>
-
-<iscomment>
-    Second comment
-</iscomment>
-```
-
-## Commenting Out Large Blocks
-
-```isml
-<iscomment>
-    Entire section commented out for testing
-    
-    <div class="promotional-banner">
-        <h2>Special Offer</h2>
-        <p>Save 20% on all items</p>
-        <isloop items="${pdict.promotions}" var="promo">
-            <div class="promo">${promo.name}</div>
-        </isloop>
-    </div>
-</iscomment>
-```
-
-**Note:** All ISML tags within `<iscomment>` are ignored and not processed.
-
-## Security Considerations
-
-### Safe in iscomment (Not Sent to Browser)
-
-```isml
-<iscomment>
-    API Configuration:
-    Service name: InventoryService
-    Endpoint: https://api.internal.company.com/inventory
-    Timeout: 5000ms
-    Retry: 3 times
-    
-    This internal documentation never reaches the browser
-</iscomment>
-```
-
-### Never in HTML Comments (Visible in Page Source)
-
-```isml
-<!-- 
-    DANGEROUS: Never put sensitive info in HTML comments
-    API Key: abc123xyz (ANYONE CAN SEE THIS IN PAGE SOURCE!)
--->
-```
-
-## Performance Impact
-
-- **Server-Side:** Minimal - comments removed during template processing
-- **Client-Side:** None - content never sent to browser
-- **Network:** None - reduces HTML size slightly (no comment in output)
-- **Cache:** No impact - comments removed before caching
-
-```isml
-<iscomment>
-    This comment adds zero bytes to the HTML sent to browser
-    Template processing removes it completely
-    No performance impact on page load
-</iscomment>
-```
-
-## Debugging Use Cases
-
-### Temporary Debug Output
-
-```isml
-<iscomment>
-    Debug output (remove before production):
-    
-    Product ID: ${pdict.Product.ID}
-    Product Type: ${pdict.Product.type}
-    Available: ${pdict.Product.available}
-    Price: ${pdict.Product.price}
-    
-    This debug info is only visible in ISML file
-</iscomment>
-```
-
-### A/B Test Documentation
-
-```isml
-<iscomment>
-    A/B Test: Checkout Button Color
-    Test ID: AB-2025-Q4-001
-    Start: 2025-10-01
-    End: 2025-10-31
-    
-    Variant A: Blue button (control)
-    Variant B: Green button (test)
-    
-    Hypothesis: Green button increases conversion by 5%
-</iscomment>
-
-<isif condition="${pdict.abTestVariant == 'B'}">
-    <button class="checkout-btn green">Checkout</button>
-<iselse>
-    <button class="checkout-btn blue">Checkout</button>
-</isif>
-```
-
-### Feature Flags
-
-```isml
-<iscomment>
-    Feature Flag: express-checkout-v2
-    Status: In development
-    Expected Launch: 2025-11-15
-    
-    When enabled, shows new express checkout flow
-    Controlled in Business Manager > Site Preferences > Custom > Features
-</iscomment>
-
-<isif condition="${pdict.features.expressCheckoutV2}">
-    <isinclude template="checkout/expressV2" />
-<iselse>
-    <isinclude template="checkout/expressV1" />
-</isif>
-```
-
-## Common Patterns
-
-### Template Header Documentation
-
-```isml
-<iscomment>
-    ============================================================
-    Template: cart/cart.isml
-    Description: Shopping cart page with line items and totals
-    ============================================================
-    
-    Author: Frontend Team
-    Created: 2025-01-15
-    Last Modified: 2025-10-03
-    
-    Requirements:
-    - Basket must exist in pdict
-    - Promotions applied before rendering
-    - Shipping estimates calculated
-    
-    Related Files:
-    - Controller: Cart.js
-    - Model: CartModel.js
-    - Styles: cart.scss
-    - Scripts: cart.js
-    ============================================================
-</iscomment>
-
-<div class="cart-page">
-    <!-- Cart content -->
-</div>
-```
-
-### Code Block Comments
-
-```isml
-<iscomment> ===== START: Product Images ===== </iscomment>
-
-<div class="product-images">
-    <!-- Image gallery -->
-</div>
-
-<iscomment> ===== END: Product Images ===== </iscomment>
-
-
-<iscomment> ===== START: Product Details ===== </iscomment>
-
-<div class="product-details">
-    <!-- Product information -->
-</div>
-
-<iscomment> ===== END: Product Details ===== </iscomment>
-```
-
-### Conditional Logic Documentation
-
-```isml
-<iscomment>
-    Display logic:
-    1. If product has master, show variant selector
-    2. If product is simple, show add-to-cart directly
-    3. If product is set, show set items
-    4. If product is bundle, show bundle components
-</iscomment>
-
-<isif condition="${pdict.Product.master}">
-    <isinclude template="product/variantSelector" />
-<iselseif condition="${pdict.Product.productSet}">
-    <isinclude template="product/productSet" />
-<iselseif condition="${pdict.Product.bundle}">
-    <isinclude template="product/bundleComponents" />
-<iselse>
-    <isinclude template="product/simpleProduct" />
-</isif>
-```
-
-## Related Elements
-
-- HTML comments `<!-- -->` - Visible in page source (use for public documentation)
-- `<isscript>` - Server-side code execution (can include JavaScript comments)
-- `<isdecorate>` - Template decoration (use `<iscomment>` to document decorators)
-
-## Notes
-
-- Content within `<iscomment>` is completely removed during template processing
-- Not sent to browser and not visible in page source
-- Provides true confidentiality unlike HTML comments
-- No attributes supported
-- Cannot be nested
-- Deprecated syntax (`<!--- --->`) still works but not recommended
-- No performance impact on client-side rendering
-- Ideal for internal documentation and sensitive notes
-- Can contain any content including ISML tags (all ignored)
-
-## Migration from HTML Comments
-
-### Before (Insecure)
-
-```isml
-<!-- 
-    Internal note: This uses custom pricing service
-    Service URL: https://pricing-api.internal.company.com
-    Credentials stored in site preferences
--->
-<div class="pricing">
-    ${pdict.Product.price}
-</div>
-```
-
-### After (Secure)
-
-```isml
-<iscomment>
-    Internal note: This uses custom pricing service
-    Service URL: https://pricing-api.internal.company.com
-    Credentials stored in site preferences
-</iscomment>
-
-<!-- Pricing Section -->
-<div class="pricing">
-    ${pdict.Product.price}
-</div>
-```
-
-## Recommended Comment Structure
-
-```isml
-<iscomment>
-    [COMPONENT NAME]
-    
-    Purpose: [Brief description]
-    
-    Dependencies:
-    - [Dependency 1]
-    - [Dependency 2]
-    
-    Important Notes:
-    - [Note 1]
-    - [Note 2]
-    
-    Last Updated: [Date]
-    Author: [Name/Team]
-</iscomment>
-
-<!-- Component HTML Code -->
-```
-
-## Example: Complete Template Documentation
-
-```isml
-<iscomment>
-    ============================================================
-    PRODUCT DETAIL PAGE TEMPLATE
-    ============================================================
-    
-    File: product/productDetails.isml
-    Purpose: Display complete product information including
-             images, pricing, variants, and add-to-cart
-    
-    Controller: Product-Show
-    Model: Product (SFRA)
-    
-    Dependencies:
-    - URLUtils helper
-    - Resource bundles (product.properties)
-    - Product availability service
-    - Image transformation service
-    
-    pdict Structure:
-    {
-        Product: Object,      // Product model
-        category: Object,     // Primary category
-        reviews: Array,       // Product reviews
-        recommendations: Array // Related products
-    }
-    
-    Features:
-    - Image zoom on hover
-    - Variant selection (size, color)
-    - Quantity selection
-    - Add to cart / Add to wishlist
-    - Social sharing
-    - Product reviews display
-    - Einstein recommendations
-    
-    Performance Notes:
-    - Template is cached for 1 hour
-    - Images lazy-loaded
-    - Reviews loaded via AJAX
-    
-    A/B Tests Active:
-    - Checkout button color (AB-2025-Q4-001)
-    - Product image layout (AB-2025-Q4-002)
-    
-    Last Updated: 2025-10-03
-    Author: Frontend Team
-    ============================================================
-</iscomment>
-
-<iscache type="relative" hour="1"/>
-
-<!DOCTYPE html>
-<html>
-<!-- Template content -->
-</html>
-```