Customize Cartridges
Learning Objectives
After completing this unit, you’ll be able to:
- List three things you can do with sgmf scripts.
- Describe how you can override the app_storefront_base cartridge.
- Explain how the global .scss file inherits styles.
- Describe how to include JavaScript modules from other cartridges.
Introduction
Vijay has been busy. He uploaded the Storefront Reference Architecture (SFRA) cartridges to the server and registered them. In Business Manager, he configured page caching and site URLs to speed development. Now he’s ready to work with SFRA to customize his storefront applications.
Create an SFRA Overlay Cartridge
Vijay wants to create an SFRA overlay cartridge to add some awesome new features that include a faster checkout process. Before getting started, he adopts an edit-free policy, so he won't need to find SFRA code changes from new releases and port them into his customized code.
He plans to customize SFRA without editing the app_storefront_base cartridge or other plugins, such as plugin_applepay. He doesn’t even need to change their names to ensure that he gets the latest security updates, bug fixes, and new features from Salesforce. He’s happy to know that SFRA will still work after a major release.
One way he can create an overlay cartridge is from the sgmf-scripts repository. Here’s what some of these scripts can do.
- Upload a file to a sandbox.
- Upload a cartridge.
- Run tests on certain files or directories.
- Compile css or js files.
- Lint scss or js files.
- Create a new cartridge structure.
These scripts are executable through the command line interface (CLI) that we covered in the previous unit.
Add Custom Cartridges to Your Application
Vijay can add custom cartridges to his application using sgmf-scripts and npx, a command-line utility bundled with npm (requires npm version 5.3.0 or later). If he wants to use sgmf-scripts in multiple projects, he can install it globally by executing npm install --global sgmf-scripts. This ensures that sgmf-scripts is installed once, instead of for every project.
To create an overlay cartridge, follow these steps, whether or not you installed sgmf-scripts globally.
- Open the command line.
- Create a project folder:
mkdir cloudkicks - Navigate into the folder:
cd cloudkicks - Create a new cartridge:
npx sgmf-scripts --createCartridge app_custom_cloudkicks - Install the dependencies required by the new cartridge:
npm install
├── cartridges └── app_custom_cloudkicks └── cartridge ... ├── dw.json ├── node_modules └── package.json
Customize CSS and JavaScript
Though Vijay can’t modify the SFRA base cartridges directly, he can selectively override CSS styles and client-side JavaScript. He might want to change the text color and font for certain discounts, or use JavaScript to create fun elements that get the shopper’s attention.
In the package.json file, the paths property lists every cartridge with CSS and client-side JavaScript functionality customized in his site. When he builds his cartridge stack, the paths property lets him import functionality from CSS and JavaScript files from other cartridges and selectively override them. The command-line compile tool compiles the JavaScript and CSS across cartridges.
Here are the steps to take.
- Open a command prompt.
- Navigate to the top level of your custom cartridge: cloudkicks-a
- Open the package.json file and modify the paths property. The paths.base property points to the local directory containing app_storefront_base.
- Add properties for the cartridges you want to import functionality from. For example, add plugin_ratings, plugin_reviews, and app_storefront_base to a custom cartridge.
This is how the code might look.
"paths": {
"base":
"../storefront-reference-architecture/cartridges/app_storefront_base/"
,
"ratings": "../plugin_ratings/cartridges/plugin_ratings/",
"reviews": "../plugin_reviews/cartridges/plugin_reviews/",
"applepay": "../plugin-applepay/cartridges/plugin_applepay/"
}
Vijay imports CSS files like this into his repository: my_repository/cartridges/my_cartridge/cartridge/client/default/myfile.scss
This sample global .scss file inherits most of its styles from the base cartridge. Vijay defines the location of the base cartridge in package.json. This sample file uses the base property defined in the package.json to import style sheets.
@charset "UTF-8";
@import "base/variables";
@import "bootstrap/scss/bootstrap";
@import "base/bootstrap_overrides";
@import "base/utilities/responsiveUtils";
@import "font-awesome/scss/font-awesome";
@import "flag-icon"; @import "components/menu";
@import "base/components/common";
@import "base/components/footer";
@import "components/footer";
@import "base/components/hero";
@import "base/components/notification";
@import url(https://fonts.googleapis.com/css?family=Source+Sans+Pro&subset=latin-ext);
body {
font-family: 'Source Sans Pro', sans-serif;
}
.modal-background {
display: none !important;
}
You can include functionality from one SFRA script module in another. Vijay uses the path object in the require() function to override client-side JavaScript functionality. For example, here’s how he uses the base property path with the require() function.
'use strict'; var base = require('../base/product/base');
Here’s what you can customize in SFRA via overlay cartridges.
| Element | Description |
|---|---|
| Hooks | Configure functionality that’s called at a specific point in the application flow or at a specific event. |
| Modules | Access JavaScript/Salesforce B2C Commerce script modules that conform to the Modules 1.1.1 CommonJS specification within the storefront script code. |
| Templates | Override a template by creating a new cartridge that contains a new template with the same name and relative path as the original template. |
| Models | A JSON object layer that converts proprietary B2C Commerce script API objects into pure JSON objects designed for the storefront. They also apply business logic for the storefront. |
| Controllers and Nodes |
Replace a base controller with custom code to:
|
| Forms | Persist form data during a session and store it in system objects or custom objects. |
| Plugin cartridges in the SFRA project on GitHub | Include plugin cartridges on the cartridge path and base path as you would any other cartridge in your stack. |
Cartridge Path Substitution
The cartridge path controls file lookup for your site and defines what code runs. B2C Commerce searches the cartridge from left to right when a specific controller, script, model, or ISML template is called via URL or code.
You can substitute the cartridge path file lookup with the require() function in these situations.
- Relative to the current file: require('./shipping') or require('../../util')
- Relative to the current cartridge: require ('~/cartridge/scripts/cart')
- From the beginning of the cartridge path: require('*/cartridge/scripts/util/array')
- Specific B2C Commerce API: require('dw/catalog/CatalogMgr')
- Specific module or cartridge: require('server')
Troubleshoot
When Vijay doesn’t see his changes on the server, he adds an empty code version and then reactivates the original code version. Here's how to do it.
- Open Business Manager.
- Select Administration > Code Deployment.
- Click Add and enter the name of your new code version.