62 Custom Modules
Advantages of the HTML Help Format
Uses for Custom Modules
Creating a Custom Module
Create Your HTML Files
Tag the Scripture References and Create a Scripture Index
Creating the HTML Help File Using the HTML Help Workshop
Create a Project File
Create a Table of Contents
Compile the HTML Help File
Adding the Custom Module to BibleWorks
Creating a CHD File
Copying Files to the BibleWorks Directory
Distributing Your Custom Modules to Others
Integrating User-Created Modules with the BW Master Index
Tools and Tutorials for Creating HTML Help Files
Book Name Abbreviations
BibleWorks enables users to create custom modules in HTML Help format that integrate fully with BibleWorks. These custom modules function the same way as the HTML Help modules included in BibleWorks. BibleWorks uses HTML Help files for grammars, commentaries, paradigms and various other books.
If you wish to add a user-created Bible version to BibleWorks, you will probably want to use the Version Database Compiler instead of creating a custom HTML Help module. It is not possible at this time to add user-created modules to the Lexicon and Dictionary Browser.
Important! Please obey copyright laws. Before creating and distributing any HTML Help module you must insure that you have the right under copyright law to distribute it. In addition, you must include with the custom module a statement of the copyright status of its contents. Creators and distributors of HTML Help modules optimized for interaction with BibleWorks should be aware that the method of integrating these modules into BibleWorks is proprietary to BibleWorks and can be changed at any time. BibleWorks, LLC shall not be liable for any consequential, incidental, special, exemplary or other direct or indirect damages arising from use, results of use, or the inability to use HTML Help files compiled for use with the BibleWorks program. Some states do not allow the limitation or exclusion of liability for incidental or consequential damages, so the above limitations or exclusions may not apply to you.
Creating a module in HTML Help format is a little more complex than simply creating a document in a word processor. But with a little patience, careful attention to the instructions given below, and use of the sample files and templates included with BibleWorks, most people will be able to create a simple HTML Help file that integrates with BibleWorks.
There are several advantages to creating your own materials in HTML Help format with tags to BibleWorks.
§ You create your HTML Help file from common HTML files. You can create these files easily using popular word processors or HTML editor programs. You can save your Microsoft Word documents as HTML files, then compile them into one single HTML Help file for integration into BibleWorks.
§ The HTML Help file format allows you to add a variety of content. You can include text documents, graphics, and even sound and video files.
§ The HTML Help file is easy to distribute to others. All the files, even hundreds of files, are compiled into one single file. There is no concern about missing files. It is a simple, self-contained book.
§ The HTML Help file is a stand-alone ebook. You can give your HTML Help file to anyone who uses Windows 98 or higher, and they will be able to read your ebook. They do not have to have BibleWorks to read it.
§ By creating your HTML Help file according to the instructions given below, you can add your ebook to BibleWorks and use your ebook the same way as you use the other HTML Help files that are included with BibleWorks.
§ You can distribute your ebook to other BibleWorks 9 users to add to their copy of BibleWorks.
There are a variety of ways to use custom modules:
§ Pastors can distribute sermon notes to their congregation.
§ Students can compile their class notes into one file for use with BibleWorks.
§ Professors can create a custom module of class notes to distribute to students.
§ Denominations can create denominational materials for distribution to pastors, students, missionaries, and Sunday School teachers.
§ Mission organizations can distribute materials, even entire websites, to their missionaries in one single file.
§ Bible translation organizations can distribute translation help documents to all their translators, and have those documents integrate with BibleWorks.
§ BibleWorks users can turn their BibleWorks chapter and verse notes into a single file that is easy to distribute to others.
§ Users can turn public domain texts found on the Internet into BibleWorks modules.
§ Authors can create commentaries, devotional studies, and other resources.
The following instructions explain how to create a custom HTML Help file that will integrate with BibleWorks. These instructions will not explain how to create a HTML file, or how to format the HTML file for a specific purpose, as BibleWorks does not create HTML files. These instructions explain HTML document creation only where necessary to show how to set up the HTML document to interact with BibleWorks.
BibleWorks includes some simple sample HTML files and HTML Help project component files as examples and templates for you to use in creation of your own HTML Help files. As you work through the following instructions, open the sample files and see how the completed HTML files and HTML Help project files are constructed. The sample files are included in the file sampleHTMLHelp.zip. It can be found in the root directory of BibleWorks. The sampleHTMLHelp.zip file contains two versions of the HTML files used in the project. One set is what the HTML files look like before they are tagged for Scripture references, and the other is a completed set of HTML files ready to be compiled into an HTML Help file. There are also template files for the table of contents, project file, and CHD file, all of which will be discussed in the instructions below. Other necessary files are contained in the sample file, plus a completed HTML Help file.
Begin by creating your HTML files using a word processor or HTML editor. If you are using a word processor, save your document as an HTML document. Be sure that the file is named ".htm", not ".html". (You may need to turn on the ability to see file extensions. In Windows XP Professional, open Windows Explorer, then select Tools | Folder Options | View, and uncheck the box next to "Hide extensions for known file types." In Windows Vista or Windows 7 open Windows Explorer by clicking on the Start button. Then select Computer and press the Alt key to expose an additional menu. Then select Tools | Folder Options | View.”)
Save all your documents in one folder. If you are including multiple documents in your custom module, be sure to name your documents so that they sort alphabetically in the same order as they should appear in the compiled HTML Help file. You may need to name your documents with numbers according to the order they should appear.
For example, the following files will appear in this alphabetically order in your compiled HTML Help file:
By adding numbers to the name of files, the files appear in the proper order:
2 Chapter 1.htm
3 Chapter 2.htm
As you create your HTML files, be sure to add a title to each of your HTML files. These title names will appear in the Resource Summary Window in BibleWorks. The title is enclosed in special "<title>My Chapter Name</title>" tags. The title is not simply text at the top of each document. If you open your HTML file in Notepad or similar text editor, you can add the title tag following the <head> tag. For example:
BibleWorks contains a tool to automatically tag Scripture references so they are hyperlinks to BibleWorks. In order to use this tool to tag the Scripture references, it is important that you enter the Bible book names accurately. The book name abbreviations listed below give the book names that the BibleWorks tagging tool will find if you use the book name file supplied with the sample files. The abbreviation to the far left is the tag that will appear in your HTML file. The BibleWorks tagging tool will find any abbreviation to the right of the first abbreviation column and convert those names/abbreviations into a Scripture hyperlink.
Once you have created your HTML files you are ready to tag the Scripture references and create a Scripture index. BibleWorks tags the Scripture references and creates the Scripture index using the Build Module Index tool.
Important: Before you run the Build Module Index tool, be sure to save a copy of your completed files in a different file location. If you decide to make changes and need to rerun the tagging process, you will need to use the original files, not the already-tagged files. There is no easy way to undo the tagging process.
On the main BibleWorks menu, select Tools | Importing/Exporting Information | Build Module Index. In the "Base directory" line enter the location of the directory that contains your HTML files. You can use the arrow button to the right of the line to browse to the directory. On the "Bookname file" line enter the location of the directory that contains the bookname file that BibleWorks should use to tag the Scripture references. You can use the sample bookname file supplied with BibleWorks (in the sampleHTMLHelp.zip file mentioned above). In the "Base name" line enter the name of the module file that you would like to use. Once you have entered this information, press the Build button.
After running the Build Module Index tool, the Scripture references in your HTML files will be tagged for interaction with BibleWorks. Once your HTML Help file is integrated into BibleWorks, you will be able to place your cursor over a Scripture reference and the verse will appear in a popup window. You will also be able to click the reference, and the verse will appear in the BibleWorks Browse Window.
An example of what the tagging utility does might be useful. Suppose you have an HTM file with the phrase "See Rom 8:28." The tagging utility will replace it with something like this:
The Build Module Index tool also creates an index of the Scripture references that it tagged in your HTML files. Once your HTML Help file is integrated into the program, BibleWorks will use the index file to find the Scripture references that appear in your HTML Help file. Whenever you view a verse in the Browse Window that is tagged in your HTML Help file, your book will appear in the Resource Summary Window.
After you tag your HTML files, you need to add a small section of code at the proper place in each HTML file. Do not add this code before you use the Build Module Index tool. To add the code, open your HTML file in Notepad or similar text editor. Find the "</head>" tag in your HTML document. Immediately before the "</head>" tag add the following text, on a separate line.
In the "<body" tag add the following text. A sample of a completed "<body" tag is given, as well. Your "<body" tag may have different elements than the sample, but must contain the BibleWorks text.
<body lang=EN-US link=blue vlink=purple onkeypress="BwOnKeyPress()" onload="BwOnLoad()">
Be sure that all your completed HTML documents, graphics, etc. that are to be included in your custom module are saved in one folder.
Before you can create a HTML Help file, you need to download and install the free HTML Help Workshop from Microsoft. The HTML Help Workshop is the tool that creates the compiled HTML Help file. Click this link to go to the Microsoft download page. Once there, download the file "htmlhelp.exe", then install the file following the Microsoft instructions. You may also want to download the HTML Help file documentation that is available for download on the same page.
The following instructions will enable you to create a basic HTML Help file. If you wish to create more complex HTML Help files, the tools and tutorials listed below will help you. Since HTML Help Workshop is not a BibleWorks product, BibleWorks technical support will not be able to assist you in using the HTML Help Workshop. You can, however, ask your question on the BibleWorks forums, and other users may be able to offer you some help.
Begin your project with the sample "mymodule.hhp" file. Open the "mymodule.hhp" file in Notepad or similar text editor. Change the red items in the text below according to names needed for your custom module file. Be sure to save your Project file in the same folder as the HTML files for your custom module.
In the [OPTIONS] section, replace the Compiled file name, mymodule, with the name of the module to be included BibleWorks. Change the name of the Contents file, Table of Contents, with the name of your table of contents, if you have one. If you not going to include a table of contents in your custom module, then simply delete the entire Contents file line. Be sure to change the Default topic file name to the name of the file that you wish to display first when you open your custom module.
Compatibility=1.1 or later
Contents file=Table of Contents.hhc
Display compile progress=No
Language=0x409 English (United States)
In the [FILES] section, replace the red HTML file names with the names of the HTML files you created earlier. Retain the "bwjs.js" file entry. Copy the included "bwjs.js" to the folder with your HTML files. If you are including any graphics or other files in your custom module, add those file names under [FILES], as well. Be sure that these files are in the same directory as the HTML files.
If you have more than one chapter in your custom module, you will want to create a table of contents. Begin with the sample "Table of Contents.hhc" file. Open the file using Notepad or similar text editor. Change the "Name" values (shown in red) to the name of your chapters. Change the "Local" values (shown in red) to the name of the corresponding HTML file. If you have less or more chapters than the chapters listed in the template file, then you need to add or delete the entire <LI> section as necessary, as shown in blue text. Save your table of contents file in the same folder as the HTML files for your custom module.
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1">
<!-- Sitemap 1.0 -->
<OBJECT type="text/site properties">
<param name="ImageType" value="Folder">
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Chapter 1">
<param name="Local" value="mymodule.htm">
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Chapter 2">
<param name="Local" value="mymodule2.htm">
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Chapter 3">
<param name="Local" value="mymodule3.htm">
Once you have created your HTML files, the Project file, and the Table of Contents file, you are ready to compile the files into one HTML Help file. Open the HTML Help Workshop. Select File | Open, then browse to the folder that contains your Project file. Open the Project file, then select File | Compile. Now you have a completed HTML Help file saved in the directory with your HTML files. This HTML Help file contains all your HTML files, graphics files, etc., plus the "bwjs.js" file.
There are two required steps for adding a custom module to BibleWorks. The first step is creating a CHD file, and the second step is copying a few files to the proper BibleWorks directory.
Before you can add your custom module to BibleWorks, you need to create a simple instruction file to tell BibleWorks how to include your custom module in BibleWorks. This file is a CHD file. The CHD file is a simple text file, with the TXT extension changed to CHD. A sample CHD file is included with BibleWorks. There are a few items in the sample CHD file that you will need to change for the file to work properly with your custom module. The items to change are in red. We will discuss each of these items in order. Do not delete any of the lines in the sample CHD file.
MENU Your Name, My Module
DESCRIPTION <b>Your Name, <i>My First Module
Change the FILE name to the name of your custom module.
Your custom module will appear on the Resources menu of BibleWorks. Change the MENUNAME to the name of the folder under Resources where you wish your custom module to appear. You can create a new menu item under Resources by entering the name of the new folder. For example, if your custom module is a commentary, you may want to enter "Commentary" as the MENUNAME, thereby creating a new Commentary menu item under Resources.
The MENU line contains the author name and the title of the custom module as it will appear on the menu under the folder name given under MENUNAME. For example, for a commentary on Galatians written by John Doe, you may enter Doe, Galatians Commentary.
The DESCRIPTION line describes how the title of your custom module will appear in the Resource Summary Window. The <b> indicates that the following text of the title will be bold, and the <i> indcate that all following text of the title will be italicized, as well. For our example, you would enter <b>Doe, <i>Galatians Commentary
The RESOURCE_LANGUAGE_TYPE tells BibleWorks what language your custom module addresses. Your options for RESOURCE_LANGUAGE_TYPE are English, Greek, and Hebrew. If your module is in another language, such as French, German, Spanish, etc., enter English. This language type indicates in which category on the Resource Summary Grammar or Resources window that your custom module will appear.
The RESOURCE_TYPE tells BibleWorks whether your module will appear on the Resource Summary Grammar or Resources window. Your options for RESOURCE_TYPE are Grammar or Reference. (Enter Reference, not References.) It is not possible to include your custom module in the Resource Summary Lexicons window.
The INDEX_FILE tells BibleWorks which file contains the list of Scripture passages included in your custom module, and which HTML files contain which references. The BibleWorks Build Module Index tool automatically created this file, and named it with the same name as your custom module file, plus the SDX extension. Enter the name of the custom module SDX file on the INDEX_FILE line.
Once you have created your files, you need to copy the files to the proper BibleWorks folder. By having the files in the proper folder, BibleWorks will integrate your custom module into the program so that it will display in the Resource Summary Window. The three files you need to copy are the CHM, CHD, and SDX files you created earlier. In our examples above, these are mymodule.chm, mymodule.chd, and mymodule.sdx. Use the Windows Explorer to copy these files to the database folder under the main BibleWorks folder. Usually this folder is C:\Program Files\BibleWorks 9\databases.
Once you have copied these files to the database folder, close BibleWorks if it is open, and restart the program. Your custom module should appear on the designated Resources menu folder, and should appear on the list of files in the proper Resource Summary Window. Your custom module will appear in the Resource Summary Window whenever a verse appears in the Browse Window that also appears in your custom module.
Distributing your custom module to others is easy. You can post your files on the Internet, send them by email, and include them on CDROMs. BibleWorks 9 users can copy your three custom module files to their database folder and the custom module will appear in their BibleWorks program. Be sure to distribute all three files: the CHM file, the CHD file, and the SDX file.
People who do not have BibleWorks 9 can also read your custom module CHM file on their Windows computer. Neither the Scripture reference links or the Scripture popups will work, but they will be able to read the text. They do not need to download any reader program in order to read your module, as the HTML Help reader is already a part of Windows 98 and higher.
The following checklist will help you see the main steps for creating a custom module, and the order in which they must be completed. If you encounter problems creating a custom module, review this checklist to see if you missed a step or completed it in the incorrect order.
1. Create your HTML files. Add <title> tags. Name your files for proper alphabetical order, and save your files in one folder, using .htm extension as the file name extension. Save all graphics or audiovisual files to be included in your custom module in the folder with your HTML files. Save a copy of your HTML files in a backup folder in a different directory.
2. Use the Build Module Index Tool to tag the Scripture references and create the Scripture index. Add the two lines of code to each of your tagged HTML files.
3. Modify the Project file template for your custom module. Save your Project file in your HTML file folder. Copy the "bwjs.js" file to your HTML file folder.
4. Modify the Table of Contents file template for your custom module. Save your Table of Contents file in your HTML file folder.
5. Use HTML Help Workshop to compile your custom HTML Help module.
6. Modify the CHD file template for your custom module.
7. Copy your compiled HTML Help file, CHD file, and SDX index file to the BibleWorks database directory. Restart BibleWorks.
BibleWorks contains the Master Module Index. The Master Module Index enables you to search at one time all the BibleWorks HTML Help modules. It is possible to include user-created HTML Help modules in this search by following the instructions provided below.
How the User-Created Module Index Works
The Master Module Index contains a link to the user.chm file, located in the BibleWorks 9/databases directory. When you conduct a search from the Master Module Index, the search engine looks through the Master Module Index Table of Contents to find the files to be searched. Each table of contents entry in the Master Module Index is a link to the table of contents in another HTML Help file. In this way, the search conducted in the Master Module Index finds the link in the table of contents, then goes to the HTML Help file being linked, then looks through that HTML Help file's table of contents to find the files to search.
Because there is a link to the table of contents file contained in the user.chm file, a search conducted in the Master Module Index will also search every file referenced in the user.chm file.
How to Modify the user.chm File
Begin by creating your user-created module(s). You can include modules created by others, but you must know the name of the index file for each user-created module you wish to include in the user-created module index.
The file "usermoduleindex.zip" in the BibleWorks 9 directory contains three files. These three files are used to create a user-created module index. The user.hhp file is the HTML Help project file. Use this file to compile the HTML Help file. The MasterIndex.htm file is a simple HTML file used in the user.chm file. You can modify this file as you wish, though you will want to keep the same file name. The third file, user.hhc, is the table of contents file for the user.chm user-created module index file. You will modify this file in the instructions below. You must use this same file name.
Add the name of the file, followed by the name of that file's table of contents file, to the user.hhc file. Below is a sample section of the table of contents file. There are three identical sections added in the user.hhc file. Copy and edit these sections for each of the user-created modules you wish to add to the user-created module index.
<param name="Name" value="USER-CREATED MODULES">
<param name="Merge" value="usermodule.chm::/tableofcontents.hhc">
The first red item, the "Name" value="USER-CREATED MODULES" item, is the name that appears in the table of contents. This name can be anything.
The second red item contains two component parts. The first part, "usermodule.chm", is the name of the user-created module that you want to include in the Master Module Index search. Replace "usermodule.chm" with the name of your user-created module. You must retain the "::/" after the user-created module name. Immediately after the two colons and a slash is the name of the table of contents file contained in the user-created module. Replace "tableofcontents.hhc" with the name of the table of contents found in your user-created module. (If your user-created module does not have a table of contents, and only contains one HTM file, enter the name of the file, but with HTM instead of HHC as the file name extension.)
When you have completed modifying the user.hhc file, compile the user.chm file using the Microsoft HTML Help Workshop or other HTML Help compiler program. Be sure to name your compiled help file as "user.chm", and place the "user.chm" file into the BibleWorks 9/databases directory, replacing the current user.chm file. Now when you conduct a search in the Master Module Index, the search will also search through your user-created modules.
There are variety of tools, tutorials, and websites that make creating HTML Help files even easier. Here are some that may be of help to you:
FAR HTML. Far is a well-designed shareware program that makes creation of even the most complex HTML Help files very easy. If you going to create a large project or more than one HTML Help file, we strongly recommend purchasing this program. The cost of the program is very low and well worth it. There is a trial period for using the program, so you can try it before you purchase.
Creating Help. Information from Microsoft about how to create HTML Help files. Also, don't forget to consult the help file that comes with the HTML Help Workshop.
MSHelpWiki. The MSHelpWiki contains information and links to helpful information on many aspects of HTML Help 1.x.
Char James-Tanny's HTML Help Workshop Tutorial. This tutorial will take you step-by-step through the process of using HTML Help.
The following comma-separated table shows the book names and abbreviations in the bookname abbreviations file included with BibleWorks. If you use this bookname file, then every Scripture reference in your custom module must use one of these abbreviations for it to be tagged by the Build Module Index Tool. Since the bookname abbreviations file is the instruction file for the tagging tool, you can change the instructions, but test your changes carefully.
If some of your verses are not tagged by the Build Module Index Too, check your Scripture references carefully. For example, perhaps the files you wish to use in your custom module sometimes use PSS as an abbreviation for a reference to the Psalms. If you look in the bookname abbreviations list, you see that PSS is an abbreviation for the book in the Apocrypha called the Psalms of Solomon. In this case, you will need to replace the PSS abbreviations in your documents to PS or other Psalm abbreviation listed in the bookname abbreviations file. Also, if your documents use Roman numerals for book names, such as II Corinthians, replace the Roman numerals with the Arabic numbers, so that the book name is 2 Corinthians. After making the Scripture reference changes in your original files, run the tagging program again on copies of the original files. You cannot run the Build Module Index Tool twice over the exact same files.
1Sa,1 Samuel,1 Sam.,1Sa,1Samuel,1 Sm,1 S
2Sa,2 Samuel,2 Sam.,2Sa,2Samuel,2 Sm,2 S
1Ki,1 Kings,1 Ki.,1Ki,1Kings,1ko,IKings,1Kgs,1 Kgs,1 K
2Ki,2 Kings,2 Ki.,2Ki,2Kings,2ko,2Kgs,2 Kgs,2 K
1Ch,1 Chronicles,1 Chr.,1Ch,1Chronicles,1 Chr,1 Ch
2Ch,2 Chronicles,2 Chr.,2Ch,2 Chronicles,2 Chr,2 Ch
Sol,Song of Solomon,Cant.,Sol,Song,hoh,Ct
1Co,1 Corinthians,1 Co.,1Co,1Corinthians,1kor,1 Cor,1Kor
2Co,2 Corinthians,2 Co.,2Co,2Corinthians,2kor,2 Cor,2Kor
1Th,1 Thessalonians,1 Thess.,1Th,1Thessalonians,1 Thes,1 Th
2Th,2 Thessalonians,2 Thess.,2Th,2Thessalonians,2 Thes,2 Th
1Ti,1 Timothy,1 Tim.,1Ti,1Timothy
2Ti,2 Timothy,2 Tim.,2Ti,2Timothy
1Pe,1 Peter,1 Pet.,1Pe,1Peter,1 Pe
2Pe,2 Peter,2 Pet.,2Pe,2Peter.2 Pe
1Jo,1 John,1 Jn.,1Jo,1John,1 Jn
2Jo,2 John,2 Jn.,2Jo,2John,2 Jn
3Jo,3 John,3 Jn.,3Jo,3John,3 Jn
1Es,1 Esdras,1 Es.,1Es,1Esdras,1 Ezr
1Ma,1 Maccabees,1 Ma.,1Ma,1Maccabees,1 Mc
2Ma,2 Maccabees,2 Ma.,2Ma,2Maccabees,2 Mc
3Ma,3 Maccabees,3 Ma.,3Ma,3Maccabees,3 Mc
4Ma,4 Maccabees,4 ma.,4Ma,4Maccabees,4 Mc
Pss,Psalms of Solomon,Ps. Sol.,Pss,PSal
Epj,Epistle of Jeremiah,Ep. Jer.,Epj,LtJ
Pra,Prayer of Azariah,Pr. Az.,Pra,Azariah
Prm,Prayer of Manasseh,Pr. Man.,Prm,Manasseh
4Es,4 Esdras,4 Es.,4Es,4Esdras