Bible Gateway Tools (Beta) Documentation

What is it?

This tool is a small block of code that, once added to a webpage, transforms all plaintext Scripture references on that page into hyperlinks to the appropriate Bible passage at the Bible Gateway. When you hover the mouse pointer over one of these links, the text of the Bible passage appears in a window, letting you see the passage without leaving the webpage you're reading.

Why would you use it?

It will automatically turns Bible references into links, which saves you the trouble of manually doing so—and that can save you a lot of work, especially if you have a webpage that contains many Scripture references. Instead of laboriously hand-coding each link, you can let us handle it!

From the perspective of your web visitors, this allows them quickly and easily read Bible references in your content while they read—they don't even have to leave your website or take any action to look them up.

Using it on your site

It's easy to add this tool to your website. All you need to do is paste the block of Javascript below into your site. Paste this code at the end of each page you want this tool to function; if you have a footer or another page element that appears on every page, it might be a good idea to place it there. Otherwise, make sure it appears just before the </body> tag. Here's the code:

<script src="http://tools.biblegateway.com/js/bg_links.js" type="text/javascript"></script>
<script type="text/javascript">
  bg_links.find_verses();
</script>

You can also customize the appearance and content of the tooltip window. The rest of this documentation describes how this tool works, and how you can adjust it to fit your needs.

How it works

As noted above, the Javascript turns all plaintext Scripture references on a webpage into links. It's important to note that it does skip over already linked verses.

It recognizes a variety of standard Bible reference formats. Here's how it handles different references:

When this Bible reference appears on your webpage...

...Bible Gateway does this

Genesis 1:1

Links to the specified verse. This is the standard Book:Chapter:Verse reference format.

Gen 1:1

Recognizes common Bible book abbreviations, such as Gen (for Genesis), Ex (for Exodus), etc.

Genesis 1:1-31

Links to the specified range of passages and verses.

Genesis 1:5ff

Links to the specified verse and all following verses to the end of the chapter.

Genesis 1:1,5

Links individually to Genesis 1:1 and Genesis 1:5.

Genesis 1

Ignores Bible book names if they aren't followed by a passage and verse. For an explanation of why it does this, and how to correctly cite Bible passages, see this explanation of Bible passage citation. If you want to link to an entire Bible book, enclose the book title in the <cite class="bibleref"> tag, like this:

<cite class="bibleref">Genesis 1</cite>

Bible references that you've already linked to other resources are skipped over.

Customizing it

You can customize this tool behavior in several different ways by editing the Javascript code before you paste it into your site. See the example below for a template for adding these options:

<script src="http://tools.biblegateway.com/js/bg_links.js" type="text/javascript"></script>
<script type="text/javascript">

  bg_links.{option} = {value};
  bg_links.find_verses();

</script>

Following the table of the different options are descriptions of what each option does:

OptionValuesDefault
version 31
related_contenttrue, falsetrue
sites (hostname of webpage)
apocryphatrue, falsefalse
show_tooltipstrue, falsetrue
click_tooltiptrue, falsefalse

Change the Bible version

Option name: version_id

Default value: 31

Possible values: see http://www.biblegateway.com/usage/linking/votdlist.php

Notes: this element lets you specify the Bible version and translation that this tool uses when it grabs your Bible references. By default, it uses the New International Version, but you can change this to any Bible version at the Bible Gateway. Each Bible version has a unique version number; to change the Bible version, just replace the number 31 in the code with the version number of your choice. You can see a list of available Bible versions and their version numbers at http://www.biblegateway.com/usage/linking/votdlist.php. Please note, however, that not all Bible versions listed there will function with this tool.

Toggle the Related Content Panel

Option name: relatedcontent

Default value: TRUE

Possible values: TRUE, FALSE

Notes: when the tooltip displays a Bible verse, it also shows a Related Content panel with related information from the site the tool is running on. If you'd rather not see the Related Content panel, you can toggle it off by changing this element from TRUE to FALSE (or vice versa, if you want to enable the Related Content panel).

Change the source of the Related Content panel

Option name: bg_links.sites

Possible values: any website domain or subdomain

Default value: gospel.com

Notes: by default, this searches the site it's on for information related to your Bible references and displays that content in the Related Content panel. If you want to search for related content on another website instead, just change the value in this element to the domain or subdomain of the website you want to use. For example, if you want to get related content from Google, change the option to 'google.com.'

Toggle the Apocrypha

Option name: bg_links.apocrypha

Default value: FALSE

Possible values: TRUE, FALSE

Notes: by default, this tool does not recognize books or passages from the Apocrypha. If you want it to recognize and convert Apocryphal books and passages, just change this element from FALSE to TRUE. Note, however, that not all Bibles at the Bible Gateway contain the Apocrypha, so be sure to also change the bg_links.version_id (see above) to point to a Bible that does contain the Apocrypha.

Toggle tooltip box

Option name: bg_links.show_tooltips

Default value: TRUE

Possible values: TRUE, FALSE

Notes: by default, a tooltip containing the Bible passage whenever a user hovers their mouse pointer over a Scripture reference or clicks on the referense, depending on the options used. You can disable the tooltip by changing this property to FALSE. Doing so means that no tooltip will appear, but your Scripture references will still be converted into normal hyperlinks.

Toggle how the tooltip box is shown

Option name: bg_links.click

Default value: FALSE

Possible values: TRUE, FALSE

Notes: by default a tooltip containing the Bible passage is shown whenever a user hovers their mouse pointer over a Scripture reference. You can change this to only display the tooltip when a user clicks on a Bible reference. Keep in mind that to close the tooltip, they'll then need to click on the 'X' or anywhere outside of the box.

Changing the Look of the tooltip box

The tooltip box can be styled by overriding the default CSS.

div.bg_popup {
  font-size: 14px;
  font-family: sans-serif;
  border: solid 1px #999;
  background-color: #FFF;
}

div.bg_popup-header {
  color: #FFF;
  background-color: #999;
  border-bottom: solid 1px #999;
}

div.bg_popup-footer {
  background-color:#CCC;
  border-top: solid 1px #999;
}

div.bg_popup-border {
  border-right: solid 1px #999;
}