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

If you have not watched the video for the basic TD training you can find the link to it under “Additional help” in the TD User Guide.

The video for this training is located here: Theme Designer Advanced Training-20250122_160147-Meeting Recording.mp4

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

Subject matter this training will touch on

1. Inspecting the page markup using Chrome dev tools

2. Basic CSS principles

3. Image cropping, optimization, and tooling

4. Azure storage containers

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 that 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?

5. What are the Theme Designer storage containers and how can I view the contents when I am debugging a theme issue?

Topics that are out of scope for this training

...

While these items are out of scope for this training, they are not being ignored. They are being addressed separately and in more appropriate contexts.

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. and more theming options.
   I am writing a proposal to address multiple common user-experience issues with theme designer for the next planning cycle. I will be seeking input from individuals as I create the proposal.

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

   1. Please submit design option requests through the normal request process by submitting a Jira card to the appropriate team and we will work with product to seek approval on the changes.

4. Exposing TD to resorts to use.
   TD is not currently designed or architected to be a resort facing tool and it requires significant user experience and interface improvements before we could ever put this in the hands of the resorts. However, the potential is here for a future proposal to release a permission managed version of TD that would allow for image updates.

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

Every themable themeable element on the page will have its attributes bound to 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”.

...

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.
   
   Shortcut for the Dev Console

2. The Styles tab in the right hand panel will display all the hard coded (static) CSS attributes 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. This is typically because the reference to the element is more specific than the reference below it, but also might be because the developer added the !important attribute to the value. 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
   
   If you follow the individual segments, it tells you where to find the control in the Theme Designer app. From left to right, starting on the first property after the --ads you can open the corresponding child tabs in Theme Designer and arrive at the control for that property.
   
   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. 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.
   

   Image RemovedImage Added

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 edgesan edge, 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 Try to crop first for a good focal point, then scale the resulting image 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/.
   

   

   
   

Lesson 5. The Theme Designer storage containers

All of the assets for resorts, including the CSS “Save File” are stored in an Azure storage container here.
You can find information on creating storage containers here.

While engineering will create these containers for you and provide the assets from their legacy theme if one exists, you may need access to their assets if you are trying to debug a theme issue.

Debugging notes:

1. Images are timestamped and preserved. When you update an image, the existing image is not deleted. The new image is timestamped and the link to it is updated in the CSS file using this new filename.
   
   Example: header-logo-image-20231213T144905.png. This was uploaded on 12/13/2023.

2. To revert an image, download the image you wish to revert to, rename it to remove the timestamp, and upload it again through Theme Designer.

3. Never delete files in the storage containers. If you need to replace images or fonts, use the TD app to do so. Doing so will ensure you do not end up with broken images on the live store.

4. Font files are also stored in the container. You can validate they exist here if debugging a font problem on the store.

   1. Font files and favicons are not timestamped. We only preserve the newest upload.