sfcc-dev-mcp 1.0.19 → 1.0.21

package/docs/sfra/render.md

@@ -1,354 +0,0 @@
-# Module render
-
-## Description
-
-The SFRA render module is the core rendering engine that processes and outputs different types of response content in Salesforce Commerce Cloud's Storefront Reference Architecture (SFRA). This module handles the execution of rendering operations that have been queued in the Response object's renderings array during the request lifecycle. It supports multiple output formats including ISML templates, JSON responses, XML output, Page Designer pages, and direct text output. The render module serves as the final step in the SFRA request processing pipeline, converting accumulated view data and rendering instructions into the actual HTTP response content.
-
-## Functions
-
-### template
-
-**Signature:** `template(view, viewData) : void`
-
-Renders an ISML template with the provided data.
-
-### json
-
-**Signature:** `json(data, response) : void`
-
-Renders an object as JSON output.
-
-### xml
-
-**Signature:** `xml(viewData, response) : void`
-
-Renders an object as XML output with proper escaping.
-
-### page
-
-**Signature:** `page(pageID, aspectAttributes, data, response) : void`
-
-Renders a Page Designer page with optional aspect attributes.
-
-### applyRenderings
-
-**Signature:** `applyRenderings(res) : void`
-
-Processes all rendering instructions in the response object.
-
-## Function Detail
-
-### template
-
-**Signature:** `template(view, viewData) : void`
-
-**Description:** Renders an ISML template using the provided view data. Creates a shallow copy of the view data for isolation and uses SFCC's ISML rendering engine to process the template.
-
-**Parameters:**
-- `view` (String) - Path to the ISML template file
-- `viewData` (Object) - Data object to be passed as pdict to the template
-
-**Returns:**
-void
-
-**Throws:**
-Error with enhanced message including Java stack trace, file name, and line number information.
-
-**Processing:**
-1. Creates shallow copy of view data to prevent modification
-2. Calls `isml.renderTemplate()` with view path and data
-3. Wraps any rendering errors with enhanced error information
-
-### json
-
-**Signature:** `json(data, response) : void`
-
-**Description:** Renders the provided data as JSON output with proper content type headers and formatting.
-
-**Parameters:**
-- `data` (Object) - Object to be serialized as JSON
-- `response` (Response) - SFRA Response object
-
-**Returns:**
-void
-
-**Processing:**
-1. Sets content type to `application/json`
-2. Serializes data with JSON.stringify using 2-space indentation
-3. Writes formatted JSON to response writer
-
-### xml
-
-**Signature:** `xml(viewData, response) : void`
-
-**Description:** Renders the provided view data as XML output with proper character escaping and root element wrapping.
-
-**Parameters:**
-- `viewData` (Object) - Object containing data to be rendered as XML
-- `response` (Response) - SFRA Response object
-
-**Returns:**
-void
-
-**Throws:**
-Error with enhanced message including stack trace, file name, and line number information.
-
-**XML Character Escaping:**
-- `<` → `&lt;`
-- `>` → `&gt;`
-- `&` → `&amp;`
-- `"` → `&quot;`
-- `'` → `&apos;`
-
-**Processing:**
-1. Creates root `<response>` element
-2. Processes each key in viewData:
-   - If key is 'xml', includes raw XML content
-   - Otherwise, creates element with escaped content
-3. Closes root element
-4. Sets content type to `application/xml`
-5. Creates XML object and writes to response
-
-### page
-
-**Signature:** `page(pageID, aspectAttributes, data, response) : void`
-
-**Description:** Renders a Page Designer page using SFCC's PageMgr with optional aspect attributes for advanced page management.
-
-**Parameters:**
-- `pageID` (String) - ID of the Page Designer page to render
-- `aspectAttributes` (dw.util.HashMap) - Optional aspect attributes for PageMgr
-- `data` (Object) - Data to be passed to the page
-- `response` (Response) - SFRA Response object
-
-**Returns:**
-void
-
-**Processing:**
-1. Checks if aspect attributes exist and are not empty
-2. Calls appropriate PageMgr.renderPage() method:
-   - With aspect attributes: `PageMgr.renderPage(pageID, aspectAttributes, JSON.stringify(data))`
-   - Without aspect attributes: `PageMgr.renderPage(pageID, JSON.stringify(data))`
-3. Writes rendered page content to response writer
-
-### applyRenderings
-
-**Signature:** `applyRenderings(res) : void`
-
-**Description:** Processes all queued rendering instructions in the response object's renderings array. This is the main entry point called by the Server during route completion.
-
-**Parameters:**
-- `res` (Response) - SFRA Response object containing renderings array
-
-**Returns:**
-void
-
-**Throws:**
-Error if no renderings are present or if invalid rendering type is encountered.
-
-**Rendering Types Processed:**
-
-**Render Instructions (`type: 'render'`):**
-- `subType: 'isml'` - Calls `template()` with view and viewData
-- `subType: 'json'` - Calls `json()` with viewData and response
-- `subType: 'xml'` - Calls `xml()` with viewData and response
-- `subType: 'page'` - Calls `page()` with page, aspectAttributes, viewData, and response
-
-**Print Instructions (`type: 'print'`):**
-- Directly writes message to response writer
-
-**Validation:**
-- Throws error if renderings array is empty
-- Throws error for unknown rendering types
-- Throws error for render instructions without valid subType
-
-## Rendering Pipeline Integration
-
-### Response Object Integration
-
-The render module works closely with the SFRA Response object:
-
-**Rendering Queue:**
-```javascript
-res.renderings = [
-  { type: 'render', subType: 'isml', view: 'template/path' },
-  { type: 'print', message: 'Debug output' },
-  { type: 'render', subType: 'json' }
-];
-```
-
-**View Data Accumulation:**
-```javascript
-res.viewData = {
-  title: 'Page Title',
-  products: [...],
-  customer: {...}
-};
-```
-
-### Server Integration
-
-The Server class calls `applyRenderings()` during route completion:
-
-```javascript
-route.on('route:Complete', function onRouteCompleteHandler(req, res) {
-    // Cache and personalization handling
-    if (res.redirectUrl) {
-        // Handle redirects
-        return;
-    }
-    render.applyRenderings(res); // Execute rendering pipeline
-});
-```
-
-## Content Type Management
-
-### Automatic Content Types
-
-**JSON Responses:**
-- Sets `application/json` content type
-- Formats output with 2-space indentation
-
-**XML Responses:**
-- Sets `application/xml` content type
-- Automatically escapes special characters
-- Wraps content in root `<response>` element
-
-**ISML Templates:**
-- Content type determined by template output
-- Typically `text/html` for web pages
-
-**Page Designer:**
-- Content type managed by PageMgr
-- Usually `text/html` for rendered pages
-
-## Error Handling
-
-### Template Rendering Errors
-
-**ISML Template Errors:**
-- Catches Java exceptions from template engine
-- Enhances error with file name and line number
-- Includes original Java stack trace
-
-**XML Rendering Errors:**
-- Catches XML parsing/creation errors
-- Provides enhanced error messaging
-- Includes stack trace information
-
-### Validation Errors
-
-**Missing Renderings:**
-- Throws error if renderings array is empty
-- Prevents silent failures in rendering pipeline
-
-**Invalid Rendering Types:**
-- Validates rendering instruction format
-- Throws descriptive errors for unknown types
-
-## Usage Examples
-
-### Basic Template Rendering
-```javascript
-// In controller middleware
-res.render('product/productDetail', {
-    product: productModel,
-    breadcrumbs: breadcrumbsModel
-});
-
-// Results in rendering instruction:
-{
-    type: 'render',
-    subType: 'isml',
-    view: 'product/productDetail'
-}
-```
-
-### JSON API Response
-```javascript
-// In API controller
-res.json({
-    success: true,
-    data: responseData,
-    message: 'Operation completed'
-});
-
-// Results in JSON output with proper headers
-```
-
-### XML Response
-```javascript
-// In XML endpoint
-res.xml({
-    status: 'success',
-    xml: '<customData>...</customData>',
-    timestamp: new Date().toISOString()
-});
-
-// Results in properly escaped XML with root element
-```
-
-### Page Designer Integration
-```javascript
-// In Page Designer controller
-res.page('homepage', aspectAttributes, {
-    banners: bannerData,
-    featured: featuredProducts
-});
-
-// Results in Page Designer page rendering
-```
-
-### Mixed Output
-```javascript
-// Debug output followed by template
-res.print('Debug: Processing complete');
-res.render('checkout/confirmation', orderData);
-
-// Results in multiple rendering instructions executed in order
-```
-
-## Performance Considerations
-
-### Data Copying
-
-**Template Rendering:**
-- Creates shallow copy of view data for isolation
-- Prevents template modifications from affecting response object
-- Minimal performance impact for typical data sizes
-
-### Memory Management
-
-**Large Data Sets:**
-- JSON serialization with formatting may increase memory usage
-- XML escaping creates additional string copies
-- Consider streaming for very large responses
-
-### Caching Integration
-
-**Template Caching:**
-- ISML templates are cached by SFCC platform
-- View data is not cached at render level
-- Page Designer pages benefit from platform caching
-
-## Security Considerations
-
-### XML Security
-
-**Character Escaping:**
-- Prevents XML injection attacks
-- Escapes all potentially dangerous characters
-- Safe handling of user-generated content
-
-**Content Validation:**
-- XML content must be well-formed
-- Error handling prevents partial output
-
-### Template Security
-
-**Data Isolation:**
-- Shallow copy prevents template-induced data corruption
-- Original response data remains unchanged
-- Safe passing of sensitive data to templates
-
----

