Builder Builder / Scratch Pad Interaction

Introduction

Builder Builder is now fully interactive with the Scratch Pad utility. Three buttons have been added to the Utility tool bar that facilitate opening the Scratch Pad application, copying content from Scratch Pad and pasting content from Builder Builder into Scratch Pad. The copy and paste buttons are only visible when Scratch Pad is open and visible. Two commands have also been added to the context menu that perform the same actions as the Scratch Pad copy and paste buttons.

Scratch Pad now has a button exposed that will paste content into Builder Builder. Read the updated Scratch Pad documentation for details.

Functionality has been added to transform Libronix citation and footnote links into PBB tags. This can be done automatically on pastes from Scratch Pad or it can be done locally on a selected range of text pasted into the editor window directly from Libronix. The selected transform is executed through a new "Transform LDLS Footnotes" command in the PBB menu.

Five new user options have been added that allow the user to determine how the citation/footnote transformations are performed. The user can choose to remove the HTML link elements, retain them or not do any transformation at all.

Builder Builder is now fully automated however there is only one usable scripting method (Paste) and one property (Visible) at this time. A Libronix toolbar with one button has been included with the distribution to demonstrate a simple application of this method. See below for details.

Installation

As in previous versions installation is accomplished simply by saving the installer exe somewhere on your hard drive and executing it. The new installer now gives the user a choice of components to install. You can choose to install Builder Builder alone or install both Builder Builder and Scratch Pad If "Builder Builder Only" is chosen and Scratch Pad is already installed on the system then the installer will produce a dialog warning that it can not remove the installed version. If you see this dialog then you should either remove Scratch Pad after the installation is finished or change your component choice to install Scratch Pad. The Builder Builder / Scratch Pad interaction will not function properly with an older version of Scratch Pad installed.

If you choose to install both versions then the Scratch Pad installer will start up as the next to last step in the Builder Builder installation. This can be a little confusing because the first thing you will see is a reappearance of the "Select Setup Language" dialog which makes it look like the installation is starting over from the beginning. Just step through it as usual. You can blame the unexpected pop up on lazy installer nesting on my part.

Details

The Buttons

There are three new buttons on the Utility tool bar. Only one of these will be visible when Scratch Pad is not open. There is also a new option in the "Panels" option group that affects how your toolbars line up when the buttons are toggled. See the "User Preferences" section for details.

Open Scratch Pad

This button will open Scratch Pad and expose the other two buttons on the Utility tool bar. If Scratch Pad is open but invisible then it will make the window visible and expose the buttons. If Scratch Pad is open and visible it won't do anything at all.

Note: When Scratch Pad is open and connected to Builder Builder hitting the "Close" button will not shut down the application. Rather it will make the window invisible and hide the "Paste Into" and "Paste From" buttons on the Utility tool bar. See the new "Scratch Pad" document for details.

Paste From Scratch Pad

This button will copy the entire contents of the Scratch Pad window and paste it into the Builder Builder main editor window at the cursor position. If text is selected in the main editor window then that text will be replaced by the Scratch Pad contents. If you want to paste only a portion of text from Scratch pad then use the "Paste Into Builder Builder" button in the tool bar area of the Scratch Pad application window.

When you paste using this button any citation and footnote links that are in the pasted content will be transformed to PBB links depending on the preferences you have set for that functionality. The same is true for content pasted from the other direction. See the "User Preferences" section for information about transforming links.

Paste Into Scratch Pad

This button will copy the selected content in the main editor window and paste it into the Scratch Pad window. If no text is selected then it won't do anything.

Note: All functions that paste into a remote window in both applications will paste the content into the spot defined by the cursor position or, in the case where text is selected in the remote window, into a spot just before the first character in the selection. It will never overwrite a selection in the remote window. The remote paste behavior is set this way to protect content from being overwritten in a window that may not be in view.

New Commands

There are four new commands. They are described in the following table.

