How to Create jQuery Selectors for WalkMe

Download as PDF

What is a jQuery Selector?

jQuery is a method you can use to select elements on the screen when you cannot easily do so with the standard WalkMe tool.

When you load a webpage, everything you see is written in HTML, the website's markup language. A jQuery Selector will target a specific element in that HTML code. The majority of these Selectors will target either the Class Attribute (general identifier) or the ID Attribute (specific identifier) of the element.

jQuery Selectors tell WalkMe where on the page it needs to focus, whether it be for content location, Triggers or Segmentation. Simply put, if WalkMe has trouble quickly and consistently finding the element you're looking for, use jQuery.

There are a couple ways to tell when there's going to be a problem with an element. If you're selecting an element for a new step, click it, and nothing happens, that means WalkMe is having trouble reading the element. If you play the step and it points to the wrong element, you might need to use jQuery (but check the precision tab first!) If your Launcher or SmartTip does not appear after you select its element, you might need jQuery. If your Launcher, SmartTip, or step only plays sometimes but not every time it's supposed to, you might need jQuery.

While an understanding of HTML can make learning how to build jQuery selectors in WalkMe faster and easier, you do not need a detailed understanding of HTML to do this. It's very rare that you will need to write anything original or build long, complicated Selectors. You can almost always find exactly what you're looking for in the HTML and then just copy and paste it into the correct format. The majority of jQuery revolves around knowing what to pull from the website's code, and that's what we're here to teach you!

Before we get started, here's a list of some key terms to help you get oriented:

• HTML: The markup language that websites are built from
• Element: HTML pieces that make up a website. Think of them as building blocks
• jQuery: The coding language that searches through and describes (queries) HTML
• Selector: The jQuery line of code that describes the HTML element you want to select

Creating a jQuery Selector

There are four steps to creating a jQuery selector:

1. Identify the element on the web page that you want to attach WalkMe content to.
2. Build a jQuery Selector for that element that will enable WalkMe to attach to it.
3. Test the Selector to ensure it is in the correct format
4. Plug that Selector into the WalkMe Editor

Step 1: Identifying an Element

To get started, open a new tab in your browser and go to www.support.walkme.com. Let's find a jQuery Selector for the "Welcome to WalkMe Support" text in the middle of the page.

Right click "Welcome to WalkMe Support" as seen in image 1 and inspect the element by clicking on either Inspect if you're in Chrome or Safari, or Inspect Element if you're using Firefox or Internet Explorer.

Your page should look like this:

The window you see on your screen is called the Developer Console. With the Developer Console open, you are able to see the HTML structure of the page along with the actual page itself. Another way to locate your desired element in the HTML is to open the console (right click anywhere on the page and click 'Inspect Element'), and click the cursor icon at the left corner of the console's header.

Once you've clicked this cursor icon, hover over any element on the web page. This will scroll you to the exact point in the console's HTML where the element lives, and highlight that element light blue. If you click an element on the web page, the console will highlight its line of HTML dark blue and anchor to that point. This is the easiest way to find elements in the HTML. In the Developer Console, you can see that the line starting with "<h2 class='site-header__title'>" is selected. When you hover over a line of HTML, its associated content will become highlighted. In this example [Image 3], if you move your mouse over the "<h2 class='site-header__title'>" text, the “Welcome to WalkMe Support” text is highlighted.

Step 2: Building a jQuery Selector for Your Desired Element

HTML Elements

Elements are the pieces of the site you use jQuery to select. Some of these include button, div, h2, input and iframe. These elements make up the entire page, and are the core of a website.

Here are a couple of common types of elements:

• div: short for divider, this is the building block of a website. Think of sites as being built of a series of rectangular blocks that contain all of the other elements.
• a: a link to another site
• h2: a reasonably large header, smaller than h1 but larger than h3.
• p: a paragraph. These break up large chunks of HTML and make it easier to read and navigate.
• form: like a div, this is a site building block. However, forms typically contain editable elements like inputs
• input: an piece of the site that a user can interact with or alter, like a textfield or checkbox
• img: an image. This one should be pretty self explanatory!
  Descriptors like classes, ID's, and attributes determine what those elements look like and how they behave on a page. When writing jQuery, the elements should always precede any descriptors. This means that you should never place a symbol of any sort before an element.

It's important to know that you do not always need to include the element you're selecting in your jQuery Selector, they're just useful for orienting yourself in the HTML. In this example, we'll
focus on the title of the page that we found with the inspector: <h2 class='site-header__title'>.

