Skip to Content

Cartridge Path Editor

Reorder, add and remove the cartridges of a local site.xml or Business Manager preferences.xml in a list window that opens from the XML element

The Cartridge Path Editor opens the colon-separated cartridge path of a local site.xml or preferences.xml as an ordered list in its own window. The top entry takes priority. Every change is an edit of the XML document

The lens on the cartridge path of a local site.xml opens the path as an ordered list. Drag entries into place or drag a linked cartridge in, and every change is an edit of the XML document that you save like any other file

Open the editor

Open the local XML file

Open a site's site.xml with a <custom-cartridges> element directly under <site>, or a preferences.xml with <preference preference-id="CustomCartridges"> for the Business Manager cartridge path

Click the lens or the gutter icon

A Code Vision lens above the element reads Edit cartridge path: RefArch (4), or Edit cartridge path: Business Manager (2) in preferences.xml. The cartridge icon in the gutter, Edit Cartridge Path, does the same

Edit the path

The editor opens in its own window, for example RefArch Cartridge Path (4)

The window doesn't block the IDE. Each XML element has one window, and clicking the lens or the icon again brings it to the front. Windows for other sites open side by side

The lens and the gutter icon need an active license or trial. Turn the lens off in Settings › Editor › Inlay Hints › Code vision › SFCC cartridge path, and the icon in Settings › Editor › General › Gutter Icons › SFCC cartridge path

The editor

The top row shows the XML file and these controls:

ControlWhat it does
Saved, UnsavedWhether the XML document has unsaved changes. It changes when the IDE saves the file, not when you edit the list
Applying...A change is being written to the XML
Update failedA change could not be written, or the element is no longer in the XML. The message below says why
Open XMLOpens the XML file at the cartridge path element and hides the window, see Back to the XML
Refresh Reads the XML and the linked cartridges again

Current path

The left list is the path, in load order. Each row shows the position, the name and where the cartridge is in the project, such as cartridges/app_custom. A name that matches no linked cartridge shows Not linked to this project and the not-linked icon

ActionHow
ReorderDrag an entry. Alt+Up and Alt+Down move the selected entry one step
RemoveThe remove icon on the row, Delete, or Remove app_custom in the context menu. The cartridge's files stay in the project
CopyThe copy icon on the row, Cmd+C (Ctrl+C) or Copy app_custom in the context menu
Add a nameType it next to Add by name: and press Enter or click Add. It goes to the top and doesn't need to be linked to the project
FilterFilter cartridges in path... matches the position, the name or the location. Dragging in a filtered list still drops at the right place in the full path

Adding a name that is already on the path selects its entry instead of adding it twice

Available cartridges

The right list shows the cartridges linked to the project that the path doesn't use yet, in name order, see Cartridges & Modules

ActionHow
Add at a positionDrag the cartridge into the path list
Add at the endThe + icon on the row, Enter, or Add int_paypal to cartridge path in the context menu
Add allAdd All appends every cartridge in this list to the path
CopyThe copy icon on the row or Cmd+C (Ctrl+C)
FilterFilter linked cartridges... matches the name or the location

A cartridge you link while the window is open shows up on its own. All linked cartridges are already included. means every linked cartridge is on the path

Saving and undo

The editor changes only the cartridge path value in the XML document, written as names joined by :. The rest of the file stays as it was

Each change is one Edit Cartridge Path command, so Undo in the XML editor reverts it

site_template/sites/RefArch/site.xml · after the example above
<custom-cartridges>app_custom:plugin_wishlists:int_paypal:app_storefront_base:int_reviews</custom-cartridges>

Edits you make in the XML yourself show up in the list right away

Back to the XML

After Open XML, the window keeps its filters and selection, and the lens or the gutter icon brings it back as you left it

The XML and the instance

The editor doesn't change the cartridge path in Business Manager or upload the cartridges. Import the site data, or change the path in Business Manager, and deploy the cartridges the path names

A local site.xml also feeds the Local project section of Site Scopes. With that site selected, code insight follows the new order

Troubleshooting

SymptomWhat to do
There is no lens or gutter iconThe file must be named site.xml or preferences.xml and contain the element above, without child elements. In preferences.xml only the preference with preference-id="CustomCartridges" has them. Check the license and the SFCC cartridge path settings above
"The XML target changed or was removed. Refresh the editor or reopen it from the updated XML."Open the editor again from the current lens or gutter icon
"Could not update the XML. Check that the file is writable and the cartridge-path element is valid."Make the file writable, for example check it out in your VCS, and try again
"Use a cartridge name without whitespace, colons, or XML markup characters."Type one name, with no separators

On this page