The Cartridge Path Editor opens a colon-separated cartridge path from local XML as an ordered list. Drag entries into place, add linked cartridges or type a name, and remove entries. The top entry loads first. Every change is an edit of the XML document, so you review, save and commit the XML as usual
Sandbox 01
version2
site.xml
RefArch Cartridge Path (5)
Global scopeOpen the editor
Open the local XML file
Open a site's site.xml with a <custom-cartridges> element, or a preferences.xml with <preference preference-id="CustomCartridges"> for the Business Manager cartridge path
Click the gutter icon
A cartridge icon appears in the gutter on that element. Hover it to see Edit RefArch Cartridge Path (4), or Edit BM Cartridge Path (2) in preferences.xml, with the number of cartridges on the path. The site ID comes from the site-id attribute of <site>, or from the folder of the file when the attribute is missing
Edit the path
The editor opens in its own tab, for example "RefArch Cartridge Path (4)" or "BM Cartridge Path (2)". Clicking the icon again selects that tab. The count in the tab title follows your changes
The editor
The header shows the path's title, for example RefArch Cartridge Path or Business Manager Cartridge Path, its count and the XML file relative to the project. On the right:
| Control | What it does |
|---|---|
| Saved, Unsaved, Update failed | Whether the XML document has unsaved changes. Update failed stays for a few seconds when a change could not be written |
| Open XML | Opens the XML file at the cartridge path element |
| Refresh | Reads the XML and the linked cartridges again |
In cartridge path
The left list is the path, in load order. Each entry shows its position, its name and where the cartridge is in the project, for example storefront • cartridges/app_custom: the content root, then the folder inside it. A name that matches no linked cartridge shows Not linked to this project and the not-linked icon
| Action | How |
|---|---|
| Reorder | Drag an entry. A line shows where it goes. Move Up and Move Down in the list toolbar move the selected entry one step |
| Add a name | Type it in Add cartridge by name… and press Enter or Add. It goes to the top. The cartridge doesn't need to be linked to the project |
| Remove | Remove from Cartridge Path in the list toolbar. The cartridge's files stay in the project |
| Copy | Copy Cartridge Name copies the selected name and confirms with Cartridge name copied |
| Filter | Filter cartridges in path… narrows the list by position, name or location. Dragging still drops at the right place in the full path |
Enter one name at a time, without spaces, :, <, > or &. Adding a name that is already on the path selects its entry instead of adding it twice
Linked cartridges not in path
The right list shows the cartridges linked to the project that the path doesn't use yet, see Cartridges & Modules
| Action | How |
|---|---|
| Add at a position | Drag the cartridge into the path list. The line shows where it goes |
| Add at the end | Double-click it, or select it and use Add to Cartridge Path in the list toolbar |
| Add all | Add All appends every cartridge in this list to the path |
| Filter | Filter linked cartridges… narrows the list by name or location |
The list is read again when you come back to the tab, so a cartridge you have just linked shows up there. Refresh reads it at once
Saving and undo
The editor changes only the cartridge path value in the open XML document. The rest of the file, its formatting and the whitespace around the value stay as they were. A self-closing element such as <custom-cartridges/> gets the path as its content
Each change is one undoable command named Edit Cartridge Path, so Undo in the XML editor reverts it. The document then stays unsaved, and the status reads Unsaved, until the IDE saves it with your other files
<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. If the element moves because you edited the file above it, the tab keeps following it
The XML and the instance
The editor edits your local XML. It doesn't change the cartridge path in Business Manager or upload the cartridges. Import the site data into the instance, or change the path in Business Manager, when you are ready, and deploy the cartridges the path names
A local site.xml also feeds the Local project section of Site Scopes. Edits to the file are picked up automatically, so with that site selected, code insight follows the new order
Troubleshooting
| Symptom | What to do |
|---|---|
| There is no gutter icon | The file must be named site.xml or preferences.xml and contain the element above, and the plugin needs an active license or trial. In preferences.xml the icon is only on the preference with preference-id="CustomCartridges" |
| "The cartridge path changed or was removed. Reopen the editor from the gutter icon." | The element is no longer in the XML. Open the editor again from the current gutter icon |
| "Could not update the cartridge path in site.xml." | The file is read-only or the IDE could not write to it. Make it writable, for example check it out in your VCS, and try again |
| "Enter one cartridge name without spaces, ':', '<', '>', or '&'." | Type one name, with no separators |
| A cartridge shows Not linked to this project | The name is on the path but no linked cartridge has it. Link the cartridge in Cartridges & Modules if you work on its code |