Getting Started

Release Notes

Release notes and version information can be found in the Release Notes document.

Supported versions

The Theme designer system is currently supported for:

1. Cloud Header

   1. Always make theme changes using the Theme Designer App. If a resort is on 2.X, you must use a Nop Widget until PPP-813 is completed. If a resort is on 3.1+ the Nop Widget is not required.

2. Cloud UI 1.1 - which controls the full page pricing calendar only.

   1. Always make theme changes using Theme Designer App. If a resort is on 2.X, you must use a Nop Widget until PPP-813 is completed. If a resort is on 3.1+ the Nop Widget is not required.

   2. Theming Cloud UI does not impact anything on the legacy site.

3. Sites on Commerce 3.1+

4. Sites on 2.44.X

5. Coming soon - Cloud UI 1.2 - PDP redesign - Theme designer App will support the PDP redesign out of the box. Targeting November

We recommend that you work in the client’s test environment first when doing the initial cut over to Theme Designer Theming.

The Theme Designer System

Theme Designer (TD) - Refers to the entire Theme Designer system, including the TD App, the TD Theme, the CSS “save file(s)” that the TD App generates and uploads, the Azure storage container(s), and the custom CSS properties that the TD App controls.

Theme Designer App (TD App) - The browser application that is used to configure the TD resorts theme.

Theme Designer Theme (TD Theme) - The theme that is necessary to implement theme control via the Theme Designer App within Legacy pages of the Store.

Custom CSS Properties - CSS Variables that are exposed to Theme Designer App, and which you control via the Theme Designer App during theme configuration.

Azure Storage Container - A storage container that the Theme Designer App saves the stores Custom CSS Property document to and from which the store imports the document on page load.

Resort Slug - The unique ID for the Stores Azure Storage Container.

Current limitations to keep in mind before starting

1. Identity and Arrival are done separately - Identity has to be manually themed and Arrival uses the existing tool

2. In order to update even the smallest item via Theme Designer App for a legacy page, the entire site must first be converted to Theme Designer Theming. (See below section on Base theme)

3. No audit trail to show who made a change when

4. IMPORTANT: Images MUST be optimized before uploading. A free online tool to use is https://tinypng.com/. Do not use images larger than 1.5 MB or there is the potential to cause site loading issues.

When you’re ready to work in Theme Designer App, start with the following setup tasks:

First Time Setup for a Resort to use the Theme Designer System on Commerce

Add NOP Settings for Theme Designer Config

The following settings must be configured in NOP Admin for the resort for the first setup of the Theme Designer System in a host application. These settings are required for the Theme Designer System to work.

Apply the Base Theme to the Resort

In order to use Theme Designer App to theme the legacy nop commerce pages, you must select the Theme Designer Base Theme from the theme list in the General Settings section of NOP. New installs will include the Aspenware Theme Designer theme as a default*. This applies a standard set of variables that can be modified to the commerce platform.

*If you don't see the “Aspenware Theme Designer” theme after you deployed, you can request a copy of the latest from the Purchase Team to upload to Local plugins.

First Time Setup for a Resort to use Theme Designer on Identity

Configuration of the Theme Designer save URL and Client Environment are performed as part of the DevOps Identity checklist. By the time you are ready to start to theme, configuration should have already been completed by DevOps for you. If you are getting an error when clicking Save or you are not seeing your changes preserved, the setup was likely not completed. Contact the PPA team in the PPA Support channel on Slack to verify the issue and they will advise on next steps.

Once you complete the steps in the “Installing the TD App” section of this guide and read the following notes about using TD to theme Identity, first-use setup for Identity theming is complete.

• Commerce and Identity have unique “save files”
  Identity and Commerce use different “save files” so the theming must be done on each web property separately. The “save file” is not shared between them.

