Developer Tools: Highlighter - Beta

Highlight Scripture References on Your Website

The Highlighter will automatically find Scripture references on your website and allow your visitors to read and explore those passages without leaving your site.

The best way to see it in action is to try it. Try clicking on John 3:16, or Psalm 23 (RSV). Those links were automatically created by the Highlighter by finding Scripture references and making them clickable.

The Highlighter is the perfect way to let your visitors read Scripture without leaving your site. When she's done reading, your visitor can click the X to close the mini Scripture window, and she'll be reading your devotional again. You can try out a demo of the Highlighter to see a few more examples.

Basic Usage

To use the Highlighter on your website, add the following line of HTML just before the closing </head> tag on every page on your website that should have Scripture references found:

<script id="bw-highlighter-config">
(function(
wdseid) {
  
w._bhparse w._bhparse || [];
  function 
l() {
    if (
d.getElementById(id)) return;
    var 
d.createElement(s), d.getElementsByTagName(s)[0];
    
n.id idn.async truen.src '//bibles.org/linker/js/client.js';
    
x.parentNode.insertBefore(nx);
  }
  (
w.attachEvent) ? w.attachEvent('on' el) : w.addEventListener(elfalse);
})(
windowdocument'script''load''bw-highlighter-src');
</script> 

Once it loads, the Highlighter will find anything that looks like a Scripture reference and link it to the Bible Search website. Visitors can now click Scripture references to read them without leaving your website.

The Highlighter recognizes references in a variety of common formats, and recognizes many common book abbreviations. Currently it supports only English-language book names and abbreviations, although you can use non-English Bible versions.

NOTE: Some versions of Internet Explorer won't display the pop-up window properly unless your page includes a valid DOCTYPE.

Configuration

You can change Highlighter's default behavior with some configuration options, which you set when adding the Highlighter to your site.

Highlighter Configuration Options
Option Default Value Valid Values Purpose
autoparse true true or false Whether or not to automatically look for Scripture references. read more
ignore highlighter-skip any valid class name A class name that should be skipped when finding Scripture. read more
maxdepth 10 any positive number Set the maximum depth for DOM parsing. read more
ssl match match, on, or off Control whether SSL (https) is used for generated links. read more
version eng-GNTD see below Specify the Bible version used for all found references. read more

These options are added as data attributes to the <script> element that loads the Highlighter. For example, to configure the Highlighter to use the RSV, and to ignore any text inside an element with the no-scripture class, the <script> element would look like:

<script id="bw-highlighter-config" data-version="RSV" data-ignore="no-scripture"

Each of the configuration options is discussed below.

Bible Versions

Changing the Default Version

By default, the Highlighter will link to the GNTD (Good News Translation). However, the Highlighter can be configured to use one of several versions available on the Bible Search website (see below for a complete list). For instance, if you would like to use the Revised Standard Version (RSV) instead, add the Highlighter to your site with this code instead:

<script id="bw-highlighter-config" data-version="RSV"

Note the new data-version="RSV" line in the configuration script. Now, when the Highlighter finds Scripture references, it will display them from the RSV instead of from the GNTD.

Specifying Versions With References

If you'd like to specify that a particular Scripture reference should use a specific Bible version, just put that version abbreviation in parentheses after the reference. For example, the reference John 3:16 (KJV) will instruct the Highlighter to use the KJV for that reference. All other found references will still use whatever version you configured when you loaded the Highlighter (or the GNTD if you didn't specify one).

Available Versions

The Highlighter supports linking to any Bible version available on the Bible Search website. Below are the English-language versions that are supported by the Highlighter, with abbreviations in bold. You can see a full list of supported version abbreviations on the versions page.

