This is a guide to help you get started using The ToolBook Batcher. It introduces the main features – and gives some useful examples.
Before you start the tutorial, download, unzip, and open the Tutorial.tbk book. Go through the pages, just to get an impression of what you are going to work with.
When you are finished, close the Tutorial book and open The ToolBook Batcher.
1. A simple search
Objective: We know that some fields have a gray background color, but we would like them to be white. First we will find the fields that have the gray color.
On the Find/Replace page you will find 3 subtitles: Scope, Search and Replace.
You always start by defining the scope.
First you choose a working directory. The working directory contains the files in which you wish to perform the search. Click on the 'Select directory' button.
Now choose the tutorial directory – the directory containing this file.
After you have chosen the directory, you see a list of the available ToolBook files (only one). From that you select in which files the search will be performed.
Choose the 'Tutorial.tbk' file.
Now click on the 'Search' tab.
Because we would like to find all the fields with a specific color, choose 'field' in the 'Object type' pull down menu.
You will notice that when you choose an object type, the contents of the 'Property' pull down menu change. The 'Property' pull down menu always shows the standard property types for the selected object type.
In the 'Property' pull down you choose 'RgbFill'. RgbFill is the property that holds the background color of a field.
We would like to search for a specific value, therefore click on the checkbox: 'Search for a specific value'.
In the corresponding field, write the color code: '192,192,192'.
We do not need to replace anything, so now you are ready to start the search. Go to the 'Save/run' page.
Make sure the 'create search report' checkbox is checked. Since we are not going to make any changes in the target books, there is no reason to save. Choose 'No save' in the save options.
Click on the 'Start the search' button.
After a while the 'Report' page appears, listing the objects that matched the search criteria.
Click on an object in the list to open the corresponding ToolBook book, and show the page containing the object.
2. Replace a property value
Objective: Perform the same search as in exercise 1, but now replace the color of the fields.
Go to the 'Find/replace' page, and choose the 'Replace' tab.
Make sure the 'Replace' checkbox is checked.
Choose 'Replace a property value'. In the corresponding pull down menu, you will see a list of all the property types you can replace.
Choose the 'RgbFill' property type; in the text field enter
the color value: '255,255,255'.
Go to the 'Save/run' page.
This time we would like to save the changes being made to the target books, therefore choose 'Quick save' in the save options.
Start the search by clicking on the 'Start the search' button.
When the Report is shown, click on one of the results, and
you will notice something strange. The field on the drag and drop page is now
white – just as is should be. But the fields on the multiple choice pages
change the color back to gray after reset or going into author. This behaviour
is caused by a shared script in the multiple choice object. When you look
into it you will discover that the group that contains the four (still gray)
fields has the user property ColorNotChosen that determines the color of the
fields.
Move on – and we will change the ColorNotChosen user property, and thereby the color of the fields.
3. Working with user properties
Objective: Replace the value of the ColorNotChosen user property.
Go to the 'Find/replace' page - Search tab.
In the 'Object type' drop down menu, choose 'All', because we would like to find any object that has the specific user property.
In the 'Property' drop down menu, you now see a list of all property types of all the object types.
We would like to find a user property so we choose 'Other'.
Now you see a new text field, just below the property drop down menu. In that field, enter the user property you wish to search for: 'ColorNotChosen'.
In the value field write: '192,192,192'.
Click on the 'Replace' tabs.
Click on the 'Replace property value' radio button.
Choose 'Other' in the drop down menu. In the text field that appears to the right, you enter the name of the user property: "ColorNotChosen".
In the now visible field write: '255,255,255'.
Go to the 'Save/run' page.
Choose 'Quick save' in the save options.
Start the search by clicking on the 'Start the search' button on the Save/run tab.
On the results page, you will see a list of all the objects that has that specific user property, their previous value, and their new value.
When you open the tutorial book, you will notice that the fields
are now white.
4. Executing a custom script
Objective: On the pages than have a Menu button, we also need a help button. We will duplicate the menu button, and change the caption, name and script, position, and create a hyperlink.
First we find the Menu button. As it is named 'Menu' it should be easy:
Go to the 'Search' tab on the 'Find/replace' page.
Select 'Button' in the 'Object Type' drop down menu.
In the 'Property' drop down menu, select 'Name'.
In the value field write 'menu'.
Now click on the 'Replace' tab.
Choose to execute a script by clicking on the 'Execute a script/command'
radio button.
When you choose to execute a script, the script will be executed every time
an object matches the search criteria. It's always a good idea to test a script
before performing the actual search. It is not possible to undo a search/replace,
so be careful and make sure you have a backup before starting the search.
Now write the following code in the text field:
select curobj
send copy
send paste
name of curobj = "Help"
caption of curobj = "Help"
position of curobj = 8160,150
get ASYM_AddHyperlink (curObj, buttonClick, page "help", NULL, "jump", NULL, false)
script of curobj = ""
First the script selects the currently found object (CurObj).
Then it duplicates the Menu button; by first copying and then pasting
It sets a new position, name and caption for the button
and gives the new button a hyperlink leading to the help page.
Finally it clears the script of the button – it is no longer needed.
Enable advanced options by clicking on the 'Advanced' radio button.
Now you will see 3 new checkboxes. We need to make sure that the 'Go to the page containing CurObj' is selected.
'CurObj' is a reference to the currently found object (i.e.
the current menu button). Click on the 'help' icon to learn more about this
feature.
Go to the 'Save/run' page, choose 'Quick save', and click the 'Start the search' button.
When The ToolBook Batcher is searching, a dialog box will show asking which form of hyperlink should be created. You choose A.
Open the tutorial book; go to the multiple choice page, and
notice the new help button.
The expert tips:
Click on the help icons to get information on the different features.
If you write a useful batch or search, you can save it by going to the 'Save/run' page, and clicking on the 'Save' button. The files you save will be placed in the settings folder, in the same folder as The ToolBook Batcher.
When choose to execute a script/command there are some useful variables:
SvBatchOutput: It is a String variable you can use to store information
in during the search. You can view the content of the variable on the results
page after the search.
svBookDirectory: It holds the directory path to the book that is currently
being searched. It is useful when you need to import recourses.
PropValue: Holds the value of the searched property of the currently
found object.
CurObj: Holds a reference to the current found object.
On the search page, use NULL if you would like to find objects that do not have a specific property.
Use The ToolBook Batcher as a navigator. Find all pages in a book, and use the results page to browse the target book.