Page Comparison

The goal of this training is to provide guidance that will make some aspects of the application functionality more transparent and less painful to use without making modifications to the TD application or TD theme options. While I know there is a desire to add more features to TD and more theming options, doing so is not in the cards at this time so this training is meant to help alleviate some of the pain points.

It is encouraged to bookmark this training document for future reference.

Primary topics covered by this training

1. How can I inspect an element on the page to determine if it is themeable with TD, and how can I use that information to determine what control in TD to use?

2. How can I inspect the page to ensure all the TD configs exist before I start theming so I don’t get save errors?

   1. How can I debug failure to save issues on my own?

3. How can I ensure that all the theme assets are ready for PROD when I migrate from UAT and prevent how can I prevent missing assets during the migration process?

4. How do I handle image selection and image prep for responsive image placement?

Topics that are out of scope for this training (and why)

1. Improvements to the TD application.
   These requests should be routed through the PUR team to be evaluated and groomed if the work is approved. PUR will communicate with me as needed.

2. Exposing TD to resorts to use.
   Due to the application complexity, TD is not currently designed or built to be a public facing tool and it has a long way to go before we could ever put this in the hands of the resorts. There is currently no appetite with leadership to move in this direction with the application as doing so would be a months long endeavor involving the product team and engineering and this years dev schedule is already planned out. This would require a proposal, possibly for submission next year.

3. Adding more design options to TD.
   These decisions are no longer in the hands of engineering. The design system is managed by Product and all design options are chosen to be themable (or not) by our Designer. Any changes to themeable options and therefore the design system will have to be evaluated by the Product team and in some cases A/B tested before they can be implemented to first determine what impacts the change will have on the user experience and the overall cohesiveness of the design system. It is important to communicate to resorts that the design decisions are often user tested and leveraged to ensure the best experience for the end user and so some things are just not going to be customizable to the degree they may desire.

Lesson 1. Inspecting page elements for themeability and identifying the bound controls in the TD App

Every themable element on the page will have one or more CSS Custom Properties assigned. The TD Application reads these properties into an internal list that it then uses to generate the proper control in the application. It keeps track of these changes and the list is reread with the updated values every time you click “Save”.

You can actually inspect the page in the browser dev tools to see what, if any themeable properties are applied to the element and use that information to locate the related control(s) in the TD App. The following steps will guide you through that process.

1. Right click on the element you wish to inspect in the browser and click Inspect from the menu. This should open dev tools with the Element tab opened and the targeted element selected in the markup.
   * Note: If the element you are trying to target is beneath another element, it may be difficult to target the underlying element by simply right clicking on it in the page. In this case, you will have to select the element from within the opened Elements tab instead.

2. The Styles tab in the right hand panel will display all the CSS and Custom CSS Properties applied to the element.

3. With the element selected, review the Styles tab in the right hand panel to look for applied Theme Designer Custom CSS Properties. Note the following when looking at the Styles tab.

   1. Styles cascade from the bottom of the Styles list to the top. This means that the styles at the bottom of the list are applied first to the element and each style block above overrides or adds to the styles in the block(s) before it. The image below explains this relationship.

4. Identify the --ads prefixed TD properties. All TD customizable properties start with the characters --ads and the naming of the property determines where the control for it will be located in the TD App as well as the control type that will be displayed. You may also see --adx prefixed properties applied to some elements. These are not customizable in the TD App and are used by engineering to manage the base Aspenware Design System.
   
   Lets take a look at one of the properties for the Card Title Color from the screenshot above to see what it tells us.
   
   color: var(--ads-page-plp-cards-header-color)
   
   color: - This is the CSS property that the value of the custom variable will be applied to. In this example this is the text color property being configured.
   var() - This wraps any custom CSS property and tells the parser that this is a variable custom property inside the parenthesis.
   --ads - this segment tells the TD app to consume and render this property as a control in the TD App
   -page-plp-cards-header - this segment tells the TD app to render the color control within the page > plp > cards > header section in the TD app.
   -color - this tells the TD app to use a color control type in the TD UI for this setting because it is acting on the CSS text color property.
   
   Other control types include fontfamily, fontsize, backgroundimage, width, and height, just to list a few. You will find a full list of the supported control types here: https://aspenware.atlassian.net/wiki/spaces/AT/pages/2573828170/Creating+CSS+Properties+for+Theme+Designer+V2#C.-Property-Names-Determine-the-Control-Type
   
   With this information you can now identify themeable properties applied to an element, as well as where to find the control for the property in the TD App. This formula apples to all --ads properties used in a TD theme.

Lesson 2. Ensuring a site is properly configured to use TD

Before starting to use the TD App on a site you will want to ensure that it is properly configured and ready to go. This will prevent discovering that there is an issue when you click Save and it will prevent accidentally overwriting other themes if the incorrect slug was applied in NOP settings.