List of English-language Bible Versions
Language Abbrev. Version Name
English (British) CEVUK Contemporary English Version (Anglicised Version)
CEVUK00 Contemporary English Version (Anglicised Version)
DARBY Darby Translation 1890
DRC1752 Douay-Rheims Challoner Revision 1752
GNBDC Good News Bible (Anglicised)
GWC The Trench Epistles GWC 1915
KJV King James Version
RV1885 Revised Version 1885
WEBBE World English Bible British Edition
English (US) AMP Amplified Bible
ASV The Holy Bible, American Standard Version
CEV Contemporary English Version (US Version)
CEVD Contemporary English Version (US Version)
CEVUS06 Contemporary English Version
ESV English Standard Version
GNTD Good News Translation (US Version)
KJVA King James Version with Apocrypha, American Edition
MSG The Message
NABRE New American Bible, Revised Edition
NASB New American Standard Bible
NIV New International Version
NLT New Living Translation
NRSV New Revised Standard Version
RSV Revised Standard Version
RV Revised Version 1885
WEB World English Bible
WMB World Messianic Bible
WMBBE World Messianic Bible British Edition
Others See the versions page. Each version's abbreviation is listed in parentheses.

You can see a live example of using a different version on the Highlighter demo page.

Non-Reference Text

In some cases, the text you want to link to Scripture is not an actual Bible reference. By default, the Highlighter looks for a variety of standard Scripture reference formats. However, let's say you have website copy like this:

<p>I really like telling people about my favorite Bible verse.</p

and you'd like to use the Highlighter to open up John 3:16 when your visitors click the words my favorite Bible verse. Just surround those words with a <cite class="bibleref"> tag that includes a title attribute that lists the specific Bible reference. Your updated HTML would look like:

<p>I really like telling people about <cite class="bibleref" title="John 3:16">my favorite Bible verse.</cite></p

Now, the Highlighter will know to display John 3:16 when your visitors click the text "my favorite Bible verse." The reference in the title attribute can specify an alternate version in parentheses, as well:

<p>I really like telling people about <cite class="bibleref" title="John 3:16 (NRSV)">my favorite Bible verse.</cite></p

You can see a live example of linking non-reference text on the Highlighter demo page.

Controlling Where the Highlighter Looks

As soon as a page's contents are loaded, the Highlighter will, by default, scan that page to find Scripture references, starting at the <body> element. You have several options for controlling where the Highlighter does and doesn't look, and when it should look for Scripture.

Ignoring Specific Elements

There are times when you don't want the Highlighter to try to find Scripture references in a portion of your webpage. Perhaps you have some text that looks like a Scripture reference, but really isn't, or perhaps it's simply an area that you simply don't want linked to Scripture.

To mark a portion of your HTML as being off-limits to the Highlighter, simply add the class highlighter-skip to an element, and the Highlighter will not look for Scripture references in its text. For example, in this HTML:

<p>Please read John 3:16.</p>
<
class="highlighter-skip">I have been a pro 2 times in my life.</p

Since it's contained inside an HTML tag with the highlighter-skip class, the phrase pro 2 will not be linked to Bible Search, even though it would normally match as a reference to Proverbs 2.

You can change the class name that Highlighter uses to skip parsing to whatever you'd like, using the ignore configuration setting:

<script id="bw-highlighter-config" data-ignore="my-ignore-class"

If you find that you are adding the ignore class to a lot of the elements on your page, you might want to consider parsing only specific elements, instead.

Parsing a Specific Element

You can tell the Highlighter to parse one or more specific portions of your website, identified by the id DOM attribute. If your HTML looks like this:

<div class="sidebar">
  <
h3>About the John 1 Blog</h3>
  <
p>This blog is mostly about Johnbut sometimes other things.</p>
</
div>
<
div id="content">
   <
p>Though not from John 1I have some thoughts on the Easter story in Luke 24.</p>
</
div

And you'd like the Highlighter to only consider the Bible references in the content div, then sometime after you insert the Highlighter code, add a call to _bhparse.push('content'). The full code would look like:

