4.1 The SmallMap Data Structure

4.2 SmallMap Database Is Organized as Two-Dimensional JavaScript Array

4.3 Using the "tabtool.htm" Data Formatting Tool

4.4 Using the "SmallMap.xls" Data Formatting Tool

4.5 Adding or Deleting Fields

This chapter explains how the Web Publisher must structure and format the data for SmallMap. It also explains the tools we have provided to help you format your data, and how you can change the data structure to suit your needs.

4.1 The SmallMap Data Structure

SmallMap is essentially a light-weight database manipulation program for Web presentation. Hence, it revolves around a small set of data we call the "mini database" of a few hundred, up to a few thousand records (items or listings).

We assume you already have a working database you wish to publish on the Web. Your database can be anything you are working on: Shops around a commercial area, club membership, MP3 collection, national park's points of interest, local rental properties, etc.

In database terminology, each listing, such as "Dino's Kitchen" is called a "record". Every listing shares the same data columns, or "fields," such as "Shop Name" or "Telephone."

You can represent the whole database in a two-dimensional table. Moving down the first column, you see a list of shop records. Moving across to the right, you see each shop's field details: ID, Name, Category, Subcategory, Telephone, ...

If entered into a spreadsheet, it may look something like this:

Figure 1. Partial view of a sample database
      

A database can take on a large number of fields. SmallMap's template, however, currently has a design of 26 fields. These fields and their intended use are shown below (the column headings in the table above are displayed as a vertical list below):

The fields of "Name," "Grid," "Category," and "Subcategory" are four special fields. They are also the headings in the listing table. You can rename these headings in the table via the variables "altName," "altGrid," "altCat," "altSubcat" under "Database Related Setting" in "index.htm," as described in manual Chapter 5.9 Database Related Settings. For example, for an alumni group, you could rename some of them "Class," "Year," "Major." The "Grid" field is only activated if you have enabled the map feature.

You can add and rearrange fields. SmallMap will automatically accommodate additional fields. SmallMap will also automatically accommodate any field data that are left blank.

But if you rearrange existing fields, you will need to also reset certain variables in Section I.A of the main program file "index.htm," under "Data Field Pointers," to point to the correct fields. See manual Chapter 5.6 Data Field Pointers.

For example, if you switched the order of the columns (fields) for Fax and Email, you will also need to make changes to "index.htm" Section I.A. for variables iFax (change 7 to 8), and iEmail (change 8 to 7).

Note that in JavaScript, array index numbers start with 0 (rather than 1). This is some time referred to as "index number based on zero." Therefore, the first record or the first field has an index number of 0. Our array described below lacks item index 0 simply because we wanted to avoid confusion for new users. The main program "index.htm" will ignore any empty array items.

Subcategory issue: You may set the variable "subCatExists" (under "Database Related Settings") to false, and SmallMap will not display subcategory information. If you have entered subcategory data for some items but not others, SmallMap will automatically fill in the missing field with value from the variable "dummySubcat" (which is "Misc" in template SmallMap).

If you want to avoid such non-descriptive "Misc" in the subcategory field, you can fill it yourself with the same data as category. For example, you may have five listings under category "Aquarium," and their subcategory fields are left blank. To avoid SmallMap automatically filling in "Misc" for subcategory, you should input "Aquarium" for subcategory as well. This will avoid visitors finding the aquariums when they search for "Misc."

4.2 SmallMap Database Is Organized as Two-Dimensional JavaScript Array

An array is a formally-defined list of things in a program.

The main program file, "index.htm," can only read your data if the data are presented in a JavaScript file, which file name ends with the ".js" file extension. This file is initially named "smallmap.js", but you can rename it. The main program file "index.htm" calls upon "smallmap.js" using the following tag reference:

        <script language="javascript1.2" src="smallmap.js"></script>

If you rename "smallmap.js," be sure to also change the name in the above reference within "index.htm." See also Chapter 5.4 JavaScript Reference to Include "smallmap.js".

