String-like DOM text manipulator.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dist
src
test
.gitignore
Makefile
README.md
gulpfile.ls
package.json

README.md

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,

<script src="vendor/fibre.js/fibre.js"></script>

AMD,

require( './node_modules/fibre.js/src/fibre', function( Fibre ) {
  var fibre = Fibre( document.body )
  …
})

CommonJS (NPM),

var Fibre = require( 'fibre.js' )
var fibre = Fibre( document.body )
…

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

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( context, noPreset )

fibre
  .replace( … )
  .wrap( … )

The noPreset switch

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
Fibre( document.body )
// Document node
Fibre( document )
// jQuery object
Fibre( $( '.container article' )[0] )
// CSS selector (will only affect the first matched node)
Fibre( '.container article' )

Fibre.fn.wrap()

The method wraps an assigned node round the matched text in the given context.

Syntax

fibre.wrap( regexp|substr, strElemName|node )

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

<body>
  <p>Apple-eaters eat thousands of apples a day.</p>
</body>
Fibre( document.body ).wrap( /\bapple(s)?\b/gi, 'em' )

Which results in:

<body>
  <p><em>Apple</em>-eaters eat thousands of <em>apples</em> a day.</p>
</body>

Works with matches spread in different nodes,

<body>
  <p><span>App</span>le-eaters eat thousands of apple<span class="pl">s</span> a day.</p>
</body>

Results in:

<body>
  <p><span><em>App</em></span><em>le</em>-eaters eat thousands of <em>apple</em><span class="pl"><em>s</em></span> a day.</p>
</body>

Fibre.fn.replace()

The method replaces the matched text in the given context with a new string.

Syntax

fibre.replace( regexp|substr, newSubStr|function )

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

<article>
  <p>Th<span>is</span> paragraph is to be later replaced.</p>
</article>
var fibre = Fibre( 'article' )

fibre
  .replace( /(\w+)/g, '*$1' )
  .replace( /\*this/ig, function( portion, match ) {
    var idx = portion.index
    return idx + match[ idx ].toUpperCase()  
  })

Will result in:

<article>
  <p>*TH<span>IS</span> *paragraph *is *to *be *later *replaced.</p>
</article>

Fibre.fn.setMode()

The method sets the portion mode of the instance.

Syntax

fibre.setMode( portionMode )

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.addBoundary( selector )

Parametres

selector
A String containing one or more CSS selector(s) to be added as text boundaries.

Examples

<div id="test">
  <p>Something</p>
  <p>Some</p><blockquote>Thing</blockquote>
  <a>Something</a>
  <a>Some</a><a class="block">Thing</a>
</div>
Fibre( document.getElementById( 'test' ))
  .wrap( /something/gi, 'span' )
  .addBoundary( 'a.block' )
  .wrap( /something/gi, 'b' )

Will result in:

<div id="test">
  <p><span><b>Something</b></span></p>
  <p>Some</p><blockquote>Thing</blockquote>
  <a><span><b>Something</b></span></a>
  <a><span>Some</span></a><a class="block"><span>Thing</span></a>
</div>

Fibre.fn.removeBoundary()

The methods removes all custom text boundaries of the instance.

Syntax

fibre.removeBoundary()

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.avoid( selector )

Parametres

selector
A String containing one or more CSS selector(s) to avoid the matched nodes while traversing.

Examples

<div id="test">
  <p>This <span class="be">is</span> a simple test.</p>
</div>

<script>
 var test = 'This is a simple test.' 
</script>
Fibre( document.getElementById( 'test' ))
  .wrap( /is/gi, 'span' )
  .avoid( '.be' )
  .replace( /is/gi, 'IZZ' ) 

Will result in:

<div id="test">
  <p>Th<b>IZZ</b> <span class="be"><b>is</b></span> a simple test.</p>
</div>

<script>
 var test = 'ThIZZ IZZ a simple test.' 
</script>

Fibre.fn.endAvoid()

The method ends the avoiding and pops back to previous state of the context.

Syntax

fibre.endAvoid( all )

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.filter( selector )

Parametres

selector
A String containing one or more CSS selector(s) to filter the matched nodes while traversing.

Examples

<div id="test">
  <p>This <span class="be">is</span> a simple test.</p>
</div>

<script>
 var test = 'This is a simple test.' 
</script>
Fibre( document.getElementById( 'test' ))
  .wrap( /is/gi, 'b' )
  .filter( '.be b' )
  .wrap( /is/gi, 'em' ) 

Will result in:

<div id="test">
  <p>Th<b>is</b> <span class="be"><b><em>is</em></b></span> a simple test.</p>
</div>

<script>
 var test = 'This is a simple test.' 
</script>

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.endFilter( all )

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.revert( [level] )

Parametres

level
Optional. A Number or a String whose value is 'all' indicating the finder level to revert. The default value is 1.

Examples

var fibre = Fibre( document.getElementById( 'test' ))
  .replace( /\bis\b/gi, 'isn\'t' )
  .wrap( /\bwill\b/gi, 'span' )

// Later,
fibre.revert( 'all' )

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.matches( node, selector, bypassNodeType39 )
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

<!doctype html>
<html lang="en">
  <head>
  </head>
  <body class="post">
  </body>
</html>
Fibre.matches( document.body, 'body.index, body.post' )  // returns true
Fibre.matches( document.documentElement, '[lang="es"]' ) // returns false 
Fibre.matches( document, 'style' )                       // returns false
Fibre.matches( document, 'style', true )                 // returns true