<script id="bw-highlighter-config">
(function(
wdseid) {
  
w._bhparse w._bhparse || [];
  function 
l() {
    if (
d.getElementById(id)) return;
    var 
d.createElement(s), d.getElementsByTagName(s)[0];
    
n.id idn.async truen.src '//bibles.org/linker/js/client.js';
    
x.parentNode.insertBefore(nx);
  }
  (
w.attachEvent) ? w.attachEvent('on' el) : w.addEventListener(elfalse);
})(
windowdocument'script''load''bw-highlighter-src');
</script>
<script>
_bhparse.push('content');
</script> 

Notice the addition of _bhparse.push('content'). Adding that code will cause the Highlighter to only consider references in the content div and ignore the reference it would otherwise have found in the sidebar div. You can send multiple DOM IDs to the _bhparse.push() function at once, for example:

<script>
_bhparse.push('header''footer''about');
</script> 

Disabling Automatic Parsing Entirely

If you'd like to load the Highlighter but not have it parse anything at all when it loads, and only trigger parsing via the _bhparse.push() method, you can load the Highlighter with the autoparse option set to false:

<script id="bw-highlighter-config" data-autoparse="false"

If you load the Highlighter this way, no Scripture references will be found until you call the _bhparse.push() function somewhere else in your JavaScript code. This is useful if you have HTML that is loaded by AJAX or some other delayed method.

Advanced Options

Controlling Use of HTTPS

The Highlighter generates links back to the Bible Search website. It will automatically choose http (non-SSL) or https (SSL) for those links, matching the page that embeds the Highlighter. For example, if your visitor navigates to your site at https://example.com/, then the Highlighter will generate links back to Bible Search using https (SSL).

If you know that you always want to use https, set the ssl configuration setting to on:

<script id="bw-highlighter-config" data-ssl="on"

This will cause Highlighter-created links to always use SSL, whether or not your page is loaded with SSL. The off option ensures that SSL is never used:

<script id="bw-highlighter-config" data-ssl="off"

The default behavior is to match, and does not need to be specified (although you can):

<script id="bw-highlighter-config" data-ssl="match"

Changing Parsing Depth

By default, the Highlighter finds the <body> element in your HTML page and, from there, searches the contents of child elements for Scripture references. To ensure that the Highlighter doesn't consume too many browser resources, it will only examine tags that are nested up to 10 levels deep from the starting point. In an HTML structure like this:

<body>
  <
p>John 3:16</p>
  <
div><div>
    <
table><tbody><tr><td>
      <
div>
        <
ul>
        <
li><em><span>Psalm 100:1</span></em></li>
        </
ul>
      </
div>
    </
td></tr></tbody></table>
  </
div></div>
</
body

the text John 3:16 will be found and linked to Bible Search, since it's only 1 level deep from the <body> tag. However, since the text Psalm 100:1 is nested 11 levels deep, the Highlighter will stop before it reaches that text.

If you have Scripture references that are not being found, you can try adjusting the maxdepth setting to have a higher number:

<script id="bw-highlighter-config" data-maxdepth="15"

This will instruct the Highlighter to continue searching for Scripture references further into your page's HTML structure.

The maxdepth setting is relative to the starting point of the parsing, so if you configure Highlighter to parse a specific element then it will search 10 levels deep (or whichever alternate setting you chose) from that particular element.

Parsing an Element loaded by AJAX

Sometimes your content is added to the DOM sometime after the full page loads, for example by an AJAX request. If that content contains Scripture references they won't automatically be found by the Highlighter (since they weren't present when the Highlighter loaded). To tell the Highlighter to parse them, add a call to _bhparse.push() somewhere in a a callback that runs after your AJAX content has loaded:

// earlier in your JavaScript code
window._bhparse window._bhparse || [];

// An AJAX request (using jQuery)
$('#someElementID').load('/some/URL', function () {
  
window._bhparse.push('someElementID');
}); 

Note that we've added a line defining window._bhparse as an array if it's not already defined. This is to ensure that in case this AJAX code runs and completes before the Highlighter loads, the Highlighter will know to find and parse the DOM node with the ID someElementID when it does get done loading.