Command	Menu	Description
Transform LDLS Footnotes	PBB	This command will transform LDLS citation and footnote links in text selected in the main editor window. It gives the user a means to do the transformation on text that has not been automatically transformed for some reason (e.g. text that is copied and pasted directly from Libronix). When you use this command make sure the entire content of the Libronix text that needs to be transformed is selected. If you miss a portion of the footnotes or one of the superscripts then the transformation won't occur for those notes and subsequent attempts to transform will fail (or, if you have the "Remove Citation and Footnote Links" option unchecked, subsequent attempts will result in double PBB links). If you make a mistake then use the "Undo" command to go back to where you were and try again. Don't try to fix it with repeated use of the command.
Paste From Scratch Pad	Context	See "Paste From Scratch Pad" button in the "Buttons" section above.
Paste Into Scratch Pad	Context	See "Paste Into Scratch Pad" button in the Buttons" section above.
Selected Remove Inline Styles	HTML	Pasted content often has inline styles that can be irritating because they locally override the style sheet styles. This is the same as the "Remove Inline Styles" command in the "Commands" menu except it will only act on the content that is selected in the editor window.

User Preferences

There are six new user options added Builder Builder. Five of them relate to Scratch Pad interaction and are implemented in a new Preferences tab named "Scratch Pad". The other has been added to the "Panels" tab.

Preamble

If you have "Include Footnotes on Copy" set in Libronix and you copy some text from a Libronix resource with a lot of footnotes and then paste it into MS Word you will notice that the footnotes are not actually visible in the word document. If you then hover over one of the footnote superscripts you will see the footnote for that superscript appear in a popup. This is because when you copy from a Libronix resource the footnotes (and citations) are embedded in Anchor tags (HTML links and bookmarks) that lie within divisions that have a proprietary MS style assigned to them. you will see this behavior in MS Word (and perhaps other MS Office products. I don't know) but you will not see it in internet browsers or other word processing applications.

If you save that document as HTML and compile it in PBB you will notice a lesser but similar behavior in your compiled resource. When you hover over the superscripts you will get a popup but it will just say "POPUP" (not very useful). However, if you click on the superscript a scrollable window will popup that lists all of the footnotes in the document. You will also see that, if you had "Tag References as Hyperlinks" checked in your PBB advanced options, then any bible references that happen to be in the footnotes will be linked in the footnotes popup. This behavior is similar to (but not nearly as satisfactory as) the behavior you see in standard LDLS resources that have bible references embedded in footnotes.

What we really want to see when we generate a PBB is the actual footnote popup when we hover over the superscript (we would also like to see a secondary popup with the linked bible references when we click on it, as in the standard case, but this is not possible with PBB). We would do this by adding a "Text" PBB tag each superscript character that contains the footnote content for that particular superscript.

Builder Builder contains a transformation function that will do this automatically on pastes from the Scratch Pad or from remote scripts. There is also a new command in the PBB menu that will do the transformation on selected text in the main editor window. This command is useful if text was pasted from a Libronix resource that was not transformed for some reason (e.g. a direct copy and paste from Libronix).

Builder Builder contains several new user options that control how (or whether) this transformation is done. There is a new tab in the Preferences dialog named "Scratch Pad" that contains these options. They are described in the table below.

Note: Sometimes when you copy from a Libronix resource not all of the elements necessary for a transformation are not included. So far I have only seen this anomaly in cases where the amount of text selected is small (say, a few verses from a bible) and the only footnote data is a citation. In these cases the transformation will not work (although the citation might disappear if you have "Remove Citation and Footnote HTML links" set). I don't know why this is but when it happens you need to tag the citation manually (or paste a larger chunk of the resource text and remove what you don't want). When citations are embedded as PBB links a copyright character (©) is inserted as the main text superscript. The character code for the copyright character is 169. If you want to manually insert a citation and use the copyright character as your superscript then paste "©" (or "©") into your "Source" window at the location where you want the character to appear and then tag that character with the citation.

