4W WebMerge Settings

Sources Tab

The Sources tab is where you tell WebMerge which exported data file to use and how that file is to be read.

Selecting a Source File

Once you've exported your source file (see Preparing Your Source File), you can load it into WebMerge by clicking the "Exported File..." button. This presents your operating system's standard file selection dialog to let you select any text file, and the name of the file you selected is displayed next to the button.

Setting Delimiter Options

After you're selected a source file, the Import Options portion of the Sources tab becomes available. This section lets you specify how the source file's fields are delimited (by tab characters, commas, etc.).

When you first assign a source file, WebMerge examines the file and makes its best guess about which delimiters are most appropriate. When the delimiters are set correctly, you'll see a list of field names on the left with a list of example data from the file on the right. If either of those displays are shown on a single line, or have quotation marks around them, you can change the delimiters using the combo box controls labeled "Delimiter" above each display.

WebMerge provides presets for most popular database and spreadsheet formats. Just choose the program and format from the popup control labeled "Presets" and WebMerge will set the delimiters for that file format. For example, if you've exported from Microsoft Access using the Microsoft Word Merge format, just choose "MS Access: MS Word Merge" from the popup list. If you don't see your program or format in the list, you can set the delimiters manually.

NOTE: If the file type you're using is shown in the Presets list, selecting that preset will set the delimiters for that file type accurately. Adjusting delimiters for file types shown in the Presets list other that what it sets may prevent WebMerge from parsing the file correctly.

Each Delimiter combo box has a menu of the most common delimiters to choose from, both in quoted (";") and unquoted (;) form. The tab character is not visible on screen, and is displayed as "<tab>". If you need a delimiter not available in the Delimiter combo box you can type it directly into the Delimiter display field.

Some file formats include the names of fields in the first line of the file. If your source file included field names, set the "First line of file contains field names" checkbox and WebMerge will use those names when looking for matching replacement tags. If your file does not include field names, uncheck that box and WebMerge will create field names for you based on the order in which they appear in the file (e.g., "Field_001", "Field_002", etc.).

Note that the field names in your replacement tags must be exactly as they appear in the list on the left of WebMerge will not be able to make a match. If your original database file had any names consisting of more than one word such as "First Name", most databases will export those with an underscore replacing any spaces so the resulting field name would be "First_Name".

Many options in WebMerge let you specify a field by selecting it from a popup list. If you've assigned a source file but the field names in that list appear in a single line, you'll need to adjust the delimiters here to let WebMerge determine the field names correctly.

Microsoft Access and some other programs use delimiters inconsistently in some export files, with textual data enclosed in quotes, while numeric values are unquoted. If your file uses this convention, just set the checkbox labeled "Text values are in quotes" to enable WebMerge to parse the file properly.

NOTE: The "Text values are in quotes" option means ONLY text values are in quotes; numeric and empty values are not quoted. That option exists to help the program conform to Microsoft's specifications for CSV files, and while there are many other inconsistencies with CSV files exported from different Microsoft products nearly all of them identified as "commas-separate" or "CSV" use this quoting convention.

The advantage of not having to use "Text values are in quotes" (in addition to parsing the file correctly <g>) is that you'll find WebMerge will run through it's "Setting up" phase much faster without it. Accomodating Microsoft's CSV format is a very time-consuming process, but files with a simpler format like tab-delimited or Merge get parsed by WebMerge in one quick move.

If you see an odd character inserted in your pages where there should be an empty field, what you're seeing is a character inserted as a placeholder during the lengthy and complex process WebMerge must use to parse Microsoft CSV files. Turning off the "Text values are in quotes" option will in most cases correct that issue.

Sorting Your Data

WebMerge lets you optionally sort your data before generating pages. This can be useful if you need the contents of an index page to be in a particular order and are unable to sort the records in the program from which the data was exported.

To sort your data first set the "Sort records by field" checkbox, and then select a field you want to sort by. Sorting is done alphabetically according to the values in the selected field. You can choose whether you want the sort to be in ascending order (small to large) or descending (large to small) with the control on the right of that group.

Sorting is limited to data sets in which each record is 64k (65,535 characters) or less. That's about 14 pages of single-spaced copy, so chances are you'll never encounter this limit. If you do have an export file with records larger than 64k, you can move the data from the largest fields into external text files, replacing it with the path to the file in your records and use the WM-FieldInclude tag to insert the data. If you must work with records larger than 64k, consider having your database program perform the sort before exporting.

Why Sorting is Important

Sorting determines the order in which WebMerge processes records. This is especially important if you're generating index pages and use the option to have WebMerge generate a new page when the value in a specified field changes (see the section on the Index Tab for details on those options). When using that option it's important that you sort by the field you specify there, or you may end up with index pages that are incomplete. Here's why:

Suppose your records have data that looks like this:

  1  California  Fresno
  2  California  Los Angeles
  3  Arizona     Phoenix
  4  Arizona     Tucson
  5  California  San Francisco

If you generate the pages without sorting, here's what WebMerge will do:

  1. It creates an index page named "California", with an entry for "Fresno".
  2. It appends the "California" index page with an entry for "Los Angeles".
  3. "Arizona" is different from "California", so it closes the "California" page and creates a new index page named "Arizona", with an entry for "San Francisco".
  4. It apppends the "Arizona" page with an entry for "Tucson".
  5. This record is another change, so it closes the "Arizona" page and creates a new page named "California", with an entry for "San Francisco".

But because there is another "California" page, that page is overwritten with the new one. Hence, a database that contains three records for "California" will appear to have only one, since the first two were overwritten.

Now, if you sort on the State field you get:

  1  Arizona     Phoenix
  2  Arizona     Tucson
  3  California  Fresno
  4  California  Los Angeles
  5  California  San Francisco

Here it's much simpler: It makes an index page for "Arizona" with an entry for "Phoenix", then it adds "Tucson", then it closes the "Arizona" page and creates one for "California", adding entries for the three California cities before closing it.

So the trick is to just sort for the field you want to generate your index pages for and your index pages will have all the records you'd expect.