File Structure
Let's start by looking at the structure of a typical script file. We use sections to group commands and settings inside script files.
The easiest way to see how they are applied is to edit a few scripts and look at the source code to learn more about them. A typical script is composed of at least these 3 important sections
- Main - will keep all details that identify your script
- Variables - used to keep variable values
- Process - where your commands are placed
In addition to the script files, there is a master project file called Script.project, which has two optional sections
- OnProcessEntry - run as first command of every project
- OnProcessExit - run as last command of every project
Here is a small example of how it should look:
[Main] Title=Add my Program Description=This script will add my program Level=5 [Variables] %myTitle%="This is a title for the program" [Process] echo,%myTitle% .... ....
We can additionally use more sections to add variables from the script interface or even specify more sections with commands to be processed.
The [Main] section
Inside this main section you can store the definitions that identify your script and allow it to be properly categorized inside the project. This section works like a normal INI section where you write all your data in the form of Key=Value (e.g. Color=Blue)
List of available keys
- Title - Title that is displayed by your script
- Description - a short description of what the script is intended to do
- Author - the author or group involved in the initial release, following releases or branches should be mentioned in Credits
- Credits - details the people involved making the script possible or persons involved in updating the work.
- Date - date of changes, any text is accepted - recommended to use "Year-Month-Day" all written in numeric format
- Version - scripts support version and they are important to mark new updated scripts on the download center
- Website / topic discussion - place a link here to help users to find their way to a site with more informations
- Download_level - used by download center to categorize scripts under download profiles (1..4) See the documentation on the Download Center for more information.
- Selected - using True/False will make your be checked or not for being processed. These are usually set (checked or not) using the !WinBUilder GUI. To completely remove any checkbox, set the value to "None". eg. Selected=None
- Locked - use True/False to allows the users to edit the script interface
- Level - very important setting to allow your script to be placed on the correct sequence when the project is running (see Script Levels for more details on this)
- Interface - Can be used in complex script to select a specific section of the script file to become the interface. If not specified, the displayed interface will be driven by the [Interface] section. See this page for more information
While some of the keys can be manipulated using the WinBuilder GUI, All of these keys can be edited easily using WinBuilder's internal source code editor. And while these keys are optional, it is recommended to place at least a few keys to better describe your script to others (i.e. Title and Description).
- Note1: Since WinBuilder will ignore any keywords not mentioned above for a specific purpose, some script authors also use the "INI" style format to add version specific history and other information. Just be sure that each key is unique. For example:
History01=This is a note about version one History02=This is about version two Note001=Another note
- Note2: If they are not found inside the script, the following values will be used (i.e. default values
Title=<Uses the filename of the script> Level=5 Download_Level=2 (i.e. Recommended)
Added in 2009 (WB78?)
- Certification - To identify if a script has been "changed", the concept of script certification was added. When a project 'owner' uploads a script, he can give a 'stamp' to the script which is unique. Every change of the script can then be detected. It was enhanced to be smart enough to allow some GUI options changes, but not changes to the logic or functionality.
In the log it is easy to be seen when the script has been changed in core areas.
() > script does not have the stamp
(+) > script is still original
(?) > script has been changed.Since this is a tool exclusive for 'project-owners' to certify their scripts, the keywords below are generated by a separate, console program to 'certify' the script before upload. In addition to the certify.exe program a personal key file <name>.wbc is also required. It writes something like this into the [Main] section:[Main] ... CertifiedBy=xxx Certification=cd55abf6082298a0044f110479f98b7eIn addition to the information shown above, WinBuilder will show who issues the certification, or give a warning if there is no certification information in the script.
The [Variables] section
This section is described in more detail on a separate page.
The [Process] section
All commands you write in this section will be executed by the program. From this section you can also call other sections from the same script or other scripts if necessary using the run command.
The result of each operation is written on the log window - which you can later view or save to an html page.
The [Interface] section
While this is important to scripts it is described in more detail on a separate page.
The [OnProcessEntry] section
This section is an optional section exclusive in script.project. If it is present, during build this section is processed before the first [Process] line of every processed script.
The [OnProcessExit] section
This section is an optional special section exclusive in script.project. If it is present, during build this section is processed after the last [Process] line of every processed script. For example, this will cause a specific section of the project.script file to be run when the build process exits.
[OnProcessExit] Run,%ProjectDir%\script.project,Process-log