package/docs/sfra/request.md

@@ -1,210 +0,0 @@
-# Class Request
-
-## Inheritance Hierarchy
-
-- Object
-    - sfra.models.Request
-
-## Description
-
-The SFRA Request object is a local wrapper around the global request object that provides enhanced functionality for SFRA (Storefront Reference Architecture) applications. This class translates the global request, customer, and session objects into a more convenient local interface with additional properties and methods. The Request object automatically handles currency setting based on locale, provides easy access to form data and query parameters, and includes customer information in a normalized format. It serves as the primary interface for accessing request-related data in SFRA controllers and provides a consistent API across different types of requests (GET, POST, PUT, etc.).
-
-## Properties
-
-### httpMethod
-
-**Type:** String (Read Only)
-
-The HTTP method of the request (GET, POST, PUT, DELETE, etc.).
-
-### host
-
-**Type:** String (Read Only)
-
-The HTTP host header value from the request.
-
-### path
-
-**Type:** String (Read Only)
-
-The HTTP path portion of the request URL.
-
-### httpHeaders
-
-**Type:** Object (Read Only)
-
-Collection of HTTP headers from the request.
-
-### https
-
-**Type:** Boolean (Read Only)
-
-Indicates whether the request was made over HTTPS.
-
-### includeRequest
-
-**Type:** Boolean (Read Only)
-
-Indicates whether this is an include request (remote include).
-
-### session
-
-**Type:** Object (Read Only)
-
-Local session object containing privacy cache, currency information, and click stream data.
-
-### httpParameterMap
-
-**Type:** dw.web.HttpParameterMap (Read Only)
-
-The raw HTTP parameter map from the global request object.
-
-### querystring
-
-**Type:** QueryString (Read Only)
-
-Parsed query string parameters as a QueryString object.
-
-### form
-
-**Type:** Object (Read Only)
-
-Normalized form data from the HTTP parameter map, excluding query string parameters.
-
-### body
-
-**Type:** String (Read Only)
-
-The request body as a string for POST and PUT requests.
-
-### geolocation
-
-**Type:** Object (Read Only)
-
-Geolocation information including country code, latitude, and longitude.
-
-### currentCustomer
-
-**Type:** Object (Read Only)
-
-Local customer object containing profile, address book, and wallet information.
-
-### locale
-
-**Type:** Object (Read Only)
-
-Current locale information including currency details.
-
-### remoteAddress
-
-**Type:** String (Read Only)
-
-The remote IP address of the client making the request.
-
-### referer
-
-**Type:** String (Read Only)
-
-The HTTP referer header value.
-
-### pageMetaData
-
-**Type:** Object (Read Only)
-
-Page metadata object for managing SEO-related information.
-
-## Constructor Summary
-
-### Request
-
-**Signature:** `Request(request, customer, session)`
-
-Creates a new SFRA Request object from global request, customer, and session objects.
-
-**Parameters:**
-- `request` (Object) - Global request object
-- `customer` (dw.customer.Customer) - Global customer object
-- `session` (dw.system.Session) - Global session object
-
-## Method Summary
-
-### setLocale
-
-**Signature:** `setLocale(localeID) : Boolean`
-
-Sets the locale for the current request.
-
-**Parameters:**
-- `localeID` (String) - The locale ID to set
-
-**Returns:**
-- Boolean indicating success of locale setting
-
-## Method Detail
-
-### setLocale
-
-**Signature:** `setLocale(localeID) : Boolean`
-
-**Description:** Sets the locale for the current request and returns whether the operation was successful.
-
-**Parameters:**
-- `localeID` (String) - The locale identifier (e.g., "en_US", "fr_FR")
-
-**Returns:**
-Boolean value indicating whether the locale was successfully set.
-
-## Property Details
-
-### session
-
-**Type:** Object (Read Only)
-
-**Description:** Provides access to session-related information including:
-
-- `privacyCache` - Simple cache for session privacy data
-- `raw` - Reference to the original session object
-- `currency` - Current currency information with code, digits, name, and symbol
-- `setCurrency(value)` - Method to update session currency
-- `clickStream` - Click stream data with clicks array, first/last clicks, and partial flag
-
-### currentCustomer
-
-**Type:** Object (Read Only)
-
-**Description:** Normalized customer object containing:
-
-**For Authenticated Customers:**
-- `profile` - Customer profile with name, email, phone, and customer number
-- `addressBook` - Address book with preferred address and addresses array
-- `wallet` - Payment instruments collection
-- `raw` - Reference to original customer object
-
-**For Unauthenticated Customers:**
-- `credentials` - Username information
-- `raw` - Reference to original customer object
-
-### geolocation
-
-**Type:** Object (Read Only)
-
-**Description:** Geographic location information:
-- `countryCode` - Two-letter country code
-- `latitude` - Geographic latitude coordinate
-- `longitude` - Geographic longitude coordinate
-
-### pageMetaData
-
-**Type:** Object (Read Only)
-
-**Description:** SEO and page metadata management:
-- `title` - Page title
-- `description` - Page description
-- `keywords` - Page keywords
-- `pageMetaTags` - Collection of meta tags
-- `addPageMetaTags(pageMetaTags)` - Method to add meta tags
-- `setTitle(title)` - Method to set page title
-- `setDescription(description)` - Method to set page description
-- `setKeywords(keywords)` - Method to set page keywords
-
----