• Configuring Identity v2 and v3.
  Identity 2 container name is set in Identity Admin, while Identity 3 container name is set in The Auth0 Application metadata in the Auth0 admin for the selected tenant.
  
  You need the following containers configured for Identity 2:
  SLUG-test-identity and SLUG-prod-identity
  You need the following containers configured for Identity 3:
  SLUG-test-accounts and SLUG-prod-accounts
  Replace SLUG with the assigned resort slug.
  
  NOTE: When adding the container names in Identity 2 or 3, do not include the suffix (remove the -identity or -accounts from the container name before adding it to the config/metadata). Identity v2 and v3 automatically appends the appropriate suffix for you when referencing the container.
  

• Adding the Configuration
  In the Resort Themes input(s) in Identity Admin add ThemeDesigner as the theme name
  In the Resort Theme Designer Environments input(s) add the resort slug without the -identity suffix.

• Fewer theme configuration options than Commerce
  Identity has fewer configuration options than Commerce does. As a result, you will have fewer styling options displayed in the TD App.

• Brand tertiary color is not used
  Tertiary color, while available in the TD app, is not used on the Identity themes. You can leave this value unset.

• Setting logo size uses Aspect Ratio
  Setting the logo size introduces the use of Aspect Ratio. Aspect Ratio is the ratio of width to height (width/height). By properly setting the aspect ratio of the logo image, the browser will automatically calculate the required image height based on the width you define for each screen size.

  • Calculating Aspect Ratio.
    This requires some simple math. You need to divide the width of the image by its height, rounding up/down to the closest tenth. You can ascertain the provided image dimensions by inspecting the images file information on your operation system.
    Example: 400px wide / 70px tall = 5.714... . As a rounded ratio this becomes 5.7/1.
    
    In the above example, you would enter 5.7/1 in the logo Aspect Ratio input and then set the widths for each display type.

Installing the TD App

Installing TamperMonkey and enabling the Theme Designer Application user script

TamperMonkey is the supporting app necessary to set up the Theme Designer App, as it gets inserted into the resort’s store via TamperMonkey.

Note: Theme Designer app is best run on Chrome, however it should also run on FireFox using the TamperMonkey Firefox Extension. Only Chrome is fully supported at this time.
- Install the TamperMonkey Extension for Chrome: https://chrome.google.com/webstore/detail/tampermonkey/dhdgffkkebhmkfjojejmpbldmpobfkfo?hl=en-US
- Download the TamperMonkey UserScript for Theme Designer App:
- Once TamperMonkey is installed, pin it to your toolbar by clicking the puzzle icon in your toolbar and then the pin icon next to TamperMonkey so it turns blue

- Close the menu
- Click the TamperMonkey Icon in the toolbar to expand the menu, and then click Dashboard
- Click the Utilities tab, and then click Import From File
- Select the Aspenware Theme Designer.user.js TamperMonkey User Script you downloaded earlier.
- Confirm to install it.
- Click the Installed UserScripts tab to confirm that the Aspenware UserScript is installed.
- Once installed and verified, close the Dashboard tab in your browser and load the site that you will be using the TD App on.
- Click the TamperMonkey Icon in the toolbar to expand the menu and make sure that both TamperMonkey is enabled (green checkmark) and that Aspenware Theme Designer is toggled ON.

- Reload the site and the Theme Designer App should load on the page.

Additional help

Download the Theme Designer Training content for video instructions on installing TamperMonkey and the Theme Designer User Script.
Contact Gibas if you cannot access the training content.

How the Theme Designer App works

Menu Options

Accessed from the Options menu

• DISPLAY GLOBAL PROPERTIES
  This toggle disables displaying global properties in the Theme Designer App property groups. It is toggled ON by default. Properties displaying a red indicator next to them are considered “Global” and may or may not be used on the loaded page. This is simply a helpful tip to let you know that if you change that value, you may not see any change reflected on the loaded page. In general, it is recommended to keep it toggled ON while using the application.

• REFRESH APP
  Clicking this button will reload the Theme Designer App and rescan the page properties. Doing so will not cause a loss of unsaved changes. This is useful if you notice that there are missing theme options when the application first loads

