This article will guide you through the process of creating branded Nop themes.

Prerequisites

• NOP repository has been setup locally. See https://aspenware.atlassian.net/wiki/spaces/CS/pages/2060812311 for more details

• Our axcommerce-theme-generator is 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:

1. Execute axcommerce-theme-generator buildtheme from within the src/Themes/ directory

2. You’ll be prompted to provide some bits of information:

   1. Resort Theme name in Title Case – This is the system name for the theme. We tend to name them after the client we’re creating the theme for. So for our example, we’ll use ExampleMountain

   2. Theme friendly name – This is the visible name of the theme in the admin section. We tend to use the name of the client so we’ll use Example Mountain

   3. Theme description – This describes what the theme is and is shown in the admin section. Usually we use something like The Example Mountain site theme

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.

1. Duplicate the src/Presentation/Nop.Web/config/env/env.dev.json file and rename the new file env.[themename]-test.json . In our example, it’d be env.examplemountain-test.json.

2. Reach out to your onboarding buddy / manager to learn where to find the values needed to populate the file.

3. 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:

1. Rename the src/Themes/[your theme name]/Content/images directory to something like my-images

2. Replace all images inside with ones provided by in the Jira ticket requesting the theme’s creation

   • Some new images may need to be created using other assets that are Frankenstein’d together

3. If nothing was provided that would make a good favicon, make one manually and ensure it’s named favicon.png in the my-images directory

4. Execute axcommerce-theme-generator processimages from the src/Themes/[your theme name]/Content directory

5. You’ll be prompted for some information and answer them with information in the Jira ticket:

   1. Source images directory – This is the name of the directory containing images we’ll use in the theme. In our case, it’s the directory we renamed to my-images.

   2. Category hero height – This is the size selected by the resort and should be indicated in the Jira ticket.

   3. Level of compression – This indicates how much the images should be compressed. You can try the available options and see which ones get the files to meet the requirements listed in https://aspenware.atlassian.net/wiki/spaces/AT/pages/768507988 .

   4. Generate logo-mark-spinner.png – Unless you’ve been given or manually created an image to use when loading, you’ll want to select Generate for me.

   5. Generate preview.jpg – Unless you’ve been given or manually created an image to use in the Admin section listing themes, you’ll want to select Generate for me.

6. Once done, a new directory should be created at src/Themes/[your theme name]/Content/images that contains the final images. We’ll leave the other my-images directory alone until we validate the theme.

7. Follow the steps under the Theme validation section to ensure the theme passes validation. You may need to repeat step 5 with a higher level of compression if the images are too large.

   • Note: It’s also possible to only run the image compression step. Find out more in the Running Compression Only section of the readme.

8. Once validation has passed, delete the my-images directory to ensure we don’t have unneeded file copies in the repository.

Favicons

You can skip this step if you’ve used the Asset Generation method detailed above.

Favicons for the theme need to be created. The following files need to exist in the src/Themes/[your theme name]/Content/images directory:

• 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.

To do this automatically, see the Asset generation section.

To do this manually:

1. 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.

For example, if a client requested a short hero image that is static, we'd do the following:

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:

1. Update src/Themes/[your theme name]/Content/scss/_theme.scss with the custom styling.

2. 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:

1. From the src/Themes directory, execute axcommerce-theme-generator validatetheme

2. You’ll be prompted for the theme directory name, in our case that would be ExampleMountain

3. Checks 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 and create a theme zip, 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

1. Once running NOP, sign into your account.

2. In NOP, click on the Administration option under the My Account menu.

   1. If the option is not visible then your account is lacking the admin role. Reach out to your manager or onboarding buddy for assistance.

3. Click on Configuration > Settings > General settings in the sidebar.

4. 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.

Useful Resources

• TinyPNG - Image Compression

• nopCommerce - Designer Documentation about theming