This article will guide you through the process of creating branded Nop themes.
| Table of Contents |
|---|
Prerequisites
NOP repository has been setup locally. See /wiki/spaces/CS/pages/2060812311 for more details
Our
axcommerce-theme-generatoris installed globally. See its installation docs for more details.
Creating a new theme
In this guide we’ll be creating a theme for a hypothetical client called “Example Mountain”.
Creating the scaffold
To start off, the scaffolding of a theme needs to be created. That can be done by doing the following:
...
There should now be a new directory populated with some starter files. For this example, the directory created was located at src/Themes/ExampleMountain. If you look at the theme.json file inside that directory you should see some of the prompt answers you provided.
Creating environment files
There are some JSON files that contain various options specific to each environment. They exist in src/Presentation/Nop.Web/config/env. We need to create a new one for our client environment, even if it doesn’t need any custom options yet.
Duplicate the
src/Presentation/Nop.Web/config/env/env.dev.jsonfile and rename the new fileenv.[themename]-test.json. In our example, it’d beenv.examplemountain-test.json.Reach out to your onboarding buddy / manager to learn where to find the values needed to populate the file.
Reach out to your manager to get the ZIP package in LastPass updated to include the new file.
Setting up the assets
Asset generation
It’s possible to automatically generate some of the required image assets using other image assets. To do so:
...
| Tip |
|---|
Make sure to remove the directory containing the original, uncompressed images to avoid needlessly enlarging the source code repository |
Favicons
You can skip this step if you’ve used the Asset Generation method detailed above.
...
favicon-16x16.png
favicon-32x32.png
favicon-48x48.png
favicon.ico
Images
You can skip this step if you’ve used the Asset Generation method detailed above.
Fonts
(Optional) If the client has requested the use of custom fonts, we specify those inside src/Themes/[your theme name]/Content/scss/_typography.scss. Any font files should be placed inside src/Themes/[your theme name]/Content/fonts.
Asset Optimization
We need to optimize the image assets that we have to ensure optimal site performance.
...
Use your tool(s) of choice to ensure the theme’s assets pass validation outlined in the Theme validation section.
Making theme customizations
Colors
Using the information from the Jira ticket, update the color values inside src/Themes/[your theme name]/Content/scss/_colors.scss.
Theme options
Depending on the choices the client has made, you will need to update & enable code in src/Themes/[your theme name]/Content/scss/_theme.scss to accomplish what is requested in the Jira ticket.
...
Learn more about this in the theme designer documentation.
Custom CSS
We try to avoid custom CSS rules in client themes to reduce the maintenance cost of theming but sometimes it’s unavoidable. If that’s the case:
Update
src/Themes/[your theme name]/Content/scss/_theme.scsswith the custom styling.Be sure to add comments by the styling explaining why it’s needed and including the Jira ticket number that contains the request.
Theme validation
To validate that a theme meets the requirements we impose on themes, we’ll do the following:
From the
src/Themesdirectory, executeaxcommerce-theme-generator validatethemeYou’ll be prompted for the theme directory name, in our case that would be
ExampleMountainChecks will be run and any issues will be logged to the terminal. If there are issues, correct them and re-run the validation until it passes. If you run into any issues, please reach out to your onboarding buddy
Working on themes
Viewing local themes on a production NOP instance
There is a way to load local themes onto production NOP instances allowing for much faster iteration times without needing to spin up a local NOP instance and mess with admin configuration settings.
For information on how to setup this functionality, please refer to the Aspenware Theming Tools documentation.
Known Issues
No automatic hot-reloading, you must manually click the refresh icon in the theme tools popup
There seems to be some issues with port numbers on mac – if you encounter any issues please reach out to your onboarding buddy
Viewing local themes on a local NOP instance
Setting the theme in the Admin section
Once running NOP, sign into your account.
In NOP, click on the Administration option under the My Account menu.
If the option is not visible then your account is lacking the admin role. Reach out to your manager or onboarding buddy for assistance.
Click on Configuration > Settings > General settings in the sidebar.
Change the Default store theme to the theme you desire then click the Save button in the top right.
...
The theme should now be visible if you go to the site’s homepage.