The "User Functions" toolbar is a new toolbar that allows the user to add external command line programs or scripts to the set of Builder Builder tools.
The toolbar has 4 buttons (as seen above). Each of these is invisible until it is assigned a command to execute. When a command is assigned to one of the buttons then the button will become visible and the new command will also be added to the end of the right click context menu in the main editor. When the new command is executed (either by clicking on the function button or selecting the command from the context menu) then the script or program assigned to it will be started up in the background and passed the parameters specified by the user. The output from the script or program will be pasted into the editor window either at the insertion point, at the beginning of the selected text or it will be pasted over the selected text depending on the user configuration.
The toolbar itself will not appear until at least one function is assigned to it. However it may be toggled on and off by the user in the 'View' menu regardless of whether or not any functions are assigned.
The user can add a script or a command line program to the User Function toolbar by invoking the "Add/Remove User Function" command from the Commands menu on the main menu bar (see above). Once executed the "Add User Function" dialog will appear.
From this dialog you can add a new function to an unassigned button, replace an function that is already assigned or remove an assigned function
The Add User Function dialog has various controls for configuring the behavior of the external program or script (described below). The only control that 'must' be set in order to add a function is the "Location of Executable File" text box. The others are used to select the function number, set the command description, set the command output behavior and configure command parameters.
The following table describes the Dialog Controls.
|
General | |
| Control | Description |
|---|---|
| The Description Text Box |
The Description text box is used to enter a text string that will describe the command's purpose to the user. This text will pop up in a text tip when the cursor hovers over the button. It is also the text that will be seen in the User Functions sub menu of the right click context menu. If nothing is entered into the "Description" text box when a function is added then a popup will not appear on a hover action over the button. In this case the command string in the right click context menu will simply read "Function #" where "#" is the function number. |
| The Function Number drop list |
This drop down list is used to select the function number that is to be added, replaced or deleted. |
| The Location of Executable
File text box and File Selection button |
This text box should be set to contain the path to the file that will begin execution when the selected function button is clicked or the function is executed from the context menu. The button at the right end of the text box will bring up a 'select file' dialog. This allows the user to select the executable file path by navigation through the local file system. The only acceptable file types for this value are 'exe' files and 'bat' files. Perl scripts, Linux shell scripts and Javascripts can all be added as user functions but in those cases the 'Executable File Location' must contain the path to the script interpreter and the path to the script must be entered as a command parameter. The position of the 'script parameter' depends on whether or not any switches are to be passed to the script interpreter exe. See examples of assigning scripts to a user function button in the Function Examples section below. |
|
Function Parameters | |
| Control | Description |
| The Type drop down box |
The 'Type' dropdown box selects the type of parameter that should be next added to the function's parameter list. It can contain one of three different values:
If 'Selected Text' is chosen and added to the parameter list then that means that all of the text contained within the selection in the main editor window will be passed as a parameter to the User Function . If 'Selected HTML' is chosen and added to the parameter list then that means that all of the text contained within the selection in the main editor window along with all underlying HTML markup will be passed as a parameter to the User Function. If 'Other...' is chosen then the 'Value' text box will become active. Whatever is typed into the 'Value' text box (or added to it by selecting a file path with the 'File Selection' button) will be passed as a parameter to the User Function if it is added to the parameter list. Note: The size of a text or HTML selection that can be passed as a parameter to a user function is quite large but it 'is' limited. My own testing has shown the limit to be around 30k. If you're working on a document that has, say, 100k of content and you try to do something like execute a function on the entire document (e.g. pass an HTML selection parameter after selecting the entire editor window) then the command will still work but you're going to lose around two thirds of the original content. This limitation has something to do with the maximum command line buffer size. There's not much I can do about it without a much more elaborate method of implementing this functionality. At the moment that sort of upgrade is not in the cards. This restriction only applies to the amount of screen data that can be passed as a parameter to the user function. The amount of data that can be successfully output from the user function (and therefore pasted into the editor window) is virtually unlimited. |
| The Value text box and File Selection button |
The 'Value' text box is used for adding constant value parameters like command switches or local files to the function parameter list. Local file paths can be entered into the box by typing the path directly or by clicking on the 'File Selection' button that is located just to the right of the 'Value' text box. The 'Value' text box is only active when 'Other...' is selected in the 'Type' drop down list. |
| The Parameters list box |
The "Parameters" list box is the larger window at the bottom of the parameters control group. It contains the list of parameters that will be passed to the User Function when it is executed. The order of the parameters in the listbox, from top to bottom, is the same order in which they will be passed to the function on the command line. To select one of the parameters just click on it in the list box. When selected a parameter may be deleted or moved up or down in the list with the buttons next to the box. |
| The Add button |
Click the "Add" button to add a new parameter to the parameter list. If the "Type" drop down box is set to "Selected Text" or "Selected HTML" then just clicking the button will do the trick. If "Other..." is selected then something must be entered into the "Value" text box otherwise nothing will be added. New parameters will be added to the end of the parameter list. Use the "Up" and "Down" buttons to reposition a new parameter in the list. |
| The Delete button |
Use the "Delete" button to remove a parameter from the parameter list. First select the parameter that is to be removed by clicking on it in the "Parameters" list box and then click on the "Delete" button. |
The Up
 and Down  buttons |
