Introduction
So far we have used Demandware pipelets to implement common functionality in a Demandware storefront: the GetProduct pipelet. In this lesson you will learn how to create your own script pipelets by writing custom Demandware Script files.
Demandware Script files have an extension of .ds and are stored in the /cartridge/scripts directory.
Script files like Pipelets, can have input and output parameters for data manipulation. The example below shows input/output parameters from a
‘GetProduct’ script:
When you create a new script file, the file will be preconfigured for scripting. The example below shows a brand new script file:
156 Input & Output Parameters
As noted previously, input and output parameters are configured within the script text. The script text below is an example of an input parameter that is called
‘ProductID’ which takes in a string value while the output parameter is called
‘Product’ and returns a product object:
When you first create a script file, the input and output parameters are commented out with a *- so you will need to delete the minus sign for the Demandware
application to read the parameters:
For input/output data types, you can use TopLevel package classes such as String, Number, Object, etc. You can also specify any other data type as long as you fully qualify it: dw.catalog.Product. In the following snippet the TopLevel.Object data type allows you to avoid having to qualify the object you are returning:
@output Subscription : Object
@output Product : dw.catalog.Product Must fully qualify this output type
Importing
When working with script files, if you access Demandware Script packages or classes other than TopLevel, you will need to import them in the script using the following syntax:
importPackage( dw.system );
You can import a single class, if you wish:
importClass( dw.system.Logger );
You can import a custom script from the same cartridge as the current script you are writing:
importScript( "common/libJson.ds" );
If you are accessing a script in another cartridge, make sure you specify the cartridge prior to the script name as the system will not look for further scripts with the same name in the cartridge path:
importScript( "<cartridge name>:[folder/]utilities.ds" );
157
Of course, you can always fully qualify the access to a specific class and avoid importing that package/class.
Using the Script Editor
You can turn on line numbers on the script by right-clicking the gray column on the left side of the editor and selecting the Show Line Numbers checkbox:
The editor offers auto-complete capabilities and syntax checking: use these tools to minimize coding errors. Studio will automatically generate code hints when you click Ctrl+Spacebar:
Warnings will appear for unknown methods after you save the file:
Syntax errors will be indicated as follows after you save:
The Script Editor allows you hover over the warning or error icon to get more precise information about the offending usage:
158 Scripts and Cartridge Path Relationship
Although script pipelets can reference scripts in the same cartridge or from dependent cartridges, scripts are NOT searched using the cartridge path, unlike pipelines. A script is expected to be in the cartridge of the current executing pipeline unless the cartridge is explicitly stated in the ScriptFile configuration property. In the figure below, the solutions cartridge, product directory (under scripts), GetProduct.ds script will be used:
Of course, this means that you will need to add the solutions cartridge to the
cartridge path so the script is found. In which order the solutions cartridge appears in the path is not relevant from the point of view of script access. However, the order of cartridges is relevant for executing pipelines and templates, in which case the first matching file found is used.
The ScriptLog Output
Every script pipelet used in a pipeline comes with a default Dictionary Output property called the ScriptLog, of type String:
You can write to the ScriptLog output within your script by using the
TopLevel.global.trace(msg : String , params : Object ...) method which uses Java MessageFormat. While this capability exists in the platform as a way to write debug or error messages to the pipeline, its use is not recommended at this time. We suggest you use the dw.systeml.Logger API to write to log files instead. This API is covered later.
159 Run the Create a Script Pipelet activity.
Demonstrate how to create a new script pipelet. Explain the commenting-out of input and output parameters and the PIPELET_NEXT and PIPELET_ERROR commands.
To create a new script pipelet, follow these steps:
1. Open the pipeline you wish to add the script pipelet to.
2. Drag a new script node onto the workspace over the transition node where you want your script to execute. Be sure the transition node turns red before releasing your mouse over the transition node.
3. In the Script File window, select the cartridge you want to store your new script file.
4. Type <scriptname.ds> or <directory/scriptname.ds> in the Script Name field:
160
5. Click OK.
6. To begin editing the script file, double-click on the new script node. The script file will open up in the workspace using a default script code template:
This script code template can be found in UX Studio under Window Preferences
Demandware UX Studio Generation Templates. Here you can customize both script and ISML generation templates to suit coding guidelines at your project.
161 7.2. Exercise: Creating a Script Pipelet
1. In the ShowProduct pipeline, remove the GetProduct Demandware pipelet.
2. Drag a Script Node from the palette onto the same location as the removed pipelet, and complete the dialog as follows:
a. Select your cartridge to store the script.
b. For Script Name, enter product/GetProduct.ds.
3. Connect the new script pipelet to the start node and the interaction nodes the same as before.
4. Double-click the script node (a.k.a. script pipelet) to enter the Script Editor.
5. Modify the generated script code as follows or copy the code from the GetProduct.ds file in the solutions cartridge:
a. Input parameter ProductID of type String b. Output parameter Product of type Object c. Import the dw.system and dw.catalog APIs.
d. Use the ProductMgr.getProduct(args.ProductID) method to obtain the product, and store it in the args.Product variable.
e. If the product is not found (args.Product is null), write a message to the ScriptLog:
i. trace("The product {0} was not found", args.ProductID);
ii. Return PIPELET_ERROR.
f. If the product exists, return PIPELET_NEXT.
6. Connect the input and outputs of the script pipelet to pipeline dictionary variables by using the pipelet properties view as shown:
162
7. Run the pipeline with a valid product in the query string: ShowProduct-Start?pid=P0048.
8. Verify that the product name appears as before.
9. Modify your productnotfound template so that it displays the contents of the pdict.Log.
163