Automating WebMerge with Apple Events

While the Settings File options will satisfy most automation needs, there may be times when you want to be able to set the values of some WebMerge settings on the fly. If you use Mac OS, you're in luck: WebMerge supports the "do script" Apple event, so you can use AppleScript or even raw Apple events to control WebMerge.

A complete description of how to use AppleScript and Apple events is beyond the scope of this discussion, but if you're familiar with the basics you'll have a good time here.

WebMerge supports the "do script" ('dosc') and "evaluate" ('eval') Apple events, which provide general hooks into WebMerge's inner workings. Below is a description of each of these events, and the internal commands you can call using them:

The "Do Script" Event

The "do script" Apple event lets you execute internal commands in WebMerge. Please keep in mind that, unlike using AppleScript, all of the arguments you send to a WebMerge command must be of type TEXT (as opposed to file alias, list, or other types sometimes supported in AppleScriptable applications).

The general syntax for the "do script" event is:

<command> "<param>"

where <command> is the name of a WebMerge command, and "<param>" is an argument passed to the command. Arguments are always passed in quotes. Not all of the WebMerge commands require arguments; some require only the command name.

For consistency, all "do script" commands begin with "Set" (e.g., "SetExportFile").

The "Evaluate" Event

The "evaluate" Apple event requests specific information from WebMerge, and returns the requested information as its result. In FileMaker Pro, you have the option of having Apple event results copied to the clipboard, which can then be pasted into a field or used in a calculation.

The general syntax for the "evaluate" event is:

<command>()

Note that all of WebMerge's commands which return a value require parentheses after them. None of them require any arguments to be passed to them.

For consistency, all "evaluate" functions begin with "Get" (e.g., "GetExportFile").

Syntax Guide

Below are the commands and functions available in WebMerge 2.1, grouped by the corresponding tab in the WebMerge window:

Sources Tab

SetExportFile "<completeFileName>"
where <completeFileName> is the full path to the exported Merge database file (e.g., "/HD/Folder/Filename").

GetExportFile()
returns the full path to the exported Merge database currently set in WebMerge.

SetSourceFormatPreset "<presetLabel>"
where <presetLabel> is a string that matches one of WebMerge's built-in presets.

GetSourceFormatPreset()
returns the label of the currectly chosen delimiter preset.

SetFirstLineIsFieldNames "<Boolean>"
where <Boolean> is either "true" or "false", determining whether or not the first line of the source data shoude be treated as field names.

GetFirstLineIsFieldNames()
returns "true" if this option is set, and false if not.

SetNameDelimiter "<delimiter>"
where <delimiter> is any character or string of characters used to delimit the first line of the source file, provided the first line is used as field names.

GetNameDelimiter()
returns the chracter or string of characters used to delimit the fields in the first record of the source file.

SetDataDelimiter "<delimiter>"
where <delimiter> is any character or string of characters used to delimit the data in the source file.

GetDataDelimiter()
returns the chracter or string of characters used to delimit the fields in the source file.

SetOnlyTextValuesHaveQuotes "<Boolean>"
where <Boolean> is "true" is "true" or "false", determining whether the source file uses quotes around textual values.

GetOnlyTextValuesHaveQuotes()
returns "true" or "false", depending on the current setting for that opion.

SetSortRecords "<Boolean>"
where <Boolean> is either "true" or "false", determining whether the records in the source file are to be sorted before being used to generate pages

GetSortRecords()
returns "true" or "false", depending on the current setting for that opion.

SetSortRecordsField "<fieldName>"
where <fieldName> is the name of the field whose values are sorted prior to generation, provided the SetSortRecords has been set to "true".

GetSortRecordsField()
returns the name of the field currecly assigned to be sorted prior to generation.

SetSortRecordsOrder "<sortOrder>"
where <sortOrder> is either "ascending" or "descending", determinging the order in which values are compared in the field specified to be sorted.

GetSortRecordsOrder()
returns either "ascending" or "descending", according to the current setting for that option.


Index Pages Tab

SetBuildIndexPages "<Boolean>"
where <Boolean> is either "true" or "false", determinig whether to generate index pages.

GetBuildIndexPages()
returns "true" or "false", depending on the current setting for that opion.

SetIndexTargetFolder "<completeFolderPath>"
where <completeFolderPath> is the full path to the folder in which WebMerge will generate index pages.

GetIndexTargetFolder()
returns the full path to the folder in which WebMerge wil generate index pages.

