As you might have noticed, our project came with only 3 cartridges. Let’s examine them a bit just so you understand what is important right now and what we can leave for later when needed.
As mentioned before, the app_storefront_base cartridge is the most important of all cartridges because all the reference SFRA base code and functionality are implemented there. Also, remember to never modify anything inside this cartridge.
You might be wondering why we keep insisting to never touch this cartridge. Imagine that this cartridge is used by all other cartridges as reference. Nw imagine that you have 2 custom cartridges that, for example, make use of a certain file inside app_storefront_base.
If you modify the file inside app_storfront_base, the changes will be reflected to all cartridges that reference it.
Now imagine that one of the custom cartridges is expecting this change. So far so good, right? But now imagine that the 2nd custom cartridge does not expect that change and, in fact, this modification will cause unexpected behavior to the custom cartridge code and something might break and even worse, the client can/will lose money because this behavior is affecting the site.
Now let’s check each folder inside a cartridge and understand what are they used for and what to put inside of them.
A cartridge is fully contained in one directory. Every cartridge has specific sub-directories where certain file-types must be stored. For instance, you must store all Controller files in a controllers folder.
All folders are placed inside a cartridge folder, as simple as that.
When you need to add new functionality to your storefront site the default approach is to create a new cartridge in your project. The base cartridge, app_storefront_base, has all of the code needed for an SFRA storefront to work in Commerce Cloud Digital. It contains:
There are 2 ways of creating a new cartridge: manually or using the sgmf-scripts node package. During this training, we will show you how to create it manually since it is a very simple process.
There are essentially 2 mandatory files:
Open your app_storefront_base cartridge and check the file named .project. You will see it looks like below:
Create a new folder inside the cartridge folder and name it, for example, app_storefront_custom. Make a copy of the .project you opened inside app_storefront_base and paste it inside your new folder
Your new cartridge needs an identical file, only changing the content of the name tag to the name of your new cartridge.
Same process for the .properties file. Check the one in app_storefront_base, copy to the correct location and replace all app_storefront_base occurrences by the name of your cartridge. At the end, it should look like below.
Whenever you create a new cartridge to add new functionality, it is critical that you respect the same folders’ structure that you see in the app_refapp cartridge, otherwise things probably won’t work.
When we say path, consider a form field with all cartridges that will be used in the project separated by a colon. Every site has its own path.
Uploading your code to the Sandbox is a mandatory step for your code to work on your storefront but it is not the only one. For a site to use a cartridge, you must add the cartridge to the path of the site in Business Manager.
In order to do that:
There are hundreds of cartridges out there for us to use, so we don’t have to reinvent the wheel and very often your project will need some of them.
SFCC has a list of more than 300 cartridges for you to use. To use it:
When a call is made to a file, your sandbox looks for the file starting with the first cartridge listed in the cartridge path. For example, if a call is made to the productDetails.isml file and that file is located in two cartridges that are both in the cartridge path, the first one it finds will be used.
Administrators/developers use WebDAV to manage files and folders on B2C Commerce servers.
Whenever you are unsure if your file or modifications in your file were uploaded to your sandbox, you can use this tool to verify.
Let’s use it to make sure all your cartridges are indeed in the sandbox.
Create a new cartridge and make it work. Repeat all the steps and create a new cartridge called app_storefront_base_test