• DOWNLOAD BACKUP
  Clicking this button will download a copy of your current cssprops.css save file from the server. Be sure to click Save before downloading a backup if you want to capture any unsaved changes as well in your download file. We recommend that you download a backup before you start making meaningful changes just in case something goes wrong. This is also useful if the engineering team needs to de-bug issues as it will allow them to inspect the properties that are causing problems. Also it will help with migrations, where you can download from the test environment and upload to the production environment.

• UPLOAD BACKUP
  Upload backup allows you to load the backup file. When you upload a backup file, it will clear any unsaved theme changes and update the loaded settings to match the backup. You must click save if you want to save your loaded backup to the server.

• RESET THEME
  Reset theme allows you to erase your saved theme settings and restore the theme to the base theme default. This is useful for debugging or simply starting from scratch. You will be provided a warning before the process is started to prevent accidental resets. The page will auto-reload once the save file is erased.

• USERS GUIDE
  Opens this document.

Theme Controls and Input Types

Theme Designer App automatically generates specific input types based on the type of data that the property controls. You can find more information about control type mapping using ADS props here.

A. Color Picker Widget

Color pickers are used to select from an unconstrained range of colors.

Note: You can toggle between the color picker and color swatch widget by clicking the related icon.

B. Color Swatch Widget

Color swatches are used to select from a limited range of colors. Color Swatch pickers have their color option hydrated from the Brand Colors as well as a select set of non-editable greyscale shades.

Note: You can toggle between the color picker and color swatch widget by clicking the related icon.

Unset - The option to unset the color selection is also provided

C. Drop Menu

Drop Menus are displayed when a property has a select set of predefined options available. Property and option mapping can be found here.

D. Text Input

Text inputs are displayed when a property has a wide range of possible input values and measurement types. For example, a property for width might be set as 180px or 11rem. To commit a text input change, you must click the SET button. This only sets the value on the screen. Don't forget to save!

E. Image Uploader Widget

Image uploader widgets allow you to replace images in the theme. There are two options.

IMPORTANT: Images MUST be optimized before uploading. A free online tool to use is https://tinypng.com/

1. Update Path - Use this option if you only want to provide a path to use for the image. No image will be uploaded to the file server. The image must be hosted elsewhere. Once you add the URL, click SET and so long as it is a valid path the target image should update in the live preview.

2. Upload Image - Click the paperclip or the empty field next to it to open a file explorer. Once you select your file the upload process will start. Upon successful upload the path to that image on the file server will be displayed in the Path input.

Path Copy - If a path is displayed in the Path field, you can click the copy icon to copy the path to your clipboard.

Path Delete - Quickly clear the path input.

F. Font Management and Font Hosting

Font widgets are used for setting the Brand Primary and Brand Secondary fonts.

Managing Fonts

You are afforded two font management options within the widget. You can either link to an existing CSS font host, or you can use the Aspenware font hosting option. To access the font hosting inputs, enable the Use Font Hosting checkbox. A panel will expand revealing the additional inputs. All inputs are required.

CSS Fonts Only!

Aspenware applications support the use of CSS @font-face defined webfonts. We do not support javascript driven webfont hosting. An easy way to determine if a web host is delivering the fonts via CSS is to open the URL that you are provided in a web browser. Somewhere in the file that opens in the browser window you should see the @font-face definitions.

You can also use this information to obtain the font-family name that you need to enter in the Family Name input (do not include the quotes)!

@font-face {
  font-family: "Merriweather";  <---This is the font family name you will use (no quotes)!
  font-weight: 100 300;
  font-style: normal;
  src: url("https://fonthost.com/fonts/Merriweather-Regular.ttf")
}

Using a 3rd Party Font Host

With this option there are two inputs and both are required. You can obtain this information from the resort or, if you have credentials, from the font provider. If using Google Fonts, then this info can be found in the Selected Families Panel under Use on the Web > Link.