As we can tell from this string of HTML, the element we're describing is an h2. That's short for "header 2". The 2 indicates the size of the header's font. An h4 element will have tiny font, while an h1 would be big. As you can see, h2 is a pretty large header element.

How to Find the Class of an Element

Classes are the most common descriptors of elements. They can describe different types of elements that have the same purpose or are found in the same part of the page. They're written in the HTML as [class="XXX"] or <element class='XXX'>. That makes them easy to find and one reason why they're such popular descriptors. Classes also tend to make it clear what an element does.

Let's consider our <h2 class='site-header__title'> string. The type of element we're looking for is an h2. Its class is 'site-header__title'. Just by looking at this string, we can tell that the h2 element we're looking for is the header or title of a site. Even without looking at the website, we can assume that the element is pretty large and centrally located.

Remember how we don't need to include the element type in jQuery? Let's stick by that and just use .site-header__title as our jQuery Selector for this section. Now that you've decided upon a selector, you can use it to identify an element for a Step, Launcher, or SmartTip or any other piece of WalkMe content.

This step will now point at the WalkMe Support logo using a jQuery Selector:

How to Find the ID of an element

If an ID exists, you'll want to use it instead of class. This is because IDs are more specific. The process of finding an element's ID is similar to that of finding its class. In a new tab, open up www.support.walkme.com, right click on the Search Bar and click Inspect.

You should see this in your Developer Console:

We see in the selected HTML line <input id="hkb-search" class="..."...> that the id is hkb-search.

Now that we've found the ID attribute of the element, it's time to turn it into a jQuery Selector. We know that "." is the shortcut for targeting Classes; IDs have a similar shortcut. Instead of using a ".", we'll target the ID with a "#". Our final jQuery Selector to target the Search Box is: #hkb-search.

This step will now point at the search bar using a jQuery Selector:

How to Find an Element inside of an iFrame

Finding an element inside of an iFrame follows a similar process. The jQuery selector template below allows WalkMe to target an element in an iFrame. Update the bold items as seen in the example with the respective selectors:

Example: {"element": "h2.mainTitle" ,"context": "iframe#Main"}

To evaluate the selector in the Dev Tools Console you would need to use the wmjQuery template below:

To learn more about iFrame iQuery, check out this Tip Tuesday:

Step 3: Testing your Selector

Now that you know how to create a basic jQuery Selector, let's test the Selectors to make sure they're working as we expect.

1. Make sure you have the WalkMe Editor open and connected to your browser. This ensures that WalkMe is on the page you're looking for your jQuery Selector on.
2. Right click on the page and click Inspect [or Inspect Element]
3. Towards the top of the drawer that opens, click "Console":
   
4. Type wmjQuery('your Selector') in the command line, replacing your Selector with the jQuery Selector you made, but keeping the single quotes. To continue with our example, we would type wmjQuery('.site-header__title'). Once you've entered your command in the console, press Enter.
   Testing our .site-header__title Selector would look like this:
   

After I press Enter, what do the results mean?

First, expand the results by clicking the arrow next to init. The length returned is the number of elements it finds that matches our Selector.

• If it returns length: 0, then it wasn't able to find an element that matches that Selector.
• If it says length: 1, that's good news as only one element matches that Selector.
• If it returns with a length of more than 1, it found multiple elements (i.e. >1) that match that Selector. With any result higher than 1, we'd want to try making the Selector more
  specific.

Another way to test your jQuery Selector is to hover over or click the result in the console to check that it's capturing the correct element on the page.

Here, we are hovering over 0: h2:site-header__title. We can see that the Welcome to WalkMe Support text is highlighted. This shows that our jQuery is correctly pointing at the element that we are trying to identify.

jQuery Pro Tip: When using jQuery Selectors in the Rule Engine (e.g. ShoutOut and Auto Play Rules), you'll be able to see if your jQuery Selector is found on the current page. This will be shown with a green checkmark [seen in image 12], whereas if it cannot be found there is a red exclamation mark. The checkmark updates in real time, as you make updates to your Selector.

This is great for troubleshooting faulty Selectors.

If you have a long Selector like div.ht-container form.hkb-site-serch (incorrect) that is returning as false (!) in the Rule Engine, you can parse it out to see which piece is causing the problem.

You would start by typing div into the Rule Engine's jQuery text field. If it returns with a checkmark, you know there's nothing wrong. Next, you would add .ht-container, for a result of div.ht-container. This HTML element exists and is written correctly. Next, you'd add form, resulting in the Selector div.ht-container form. The form is a child*** of div.ht-container, so this is a valid Selector. The checkmark is still there!