SetIndexTemplateMode "<modeSpecifier>"
where <modeSpecifier> is either "new" (to have WebMerge auto-create a template on the fly), "file" (use an HTML template), or "field" (using a field in your database to specify a path to a template file, letting you use a different template for each file).

GetIndexTemplateMode()
returns the mode specifier currently in use, as described above.

SetIndexAutoCreateField "<fieldName>"
where <fieldName> is the name of a field whose vales will be shown on an index page auto-created by WebMerge.

GetIndexAutoCreateField()
returns the name of the field currently assigned for this option.

SetIndexTemplateFile "<filePath>"
where <filePath> is the full path to the teplate page to be used when the IndexTemplateMode is set to "file".

GetIndexTemplateFile
returns the path to the file assigned to this option.

SetIndexTemplateField "<fieldName>"
where <fieldName> is the name of a field containing the path to a template file when the Index Template Mode is set to "field".

GetIndexTemplateField()
returns the name of the field set for this option.

SetIndexFileNameMode "<modeSpecifier>"
where <modeSpecifier> is either "single" (generate one index page for all records), "field" (use the contents of a field to specify the index file name), or "serial" (create unique serialized names for each index file created).

GetIndexFileNameMode()
returns the value set for this option.

SetIndexFileBaseName "<name>"
where <name> is the base name WebMerge uses to create serialized file names for generated index pages.

GetIndexFileBaseName()
returns the current index file base name.

SetIndexFileNameStartNum <number>
where <number> is an integer used as the starting number for serialized index file names.

GetIndexFileNameStartNum()
returns the current starting number for serialized index file names.

SetIndexFileNameField "<fieldName>"
where <fieldName> is the name of a field whose value is used to determine the names of generated index pages when the File Name Mode is set to "field".

GetIndexFileNameField()
returns the value set for this option.

SetIndexFileNameExtension "<extension>"
where <extension> is a string appended the generated index files to specify their type (commonly "html").

GetIndexFileNameExtension()
returns the current file type extension for index pages.

SetIndexCreateNewPageMode "<modeSpecifier>"
where <modeSpecifier> is one of the following, which correspond to the choices in the popup control: "value in this Field changes:", "first char in this Field changes:", "first word in this Field changes:", or "a number of records is reached:".

GetIndexCreateNewPageMode()
returns the value set for this option.

SetIndexCreateNewPageField "<fieldName>"
where <fieldName> is the name of a field used for comparison according to the criteria mentioned in the IndexCreateNewPageMode option.

GetIndexCreateNewPageField()
returns the value set for this option.

SetIndexCreateNewMax <number>
where <number> is the maximum number of records to be written to a given index page before generating a new one, if the IndexCreateNewPageMode is set to "a number of records is reached:".

GetIndexCreateNewMax
returns the value set for this option.


Detail Pages Tab


SetBuildDetailPages "<Boolean>"
where <Boolean> is either "true" or "false", determinig whether to generate detail pages.

GetBuildDetailPages()
returns "true" or "false", depending on the current setting for that opion.

SetDetailTargetFolder "<completeFolderPath>"
where <completeFolderPath> is the full path to the folder in which WebMerge will generate detail pages.

GetDetailTargetFolder()
returns the full path to the folder in which WebMerge wil generate detail pages.

SetDetailTemplateMode "<modeSpecifier>"
where <modeSpecifier> is either "new" (to have WebMerge auto-create a template on the fly), "file" (use an HTML template), or "field" (using a field in your database to specify a path to a template file, letting you use a different template for each file).

GetDetailTemplateMode()
returns the mode specifier currently in use, as described above.

SetDetailTemplateFile "<filePath>"
where <filePath> is the full path to the teplate page to be used when the DetailTemplateMode is set to "file".

GetDetailTemplateFile
returns the path to the file assigned to this option.

SetDetailTemplateField "<fieldName>"
where <fieldName> is the name of a field containing the path to a template file when the Detail Template Mode is set to "field".

GetDetailTemplateField()
returns the name of the field set for this option.

SetDetailFileNameMode "<modeSpecifier>"
where <modeSpecifier> is either "field" (use the contents of a field to specify the detail file name), or "serial" (create unique serialized names for each detail file created).

GetDetailFileNameMode()
returns the value set for this option.

SetDetailFileBaseName "<name>"
where <name> is the base name WebMerge uses to create serialized file names for generated detail pages.

GetDetailFileBaseName()
returns the current detail file base name.