Family Name - This is the font family name. It is required for both 3rd Party and Aspenware Font Hosting. When using Aspenware Font Hosting, you can use whatever family name you want, but it should be similar to the actual family name of the font.

If you are using a font hosting service then the name needs to exactly match the Font Family defined in the linked CSS file (see the code block above). Do not include quotes!

Example Google Font Family Name: Roboto Slab

Note: If a resort ever has a “Split font” eg, Requiem Display A and Requiem Display B, put both of the family names in the same Font Family name input in TD. Comma Separated. No Quotes. IE:
Requiem Display A, Requiem Display B

This is an uncommon config, but may occur.

CSS Path - Input the path to the CSS font file where the @font-face font definitions exist. If you are using the Aspenware font hosting option, then this input will be greyed out and read-only. The URL in it will update automatically when you publish the uploaded font(s), and it will be contain the URL to the generated @font-face file.

Example Google Font Path: https://fonts.googleapis.com/css2?family=Montserrat:wght@400;500;700&family=Roboto+Slab:wght@400;500;700&display=swap\Using Aspenware Font Managemet

Use Font Hosting - Enable this checkbox if you want to use Aspenware Font Hosting

Upload Font - Select this input to open a file dialog and upload a font file. Accepted file types are .woff, .woff2, .ttf, .otf, .eot, and .svg (svg is not recommended due to limited browser support). The uploaded file(s) will be hosted by Aspenware.

Font Weight - This is the weight that this variant will be applied to within the page. Often the font name indicates the weight, but you may need to check with the resort to determine which variant is intended to be used for each weight. Weights can be numeric or keyword.

Note that font weights, in simplest terms, will default to the closest numerical weight available when the exact weight is not defined in the available variants. For example, if you have a variant defined with a weight of 400, and the CSS defines a section of text as 200, then the browser will use the variant you defined as 400. The same behavior applies to weight keywords.

If you are not sure what weights to use for your variants, contact the PUR team via the PUR support channel for guidance.

Font Style: Leave this as normal unless otherwise directed by the resort. It is very rare that you will need to change this value.

Also Add to Secondary: Enable this checkbox if you want to copy the the font configuration over to the secondary font family when you click 'ADD FONT'. Only applies to the current font you are adding while enabled. If you added a variant to the Primary Font without the checkbox enabled and needed it added to the Secondary font as well, you will have to add it manually.

Add Font: After you have added all of the required font information and attached the font to be uploaded, click this button to add the font variant to the font family group.

Removing Fonts From a Font Group: Click the garbage can icon next to the variant in the font family list.

Applying Fonts to the Page: Click APPLY FONTS after entering the required information to set the font option. This does not commit your change to the server. Remember to save!

G. Navigating Categories

Click the close all categories button to close all expanded categories at once.

Click on any section title to expand that section.

H. Saving

The Theme Designer App does not do automatic saving. You should make it a habit to save periodically. You will receive a warning if you try to navigate away from the site or reload the page with unsaved changes.

Changes Pending Save Indicator

To the right of the save button is a save notification icon to let you know if you have any changes that are pending a save.

⚠️ Troubleshooting Saving Issues

If saving your changes does not appear to be working, try these troubleshooting steps in numbered order.

1. Try clearing cache: If automatic cache busting is not working for you you can force a hard refresh of your browser to force clear your cache by holding shift + clicking refresh on Mac, or control + click refresh on PC. If you saved and don't see your changes after a page reload, do a hard refresh to clear the cache before clicking save again or you will overwrite your last changes with the cached settings.

2. Check all theme designer settings: If initial changes are not saving, confirm that the nop settings, such as the client environment setting has been set properly. Ex. “svlt-test”.

3. Check Scaling: Check to see if the store is scaled and, if so, perform an advanced restart in Azure.

4. Request support from Engineering: If the above steps have not resoled the saving problem, contact Purchase Team for assistance.

Moving from Test to Prod

If going Live:

