Cartridges

Business functionality in B2C Commerce is organized in cartridges.

A cartridge is a mechanism for packaging and deploying program code and data. Use cartridges to extend business functionality or integrate with external systems. A cartridge can deliver generic or application-specific functionality.

  • Generic cartridges: contain reusable business functionality that can be deployed to many sites.
  • Application-specific cartridges: designed to provide functionality that is specific to the needs of a particular ecommerce site.

Add a cartridge for functionality that is:

  • Generic: you want to reuse functionality among multiple projects.
  • Large and self-contained: you want the functionality self-contained for easier maintenance.

New functionality doesn't always require a new cartridge.

Cartridges can contain:

  • Controllers
  • Templates
  • Scripts
  • Form definitions
  • Static content (images, CSS files, and client-side JavaScript files)
  • WSDL files

You configure which cartridges are in use by entering a list of those cartridges in Business Manager. The order in which cartridges are listed matters. The list is basically a classpath, with the cartridge as the class. If you want to overwrite files with a particular cartridge, put the cartridge at the end of the list. Use the code upload version directories to change the active directory.

Download or view cartridges using a browser or a WebDAV client.

Use the following URL convention:

An example of <organization> is Sites, for example, https://ddd.ddd.dw.demandware.net/on/demandware.servlet/webdav/Sites/Cartridges

If you want to use WebDAV to access cartridges, the name of the directory that contains the cartridges can contain no more than 50 characters.

The currently selected code version is stored in this file:

When using WebDAV to access your cartridges, you’re prompted to enter a username and password. Use your Business Manager username and password.

There are other WebDAV URLs for accessing catalog and content library assets. Select Administration > Site Development > Development Setup for WebDAV access via URL references.

Using WebDAV is one way to access a server-based file system to verify if the correct code has been uploaded. Another way is via the Business Manager.

Common problems include:

  • The server connection was disabled.
  • The server didn’t access your cartridge.

A best practice is to maintain cartridge code in a source control system available to developers. However, in rare cases, it’s useful to download a cartridge from a working instance.

Downloading the cartridge doesn't download the related site data. To download that data, use Site Import or Export.

  1. Select Administration > Site Development > Code Deployment.

  2. Click the code version you want to download.

    Usually you want to download the currently active code version, indicated by a green check mark in the Active column.

  3. On the Version Summary page, click Download.

After creating a cartridge, upload it to a server and register it to a site. You can register a cartridge to multiple sites.

  1. Select Administration > Sites > Manage Sites > site.

  2. On the Settings tab, enter one or more cartridge names in Cartridges, separated by colons.

    Cartridges take precedence in order from left to right.

  3. Click Apply.