> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ordergroove.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ordergroove.com/_mcp/server. # Tour of Subscription Manager v25 This article provides an overview of the design of v25 of the Subscription Manager for advanced users planning to make code customizations. It includes folder and file organization and tips for navigation. If you're new to developing on Subscription Manager, this article will help you find your way around the base template with confidence. *** ## Requirements This article is intended for developers on Subscription Manager 2.0 — shown as v25 templates and beyond. You should already have a thorough understanding of the fundamentals of HTML, CSS, and JavaScript. ### How to Tell What Version You're On Before the September 2024 release of v25, all Subscription Manager installations were on version 0, displayed in the Theme Designer as version 0.X.X. You can check your version by going to [Ordergroove](https://rc3.ordergroove.com/) > Subscription > Subscription Manager. *** ## Advanced Editor Layout The Subscription Manager has 5 folders in the advanced editor. This guide covers each folder and how its contents fit into the overall Subscription Manager experience. #### SM Tracking Code If you use the Advanced Editor to customize your Subscription Manager, be careful not to remove or modify elements that Ordergroove's tracking library depends on. These changes can disrupt analytics and customer behavior tracking. For guidance, see [Customize your Subscription Manager](https://developer.ordergroove.com/docs/sm-template-customization-tracking). ### Locales As you browse the `views` files, you'll notice that the Subscription Manager does not have text content written directly in the templates. Instead, Nunjucks templating code retrieves text from the locales files: ``` {{ 'locale_key' | t }} ``` That code looks for the key `locale_key` in the locale file corresponding to the current language. For example, if `locale_key` represents "Hello!" in English, you would find `"Hello!"` as the value in locale files starting with `en` (the code for English). In locale files starting with `fr`, you would see `"Bonjour!"` instead. When a user loads the page in a supported language, all Subscription Manager content will be filled with the appropriate text. Out of the box, English, French, and Spanish are available. If a matching language isn't found, the SM will use the first available language. You can add as many languages as you want, but ensure translations are added for all locale keys to avoid blank spaces. Translations used only for accessibility (e.g. hidden labels) are prefixed with `a11y`. ### Views The views folder holds `.liquid` files with Nunjucks-syntax templating code. Our custom implementation of Nunjucks is built to maximize readability and ease of development without compromising performance. The views folder is organized into subfolders representing different sections of the SM and their functionality. The diagram below shows some of the basic sections, which correspond to files and folders: Tips for navigating the `views` folder: 1. Check the diagram above to locate the section or feature you're looking for. Check that folder and its files. 2. In some folders, `main.liquid` is the entrypoint — it's the file referenced by `include` in other folders, and all other files in the folder branch out from it. * `item-level-actions` and `order-level-actions` are exceptions — these features generally have buttons in the `order-item` and `order` folders respectively, which include the corresponding file. 3. Most actions open a dialog for the user to confirm and make selections before the API request is sent. Sometimes the button and dialog are in the same liquid file; sometimes they aren't. * If an action file has `dialog` suffixed, it contains only the dialog, not the button that opens it. If it does not have `dialog`, it should contain both. Tips for developing in v25: * The Subscription Manager files have global scoping, so ensure variables are defined before use and not null when accessing object properties. At the beginning of every file in v25, a comment specifies required non-null variables and required-but-nullable variables. If you change where a file is included, verify that all required variables are already defined. * The base template uses attributes and custom elements to add special interactivity. Removing or editing these attributes may break SM functionality. * Classes are used only for styling — you can freely modify them in conjunction with the `less` files in the `styles` folder. * Some elements have `data-testid` defined for Ordergroove's internal testing purposes. You can remove these in your version of the template if desired. ### Styles The styles folder contains all `.less` files with CSS styling for the Subscription Manager. The folder structure mirrors `views` to make it easy to find the styles corresponding to a particular liquid file. The one additional folder compared to `views` is the `components` folder, which contains styling for custom elements defined in `script.js` and styling for HTML elements used across the SM (such as buttons). Other folders contain section- and feature-specific styles that correspond to folders and files in `views`. Styles relating to a single liquid file are in a corresponding `.less` file with the exact same name and path. Styles spanning multiple liquid files in the same folder share a more generically-named file. Several files outside the subfolders modify styling across the entire Subscription Manager: * `design-tokens.less` — holds Less variables for colors, sizes, radii, and more. For simple color changes, start here to see if a variable covers your customization. * `default-theme.less` — holds styling for elements that create the "theming" of the SM across components and sections (e.g. info box styling). * `main.less` — the entrypoint for Less files into the Subscription Manager. It must import all Less files used for styling. If you add a Less file, add it here. * `page-title.less` — contains styling for the title block of the Subscription Manager. * `page.less` — contains styling not limited to the SM, but targeting other elements on the page the SM is loaded on. Generally, you probably don't want to edit this file. * `reset.less` — reduces browser inconsistencies. * `utility.less` — holds basic utility classes used across the SM for font size and other styling. * `variables.less` — used by the basic editor to override values in `design-tokens.less` for quick, code-free theme changes. This file is automatically generated by Ordergroove when you make changes in the basic editor. ### Scripts The scripts folder holds only `script.js`. The beginning of the file, under the "Subscription Manager loading" header, contains key functions for the SM to load. **Do not edit these.** The "Custom Elements" section introduces key components used throughout the SM to encapsulate interaction-heavy functionality. The end of the section defines them as [custom HTML elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements). You are unlikely to need to modify this section. The final section is "Utilities," which contains utility functions used elsewhere in the scripts file and in the SM. This is where you should add any custom JavaScript functions. You can reference JavaScript functions in `liquid` files using the `js` filter. For example, a custom function `callNewApi` could be added as an `onClick` method with the code: ``` @click="{{ 'callNewApi' | js }}" ``` ### Controls The controls folder contains `theme-settings.json`, which surfaces functionality options to the basic editor. You typically don't need to edit this file for customizations, but you may encounter its values in the template (e.g. `{% if 'show_upgrade_to_subscription' | setting %}`). It's up to you whether to maintain that functionality for basic editor users in your organization, or remove the reference to disable the basic editor knob.