jQuery should be used for edge cases only
We recommend using jQuery as little as possible. Web applications are constantly changing and small updates to the UI and page structure can break any jQuery used.
WalkMe's out of the box element selection adapts to changes in the underlying application without the use of jQuery.
Brief Overview
jQuery is a JavaScript library used to identify and manipulate HTML elements on a page. While WalkMe provides out-of-the-box element selection that adapts to UI changes, jQuery selectors act as a powerful alternative for edge cases.
These selectors identify elements based on specific characteristics, such as ID, Class, Type, and Attributes.
Use Cases
We recommend using jQuery sparingly to maintain build stability. However, it is a vital tool for the following tasks:
- Create Onboarding Goals: Define goals based on an On Screen Element
- Configure launchers: Input specific selectors into the Selected Element tab
- Grab values: Capture user variables or on-screen text for dynamic announcements
- Check page conditions: Use the Rule Engine to analyze element attributes
How It Works
Follow these steps to build, test, and implement custom selectors in your WalkMe content.
🎓 Digital Adoption Institute
Available Rule Engine operators
When using the jQuery rule type in the Rule Engine, use these operators to define your logic:
- True: At least one element was found
- False: No elements were found
- Visible: The element is currently visible on the page
- Text Is / Is Not: The element text matches or does not match your input
- Note: When the selector returns more than one element, all elements' text are combined as one element
- Greater Than / Less Than: Value is above or below a whole number
- Like / Not Like: Means a complicated text syntax
- Length Is / Is Not / Greater Than / Less Than: The number of elements returned by the query
- Find the exact query length: wmjQuery(“element.value”).length
Note
The WalkMe Editor only supports selectors written in jQuery syntax up to that used in jQuery 1.8.3. However, you may use any version of jQuery for other purposes on your website without fear of a conflict with WalkMe's version of jQuery (wmjQuery).
We recommend that you also utilize WalkMe's jQuery Selector Optimizer.
Common jQuery Selectors
Use these patterns to identify elements within your application:
- element: Locate a specific HTML element by its tag name
- element[attribute]: Locate an element that contains a specific attribute
- element[attribute][attribute]: Locate an element that matches multiple attributes simultaneously
- element[attribute="value"]: Locate an exact match for an attribute and its value
- element[attribute^="text"]: Locate an element where the attribute starts with specific text
- element[attribute*="text"]: Locate an element where the attribute contains specific text anywhere within the string
- element[attribute!="text"]: Locate an element that does not contain the specified attribute text
- element child-element: Locate a nested child element (the space indicates a parent-child relationship)
- element:checked: Locate the status of a checkbox or radio button
- [element]:visible: Verify if a specific element is currently visible on the page
- element:contains(Text): Locate an element based on the specific text string it contains
- element:eq(#): Locate a specific index in a list of results (note that the count starts at 0)
Step 1: Build the selector
- Locate the element in the HTML by right-clicking it and selecting Inspect Element
- Identify unique characteristics like class, ID, or style
- Draft your selector using the syntax: Element → Selector → Value
- Example (ID): ul#create-account
- Example (Class): ul.nav
Create jQuery using your WalkMe Data
You can now utilize existing WalkMe Data in favor of a jQuery selector.
This can be accomplished by adding '${wm-data-key}' to the desired selector. For example: the selector: [id="${key}"], will have the '${key}' replaced by the actual WalkMe data and will look like: [id=”value”].
Step 2: Test in the console
Note: You must have the Editor Extension enabled to use this method.
- Open your browser's Developer Tools and select the Console tab
- Type wmjQuery("your-selector-here") and press Enter
- Hover over the returned objects in the console to verify the correct element is highlighted on screen
Step 3: Implement in the editor
Once verified, you can apply your selector in several locations:
- Selected Element tab: Use for specific Step or Launcher identification
- Additional step triggers: Use to trigger steps on click or hover
- Rich Text Editor: Use to display Dynamic Text in balloons or Shoutouts
- Rule Engine: Select the jQuery Rule Type to build complex logic
To ensure the best user experience, compare the speed of your selectors:
- Type the following script into your console: var time1 = window.performance.now(); wmjQuery('selector'); var time2 = window.performance.now(); console.log(time2 - time1);
- Run the command several times to find the average execution time
- Select the version with the lowest average time
Tip
Remember that jQuery should be used sparingly in your WalkMe builds, and always in combination with lighter conditions. Please refer to the following article for more information: WalkMe Performance Best Practices
Technical Notes
- For sites using Shadow DOM you won't be able to run wmjQuery in the DevTools Console, you'll need to use this syntax instead:
_walkmeInternals.ctx.get('JQuerySelectorRunnerShadow').run('enter your selector here')