Within "smallmap.js," the data must be formatted as an array named "un[index_number]." The "un" name stands for the not-so-inspiring "unit number."

The "smallmap.js" template is initially populated with data about fictitious shops to make it easier for you to visualize what you need to input and replace. For example, the first three array items in the sample "smallmap.js" are:

The "un" is the name given to the array. The "[1]", for example, represents item index number 1. In this case, each array item is, in turn, another array of items. This is why it is actually a two-dimensional array. Item un[1] .... un[N] represents N number of shops. While each shop, eg, un[1], contains a "sub-array" of values, eg, "1", "B1", "The Grande", etc. These are the "fields" described in Figure 2 in Chapter 4.1 above.

This two-dimensional array is just another way of presenting the database table in Figure 1, in Chapter 4.1 above.

The square brackets "[" and "]" contain the second-dimension array of items. Items are separated by commas (,). The pair of double quotes around each item is to define their type as text string, mainly to make sure that long text with multiple words and commas like addresses are correctly identified as a chunk, rather than as many individual data items.

4.3 Using the "tabtool.htm" Data Formatting Tool

How do you go from your database/spreadsheet file to the JavaScript array described above? Our Download page provides two alternative tools to convert your database/ spreadsheet data, described in Chapter 4.1, into JavaScript formatted data, described in Chapter 4.2.

The first alternative, tabtool.htm, is a dynamic HTML Web page. This Web page has two large boxes or "textareas," one for input, the other for output. Your input must be a text block of tab-delimited or tab-separated data columns

Try copying a block of data from your spreadsheet or database program, and paste directly into "tabtoo.htm," into Step 1's textarea. Use the arrow keys to navigate to check that the data columns are indeed separated by tab characters. Then click "Convert" to see the output in Step 2's textarea.

Figure 4. Partial view of tabtool.htm
      

If this direct copy-and-paste approach does not work. You may need to copy from your spreadsheet/database program, then "paste as text" into an intermediary, such as a text editor, before transplanting the resulting text into "tabtool.htm."

If this fails, you can get your spreadsheet/database program to output to a tab-delimited text file. Most spreadsheet/database program's menu should have a "Save As" option, where you can choose the output file type. Choose "tab delimited" or "tab separated" file type. Open that file, copy all, and paste into "tabtool.htm" input area.

"Tabtool.htm" will immediately add array name, and adapt the data line by line into JavaScript array, described in Chapter 4.2. You can then copy the output, and paste into "smallmap.js," replacing any older or sample data.

The file "tabtool.htm" is available as a normal Web page at our download page. A stripped-down version, tabtoollocal.htm, removed of some links and formatting, is also available within the Windows zipped file "smallmap.zip".

Ensure correct order of data fields

If the order of the "fields" in your original spreadsheet or database programs is different from what appears in Figure 2 above, you will need to rearrange either (1) your data fields, or (2) the data field pointers described in Figure 2 above and in Chapter 5.6 Data Field Pointers, before copying your data to "tabtool.htm."

4.4 Using the "SmallMap.xls" Data Formatting Tool

The second tool to convert tabulated data to JavaScript array of data is "smallmap.xls." This is an Excel spreadsheet that contains two worksheets: "data" the input worksheet, and "output" the output worksheet.

You do not need "smallmap.xls" if you are able to use "tabtool.htm." However, you may still find "smallmap.xls" useful as an intermediate file to help you store or organize your data, restructure the columns (fields), etc.

The file "smallmap.xls" is available within the Windows zipped file "smallmap.zip" available for download at our Download page. The same file in the Open Office spreadsheet and Star Calc formats are also available for download on the same page.

The "data" worksheet is where you input and store your data. Each row represents a record of a client. Each column represents a field about the clients, such as name, telephone number, etc. It looks like Figure 1 in Chapter 4.1 above.

