Get to Know B2C Commerce Cartridges

After completing this unit, you’ll be able to:

• List three ways you can use a cartridge.
• Explain why you need at least one custom cartridge to implement a storefront.
• Describe where you can find the code version number.
• Explain the purpose of the cartridge path.

Vijay Lahiri is a senior developer at Cloud Kicks, a company that specializes in high-end custom sneakers. He wants to develop a new Salesforce B2C Commerce storefront and needs to better understand how cartridges work in the context of the overall software development and delivery architecture. In fact, he wants the process of building cartridges to be the easiest part of his job.

B2C Commerce developers like Vijay are all about creating and maintaining amazing storefront applications. These applications—a combination of client and server code—make online retail happen. They are based on a reference architecture such as the Storefront Reference Architecture (SFRA). These reference architectures provide an example of what a storefront should look like, and in the case of SFRA, a framework for site design. Picture software as a service (SaaS) and client/server.

A cartridge is a container for packaging and deploying program code and data. It’s structured in folders and subfolders for maximum efficiency. A storefront needs at least one cartridge, but typically it has multiple cartridges. You can use a cartridge to extend business functionality or to integrate with external systems. It can contain generic or application-specific functionality. Generic cartridges contain reusable business functionality you can deploy to many sites. Application-specific cartridges contain merchant-specific and site-specific functionality. Third-party cartridges provide functionality such as tax calculation or credit card processing, you can find them on the AppExchange.

Here’s what cartridges can contain.

• Controllers
• Form definitions
• Scripts
• Static content (text, images, CSS files, and client-side JavaScript files)
• Templates
• Web Services Description Language (WSDL) files
• Page Designer experiences (SFRA only)

Vijay must consider how he structures code and data within cartridges and decide how he wants to stack cartridges that he’ll deploy. He wants to make his cartridge creation, modification, and deployment processes consistent and organized as part of his overall application development process. The more attention to detail, the smoother his rollout to the storefront.

Here are the steps to take when working with cartridges.

1. Configure the development environment.
2. Download reference architecture cartridges.
3. Review and structure cartridge files on the local drive.
4. Define and test a cartridge-upload process.
5. Customize, extend, or overwrite cartridges.
6. Upload changes to the server.
7. Register cartridges in Business Manager.
8. Run the storefront application to test changes.

It’s best practice to extend or override the base cartridges to streamline the development process and ongoing maintenance.

Before Vijay gets started with cartridges, he makes sure his development environment is ready to go. Take a look at the Develop for Salesforce B2C Commerce trail to learn how he does this.

He needs an interactive development environment (IDE) to work in and a connection to a B2C Commerce sandbox instance. Most developers use an IDE such as Microsoft Visual Studio Code, IntelliJ IDEA, or Eclipse. The sandbox can be an on-demand sandbox or a POD-based sandbox in his realm’s secondary instance group (SIG).

A B2C Commerce instance is like a Salesforce org. Multiple instances make up a realm that includes a primary instance group (PIG) and a SIG. There are nine instances per realm: three for staging, testing, and deployment on the PIG; five sandbox instances for code development on the SIG; and one demo instance.

When Vijay’s cartridges are ready to deploy, he works with Linda Rosenberg, the Cloud Kicks administrator, to push his changes to the realm’s PIG.

B2C Commerce loads individual cartridges in a specific order, starting with cartridges that contain basic functionality, followed by increasingly customized functionality. This is called the cartridge stack.

This graphic illustrates a typical cartridge stack that’s based on SFRA.

At the bottom of the stack are the base cartridges, which are loaded first. They provide the foundation of the storefront application and are maintained by Salesforce developers. Partners and other developers can submit change suggestions via the development community.

Plugin cartridges, such as Apple Pay code, are loaded next. Finally, B2C Commerce loads the custom cartridges. In this case, the custom cartridges contain Cloud Kicks custom functionality and branding.

Vijay needs at least one custom cartridge to implement his storefront. Otherwise, the site would have no individual branding. A generic site won’t pique enough interest. In fact, each of his sites requires a custom cartridge to reflect a specific language, look, or functionality. He also needs country-specific, third-party cartridges to handle things like country-specific payment methods. When he creates a separate functionality-specific cartridge per brand or locale, he can reuse most of his cartridge stack for every storefront. This makes it easy to roll out general changes that affect all sites, or specific changes that affect only one or a few sites.

While the cartridge stack represents increasing levels of customization from bottom up, the cartridge path determines the order in which B2C Commerce identifies an element, such as a controller, template, or script file, to run. Cartridges earlier on the path (to the left) override the functionality of cartridges later on the path.

For example, Vijay wants to customize the cart process so there are fewer steps for shoppers to take. In the SFRA application, he creates a new cartridge called app-custom-cart-cloudkicks and within it a file with this path: cartridge/controllers/Cart.js.

To take advantage of SFRA capabilities, he extends his version of Cart.js to meet his business requirements without having to copy/paste the original code. Then he places the new cartridge before the base cartridge within the cartridge path. Now when B2C Commerce runs the storefront application, it runs the custom version first, which might also use code from the base version.

Here’s the cartridge path for the Cloud Kicks stack, which is the same as what Vijay configures in Business Manager in a later unit.

app-custom-cart-cloudkicks:app_custom_cloudkicks-us:plugin_applepay:plugin_comparison:app_storefront_base

Vijay builds each cartridge independently, and then uploads them to add them to the cartridge stack. He can change and upload cartridges independently as long as he develops using the same code version.

In this module, we assume you are a B2C Commerce developer with the proper permissions to perform these tasks. If you’re not a B2C Commerce developer, that’s OK. Read along to learn how your developer would take these steps in a sandbox instance. Don’t try to follow our steps in your Trailhead Playground. B2C Commerce isn’t available in the Trailhead Playground.

If you have a sandbox instance of B2C Commerce, you can try out these steps in your sandbox. If you don’t have a sandbox and you’re a customer or partner developer, ask your manager if there is a sandbox that you can use.

Here’s how to check your code version.

1. Open Business Manager in your browser.
2. Select Administration > Site Development > Code Deployment. 
3. Click the version of the code you want. (You can only have one code version active at a time.)

B2C Commerce uses this version to execute the cartridge code on a particular storefront. You can upload many cartridges to a code version, but the configured cartridge path for each site (including the Business Manager site) determines which cartridge runs.

You explored how cartridges are a key part of the B2C Commerce application development environment. You learned about the types of cartridges you can use, how they are stacked, and the order in which they are loaded. Next, you review the SFRA cartridges to learn how they are structured.

• Trailhead: Salesforce B2C Commerce On-Demand Sandboxes