1. Anytime that you are going to work on a theme, whether it is a new setup or a theme update, you should always check the TD config first to make sure it is configured and targeting the correct container. This should be done both in NOP admin per the instructions in the TD Documentation and by inspecting the page markup to make sure the settings are rendered correctly in the page markup.

2. To check the page markup, open the browser dev tools. Then, select the Elements tab and perform a search of the page (CMD/CTRL + F). Search for the text --adx-theme-id. You should find it wrapped in a <style> tag within the <head> section of the page. Directly above the container slug should be the <link> element that targets the resorts cssprops.css save file. If EITHER of these elements are missing from the page markup, then the site is not properly configured for TD theming and saving will not work.

   1. If you are on the UAT site then this slug should end in -test. If you are on the prod site then the slug should end in -prod.

   2. The link to the cssprops.css file should include the slug in the file path.
      

      

3. Fixing any issues here is pretty straight forward. Simply update or add the correct TD settings in NOP per the user guide and the elements should automatically get added into the page markup. Incorrect config is the primary reason for TD failing to save and you now have the knowledge of how to debug this issue.

Lesson 3. Migrating themes from UAT to PROD

Unfortunately there is no instant migration process yet, so this lesson focuses on providing a recommended setup flow that will minimize the migration work while ensuring minimal downtime for the product site during theme setup. This process is recommended for both new site setups and migrations to TD for current resorts.

1. Set up in UAT initially using the production slug. Do not add the production slug to the production site until it is ready to go live. Doing it this way will provide a few advantages. It will ensure the image uploads are ready to go in production without having to re-upload them. It will ensure that the production theme is instantly live when the production slug is added in NOP for the production site. It will reduce the risks of missing assets in the production site when it goes live.

2. Do all your theming in UAT for resort approval

3. When approval is received to go live with the theme, only then do you add the production slug to the production site. This will apply the theme you set up in UAT to production and all the assets will already have been uploaded to the production container and are ready to go.

4. Next, do an export of the configured theme save file from the TD App and save it to your local machine

5. Then update the UAT site to use the UAT slug.

6. Upload the theme export in TD to the UAT site container using the upload theme option in TD App.

7. The production theme is now duplicated in UAT but is using the -test slug.

8. Now you can re-upload the images and fonts in UAT at any time without impacting the production theme.

Lesson 4. Cropping responsive images to work well on all display sizes

Images in commerce are largely set as background images, both so they can be managed by Theme Designer and so that they can be displayed responsively. By setting them as background images they will crop and scale automatically on the page while maintaining the proper aspect ratio.

The downside of this that in order to maintain the proper aspect ratio at all display sizes, parts of the image are going to get cropped off at some aspect ratios. The alternate (which is currently not supported) would be having to manually crop and upload separate images for each display size – which would substantially increase the effort needed to manage photos on the site. This is not just an issue we experience -- this is a common issue with responsive issues across the industry and there are no simple solutions. It all boils down to good image selection.

Given the tradeoffs, using a single auto cropping background image was opted as the preferred method for image responsiveness. Given that tradeoff, this lesson focuses on tips for image selection and preparing images to work well at all aspect ratios.

1. Understanding how the browser crops background images
   If we take a look at the image below we can examine how the background image gets cropped when displayed on desktop vs mobile. The browser will always center the image in the image container and will always maintain the image aspect ratio. In order to do that, it scales the image to fit either the height or the width of the container and then crops off the overflow. This means content around the edge (sides, top, and/or bottom) of the image is likely to get cropped out in some aspect ratios.
   

   

2. Selecting the right images
   When working with resorts on image selections it is important to select images that centralize the focal point (the main focal element(s)) of the image. If the image has its focal point too close to the edges, it is likely to get cropped out on some device aspect ratios. When requesting images from resorts, be sure to communicate this to them so that they are not providing you with images that are going to have undesirable results.
   

3. Preparing the images
   Sizing and cropping images can be done right in both the Windows and Mac image preview tools. But a more powerful free option is GIMP (Gnu Image Manipulation Program) https://www.gimp.org/downloads/, which I will be using for this lesson. Before uploading an image you will want to scale and appropriately pre-crop the image to the required size for the image location.
   
   Tips for scaling and cropping.
   - If the resort provides an image with the focal point off center, consider how you can crop that image to size to centralize the focal point
   - If the image is larger than the size requirement, use this to your advantage. You may not need to scale it at all and instead you can crop it to the correct size while centralizing the focal point of the image.
   - Always try to crop first for a good focal point, then scale as needed
   
   Consider this example (red overlay indicates the crop area). The image provided was larger than the requirement, and the focal point (the skiier) is a bit too much off center. To fix this, instead of scaling the image down to size we can crop out the size we need while centralizing the focal point. We solved two issues with a single crop. Now when the image gets cropped in the browser to maintain the aspect ratio, the focal point will remain visible.
   
   Finally, optimize the image by running it through the TinyPNG optimizer at https://tinypng.com/.