npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

dom-node-selection-mapper

v1.0.0

Published

A client-side JS lib for producing reusable selector strings to target DOM nodes on an HTML page

Downloads

6

Readme

DOM Node Selection Mapper

This is a client-side JS library that allows you to pass in an HTML Element node and identifiable string(s) associated with that node, and builds a resuable CSS selector string that allows you to target that same node again in the future.

It conforms to CSS Level 3 specifications, and builds selectors that are usable directly from javascript (aka document.querySelectorAll) or via jQuery's sizzle selector engine.

It also allows you to build loose selectors that can be flexible as the page format & item attributes change, or high-specificity selectors that target element attributes with exact matching based on your classifiers (such as ID & name attributes).

Authored by Evan Carothers

What can I use this library for?

It is ideally designed for use cases where a user selects an element on an HTML page, and you need to programatically target that same element in the future (on this exact page , or pages with similar structure/formatting).

Installation

The package is available directly on github, or via package management (bower / npm):

bower install dom-node-selection-mapper --save
npm install git+https://github.com/ecaroth/dom-node-selection-mapper --save

Usage

Include the script file /dist/dom_node_selection_mapper.min.js on your webpage. This creates a global object DOMNodeSelectionMapper, which exposes a single static function:

####DOMNodeSelectionMapper.mapNode( node, mappings, loose_match)

node (HTML Element) DOM node that you wish to map selector for

mappings (string or array of strings) Matches that you want to use when building the selector string that can help identify the node and it's parents

loose_match (boolean) Allow loose attribute matching based on mapping values, else uses strict attribute matching which can tighten up selector specificity, but also allows for less flexibility in the selector reuse if you expect changes in IDs/classnames/etc

For example, given the following HTML fragment:

<body>
    <form>
        <div class="row address">
            <label>
                <input name="street" id="street_1" placeholder="Enter your street">
            </label>
            <label>
                <input name="city" id="city_1" placeholder="Enter your city">
            </label>
        </div>
        <div class="row address">
            <label>
                <input name="street" id="street_2" placeholder="Enter your street">
            </label>
            <label>
                <input name="city" id="city_2" placeholder="Enter your city">
            </label>
        </div>
    </form>
</body>

you can leverage the object to build reusable selectors to the id="city_2" input like so:

var node = document.getElementById('city_2');
var selector = DOMNodeSelectionMapper.mapNode( node, ['address','city'], false );

with loose_match set to true you would get a resulting selector string like:

FORM > DIV[class*="address"]:nth-of-type(2) INPUT[id*="city"][name*="city"]

and with loose_match set to false you would get a resulting selector string like:

INPUT[id="city_2"][name="city"]

Specificity and mapping inputs

You will notice that for non-loose matching, more specificity is used which often means more brevity for the selector. And, when a match with high confidence can be found (aka with an ID or name attribute) then the selector mapping ends there matching the specific high-confidence values, since that will be adequite for reuse.

In the example above, you are able to get a more replicatable match by providing more than 1 item in mappings. If you were to simply pass in 'city' you would get a loose match result like:

FORM > DIV:nth-of-type(2) INPUT[id*="city"][name*="city"]

Loose matching is intended for use cases where the context of the DOM node on the page might not be consistent, but you want to try and match it if possible. It can lead to edge cases where more than 1 element on the page can be matched from the generated selector, but it usually does a good job of coercing the selector to include only the specificity it needs to match in the current context and leave it flexible enough for reuse.

Development

The dev server runs on localhost:3003. Once running you can load the JS in running local pages from localhost:3003/dom_node_selection_mapper.js

npm install
npm run dev

When working with the DOMNodeSelectionMapper object, you can enable a debug mode with verbose logging by setting the debug param to true

DOMNodeSelectionMapper.debug = true;

There is an example of a page you can use locally for development in dev/sample_dev_page.html

Testing

The test suite builds and checks for exact and loose matches in variety of HTML templates in the /test/templates directory. To execute the tests you must install all the npm dependencies

npm test

Building for distribution

You can generate the needed (dev & minified) files by running the gulp build command, which builds scripts in the /dist directory

gulp build