These buttons are used to change the order of the parameters in the parameter list. Just select one of the parameters in the "Parameters" list box and use these buttons to move it up or down in the list relative to its current position. |
|
Output Options | |
| The Replace Selection radio button |
If the "Replace Selection" radio button is selected then the output of the user function will be pasted over the selected content in the editor window. If there is no text selection then it will be pasted at the point where the cursor is located, displacing all of the text that lies after the insertion point downwards. User "Replace Selection" in cases where the purpose of the user function is to change the selected text in the window in some way (e.g. wrap it in a particular HTML tag). |
| The Insert Before
Selection radio button |
If the "Insert Before Selection" radio button is selected then the user function output will be pasted into the document at the point just before the selected content in the editor window or at the insertion point if no content is selected. User "Insert Before Selection" in cases where the purpose of the user function is to insert some object into your document that is independent of the text selection(e.g. add a form element). |
|
The Main Dialog Buttons | |
| Control | Description |
| The Add/Replace button |
The button in the top right hand corner of the "Add User Function" dialog is the "Add/Replace" button. If the current function number is set to an unassigned button then the text in the button will read "Add", otherwise it will read "Replace". If a function is being replaced then all of the function data that exists in the dialog will be saved. Hence the "Replace" button can be used to change parameter info, description info, etc. as well as replace the current function with an entirely new script or program. |
| The Remove button |
Click the "Remove" button to remove the assignment from the currently selected function number. The "Remove" button is disabled when the selected function number doesn't have a script or program assigned to it. |
| The Cancel/Finish button |
The "Cancel" button simply closes the dialog and returns the user back to the editor. If an "Add", "Replace" or "Remove" action is executed by the user at any time then the button text will change to read "Finish". The action of the button is the same whether it reads "Cancel" or "Finish". |
There are several sample scripts and one sample exe file distributed with this document. They are:
| Insert Media.exe |
This is a console application that will output a multimedia "EMBED" HTML element. When executed a dialog will appear that will prompt the user to set the object parameters. If the user responds "OK" to the dialog then an HTML EMBED tag with the chosen parameters is written to STDOUT. When executed in Builder Builder it will insert a Media element at the cursor. |
| BatScript.bat |
This script simply writes the string "<H1> $s </H1>" to STDOUT where "$s" is a string that is comprised of the command line parameters passed to the bat script. When executed in Builder Builder it will change the editor selection to and H1 element. |
| JavaScript.js |
This script writes an HTML Table element to STDOUT. The table contains one column. The number of rows is the same as the number of tokens passed to the script on the command line. Each cell in the table contains one of the parameter tokens. When executed in Builder Builder it will change the selected text into a 1 X N table where N is the number of words selected in the main editor. Each of the selected words will be placed in one of the table cells. |
| PerlScript.pl |
The Perl script example is only applicable if you have Perl installed on your computer. This script emulates the Builder Builder "Greek Reference Tag" button. That is, all of the tokens passed as parameters to the script are wrapped in Greek PBB tags and then written to STDOUT. |
| ShellScript.sh |
The Shell script example is only applicable if you have cygwin (or some other Linux or Unix emulator) installed on your computer.This script simply writes the string "<FONT size="3" color="red"> $s </FONT>" to STDOUT where "$s" is a string that is comprised of the command line parameters passed to the script. |
Insert Media.exe
The insert media program does not take any parameters and should be assigned such that any selected text in the editor window is not overwritten by the output. Copy the file "Insert Media.exe" to a secure spot on your hard drive and in the "Add User Function" dialog set the input controls as follows:
- Description - Insert Media
- Function Number - a function number of your choosing.
- Location of Executable File - the path to "Insert Media.exe".
- Output Options - Set "Insert Before Selection"
- Parameters - None
BatScript.bat
Copy the file "BatScript.bat" to a secure spot on your hard drive and in the "Add User Function" dialog set the input controls as follows:
- Description - Make Header 1
- Function Number - a function number of your choosing.
- Location of Executable File - the path to "BatScript.bat ".
- Output Options - Set "Replace Selection"
- Parameters (1) - Selected Text
please see Notes concerning Bat scripts
JavaScript.js
Either "wscript.exe" or "cscript.exe" must be entered as the executable file in order to execute Javascript files. The JavaScript file location must be entered as the second parameter. The first parameter should be set to the wscript "Batch" switch (/B). If this switch is not used then the "Command Prompt" default intro text will be added to the beginning of the output.
Copy the file "JavaScript.js" to a secure spot on your hard drive and in the "Add User Function" dialog set the input controls as follows:
- Description - Make a Table out of the selected text
- Function Number - a function number of your choosing.
- Location of Executable File - "C:\WINDOWS\system32\wscript.exe".
- Output Options - Set "Replace Selection"
- Parameters (3) - 1) /B
- 2) the path to "JavaScript.js".
- 3) Selected Text or Selected HTML
please see Notes concerning JavaScripts
PerlScript.pl
For perl scripts the "Location of Executable File" must be set to contain the path to the Perl interpreter exe. On my machine this is located at "C:\cygwin\bin\perl.exe" but that's going to vary depending on your operating system and the type of Perl you have installed. The path to "PerlScript.pl" should be added as the first command parameter unless Perl command switches are used.
Copy the file "PerlScript.pl" to a secure spot on your hard drive and in the "Add User Function" dialog set the input controls as follows:
- Description - Greek Reference Tag(s)
- Function Number - a function number of your choosing.
- Location of Executable File - "C:\cygwin\bin\perl.exe" (e.g.)
- Output Options - Set "Replace Selection"
- Parameters (2) - 1) the path to "PerlScript.pl".
- 2) Selected Text or Selected HTML
ShellScript.sh
For Unix and Linux shell scripts the "Location of Executable File" must be set to contain the path to a Shell interpreter exe. It usually doesn't matter if you use KSH, CSH, BASH or whatever. I use BASH and on my machine this is located at "C:\cygwin\bin\bash.exe". That location is going to vary depending on your operating system and the Linux or Unix emulator you have installed. The path to "ShellScript.sh" should be added as the first command parameter unless Shell command switches are used.
Copy the file "PerlScript.pl" to a secure spot on your hard drive and in the "Add User Function" dialog set the input controls as follows:
- Description - Large Red Font
- Function Number - a function number of your choosing.
- Location of Executable File - "C:\cygwin\bin\bash.exe" (e.g.)
- Output Options - Set "Replace Selection"
- Parameters (2) - 1) the path to "ShellScript.sh".
- 2) Selected Text or Selected HTML
A Caution about "Bat" files: The "|", ">" and "<" characters have special meanings in the DOS scripting environment and will cause problems when encountered on the command line input to a BAT file. That is, if you pass a "|" character on the command line to a BAT file it will interpret it as a "pipe" rather than part of the script input. Likewise if the BAT file encounters a ">" character or a "<" character it will interpreted as a redirection directive. Therefore, if you're using BAT files for your user functions you're going to run into problems if you try to execute them on PBB reference tags or you pass "Selected HTML" as a parameter to the script. Instead of seeing the expected output pasted into your editor you will see error messages pasted there.
E.G. in the case of a Bible Reference tag if you select the text "[[John Ref|bible: John 3:16]]" and pass it to your BAT function the BAT interpreter is going to think your text parameter is "[[John Ref" and you are trying to pipe the output it to a command named "bible:". This will produce an error message something along the lines of "Error: Unknown command - unable to locate 'bible:'". That error message will be pasted into your editor instead of the expected output.
I know very little about BAT scripting so I don't know if there is a way to work around this with command line switches or by some other method.
Linux shells use the same character syntax as DOS for piping and redirection but it doesn't seem to be a problem within the Builder Builder context that I have been testing. I reckon that's because of the method used to invoke the shell (i.e. from outside of the Linux X-Window environment). Still I've only done this with cygwin and it doesn't necessarily follow that the same is true for all Linux emulators.
Javascript I/O: For security reasons Javascript does not contain methods for reading from or writing to Standard I/O. However locally executed js files can access Standard I/O through Windows Scripting Host variables. STDOUT can be accessed through the "filesystemobject" GetStandardStream method and the command line parameters can be accessed from the WScript "Arguments" collection. It's a bit convoluted but not really difficult. The "Javascript.js" sample file demonstrates a simple application of the methods used to access these variables.
I've found that you may use either "cscript.exe" or "wscript.exe" to execute your javascript files in Builder Builder. However in order to test your scripts in a "Command Prompt" window it appears that "cscript.exe" must be used. I don't know why. Also, remember to enclose your "Path to the Javascript file" parameter in double quotes when you execute from a command prompt window. Single quotes won't work and "no" quotes will cause the scripting host to lose the path if it encounters a space in one of the folder names or in the file name.
Definitions:
STDOUT - Where all of the program output is written if it is not directed to a file. Normally it is just the Command Prompt window. The Builder Builder function utility captures STDOUT and writes the content to the main editor window.
God Bless and happy book building.
John McComb