Descop
A small Library allowing you to get caret [start, end] offset position of element in source HTML code
Basic Overview
Descop is a library which allows you to find a source code position of target document element in standardized way.
Note: it works only with a static document without scripts or any dynamic markup. If you need to find an element inside a dynamic document - use a some kind a Static to Dynamic DOM mapper first. Or, simply wait a bit - i'm on my way to create a one for you.
- Eugene Ford, author
Library can be used both in Node.js and directly in Browser. It is well-documented and completely covered with test specs (excluding webpack bundling definitions and external modules).
If you want to add some features or to suggest any idea, feel free - contributions are always welcome.
How to Install
Using NPM
To use Descop with NPM simply call:
npm install --save descop
In Browser
To use Descop directly in browser simply download this repository and copy dist/descop.js into your project. Next, include it on your .html page:
Get Started
First, there are two simple conditions to use Descop:
- Your html source must be Valid. (use w3c validator for example)
- Your document must be a static one.
That's all.
You are able to use Descop as the importable npm package or directly in browser.
In Node.js
; // Get the source html code of target documentvar html = ; // Get the target document itselfvar dom = ; // Get the element you want to found in source codevar element = document; // Create an instance of Descopvar descop = ; // Connect documentdescop; // Connect source codedescop; // Get element position in source codevar position = descop;// eg. position => { start: 320, end: 480 }
In Browser
API
connectSource(html)
Connects an html source to Descop instance
var descop = ;var html = "<!DOCTYPE html><title > Example </title ><div>Hello World</div>";descop;
connectDocument(document)
Connects a document to Descop instance
var descop = ;descop;
findFragmentPosition(fragment, fromIndex)
Returns the position (start and end offset) of the first occurrence of specified html fragment inside connected html source. Fragment - html string to search for, FromIndex - optional index to start search from
var descop = ;... var position = descop;// position => { start: 15, end: 41 }
findFragment(fragment, fromIndex)
Returns the first occurrence of specified html fragment inside connected html source. Fragment - html string to search for, FromIndex - optional index to start search from.
var descop = ;... var html = descop;// html => "<title > Example </title >"
findElementPosition(element)
Returns the position (start and end offset) of target element in source html code. Element - element to search for.
var descop = ;...var element = document; var position = descop;// position => { start: 41, end: 63 }
findElement(element)
Returns the source html code of target element. Element - element to search for.
var descop = ;...var element = document; var html = descop;// html => "<div>Hello World</div>"
getSource()
Gets current html source.
var descop = ; ... var source = descop;
getDocument()
Gets current document.
var descop = ; ... var doc = descop;
Contributing to Descop
Contributions are always welcome. Before contributing please read the code of conduct & search the issue tracker (your issue may have already been discussed or fixed).
To contribute, follow next steps:
- Fork Descop
- Commit your changes
- Open a Pull Request.
Feature Requests
Feature requests should be submitted in the issue tracker, with a description of the expected behavior & use case, where they'll remain closed until sufficient interest (e.g. 👍 reactions). Before submitting a feature request, please search for similar ones in the closed issues.
License
Released under the MIT License