1. Update the themedesignersettings.clientenvironment setting in the prod environment in NOP to point your resorts prod container, ****-prod

2. Export the theme from Theme DesignerApp options > download backup

3. Upload that downloaded theme into TD in the prod environment options > upload backup. You should see your theme loaded into the page at this point.

4. When you migrate the save file, the images (logo, hero, favicons) that you uploaded in the test env will not be moved to the prod env automatically. It is recommended that you re-upload them to the prod environment via TD so that the production save file gets updated to point at the images in the prod container. Not doing so carries a risk in that if someone changes the images in test it will impact the images in prod as well since the save file still has them linked.

5. Then save the theme to make it live for all visitors to the prod site. You must click save or your theme upload will not be preserved.

To preview in dev without migrating the save file:

This option is for temporary previewing the theme in the production env only. If you are going live, use the “If going live” option above.

1. Update the themedesignersettings.clientenvironment setting in the prod environment in NOP to point at your resorts test container, ****-test. This will cause the site to load in the theme settings from the test environment that you have configured there.

Footers

Footers can be managed with Theme Designer so long as the resort is set up using either the Simple Footer add-on or if they build their custom footer using the Guidance for Resort Footer Development documentation.

These setups will allow you to configure footer logos, text colors, and background colors using the Theme Designer App. Theming options for footers will be found in the Plugins section of the Application if either footer option is properly configured.

Simple Footer Documentation

Guidance for Resort Footer Development Documentation

Updating the Theme Designer App

Your local instance of the Theme Designer App should automatically update to reflect the current release version the next time you restart your browser. However, if you are not seeing your version update to match the newest release then TamperMonkey may be caching your current version. (See the version number under the logo to confirm)

First, try closing and restarting your browser again. If that does not work, proceed with these steps.

1. Click the TamperMonkey icon in your toolbar

2. Click the Arrow next to Aspenware Theme Designer

3. Click Edit

4. In the Theme Designer App user script, locate the script import on line 12.

5. Add the release version (for example?v=1.5.0) at the end of it so it looks like this: https://themedesignerdev.aspenware.net/index.js?v=1.5.0

6. Click File > Save

7. Close the tab and refresh the site you have the Theme Designer App opened in. You should now see the latest version displayed below the Theme Designer App’s logo.

The Store Closed Page

The Theme Designer Theme provides a standard NOP Store Closed page. The content of the page is defined through NOP Settings. You can provide simple text or HTML with inline CSS in the settings. The logo is set in the Theme Designer App under page -> storeclosed -> logo.

You can view the store closed page without closing the store by going directly to /storeclosed on the site.

The Theme Designer App’s Plugins

Plugins come pre-installed and ready to go out of the box. Below you’ll find instructions on how to use the plugin(s) in the Theme Designer App’s UI. You can use this if you want to demo the different card options or tab options to resorts during a live phone call without having the manipulate the Nop settings on the call. It can also be used to help you make sure you’re going to pick the right options in the Nop admin. Just keep in mind this will not be used for saving actual theme values, it’s just a helpful tool for presentation purposes.

A. Options Previewer

Options Previewer provides the ability to live preview theme options that are configured in NOP admin only and NOT in Theme Designer App. These include the card option, tab option, and PDP Slider on/off. These options are for preview only in order to help you feel more confident you are making the right choices in Nop Admin. They will not be saved via Theme Designer App, when you save your theme. You must save your selections in NOP Admin in the “All Settings” page for the following options.

themedesignersettings.cardoption : Options [a, b, c, d]

themedesignersettings.taboption : Options [a, b, c, d]

themedesignersettings.showslider : Options [on, off]

Options Previewer “Enable” must be toggled on to use it. The initial selected values reflect the options saved in the loaded theme. When you “Disable” the Options Previewer the initial value (ie whatever settings are live at that moment in Nop admin) will be re-applied to the page.

FAQ

Q: I have read this document and I am still stuck. Where can I get additional assistance?

