Add Custom Cartridges
Implementing a site requires at least one custom cartridge. However, if you intend to create multiple sites, we suggest you create multiple custom cartridges. Each cartridge can separate functionality specific to a brand or locale, so that you can reuse most of your cartridge stack for a new site.
All available LINK and plug-in cartridges are on GitHub. Plug-in cartridges are in the SFRA project in GitHub. You can Include link and plug-in cartridges on your cartridge path and base path as you would any other cartridge in your stack.
app_storefront_base
cartridge or other provided
plug-ins. Keep your version of the app_storefront_base
cartridge and other
plug-ins up-to-date. By doing so, you ensure that you have the latest bug fixes and
performance improvements.Adding Custom Cartridges When sgmf-scripts
Is Globally Installed
If you globally installed
sgmf-scripts
through npm, follow these steps to add a
custom cartridge:
-
Create a folder for your project. For example:
mkdir mysite
- Navigate into the folder.
cd mysite
- Install the
sgmf-scripts
node.npm install sgmf-scripts
-
Use the
sgmf-scripts --createCartridge
command.sgmf-scripts --createCartridge app_custom_storefront
These directories and files are created in your folder:├── cartridges └── app_custom_mybrand └── cartridge ... ├── dw.json ├── node_modules └── package.json
- Install the dependencies required by the new cartridge:
npm install
sgmf-scripts --help
.
Adding Custom Cartridges When sgmf-scripts
Isn't Globally Installed
If you want to avoid globally installing sgmf-scripts
, follow these steps to add
a custom cartridge:
-
Create a folder for your project. For example:
mysite
.mkdir mysite
- Navigate into the folder.
cd mysite
- Install the
sgmf-scripts
node via npm.npm install sgmf-scripts
-
Use Node.js to call the
sgmf-scripts createCartridges
command.node node_modules/sgmf-scripts --createCartridge app_custom_mybrand
The following directories and files are created in your folder:├── cartridges └── app_custom_mybrand └── cartridge ... ├── dw.json ├── node_modules └── package.json
- Install the dependencies required by the new cartridge:
npm install
sgmf-scripts --help
.
Updating Your package.json
Because you're not modifying theapp_storefront_base
cartridge directly, Salesforce B2C Commerce provides a
mechanism to selectively override CSS styles and client-side JavaScript. In the
package.json file, the paths property lists every cartridge with CSS
and client-side JavaScript functionality customized in your site. When building your cartridge
stack, the paths
property lets you import functionality from CSS and
JavaScript files in other cartridges and selectively override it. When you use the
command-line compile
tool, it compiles the JavaScript and CSS across
cartridges. - Navigate to the top level of your custom cartridge. For example,
mysite.
-
Open the
package.json
file and modify thepaths
property. Thepaths.base
property points to the local directory containingapp_storefront_base
. Add properties for the cartridges you want to import functionality from.Example: adding
plugin_ratings
,plugin_reviews
, andapp_storefront_base
to a custom cartridge:"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/" } }
- Import the CSS files you want to include and override into the
my_repository/cartridges/my_cartridge/cartridge/client/default/myfile.scss file
.The following sample global .scss file inherits most of its styles from the base cartridge. The location of the base cartridge is defined in package.json. This example uses the
base
property defined in thepackage.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; }
- Use the path object to include JavaScript modules from other cartridges when you want
to inherit and override client-side JavaScript functionality.
The following example uses the path described by the base property to require in a client-side script in the base cartridge.
'use strict'; var base = require('../base/product/base');
After Creating Your Custom Cartridge
-
Upload Your Code to the platform. If you are
using the command line to watch and upload code, you can update your
dw.json
file. - Add the Cartridge to the Cartridge Path
- Disable Page Caching.
- Generate Search Indexes.
- View the Storefront.
Best Practices When Creating Custom Cartridges
- Create unit tests for models.
- Check for possible naming collisions between cartridges.
Anti-patterns:
- Don't override
pdict
variables. - Don't delete properties off the
pdict.
- Don't replace something in
pdict
with something else with a different signature.