Now let's add the last piece of our Selector: .hkb-site-serch. If you take a look at the highlighted line, you can see that .hkb-site-serch is a class that is spelled incorrectly. When we add it to the
end of our correctly-written div.ht-container form, the green checkmark would turn into a red exclamation point. Therefore, we know that .hkb-site-serch is the piece of jQuery that ruins our
Selector. Upon closer inspection, we can find the typo (serch), and correct it to search. Once we correct the typo for a new Selector of div.ht-container form.hkb-site-search, the exclamation point will turn into a checkmark. We've successfully troubleshooted and fixed our Selector!

Step 4: Implementing your Selector

Now that we've tested the Selector, we can add it to the WalkMe Editor following the steps below:

1. Open the Smart WalkThru that contains the step we want to edit.
2. Click on the step
3. Click into the precision tab
4. Select "jQuery Selector"
5. Paste in the jQuery that we created
6. Click Save
7. Click Play on that step and check to see that it's working correctly!

If you're using jQuery for a Launcher or SmartTip instead of a Smart WalkThru step, just open that Launcher or SmartTip and skip to number 3.

Alternatively, the jQuery Selector can be added into any rule set that has the jQuery Selector option.

For example, if we wanted to make a ShoutOut autoplay when the “Welcome to WalkMe Support” text is visible, it would look like this:

Targeting the Class or ID Attributes of an element will cover the majority of use cases where you need to apply jQuery Selectors. However, there may be some scenarios in which you need to target something besides the Class or ID Attribute.

Advanced Learning with jQuery

In the first article, we learned how to create basic jQuery Selectors by targeting an element's Class or ID Attribute. However, an element won't always have a Class or an ID Attribute. In this article, we'll learn how to target the element's other attributes, without using a . or #.

What if my Element doesn't have a Class or ID?

If the element you are looking to select does not have a class or ID that you can use, no need to worry! We can use most parts of the HTML as part of our jQuery Selector.

In the event that you can't use a class or ID to select an element, you can use any of the element's other attributes. Attributes provide additional information about the element. The
jQuery Selector will be in the format of [Attribute="Value"].

First, let's identify the attributes of an element.

Here, where we identify the WalkMe logo element, we see that the element does not have a class or an ID to use. However, we see that the element has an attribute called href that has the value of https://support.walkme.com. We can use that attribute to target the WalkMe logo element. A valid jQuery Selector would be: [href="https://support.walkme.com"].

The logo element also has another attribute called data-ht-sitetitle with a value of WalkMe Support. We could alternatively target that attribute instead of the href attribute by using the
jQuery Selector: [data-ht-sitetitle="WalkMe Support"].

There's one thing to remember about attributes that aren't ID or Class. You should always include the element type before the attribute. This helps WalkMe target which type of element to
look for. Attributes can apply to any type of element, so it's best to narrow down the results a bit for the sake of speeding up WalkMe's search. Therefore, if we're trying to select WalkMe's logo from the support site, we would use a Selector of a[href="https://support.walkme.com"].

Remember, an a is HTML code for a link. An href is a URL. This means that the logo is a link to the WalkMe support page!

The step show below will now point at the WalkMe Support logo using an href attribute Selector:

You may notice that IDs and Classes have the same format as attributes. This is because IDs and Classes are attributes too! Using [class="CLASS NAME"] and [id="ID NAME"] would
allow you to target those elements, however, this format is more tedious. We recommend you use the shortcuts we discussed earlier to save yourself time.

How to Use Parent Child Elements in Your jQuery

Let's say we want to use the Selector without the element type. On https://support.walkme.com, open the Developer Console and enter the following:

wmjQuery('[href="https://support.walkme.com"]')

Review the results and note the length that it returns. In this example, you should have a returned length of 2:

Try hovering over the results to see which elements that Selector is finding. You will see that this jQuery Selector is targeting both the WalkMe Logo and the “Home” text. If we wanted to target the “Home” text, this Selector wouldn't work as it's finding the WalkMe Logo first.

How can we make it more specific? We could add the Home text's element type, a. However, this wouldn't work well because the logo is also an a. Adding a before the href would still return a length of 2 because there are 2 elements that fit the jQuery Selector.

Let's try something new. In HTML, there's a handy way of coding that is called the Parent Child Element. You may have noticed that within the HTML, there are HTML lines that can be expanded to show more HTML code underneath. When you expand an element, the expanded element is the parent and the code that appears beneath contains its children.

