Overview
Use this article to help explain the process of selecting a good element location for guide targeting, help determine the quality of an automatic selection, and provide some information on how to test selectors. Please note that this article is assuming some technical knowledge and is not a suggested approach for all users.
Pre-Requisites: CSS Selectors and Chrome DevTools
Reseller Adopt’s element selection uses a subset of CSS selectors as a means of identifying the components of your application. Before getting started here, we recommend familiarizing yourself both with general CSS selector knowledge as well as what we specifically permit for element location selectors. Here are some resources to get started:
CSS:
- W3 Schools CSS Selectors Reference
- Mozilla’s Introduction to CSS Selectors
- CSS Diner: A Game to Practice CSS Selectors
- What CSS Selectors Are Supported For Element Location?
Chrome DevTools:
Determining the Quality of an Element Location
Depending on the implementation of your application or how a user selects an element location when targeting a guide, the suggested match may not ideally target the guide in the way you intended. A simple and common example is a span contained in a button or anchor tag:
You can see from this example there is an anchor element (indicated by <a...) who’s child is a span (indicated by <span\>) that contains the text ‘Generic Page’. The highlighting in the image reveals how feature clicks will be tracked at its lowest level: A click in the blue space will be tracked against the span while a click in the green space will be tracked against the anchor. If we target this in the designer for a guide step's element location in-app, depending on where we click, we’ll get one of two selectors:
The anchor, Rule A:
[href="/assets/pages/generic.html"]The span, Rule B:
span:contains('Generic Page')In this example, if you had chosen to set the element location to Rule B, the user would see the guide step specifically targeting the text "Generic Page" (the blue area in the image above). If you used Rule A as the element location, the guide would target the entire button (the green + blue area in the image above).
Testing Your Target Element Location
Sizzle library for reading and selecting elements from a webpage. To begin testing your targeted element location, navigate directly to the page (outside of the Designer) where that element lives and open the Chrome DevTools. Enter the following into the console:
pendo.Sizzle('ELEMENT_LOCATION_HERE')There will be a dropdown with your results from your selector once you run the command:
Hovering over any of these results will highlight the item inside your application:
You can also double click the result to reveal the element in the ‘Elements’ panel. Using this information in combination with the highlighting should tell you how effective your element location is.
Dynamically Rendered Frameworks
Dynamically generated attributes such as classes and ID’s are very common in frameworks such as React.js, EXT.js, or Ember. Reseller Adopt has created some automatic exclusions so that our Suggested Match will try to avoid these, however, you may find that you need to customize in order to capture all data or get a tooltip to show every time.
Some examples of dynamically generated attributes would look like:
.nav_bar__2RnO8
#ember123
#btn-1050-el
The numbers here are randomly generated on each page load, so you’ll need to make sure that you choose something different OR wildcard the match.
Wildcard The Suggested Match
After you have used the in-app designer to target an element location, toggle over to "Custom CSS".
Let's use an example. Say your suggested match had been `.nav_bar__2RnO8`. Reseller Adopt supports `^` which means “the attribute begins with” which is a great option when targeting elements with React.js classes. The format for `.nav_bar__2RnO8` would be:
[class^=“nav_bar__”]
Tip: You should see a red box around the element to indicate that you have used the right syntax to target the appropriate element.
“class” in the above example is the attribute because of the `.`, whereas this same syntax works for other attributes such as id (depicted as `#`) or `href`.
Rules Reseller Adopt Supports
[attribute^=“what it begins with”]
[attribute$=“what it ends with”]
[attribute*=“what it contains”]