https://github.com/telenko/xdompath
Library for query DOM nodes via XPATH language with new features (ShadowDOM support)
https://github.com/telenko/xdompath
shadowdom shadowdom-support xml-model xpath-language
Last synced: 9 months ago
JSON representation
Library for query DOM nodes via XPATH language with new features (ShadowDOM support)
- Host: GitHub
- URL: https://github.com/telenko/xdompath
- Owner: telenko
- License: mit
- Created: 2019-06-24T10:43:12.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2019-07-20T18:03:49.000Z (almost 7 years ago)
- Last Synced: 2025-08-31T21:24:09.480Z (9 months ago)
- Topics: shadowdom, shadowdom-support, xml-model, xpath-language
- Language: JavaScript
- Size: 62.5 KB
- Stars: 8
- Watchers: 1
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
### XDOMPATH
Library for query DOM nodes similar to XPATH language with new features (ShadowDOM support)
### Purpose of creating
XPATH language is oriented only on clear XML document model, but real DOM model now differs from XML because of ShadowDOM technology. XDomPath is new extended language which can handle ShadowDOM and allows to use DOM with ShadowDOM as XML language.
### API
1) Import library into your file:
```Javascript
import { XDomPath } from '@telenko/xdompath';
```
2) Create a xdompath instance by using query as argument
```Javascript
const allDivsPath = new XDomPath('.//div');
```
3) Select a scope to query for and run XDomPath:
```Javascript
const divsArr = allDivsPath.perform(document.body);
```
### Extended XML model for DOM with ShadowDOM:
XDomPath is trying to treat DOM with ShadowDOM as XML model. To achieve that DOM model XDomPath parses in such way:
1) shadowRoot elements are parsed as **always first children** of host element
2) child nodes of shadowRoot are parsed as direct children of shadowRoot element
3) slotted elements are parsed as direct children of host element
### Examples
```Javascript
//setup DOM
const container = document.createElement('div');
container.innerHTML = `
some text
another text
`;
const divWithShadow = container.children[0];
divWithShadow.attachShadow({ mode: "open" });
divWithShadow.shadowRoot.innerHTML = `
text inside shadow
some container inside shadow
text
`;
```
1) Deep querying through Light/Shadow DOM
```Javascript
//let's query
const queryDivs = new XDomPath('.//div');
const allDivs = queryDivs.perform(container);
console.log(allDivs.length);//3
const divsInsideShadow = new XDomPath('.//shadow()//div');
const shadowDivs = queryDivs.perform(container);
console.log(shadowDivs.length);//1
const particularText = new XDomPath('.//text()[.="text inside shadow"]');
const texts = particularText.perform(container);
console.log(texts.length);//1
```
2) Querying by class existence
```Javascript
const withClassQuery = new XDomPath('.//p[class("bold_paragraph")]');
const psWithClass = particularText.perform(container);
console.log(psWithClass.length);//2
```
3) Querying focusable elements
```Javascript
const withClassQuery = new XDomPath('.//focusable()');
const psWithClass = particularText.perform(container);
console.log(psWithClass.length);//1
```
4) Using regular XPATH axes
```Javascript
const withClassQuery = new XDomPath('.//p[class("bold_paragraph")]/following-subling::input');
const psWithClass = particularText.perform(container);
console.log(psWithClass.length);//1
```
### Supported features
1) All XPATH axes
2) Function list:
- text()
- position()
- last()
- not()
- name() -- planned, but not supported for now
- id() -- planned, but not supported for now
- string()
- substring()
- substring-after()
- substring-before()
- string-length()
- count()
- concat()
- normalize-space()
- starts-with()
- contains()
- translate() -- planned, but not supported for now
- ceiling()
- floor()
- round()
- sum() -- planned, but not supported for now
**new XDomPath functions:**
- shadow() -- returns nodes which are instances of ShadowRoot
- class() -- receives string and returns true if node has class
- focusable() -- returns nodes which are focusable HTML elements
### Limitations
1) Mathematical operations (except of comparison operators '=' '<' '>' '<=' '>=')
2) Some particular functions (from item above)
3) Union operator | (plan to support in future)
4) 'or' 'and' operators inside filters
5) '( )' group operators inside of filters:
```Javascript
new XDomPath('(.//div)[0]');//will work
new XDomPath('.//div[(position() < 3)]');//won't work
```
6) NodeList -> String type conversion for now works by different algorithm:
```Javascript
list[#text, #text, #text] -> list[0].textContent;//only 1st item's textContent
```
### Dist folder
Dist folder contains of 2 compiled js files:
- xdompath.min.js - compiled version of XDomPath
- xdompath.global.min.js - compiled version, but auto-pushed to global window scope as
```Javascript
window.XDomPath
```
### Current issues
1) '..' parent axis working not properly for now. For now alias '/parent::' recommended to use instead
### Plans
1) Cover more XPATH features
2) Introduce new method:
```Javascript
XDomPath.defineFunction(...);
```
to make possible extend base set of functions with custom ones