# ISML isscript Element
## Overview
The `<isscript>` element enables server-side JavaScript execution within ISML templates. It provides a way to perform calculations, manipulate data, call API methods, and set variables using the full power of JavaScript and the Salesforce B2C Commerce Script API (dw.* namespace).
**Key Features:** Server-side JavaScript execution, access to B2C Commerce APIs, variable manipulation, shared execution context across multiple script blocks, integration with inline expressions using `${}` syntax.
**Important:** Scripts execute on the server during template rendering, not in the browser.
## Syntax
```isml
<isscript>
// JavaScript code here
</isscript>
```
## Attributes
**None** - This tag has no attributes. JavaScript code is placed between the opening and closing tags.
## Purpose
The `<isscript>` element serves to:
1. **Server-Side Logic:** Execute JavaScript business logic during template rendering
2. **Data Manipulation:** Transform, calculate, or process data before display
3. **API Access:** Call B2C Commerce Script API methods (dw.* namespace)
4. **Variable Assignment:** Create and set variables for use in templates
5. **Complex Operations:** Perform operations too complex for inline expressions
6. **Code Organization:** Group related logic in dedicated script blocks
## Top-Level Variables
The following variables are automatically available in all `<isscript>` blocks:
| Variable | Type | Description | Scope |
|----------|------|-------------|-------|
| `session` | `dw.system.Session` | Current internal B2C Commerce session | Session-wide |
| `request` | `dw.system.Request` | Current internal B2C Commerce request | Request-wide |
| `pdict` | `dw.system.PipelineDictionary` | Pipeline Dictionary (request parameters and data) | Request-wide |
| `out` | `dw.io.PrintWriter` | PrintWriter for direct HTML output | Page-wide |
**Example:**
```isml
<isscript>
// Access session
var customerId = session.customer.ID;
// Access request
var httpMethod = request.httpMethod;
// Access pipeline dictionary
var product = pdict.Product;
// Write directly to output (uncommon)
out.print("<p>Hello World</p>");
</isscript>
```
## Variable Scopes
Variables created in `<isscript>` blocks have different scopes based on how they're declared:
### Page Scope Variables
**Definition:** Variables set using `var`, `let`, or `const` in scriptlets, or well-known variables set by the template at runtime.
**Availability:** Available throughout template execution context and can be referenced from multiple scriptlets or expressions in the template or its local includes.
**Persistence:** Lasts for the duration of the current page/template execution.
```isml
<isscript>
var userName = pdict.customer.firstName; // Page scope
var orderTotal = pdict.basket.totalGrossPrice.value; // Page scope
</isscript>
<!-- Variables available in expressions -->
<h1>Welcome, ${userName}</h1>
<p>Total: ${orderTotal}</p>
<!-- Variables available in other script blocks -->
<isscript>
var greeting = "Hello, " + userName; // userName from previous block
</isscript>
```
### Tag Scope Variables
**Definition:** Variables defined within certain ISML tags (e.g., loop status variables).
**Availability:** Only available within the context of that specific tag.
**Example:**
```isml
<isloop items="${pdict.products}" var="product" status="loopStatus">
<!-- loopStatus is tag-scoped, only available inside this loop -->
<isif condition="${loopStatus.first}">
<p>First product!</p>
</isif>
</isloop>
<!-- loopStatus NOT available here -->
```
## Shared Execution Context
**Important:** Multiple `<isscript>` blocks in the same template share the same execution context. Variables declared in one block are available in subsequent blocks.
```isml
<!-- First script block -->
<isscript>
var user = pdict.User;
var firstName = user.firstName;
</isscript>
<!-- Some HTML content -->
<div class="header">
<h1>Welcome</h1>
</div>
<!-- Second script block - can access variables from first block -->
<isscript>
var fullName = firstName + " " + user.lastName; // firstName and user available
var welcomeMessage = "Hello, " + fullName;
</isscript>
<!-- Use variables in expressions -->
<p><isprint value="${welcomeMessage}"/></p>
```
## Common Use Cases
### Data Transformation and Calculation
```isml
<isscript>
var product = pdict.Product;
// Calculate discount percentage
var listPrice = product.price.list.value;
var salesPrice = product.price.sales.value;
var discount = listPrice - salesPrice;
var discountPercent = (discount / listPrice) * 100;
// Format for display
var discountDisplay = Math.round(discountPercent) + "% OFF";
</isscript>
<div class="product-price">
<span class="original">${listPrice}</span>
<span class="sale">${salesPrice}</span>
<span class="discount">${discountDisplay}</span>
</div>
```
### API Method Calls
```isml
<isscript>
var ProductMgr = require('dw/catalog/ProductMgr');
var URLUtils = require('dw/web/URLUtils');
var StringUtils = require('dw/util/StringUtils');
// Get product by ID
var productID = request.httpParameterMap.pid.stringValue;
var product = ProductMgr.getProduct(productID);
// Generate URLs
var productURL = URLUtils.url('Product-Show', 'pid', productID);
// String manipulation
var productName = StringUtils.trim(product.name);
</isscript>
```
### Complex Conditional Logic
```isml
<isscript>
var customer = session.customer;
var basket = pdict.basket;
// Determine eligibility for free shipping
var freeShippingThreshold = 50;
var basketTotal = basket ? basket.totalGrossPrice.value : 0;
var isFreeShipping = basketTotal >= freeShippingThreshold;
var amountToFreeShipping = isFreeShipping ? 0 : freeShippingThreshold - basketTotal;
// Determine customer tier
var customerTier = "bronze";
if (customer.authenticated) {
var orderHistory = customer.orderHistory;
var totalSpent = 0;
var orders = orderHistory.getOrders();
while (orders.hasNext()) {
var order = orders.next();
totalSpent += order.totalGrossPrice.value;
}
if (totalSpent > 1000) {
customerTier = "gold";
} else if (totalSpent > 500) {
customerTier = "silver";
}
}
</isscript>
<div class="shipping-message">
<isif condition="${isFreeShipping}">
<p>You qualify for FREE shipping!</p>
<iselse>
<p>Add <isprint value="${amountToFreeShipping}" style="MONEY_LONG"/> for FREE shipping</p>
</isif>
</div>
<div class="customer-tier ${customerTier}">
<p>Your tier: ${customerTier.toUpperCase()}</p>
</div>
```
### Array and Collection Processing
```isml
<isscript>
var products = pdict.products;
// Filter products on sale
var saleProducts = [];
for (var i = 0; i < products.length; i++) {
var product = products[i];
if (product.price.sales.value < product.price.list.value) {
saleProducts.push(product);
}
}
// Sort by price (low to high)
saleProducts.sort(function(a, b) {
return a.price.sales.value - b.price.sales.value;
});
// Get top 5 cheapest sale items
var topDeals = saleProducts.slice(0, 5);
</isscript>
<div class="top-deals">
<h2>Top Deals</h2>
<isloop items="${topDeals}" var="deal">
<div class="deal-item">
<h3>${deal.name}</h3>
<p><isprint value="${deal.price.sales}" style="MONEY_LONG"/></p>
</div>
</isloop>
</div>
```
### Date and Time Manipulation
```isml
<isscript>
var Calendar = require('dw/util/Calendar');
var StringUtils = require('dw/util/StringUtils');
var now = new Calendar();
var currentDate = now.time;
// Calculate shipping estimate (3 business days)
var shippingEstimate = new Calendar(now);
shippingEstimate.add(Calendar.DAY_OF_MONTH, 3);
// Format dates
var orderDate = StringUtils.formatCalendar(now, "MMMM d, yyyy");
var deliveryDate = StringUtils.formatCalendar(shippingEstimate, "MMMM d, yyyy");
</isscript>
<div class="order-info">
<p>Order Date: ${orderDate}</p>
<p>Estimated Delivery: ${deliveryDate}</p>
</div>
```
### Session and Cookie Management
```isml
<isscript>
var Cookie = require('dw/web/Cookie');
// Read cookie
var cookies = request.httpCookies;
var viewedProducts = cookies['recentlyViewed'];
// Set session custom property
if (!session.custom.pageViews) {
session.custom.pageViews = 0;
}
session.custom.pageViews++;
var pageViewCount = session.custom.pageViews;
var isFirstVisit = pageViewCount === 1;
</isscript>
<isif condition="${isFirstVisit}">
<div class="welcome-modal">
<h2>Welcome to our store!</h2>
<p>First time here? Get 10% off your first order.</p>
</div>
</isif>
```
### Form Validation and Processing
```isml
<isscript>
var form = pdict.CurrentForms.registration;
var errors = [];
// Validate email
var email = form.email.value;
if (!email || email.indexOf('@') === -1) {
errors.push({
field: 'email',
message: 'Please enter a valid email address'
});
}
// Validate password
var password = form.password.value;
var confirmPassword = form.confirmPassword.value;
if (password !== confirmPassword) {
errors.push({
field: 'password',
message: 'Passwords do not match'
});
}
var hasErrors = errors.length > 0;
</isscript>
<isif condition="${hasErrors}">
<div class="error-messages">
<isloop items="${errors}" var="error">
<p class="error">${error.message}</p>
</isloop>
</div>
</isif>
```
### Custom Object Access
```isml
<isscript>
var CustomObjectMgr = require('dw/object/CustomObjectMgr');
// Retrieve custom object
var storeConfig = CustomObjectMgr.getCustomObject('StoreConfig', 'main');
if (storeConfig) {
var storeName = storeConfig.custom.storeName;
var storeHours = storeConfig.custom.hours;
var storePhone = storeConfig.custom.phone;
} else {
var storeName = "Our Store";
var storeHours = "9 AM - 5 PM";
var storePhone = "1-800-555-0123";
}
</isscript>
<div class="store-info">
<h3>${storeName}</h3>
<p>Hours: ${storeHours}</p>
<p>Phone: ${storePhone}</p>
</div>
```
### SFRA-Style Module Imports
```isml
<isscript>
// Import modules
var ProductFactory = require('*/cartridge/scripts/factories/product');
var collections = require('*/cartridge/scripts/util/collections');
var URLUtils = require('dw/web/URLUtils');
// Use imported modules
var productDetails = ProductFactory.get(pdict.product);
var productImages = collections.map(productDetails.images.large, function(image) {
return {
url: image.url,
alt: image.alt,
title: image.title
};
});
var addToCartUrl = URLUtils.url('Cart-AddProduct');
</isscript>
```
### JSON Data Preparation
```isml
<isscript>
var product = pdict.Product;
// Prepare JSON data for client-side JavaScript
var productData = {
id: product.ID,
name: product.name,
price: product.price.sales.value,
currency: product.price.sales.currencyCode,
available: product.available,
inStock: product.availabilityModel.inStock,
images: []
};
// Build images array
var images = product.getImages('large');
for (var i = 0; i < images.length; i++) {
productData.images.push({
url: images[i].getURL().toString(),
alt: images[i].getAlt()
});
}
var productJSON = JSON.stringify(productData);
</isscript>
<script>
window.productData = ${productJSON};
</script>
```
## Best Practices
### 1. Keep Scripts Focused and Small
Break large scripts into smaller, focused blocks:
```isml
<!-- Good: Small, focused script blocks -->
<isscript>
var product = pdict.Product;
var price = product.price.sales.value;
</isscript>
<!-- Display product info -->
<div class="product">${product.name}</div>
<isscript>
var discount = calculateDiscount(price);
</isscript>
<!-- Avoid: One large script block with everything -->
<isscript>
// 100 lines of mixed logic
</isscript>
```
### 2. Use require() for API Access
Always use `require()` to import B2C Commerce API classes:
```isml
<!-- Good: Explicit require statements -->
<isscript>
var ProductMgr = require('dw/catalog/ProductMgr');
var URLUtils = require('dw/web/URLUtils');
var product = ProductMgr.getProduct(productID);
</isscript>
<!-- Avoid: Assuming classes are globally available -->
<isscript>
var product = ProductMgr.getProduct(productID); // May not work
</isscript>
```
### 3. Minimize Business Logic in Templates
Move complex business logic to controllers or scripts:
```isml
<!-- Good: Simple data access in template -->
<isscript>
var productHelper = require('*/cartridge/scripts/helpers/productHelper');
var productData = productHelper.getProductData(pdict.Product);
</isscript>
<!-- Avoid: Complex business logic in template -->
<isscript>
// 50 lines of complex pricing calculations
// Discount rules
// Inventory checks
// etc.
</isscript>
```
### 4. Use Descriptive Variable Names
Choose clear, meaningful variable names:
```isml
<!-- Good: Descriptive names -->
<isscript>
var currentProduct = pdict.Product;
var discountPercentage = calculateDiscount(currentProduct);
var formattedPrice = formatCurrency(currentProduct.price);
</isscript>
<!-- Avoid: Unclear names -->
<isscript>
var p = pdict.Product;
var d = calc(p);
var f = fmt(p.price);
</isscript>
```
### 5. Handle Null and Undefined Safely
Always check for null/undefined before accessing properties:
```isml
<isscript>
var product = pdict.Product;
var productName = product ? product.name : "Product Unavailable";
var basket = pdict.basket;
var itemCount = basket && basket.productLineItems ? basket.productLineItems.size() : 0;
// Or use optional chaining if available
var manufacturer = product?.manufacturer?.name || "Unknown";
</isscript>
```
### 6. Avoid Direct HTML Output with out.print()
Use ISML elements instead of `out.print()`:
```isml
<!-- Good: Use ISML elements -->
<isscript>
var message = "Welcome, " + customer.firstName;
</isscript>
<p>${message}</p>
<!-- Avoid: Direct HTML output -->
<isscript>
out.print("<p>Welcome, " + customer.firstName + "</p>");
</isscript>
```
### 7. Comment Complex Logic
Add comments to explain non-obvious logic:
```isml
<isscript>
// Calculate loyalty discount based on customer tier and purchase history
var loyaltyDiscount = 0;
if (customer.authenticated) {
var tier = customer.custom.loyaltyTier;
var purchaseCount = customer.orderHistory.orderCount;
// Gold tier: 15% discount, Silver: 10%, Bronze: 5%
if (tier === 'gold' && purchaseCount > 10) {
loyaltyDiscount = 0.15;
} else if (tier === 'silver' && purchaseCount > 5) {
loyaltyDiscount = 0.10;
} else {
loyaltyDiscount = 0.05;
}
}
</isscript>
```
### 8. Use Modern JavaScript Features
Leverage ES6+ features when appropriate:
```isml
<isscript>
// Use const/let instead of var when appropriate
const TAX_RATE = 0.08;
let totalWithTax = subtotal * (1 + TAX_RATE);
// Use arrow functions
const activeProducts = products.filter(p => p.online && p.available);
// Use template literals
const greeting = `Welcome, ${customer.firstName} ${customer.lastName}!`;
// Use destructuring
const { firstName, lastName, email } = customer.profile;
</isscript>
```
## Integration with Inline Expressions
Variables created in `<isscript>` blocks are available in inline expressions `${}`:
```isml
<isscript>
var userName = pdict.customer.firstName + " " + pdict.customer.lastName;
var currentYear = new Date().getFullYear();
var copyrightText = "© " + currentYear + " Our Company";
</isscript>
<!-- Use variables in inline expressions -->
<h1>Welcome, ${userName}</h1>
<footer>
<p>${copyrightText}</p>
</footer>
<!-- Use in attributes -->
<div class="user-${userName.toLowerCase().replace(' ', '-')}">
Content
</div>
<!-- Use in isprint -->
<isprint value="${userName}" encoding="on"/>
```
## Script Expression Support
Script expressions using `${}` syntax are supported in various contexts:
### In HTML Content
```isml
<p>Hello, ${customer.firstName}!</p>
<h2>${product.name}</h2>
```
### In Tag Attributes
```isml
<div class="${pdict.cssClass}">
<img src="${product.imageURL}" alt="${product.name}">
<a href="${URLUtils.url('Product-Show', 'pid', product.ID)}">
```
### In ISML Tag Attributes
```isml
<isif condition="${product.available}">
<isprint value="${product.price}" style="MONEY_LONG"/>
<isloop items="${pdict.products}" var="product">
```
## Performance Considerations
### 1. Minimize Script Execution Time
Keep scripts efficient to avoid slow page rendering:
```isml
<!-- Good: Efficient operations -->
<isscript>
var productCount = products.length; // Fast
var firstProduct = products[0]; // Fast
</isscript>
<!-- Avoid: Expensive operations in templates -->
<isscript>
// Expensive database queries
// Complex calculations
// Large loops processing thousands of items
</isscript>
```
### 2. Cache Expensive Calculations
Store results of expensive calculations:
```isml
<isscript>
// Cache result in session for reuse
if (!session.custom.cachedData) {
session.custom.cachedData = expensiveCalculation();
}
var data = session.custom.cachedData;
</isscript>
```
### 3. Avoid Nested Loops
Minimize nested iterations:
```isml
<!-- Less efficient: Nested loops -->
<isscript>
for (var i = 0; i < products.length; i++) {
for (var j = 0; j < categories.length; j++) {
// O(n²) complexity
}
}
</isscript>
<!-- Better: Pre-process data -->
<isscript>
var categoryMap = {};
categories.forEach(function(cat) {
categoryMap[cat.ID] = cat;
});
products.forEach(function(prod) {
var category = categoryMap[prod.categoryID]; // O(1) lookup
});
</isscript>
```
## Security Considerations
### 1. Sanitize User Input
Never trust user input in scripts:
```isml
<isscript>
var searchQuery = request.httpParameterMap.q.stringValue;
// Sanitize before use
var StringUtils = require('dw/util/StringUtils');
var safeQuery = StringUtils.trim(searchQuery || '');
// Validate
if (safeQuery.length > 100) {
safeQuery = safeQuery.substring(0, 100);
}
</isscript>
```
### 2. Avoid Exposing Sensitive Data
Don't expose sensitive information to client-side:
```isml
<!-- Bad: Exposing sensitive data -->
<isscript>
var customerData = {
email: customer.email,
password: customer.password, // NEVER DO THIS
creditCard: customer.creditCard // NEVER DO THIS
};
</isscript>
<script>
window.customer = ${JSON.stringify(customerData)};
</script>
<!-- Good: Only expose safe data -->
<isscript>
var customerData = {
firstName: customer.firstName,
loyaltyPoints: customer.loyaltyPoints
};
</isscript>
```
### 3. Use Proper Encoding
Encode output to prevent XSS:
```isml
<isscript>
var userComment = request.httpParameterMap.comment.stringValue;
</isscript>
<!-- Good: Use encoding -->
<p><isprint value="${userComment}" encoding="on"/></p>
<!-- Bad: Direct output without encoding -->
<p>${userComment}</p> <!-- Potential XSS -->
```
## Common Errors and Troubleshooting
### Script Syntax Errors
**Symptom:** Template fails to render with JavaScript error.
**Solution:** Check JavaScript syntax carefully:
```isml
<!-- Bad: Syntax error -->
<isscript>
var product = pdict.Product
var price = product.price // Missing semicolon
</isscript>
<!-- Good: Correct syntax -->
<isscript>
var product = pdict.Product;
var price = product.price;
</isscript>
```
### Variable Not Defined
**Symptom:** ReferenceError - variable is not defined.
**Solution:** Ensure variable is declared before use:
```isml
<!-- Bad: Using undeclared variable -->
<isscript>
var fullName = firstName + " " + lastName; // firstName not defined
</isscript>
<!-- Good: Declare variables -->
<isscript>
var firstName = pdict.customer.firstName;
var lastName = pdict.customer.lastName;
var fullName = firstName + " " + lastName;
</isscript>
```
### Null Pointer Errors
**Symptom:** TypeError - cannot read property of null/undefined.
**Solution:** Check for null/undefined:
```isml
<!-- Bad: No null check -->
<isscript>
var productName = pdict.Product.name; // Error if Product is null
</isscript>
<!-- Good: Null check -->
<isscript>
var product = pdict.Product;
var productName = product ? product.name : "Unknown Product";
</isscript>
```
## Related Elements
- **`<isset>`** - Set variables (alternative to isscript for simple assignments)
- **`<isprint>`** - Output script variables with formatting
- **`<isif>`** - Use script variables in conditions
- **`<isloop>`** - Iterate over collections created in scripts
## Related APIs
- **`dw.*` packages** - All B2C Commerce Script API classes
- **`require()`** - Module import function
- **`session`** - Session object
- **`request`** - Request object
- **`pdict`** - Pipeline Dictionary
## See Also
- [B2C Commerce Script API Documentation](../dw_system/)
- [ISML Expressions](./expressions.md)
- [isset Element](./isset.md)
- [SFRA Client-side JS Skill](../../ai-instructions/skills/sfcc-sfra-client-side-js/SKILL.md)
- [Security Skill](../../ai-instructions/skills/sfcc-security/SKILL.md)
- [Performance Skill](../../ai-instructions/skills/sfcc-performance/SKILL.md)