Option	Tab	Description
Transform Citation and Footnote Links on Paste	Scratch Pad	Uncheck this option if you don't want the citation/footnote transformation done on pastes from Scratch Pad or remote pastes from scripts. This option does not affect the "Transform LDLS Footnotes" command in the PBB menu. The Default for this option is "checked".
Remove FONT Tags on Link Transform	Scratch Pad	Remove all FONT tags from the pasted content. Whenever you read an HTML/CSS manual these days they always tell you that the FONT tag is depreciated (or obsolete) and warn you not to use them. They always say to use CSS font styles instead. But whenever you use MS driven HTML software it always inserts FONT tags (and other depreciated HTML elements) all over the place. The Libronix copy is no different. The problem with these tags is that they always override whatever styles you have set in your style sheets. If you don't want the fonts then check this option. The Default for this option is "unchecked".
Remove SUP tags on Link Transform	Scratch Pad	Remove all FONT tags from the pasted content. The transform process always wraps the tagged text with a span with the "super" CSS class (part of the PBB style sheet). The default for this style is superscript so if the tagged text is also wrapped with an HTML SUP tag (as they usually are) the result you will see is a superscripted superscript, which winds up being a very small character. Leave this option checked if you use the CSS super class and haven't deleted or changed it's "vertical-align" style. The Default for this option is "checked".
Remove Citation and Footnote HTML Links on Transform	Scratch Pad	Set this option to remove all of the Libronix generated footnote elements from the pasted content. If you leave this option unchecked then the compiled source in at PBB generated book will contain both the PBB generated hover popups and the footnote list popup as described above. The Default for this option is "unchecked".
Overwrite Selected Text on Paste from Scratch Pad	Scratch Pad	If you uncheck this option then the "Paste From Scratch Pad" command will paste into an insertion point at the beginning of the selected text instead of overwriting the text. This is the same behavior as when pasting from a remote window or script. The default is the same as the default for an ordinary paste. The Default for this option is "checked".
Automatically Adjust Toolbars	Panels	The Utility toolbar's"Paste From" and "Paste To" buttons appear and disappear depending on the activity and visibility of Scratch Pad. Without this option set the toggling of these buttons will cause gaps in your toolbar area. Having the option set simply tidies up the toolbar area dynamically. If your saved window setup moves toolbars to different locations (or if you are in the habit of undocking them) then uncheck this option. The Default for this option is "checked".

Automation

Builder Builder is now fully automated however most of the exposed methods are designed for communication with the Scratch Pad application and should not be used in scripts. Therefore I will not document them here. I did, however, add one method (Paste) that can be useful for scripting. That method along with the "Visible" property are described in the table below.

There is also a Libronix toolbar included in this distribution that contains one button that demonstrates a simple application of the Builder Builder scripting object. More on that in the next section.

In javascript the application can be opened with the "ActiveXObject" function and a handle to an object of a running instance can be obtained with the "GetObject" function.

e.g.

var objBB = new ActiveXObject("BuilderBuilder.BuilderBuilder");

var objBB = GetObject("", "BuilderBuilder.BuilderBuilder");

Methods
	Parameters
Paste	None	Paste the contents of the clipboard into the main editor window. If the clipboard contents contain mso–footnote elements then the footnote links will be transformed according to the criteria set by the Scratch Pad options.
Properties
Visible	Hide or show the Builder Builder window. e.g. objSP.Visible = false; // keeps the application open but hides the //window. objSp.Visible = false; // Shows the application window. Note: Usually, when an automated application is opened via a com directive it will open hidden and the Visible bool has to be set to make the window appear. For reasons that are a bit too complicated to go into here Builder Builder does not act this way. In other words it "always" opens visible regardless of how you open it. The down side of this is that if you want it to open the application hidden you must open it and set visible to false. This causes a bit of annoying flicker at startup. I really couldn't see any reason why anybody would want to open an application like this in a hidden state so I left it the way it is. I can change it if somebody gives me a good reason why it should be changed but it will take a little work so, for now, it behaves in an unusual manner.

With only this one method exposed any scripts you may write that direct content to Builder Builder should have the same basic form.

I.E.

try
{
   var objBB = GetObject("", "BuilderBuilder.BuilderBuilder");
}
catch (e) {
     try
      {
            var objBB= new ActiveXObject("BuilderBuilder.BuilderBuilder");
      }
   catch (e) {}
}
if (objBB != null)
{
       // Do some scripting with the LDLS object that copies some data to
       // the clipboard.

       objBB.Paste();
}

I could expose more methods in a later release if I get some requests for them.

The ToolBar

The Libronix toolbar has one button (pictured above) that will paste the selected text in the active resource into the main Builder Builder editor window if Builder Builder is running. If Builder Builder is not running it will first open the application and then paste the active text. The footnotes and citation attached to the pasted text will be transformed according to the criteria set in the "Scratch Pad" options. If a resource window is not active in Libronix or if there is not text selected then the button will do nothing at all.

This program was designed and implemented by John McComb