Fibre.js
Fibre.js is a small library based on FindAndReplaceDOMText
by James Padolsey.
The method collections of Fibre.js help search for the regular expression matches in a given context (a DOM node) and replace/wrap each one of them with a new text run or a new DOM node.
Chaining & string-like syntax supported.
Install
- NPM
npm i fibre.js --save
Require the library
Use the script
element,
AMD,
CommonJS (NPM),
var Fibre = var fibre = …
Run test
- Install dependencies
sudo npm i
- Run test
gulp test
Browser support
Fibre.js works on all modern browsers with no legacy support for older IE.
License
Fibre.js is released under MIT License.
API
- Introduction
- Fibre.fn.wrap()
- Fibre.fn.replace()
- Fibre.fn.setMode()
- Fibre.fn.addBoundary()
- Fibre.fn.removeBoundary()
- Fibre.fn.avoid()
- Fibre.fn.endAvoid()
- Fibre.fn.filter()
- Fibre.fn.endFilter()
- Fibre.fn.revert()
- Fibre.matches()
Introduction
The syntax is as simple as jQuery!
Fibre
needs no new
operator to create an instance. Assign one DOM node to the first parametre context
to initialise.
Syntax
var fibre = fibre
noPreset
switch
The By default, Fibre ignores elements like style
, script
, img
, etc and considers elements like div
, p
, h1
, etc the boundaries of text. Set the second parametre noPreset
to true
to turn off such configuration.
Examples
// Regular DOM node// Document node// jQuery object// CSS selector (will only affect the first matched node)
Fibre.fn.wrap()
The method wraps an assigned node round the matched text in the given context.
Syntax
fibre
Parametres
regexp
- A RegExp object. Text that matches will be wrapt by the return node of parametre #2.
substr
- A String of which matches is to be wrapt by the return node of parametre #2.
strElemName
- A string of an element name to wrap round the matched text.
node
- A node that is to be cloned for each match portion.
Examples
Apple-eaters eat thousands of apples a day.
Which results in:
Apple-eaters eat thousands of apples a day.
Works with matches spread in different nodes,
Apple-eaters eat thousands of apples a day.
Results in:
Apple-eaters eat thousands of apples a day.
Fibre.fn.replace()
The method replaces the matched text in the given context with a new string.
Syntax
fibre
Parametres
regexp
- A RegExp object. Text that matches will be replaced by the return value of parametre #2.
substr
- A String that is to be replaced by the return value of parametre #2.
newSubStr
- The String that replaces the substring received from parametre #1. Common replacement patterns supported.
function
- A callback function to be invoked and returns the new substring or node.
Examples
This paragraph is to be later replaced.
var fibre = fibre
Will result in:
*THIS *paragraph *is *to *be *later *replaced.
Fibre.fn.setMode()
The method sets the portion mode of the instance.
Syntax
fibre
Parametres
portionMode
- A String of either `'retain'` or `'first'`, which indicates whether to re-use the existing node boundaries when wrapping a match text, or simply place the entire replacement in the first-found match portion's node. The default value is `'retain'`.
Fibre.fn.addBoundary()
The method adds text boundary(ies) to avoids their cross-node matching and replacing.
Syntax
fibre
Parametres
selector
- A String containing one or more CSS selector(s) to be added as text boundaries.
Examples
Something SomeThing Something SomeThing
Will result in:
Something SomeThing Something SomeThing
Fibre.fn.removeBoundary()
The methods removes all custom text boundaries of the instance.
Syntax
fibre
Note: The preset configurations will not be removed by the use of the method.
Fibre.fn.avoid()
The method avoids the nodes matching the given selector which will later not apply the wrap/replace method.
Note: An older name of the method filterOut()
is deprecated since v0.2.0. Will be removed in the next major update.
Syntax
fibre
Parametres
selector
- A String containing one or more CSS selector(s) to avoid the matched nodes while traversing.
Examples
This is a simple test.
Will result in:
ThIZZ is a simple test.
Fibre.fn.endAvoid()
The method ends the avoiding and pops back to previous state of the context.
Syntax
fibre
Parametres
all
- *Optional.* A Boolean that decides whether to reset all the avoiding conditions or just one level.
Note: The preset configurations will not be reset by the use of the method.
Fibre.fn.filter()
The method filters the nodes matching the given selector which will later apply the wrap/replace method.
Syntax
fibre
Parametres
selector
- A String containing one or more CSS selector(s) to filter the matched nodes while traversing.
Examples
This is a simple test.
Will result in:
This is a simple test.
Note: The matched text inside script
element isn't altered for Fibre avoids script
, style
, etc by default.
Fibre.fn.endFilter()
The method ends the filtering and pops back to previous state of the context.
Syntax
fibre
Parametres
all
- *Optional.* A Boolean that decides whether to reset all the filtering conditions or just one level.
Note: The preset configurations will not be reset by the use of the method.
Fibre.fn.revert()
The method reverts the finder by a given level.
Syntax
fibre
Parametres
level
- Optional. A Number or a String whose value is
'all'
indicating the finder level to revert. The default value is1
.
Examples
var fibre = // Later,fibre
Description
The last line of the script above will revert the context (document.getElementById( 'test' )
) back to the state before any replace or wrap method has executed.
Fibre.matches()
The method compares and returns whether a given node matches the given CSS selectors.
Syntax
Fibre
node
- A node object to compare.
selector
- A string of CSS selectors to check if the node matches.
bypassNodeType39
- Optional. A boolean that decides whether to always return `true` for Document or Text nodes.
Examples
Fibre // returns trueFibre // returns false Fibre // returns falseFibre // returns true