A. Contact the Purchase Team by posting a request for assistance in the purchase-support Slack channel. You can also check the Open Issues document to determine if the problem you are facing is a known issue.

Q: Is there a document that lists all the properties, what categories they are in, and what they effect?

A: There is. However, this document is not regularly updated, so it may be missing newly added properties.

Commerce CSS Property List [NOP & Public UI]

Q: My favicon isn’t showing up properly, what do I do?

A: When upgrading to Commerce 2.44.6 or 3.1+, you’ll need to follow the steps here: /wiki/spaces/DB/pages/2739404801.

Q: I can’t type into forms or can’t see what I’m typing when using Theme Designer App

A: There is a security feature in Chrome that will not allow entry into forms when a JavaScript has been added to the page (as TD does). Turn off Theme Designer App and you can fill out forms normally.

Q: I need to keep the resort on their Legacy theme, but add PUI and cloud header. How do I configure this?

A: If the resort is adding the cloud header and PUI to their site, but staying on their legacy theme for Legacy Commerce (PLP, Checkout, MyAccount), do not enable the Theme Designer Theme. It is not needed for PUI or the Cloud Header. You must keep it set on their current Legacy theme in Admin > General settings. This allows their current legacy theme to work alongside PUI and Cloud Header theming, both of which are configured in the TD App. You must then ensure that the themedesignersettings in Admin > Settings > All Settings as applicable for that store as described here.

Q: Why do I need to enable the Theme Designer Theme for Legacy Commerce and not PUI?

A: There are a couple reasons for this.

The first reason is that we need to support both Legacy and TD themed resorts at the same time because the transition to TD is going to take awhile. To avoid the risk of altering resort Legacy themes we did not apply the theme properties to the legacy css, and instead override the properties we need to theme in the Theme Designer Theme via Theme Designer App .

The second reason is that PUI was engineered to utilize the theme-able properties as a requirement of using PUI. The properties are included in the core PUI CSS. As such, no additional theme is required to override the base CSS settings in the PUI CSS.

Theme Designer App Recipes

This section provides step by step “recipes” to configure options in the Theme Designer App.

Recipe: I want to change the cloud nav to use underlines for active and hover state

The cloud navigation supports a couple of different hover and active state appearances. This recipe is for setting up the underline option. The default appearance uses a colored background for the navigation item states.

1. Header > Nav > Item > Hover > Background Color > Click the swatch > Select unset

2. Header > Nav > Item > Focus > Background Color > Click the swatch > Select unset

3. Header > Nav > Item > Underline > Underline Display > Click dropdown > Select block

Continue if you want to change the default underline state colors, otherwise stop here.

4. Header > Nav > Item > Underline > Underline Display > Hover > Background Color > Select new color (default is Primary:Hover Color)

5. Header > Nav > Item > Underline > Underline Display > Focus > Background Color > Select new color (default is Primary:Hover Color)

6. Header > Nav > Item > Underline > Underline Display > Active > Background Color > Select new color (default is Primary Color)

Recipe: I want to change the cloud sidebar to use sidelines for active and hover state

Feature coming soon

The cloud sidebar supports a couple of different hover and active state appearances. This recipe is for setting up the sideline option. The default appearance uses a colored background for the navigation item states.

1. Sidebar > Nav > Item > Hover > Background Color > Click the swatch > Select unset

2. Sidebar > Nav > Item > Focus > Background Color > Click the swatch > Select unset

3. Sidebar > Nav > Item > Sideline > Sideline Display > Click dropdown > Select block

Continue if you want to change the default underline state colors, otherwise stop here.

4. Sidebar > Nav > Item > Sideline > Sideline Display > Hover > Background Color > Select new color (default is Primary:Hover Color)

5. Header > Nav > Item > Sideline > Sideline Display > Focus > Background Color > Select new color (default is Primary:Hover Color)

6. Header > Nav > Item > Sideline > Sideline Display > Active > Background Color > Select new color (default is Primary Color)