The ReCharge Theme Engine gives you control to create a tailored customer portal experience for your store. In this tutorial, we demonstrate a walkthrough of a Theme Engine build and how you can adopt this build into your own ReCharge customer portal. It is not advised to follow this tutorial verbatim when adopting into your theme, but used as a starting point if you are having trouble understanding the ReCharge Theme Engine.
You can download the example starter template for your own use.
To view this implementation in action, view our demo store.
Before you start
- You will need access to the ReCharge Theme Engine. Visit ReCharge Theme Engine to learn more.
- It is not advised to follow this tutorial verbatim when adopting into your theme, but used as a starting point if you are having trouble understanding the ReCharge Theme Engine. We encourage you to use the tech stack you are most comfortable with.
Most of the tutorial will focus on three pages: subscriptions.html, subscription.html, and onetime.html. These pages allow you to view all of your subscription and one-time items, as well as manage and update these products. The build featured in this tutorial will focus on a frontend approach and use modals plus AJAX for the majority of updates. Three files were created to handle the layout and functionality in this implementation: _recharge.css, _recharge.js, and _modal_base.html.
_recharge.css contains all of the CSS classes used throughout the build. It is built on top of _styles.css, which is ReCharge’s default CSS file to handle basic layout and structure styles. Classes have been included to display the modals that are built, containers with outlines/shadows to group similar objects, primary and secondary fonts/buttons, and margin/padding classes to add dynamic margins or paddings to various elements. The file used in the tutorial has been kept very minimal so you can update or override your theme with the CSS or framework that makes sense for your site.
_recharge.js contains the bulk of the new functionality added throughout this build to support updating the products through modals on the frontend. The file is used to build a ReCharge object, which is actually an object of objects that is used to support the actions we implement throughout the site. On initialization, the ReCharge object does many things such as setting the customer hash token, loading jQuery, and creating jQuery listeners. Once the ReCharge object has been initialized, the page is now set up to handle the actions that have been implemented to update the subscriptions and one-time products.
The different sub-objects of the ReCharge object are outlined below:
Utils contains utility functions that are used by other parts of the ReCharge object.
Actions contains functions to wrap jQuery’s AJAX function. There are functions for GET, POST, PUT, and DELETE calls included. These functions couple with the Map property in the Modals sub-object to determine where to route the response of the AJAX call.
Endpoints contains convenience functions that return the theme API endpoint for each modal action.
Schemas contains convenience functions that return the schema needed for the request objects endpoint when retrieving data for each modal action
Modals contains the logic for displaying/hiding modals and processing them when submitted. We use a mapping object to map which modal goes with which property class inside the Modals sub-object. The map object is found in ReCharge.Modals.Utils.Map. The keys in this object will represent the div id of the modal, while the value will represent the class name inside ReCharge.Modals that should be called.
When we initialize the ReCharge object, we set three jQuery listeners that fire when a div is clicked that has the data-rc-modal attribute. The different actions are determined based on the value of this attribute.
- [data-rc-modal="open"] – Handler when a modal is opened. Each div that has this property will also have a data-rc-data property that contains an object of values needed to process the modal. There should always be an id property in this object. The id property signifies the id of the modal to open as well as provide the key to use to map the modal to the proper function handler. Other properties such as customer_id, address_id, etc. can also be included based on the type of modal being opened. This handler will also call the mapped modal’s onOpen function for further processing.
- [data-rc-modal="close"] – Handler when a modal is closed. Typically will be present in the divs for the modal’s cancel button as well as the div for the corner X on the modal.
- [data-rc-modal="submit"] – Handler when a modal is to be processed. This handler will call the mapped modal’s onSubmit function for further processing.
There are three private variables that are created to use throughout the lifecycle of the modal. Each of these variables are set when a modal is opened and reset to null when the modal is closed. Because of these variables being used, the page can only support one modal opened at a time. If multiple modals at one time are necessary, you will need to manipulate the positioning of these variables so they live on the modal itself instead of globally in the Modals object.
- _modal – This variable holds the currently opened modal. This variable will be set to the jQuery selector of the top level div of the modal when the modal open action is fired. When the modal close action is fired, this variable will be set to null.
- _data – This holds the properties relevant to the currently opened modal. This variable will be set to the value of the data-rc-data attribute on the clicked div when the modal open action is fired. When the modal close action is fired, this variable will be set to null.
- _name – This holds the object name of the currently opened modal. This variable will be set when the modal open action is fired and will be set to null when the modal close action is fired.
Each action has a set of functions that are used to handle the various states when opening, closing, and processing a modal.
- onOpen – This is called when opening a modal. It will typically be used to make an AJAX call to the server to retrieve the data necessary to populate the form of the modal.
- onSubmit – This is called when processing a modal. It will typically be used to make a put or post call to the server to update or create subscription and one-time items.
- getCallback – This is a callback function that is linked to the onOpen function. If onOpen makes an AJAX call, the response will be returned to this function for further processing. This is typically where you will fill in the form data tied to the modal and make the jQuery call to open the modal.
- putCallback – This is a callback function that is linked to the onSubmit function. If onSubmit makes an AJAX call, the response will be returned to this function for further processing. This is typically where you will display a toaster to alert the user of the status of the request as well as close the modal and update any content on the page.
- updateContent – This is the function to use when needing to update content on the page due to a modal update. This function will typically be called in the putCallback.
_modal_base.html contains the skeleton for all modals that are created. The file uses the CSS we outlined in recharge.css to build the modal and the actions we created in recharge.js to display or hide the modal. Each modal will have 3 block statements to populate when being created.
- modal_id – This contains the id of the top level div for the modal. This id is used when mapping the modal to the correct function handler in recharge.js.
- modal_title – This contains the title of the modal. This text will show up in the header of the modal when it is displayed.
- modal_body – This contains the content of the modal. This text will typically contain the form that is used to update subscription or one-time properties.
With an explanation of the build design explained, we will now iteratively implement the customer portal. First we will create our new theme and set up a few helper files that we use consistently throughout the build. Then we will walk through each page individually by first updating the layout, and then implementing the button actions.
- Part 1: Base Files
- Part 2: Page Files
- Create your base files.