After making any changes in the "data" worksheet, in Excel press F9 key (or other similar function keys in other spreadsheet program) to recalculate the changes. You may input any characters in the cells except double quote ("), as this may later confuse JavaScript, which uses double quote to define the string variables.

The "output" worksheet contains functions that link to cells in the "data" worksheet. The functions string together the information, add the array name, index number, square brackets, double quotes, and commas to create the JavaScript array format. It looks like this:

Figure 5. Partial view of "output" worksheet
      

In Microsoft Excel spreadsheet program, the functions and formulas contained in "output" worksheet's cell B2, for example, is:

To provide a simple hurdle against accidental changes, the "output" worksheet is protected by a blank password. To unprotect if you need to restructure the spreadsheet, in Excel menu, click Tool>Protection>Unprotect. Password is blank or nothing. Remember to protect the sheet again to guard against accidental changes.

If you have more than 200 listings

In the template version of smallmap.xls, to reduce download file size, only 200 rows in "output" worksheets are linked to "data" worksheet. When you require more than 200 rows of output, simply unprotect the "output" worksheet, then copy the last row (row 201 in the template) with the valid formula, and paste downward to as many rows as you need.

Copy and paste your output

When you have made all the necessary changes to "data" and "output" worksheets, recalculate the spreadsheet. Next highlight a single column in "output" worksheet, from cell B2 to the end of your data row, copy, and paste into "smallmap.js," the JavaScript data file, as unformatted text. You may need to specify that you want to "paste special", or "paste as text" to transfer only the text information.

Replace any older data or the sample data. The format of the resulting JavaScript array should look something like those in Figure 3 in Chapter 4.2 above.

4.5 Adding or Deleting Fields

You should not attempt to add/delete/restructure the database unless you are familiar with your spreadsheet/database program, and with JavaScript (because you will need to make significant modification to the main program file "index.htm").

To add, delete, rearrange the order of data fields (eg, move email data column to before telephone number), you need to first make the changes in your spreadsheet or database program. Look up the manual for these programs for instruction.

If you only want to skip a few data columns in "smallmap.xls" such as "telephone #2", you can simply leave them blank. Blanks will be output as "" whether you use "smallmap.xls" or "tabtool.htm" and will be accommodated by the SmallMap program. This is the simplest solution.

However, if you decide to make major changes, and add/delete/rearrange the data fields, so that they are different from what appears in Figure 2 in Chapter 4.1 above, you will also need to make a few other changes.

If you are using "smallmap.xls" conversion tool, you will first need to rename the top row in "data" to avoid confusion. Second, you will need to reprogram the formulas in "output" to reflect any changes. Please refer to your spreadsheet program manual for further instruction.

If you are using "tabtool.htm" you will not need to make changes to this HTML file.

Either way, you will have to modify the main program file, "index.htm," under Section I.A., under "Data Field Pointers." If you have only deleted the second telephone number field, for example, you will need to delete the variable "iTel2", renumber iEmail to 7, and shift the rest of the variables up by one index number.

In the case of addition and deletion, you will also have to go through the rest of "index.htm" to make changes to these variables, such as deleting any references to "iTel2".

See also Chapter 5.6 Data Field Pointers.

Web SmallMap.com

Two Sample Websites

1. Sample Town - This is a fictitious town's directory and "map," a demonstration, and a template containing the latest SmallMap codes and scripts. To illustrate the capability to link to external map and direction Websites, we have input the addresses of actual public places under the Aquarium, Arboretum, and Museum categories. It uses single-grid, PNG-formatted, map images for zoomed-in view. Click for an alternative color scheme.

2. S2BJ - A real-life commercial area with a real map: Sungаi Duа and Bukit Jаmbul, Pеnаng, MaIаysiа. It makes use of 3-grid-by-3-grid GIF subdivided map images.

Promotions

Free: First 10 registrations

Recent News

Apr 30, 2005 (Press Release)