SetDetailFileNameStartNum <number>
where <number> is an integer used as the starting number for serialized detail file names.

GetDetailFileNameStartNum()
returns the current starting number for serialized detail file names.

SetDetailFileNameField "<fieldName>"
where <fieldName> is the name of a field whose value is used to determine the names of generated detail pages when the File Name Mode is set to "field".

GetDetailFileNameField()
returns the value set for this option.

SetDetailFileNameExtension "<extension>"
where <extension> is a string appended the generated detail files to specify their type (commonly "html").

GetDetailFileNameExtension()
returns the current file type extension for index pages.


Generation Tab

SetAutoRun "<Boolean>"
where <Boolean> is either "true" or "false", determinig whether the auot-run feature o enabled for the current settings file.

GetAutoRun()
Returns "true" if the "Have WebMerge start building page when this settings file loads" option is set in the Settings File Options dialog, or "false" if not.

SetPrependImagePath "<Boolean>"
where <Boolean> is either "true" or "false", determinig whether the Prepend Image Path feature is enabled.

GetPrependImagePath()
returns "true" if this option is set, and false if not.

SetImagePath "<relativeFolderPath>"
where <completeFolderPath> is the relative path to a folder which contains images to be used by the generated HTML file (e.g., "../../images/").

GetImagePath()
If the "Prepend Image Path" control is currently checked in WebMerge, this command returns the value in the field below that checkbox control. If the "Prepend Image Path" control is not currently checked, this command returns "false".

SetPrependImagePathField "<fieldName>"
where <fieldName> is the name of the field in the current exported Merge database file which will be used for images in any image links which may be in the template file.

GetPrependImagePathField()
Returns the name of the field in the current exported Merge database file which is to be prepended with the contents returned by GetImagePath(). If the checkbox associated with this option is not set, an empty string is returned.

SetWriteURLsAsLinks "<Boolean>"
where <Boolean> is "true" if you want to set the option labeled "Write URLs as links", or "false" if you do not want this behavior.

GetWriteURLsAsLinks()
Returns "true" if the option labeled "Write URLs as links" is set, and "false" if not.

SetRunMoreSettings "<Boolean>"
where <Boolean> is either "true" or "false", determinig whether other queued WebMerge files will be executed when the current one is done.

GetRunMoreSettings()
returns "true" if this option is set, and false if not.

SetSettingsQueue <fileList>
where <fileList> is a return-delimited list of the complete paths to other WebMerge settings files.

GetSettingsQueue()
returns the current list of queued settings files.

SetUploadPages "<Boolean>"
where <Boolean> is either "true" or "false", determinig whether

GetUploadPages()
returns "true" if this option is set, or "false" if not.


SetFTPServer <ftpSetName>
where <ftpSetName> is the name of the FTP settings to be used when uploading files.

GetFtpServer()
returns the name of the FTP settings currently in use.

SetRootFolder <folderPath>
where <folderPath> is the full path to a local folder that contains your Web site.

GetRootFolder()
returns the path to the local folder that contains your Web site.

SetDontShowResults "<Boolean>"
where <Boolean> is either "true" or "false", determining if the results dialog that normally appears at the end of a WebMerge run will be supressed.

GetDontShowResults()
returns "true" if this option is set, and false if not.

SetDontShowResults "<Boolean>"
where <Boolean> is either the string "true" or "false", which determines whether WebMerge will show its results dialog after it's done generating Web pages. If you want to have WebMerge quit when it's done, it's a good idea to set this value to true.

GetDontShowResults()
Returns "true" if the "Don't show results dialog after building pages" option is set in the Settings File Options dialog, or "false" if not.

SetAutoQuit "<Boolean>"
where <Boolean> is either the string "true" or "false", which determines whether WebMerge will automatically quit after it's done generating files.

GetAutoQuit()
Returns "true" if the "Have WebMerge quit after building pages" option is set in the Settings File Options dialog, or "false" if not.

SetLogResult"<Boolean>"
where <Boolean> is either the string "true" or "false, determining whether logging is enabled."

GetLogResults()
returns "true" if this option is set, and false if not.

on SetLogFile <filePath>
where <filePath> is the complete path to the text file to log file.

GetLogFile()
returns the full path to the log file.

SetLogWriteMode <modeSpecifier>
where <modeSpecifier> is either "append" or "overwrite", determining how the log file will be written.


GetLogWriteMode()
returns the current log mode.

General

BuildPages
No arguments are passed with this one. It simply tells WebMerge to start generating files based on the current settings.