Here, you can see the div with class ht-sitecontainer is the parent element of all the elements below it, such as the div with the class of site-header. If we look further down the HTML tree we can see that the div with the class ht-container is the parent of the div with the class site-logo, but the div with the class ht-container would be the child of the header element above it.

Now that we know about Parent Child Elements, let's talk about how to apply this to our jQuery Selectors and why it's useful in our current scenario. When we have elements that have a similar class or attribute, we can also take a look at the Parent elements to see if they're different and reference the Parent Element in our jQuery to make our Selector more specific.

If we take a look at the HTML for the WalkMe Logo and Home text below, we can see that the WalkMe Logo element is a child element of a div with a class of site-logo:

If we look at the Home text, we can see it's a child element of a li element with a couple attributes. Since the parents are different, we can use that in our Selector.

Parent-Child Elements are specified by putting a space in between the two elements. The Parent element li comes before the space and the Child element [href=”https://support.walkme.com”] comes after the space.

If we put that together, our more specific jQuery targeting the Home text will look like this: li [href='https://support.walkme.com']. If we input this into the wmjQuery Command and look at the results below, we see that this time we're only bringing back one result for the Home text.

Let's say we want to narrow down our logo Selector by using its Parent Child relationship. We know that the logo's Selector is a[href='https://support.walkme.com"]. As we saw above, its parent is div.site-logo. Therefore, we could write our logo Selector as div.site-logo a[href="https://support.walkme.com"].

Modifiers

Modifiers are used to narrow down the results that your Selector returns. You simply append them to the end of your Selector. Although you can use multiple modifiers at a time, try not to use more than two. Some commonly used modifiers are :contains(), :visible, :has(), and :eq().

• h2:contains(Welcome to WalkMe):visible
  • :contains() → select an element that contains characters specified in the parentheses
  • :visible → select an element visible to the user, not just the computer
• .hkb-site-search:has([type=”text"])
  • :has() → select an element that contains another element (specified in the parentheses) inside it. In this case, you're selecting one that has an element with the attribute ([type=”Text"] nested inside
• form.hkb-site-search input:eq(0)
  • :eq() → select the first (or whichever number you specify in the parentheses) element matching your Selector. It is important to remember that the number in the parentheses is indexed, meaning that the counting starts at 0.  The first element is :eq(0), the second is :eq(1), and so on.
• form.hkb-site-search input:last
  • :last → select the last element matching your Selector. This works similarly to :eq(). You can also use :first to select the first element matching your
    Selector.

Dynamic IDs

There's one pitfall you'll have to look out for when writing jQuery Selectors: dynamic ID's. They typically consist of long strings of numbers followed by or preceded by a word or two. Try to avoid using them to identify your element, as the string of numbers will change on refresh. This means that as soon as the page refreshes, the ID will change and your jQuery Selector will no longer work. To make sure this doesn't happen, you should find a different Selector for elements with dynamic ID's. For example, if you're trying to select the td with the dynamic ID below, you could use .dataCol.inlineEditWrite or .labelCol:contains(Complexity Factors) + td. However, you should not use td#00N00000067211_ilecell. This is a dynamic ID and will change:

If you absolutely need to use a dynamic ID to identify an element, you should only use part of it, the part that does not change. This will take some guesswork, but typically you should try to find a word or string of text that looks like English. In this case, using "ilecell" would probably be a safe bet. To turn this piece of a dynamic ID into a Selector, use the partial format we discussed above, in the partial attribute section. If the full ID is written as [id="00N00000067211_ilecell"], a partial Selector will look like this: [id*="ilecell”]. Here we are writing the ID in the same format we use for other attributes (remember, ID's are just commonly used attributes). By adding the * after id, we tell WalkMe to look for an ID that contains "ilecell".

Now we've written a partial attribute for this dynamic ID. It is a safer and more robust alternative to using the full dynamic ID. However, while [id*="ilecell"] will probably select the element we want consistently, it may pick up on others we don't want. By removing the dynamic part of the ID, we've reduced the Selector to a fairly general attribute that probably describes other fields
on this website. Therefore, you should plug this partial attribute into a larger jQuery Selector. Let's use one from above. If we want to add our partial attribute to .dataCol.inlineEditWrite, we can swap it out for one of the two classes, creating [id*="ilecell"].inlineEditWrite. We can also just tack it on to the end: .dataCol.inlineEditWrite[id*="ilecell"].