|
SmallMap Manual
Chapter 5 Customizing the Main Program File "index.htm" |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
This is a long chapter that explains how the Web Publisher can customize the SmallMap main program file "index.htm." We outline the sections within this HTML file (Chapter 5.1 through 5.4), and then go through the JavaScript segment by segment. The emphasis is on Section I.A (Chapter 5.5 through 5.16), which is designed for customization by non-programmers. We take only a cursory look at the remaining sections (Chapter 5.17 through 5.22), which should only be modified by programmers familiar with dynamic HTML. The file "index.htm" should be viewed using a text editor, in a "no-wrap" mode. That is, each line should be allowed to extend to the right of the screen without wrapping. We have written long comments and script lines that may look confusing if they are wrapped around. The JavaScript double-slash characters (//) comment out the code to their right. Any text to their right is not part of the script or variables. After you've followed our links to other parts of this manual, just click the browser's "Back" button or press "Alt-left-arrow-key" to return to this page. 5.1 An Outline of the Main Program File The table below outlines the main program file "index.htm," its sections, and functions. There are further "functions within functions" that are not included here. The bulk of the customization is contained within Section I.A. "Customizable Variables and Functions." The light-yellow rows indicate segments where a Web Publisher may customize. Modifying these segments does not involve JavaScript programming. They involve resetting variable values, such as a choice of true/false, a different number, or a different name. The last row suggests two positions in the HTML body where Web Publisher may consider inserting Web ads, for the Web Publisher to earn revenues. It is up to the Web Publisher to identify the appropriate Web ad agencies, and to figure out how they work. More significant modification or reprogramming Those Web Publishers familiar with dynamic HTML may be more adventurous and modify other sections. However, the "IMPORTANT NOTICE TO WEB PUBLISHERS" must not be changed, in accordance with the terms of SmallMap Software License Agreement. Programmers may add copyright notices below "IMPORTANT NOTICE ..." and modify "A Brief Introduction ...." to reflect the modifications. Web Publisher may also want to delete most of the comment lines, to reduce the file size and speed up download by your visitors. For future reference, remember to save a backup copy before deleting the comment lines.
You may want to change the main program file's name from "index.htm" to some other, more descriptive, name.
However, "index.htm" can be a convenient name if you have placed this and other SmallMap-related files in a separate directory. Web server program such as Apache will generally look for "index.html" and "index.htm" by default.
5.3 The Meta Tags and HTML Document Title The first few lines of "index.htm" look like this (without the border and background color):
You should take advantage of the last two meta tags and the HTML document title <title>...</title> to describe your community. These are standard HTML tags that help search engines to find your Web pages and correctly index them, to make it easier for visitors to find your page. The "description" meta tag can accept sentences. The "keyword" meta tag should include only important words. Don't inflate these tags; many search engines today are smart enough to ignore your page if you place too many irrelevant or repeated words here.
5.4 JavaScript Reference to Include "smallmap.js" SmallMap program file "index.htm" requires a set of data to function. The template version will look for a JavaScript file (some times called a "client-side include"). This supporting file that contains the data is named "smallmap.js" in the template package. "Index.htm" knows which file to call because it contains a tag (below the section "A Brief Introduction ...") that reads like this: <script language="javascript1.2" src="smallmap.js"></script> You may change the data file name "smallmap.js" to another name more descriptive of your Web site. The file extension must be ".js" or it will not work. Be sure to change the name in the above reference within "index.htm."
5.5 Section I.A: Customizable Variables and Functions Section I of "index.htm" is divided into I.A. "Customizable Variables and Functions" and I.B. "Not-for-Customization Global Variables." Web Publishers who don't intend to explore advanced JavaScript should only modify Section I.A. We have divided I.A. into 11 segments, as listed in Figure 1, and explained below (Chapter 5.6 to 5.16). We suggest viewing the rest of "index.htm" in a text or HTML editor with the wrap mode turned off. Remember that the double-slash (//) signify a comment line for all the text to the right, and not a programming code line. We have appended substantial explanatory notes as comment lines. We have also turned the action needed into a question, to help you get a clearer idea of what needs to be done. You can delete most of the comment lines to reduce the file size of "index.htm," so that it will be faster for your visitor to download. Be sure to back up a fully-commented version for easier reference later.
This segment coordinates the index numbers for all database fields throughout the program. In the Sample Town template, it looks like this (comment lines abbreviated): //Data Field Pointers //------------------- //Index numbers refer to data fields in the un[shop][index]... //Change these if you have re-ordered the mini ... //Question: In your database arrays, what is the ... var iCustomerID=0 //index position of unique ... var iGrid=1 //index position of Grid number ... var iName=2 //index position of client name ... var iCat=3 var iSubCat=4 var iTel1=5 var iTel2=6 var iFax=7 var iEmail=8 var iNumStreet=9 var iCity=10 var iState=11 var iZip=12 var iCountry=13 var iWebsite=14 var iCardBgColor=15 //index position of client name ... var iCardTextColor=16 //index position of each client ... var iImg1=17 var iImg2=18 var iDescription=19 var iNote1=20 var iNote2=21 var iNote3=22 var iNote4=23 var iNote5=24 var iNote6=25 The Question is: In your database arrays, what is the index position (data column number) for each of these pieces of information (counting from 0)? If you reshuffle the fields in your database, for example, by changing the position of "Client Name" from index number 2 to index number 3, you will only need to change the number once, here in Section I.A. In this example, you would change "var iName=2" to "var iName=3." Without this segment and "iName", you would have go through the whole program to change all references to "Client Name" from 2 to 3, a tedious and error-prone approach. Note that index number in JavaScript array starts from 0, rather than 1. Hence, the first item on a list has an index number of 0, the second item index 1, and the third item index 2. If you add any fields, it is good practice to also add a pointer here. For example, if you add field index 26 to record "Client Slogan," you could add "var iSlogan=26" at the bottom of this segment, and use "iSlogan" through the rest of the modified program, rather than "26". You can also change a pointer variable name, eg, from "iNote1" to "iBranchNumber," but you would have to make sure any other "iNote1" in the program file must be changed accordingly.
5.7 Web Publisher Project Title, Description, URLs, Contacts This segment lets you the Web Publisher specify your project title, description, owner URL, home page URL, email, telephone, contact. Some of the information, such as contact person, if left blank (as ""), will not be displayed on the rendered Web page. In the Sample Town template, it looks like this (comment lines and long text abbreviated): //Web Publisher Project Title, Description, URLs, Contacts //-------------------------------------------------------- var mapTitle="Sample Town, Sample State E-Map" //Question: What is the main title of your ... var briefWebMapDataDescription="Find shops in Sample ... // Subtitle to the rendered page. Keep it short ... // Question: Given 2 lines to briefly describe ... //Web Publisher information // Question: Who are you (the publisher of your ... var webPubURL="www.smallmap.com" //don't include http://... var webPubHomeURL="www.smallmap.com" //may be the same ... var webPubEMail="contact@sampletown.org" //You may leave ... var webPubTel="222-555-1525" var webPubContact="Jo Townson" Further down Section I.A, there is another segment, actually a function called "drawCredit()" that allows you to write a paragraph about your project and community in more details. This is explained below in the manual Section 5.16 "Web Publisher's Copyright and Credit Statement."
5.8 Cookie Variables and Their Default/Initial Values This segment allows you to set 23 pieces of default variable values that, working through the cookie, determine how SmallMap will look when reloaded. Every time SmallMap loads or reloads, it will read this set of default values to decide how it would appear. They determine what a new visitor will see on your SmallMap Web page. The Question is: What do you want the initial values to be when end user first open your Web page? Modify these default values if you wish a freshly-loaded SmallMap to be sorted another way, to always open to a particular grid, shop, display or not display help information, etc. //Cookie Variables and Their Default/Initial Values //================================================= //Question: What do you want the initial values to be ... // Each piece of info below is saved into the cookie // See getCookie() function for more descriptive ... // *** IMPORTANT: *** // During customization, after changing ... // You must click "Forget Cookie" and refresh... var sortByWhat=1 var sFind="" var nnMap="" var idShop="" var searchAndOr=2 var isCatIndex=true var isAlphaIndex=false var currentListing=0 var maxListingPerPage=50 var namCharSegment="" var catCharSegment="" var findInCat=true var findInName=true var findInAddress=true var findInAll=true var cookieDay=0 var dirListingOnlyNoMap=false var showHelp=false var trackCat=false var trackSubcat=false var trackGrid=false var trackName=false var find20="" // // //Below is related to cookie expiry time, but is NOT ... var altCookieDay=30 //Alternative number of days the cookie can ... // End user has the options of forgetting ... // Question: At most how many days can ... "altCookieDay" The variable "altCookieDay" near the bottom of this segment is different from the others. It is not part of the cookie itself, but a value offered by the Web Publisher that the end user might choose to set to cookie. Set "altCookieDay" to a certain number of days to offer the end user the option to set cookie expiry day to that value. For example, the Web Publisher can set "altCookieDay" to 90. Yet it is up to the end user to choose whether to use this expiry day. The end user can choose from Session-length expiry, 1-day expiry, or this 90-day customized expiry period, using the cookie-management links near the bottom of the SmallMap rendered Web page. This "altCookieDay" variable is not saved into cookie by the Web Publisher. By changing this "altCookieDay" to, say 90, the Web Publisher saves the value into the SmallMap program file. Only the end user can select it by clicking on the link near the bottom left of SmallMap Web page, and save it into the cookie using the cookie-related variable "cookieDay." The Question is: At most how many days should the users save their settings in the cookie? See Chapter 1.14 Forget or View Cookie, Reset Expiry Days What exactly do these variables mean?
You can see the same information in the "getCookie()" function You can view their current values by clicking "View cookie" near the bottom of the left column of the rendered SmallMap Web page. For debugging during customization, you can trigger this "view cookie" alert every time you reload. You can do this by removing the comment characters (//) in front of a line of code "// viewCookie()" near the end of the "getCookie()" function. How are these 23 variables related to the "cookie?" Information about these 23 variables are organized as an array, "arrayCookie," then stored into (and retrieved from) the SmallMap cookie. If a cookie is present, the cookie's array of values overrides the default file values. Later in Section II of "index.htm," the "setCookie()" function define its 23-piece array this way:
arrayCookie=[sortByWhat,sFind,nnMap,idShop, searchAndOr,
isCatIndex, isAlphaIndex,currentListing, maxListingPerPage,
namCharSegment,catCharSegment, findInCat,findInName,
findInAddress,findInAll,cookieDay, dirListingOnlyNoMap,
showHelp,trackCat,trackSubcat,trackGrid, trackName, find20]
How the file/default values are read, then overridden by any cookie values Every time a visitor clicks or input a cookie-related command or text to search, the SmallMap program executes "setCookie()," which saves the whole "arrayCookie" including your new commands into the browser cookie, then reloads itself. After reload, SmallMap first reads and defines the default values under "Cookie Variables and Their Default/Initial Values". But the program, in quick order, also looks up the cookie using the "getCookie()" function. If it finds the cookie, the cookie's values override the default file values. And the Web page is drawn according to the cookie values - as you wished. Because the original SmallMap uses a session cookie that wipes itself out at the end of browser session, the default values are the only set available after the browser is closed and reopened. But a Web Publisher may modify the cookie to last longer, to persist beyond the browser session. The Web Publishers should provide adequate disclosure about the cookie in their privacy policy.
See also
This segment allows you to customize how data should be displayed, or treated if there is a blank. You can change any of these to suit your needs. This segment in the template "index.htm" looks like this (comment lines abbreviated):
//Database Related Settings
//=========================
var subCatExists=true
//Default true if your listings is meant to ...
// Set to false if ALL your listings contain ...
// Questions: In addition to "Category," does ...
var dummyCustomerID="z000000"
var dummyGrid="z00"
var dummyCat="Misc"
var dummySubcat="Misc"
//Default values for four key data fields if any ...
// Question: If I forgot to input any Customer ...
var blanks=["","","","","", "","","","","", "","","",
"","", "","","","","", "","","","","", ""]
// array of blanks ("" is not the same as null)
// "blanks" is the "dummy array," automatically ...
// Keep the same number of "" inside blanks as ...
var altCat="Category"
var altSubcat="Subcategory"
var altGrid="Grid"
var altName="Name"
//Alternative text for default column headings: ...
// Question: Do you want to change the above ...
// For example, perhaps to "Division", "Rank"...
"subCatExists" Change "subCatExists" to false if your data does not contain a "Subcategory," and only some sort of "Category." Questions: In addition to "Category," does any record in my database contain "subcategory" information? If you set the variable "subCatExists" to true, and 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. See above and below). 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." "dummyCustomerID," "dummyGrid," "dummyCat," and "dummySubcat" Next are four dummy values you want SmallMap to automatically fill in, if iCustomerID, iGrid, iCat, and iSubCat fields are left blank for any shop/client/record. For example, you may want to change "dummyCat" to "Meow" if you want to automatically insert "Meow" into "Category" every time it is left blank. Question: If I forgot to input any Customer ID (or Grid, Category, Subcategory) for any client in my mini database, what should be automatically filled in? "blanks" The array "blanks" is an array of 26 empty strings ("") - one empty string for each data field. This array is used when the program is running, to "white out" unwanted array item. If you add or delete any data field into your database structure, be sure to add or delete an empty string ("") into this array. "altCategory," "altSubcat," "altGrid," and "altName" The variables "altCategory," "altSubcat," "altGrid," "altName" add flexibility to rename your column titles in your presentation. For example, you may be setting up a community for former students, and instead of "Category" and "Subcategory," it may be more useful to rename the columns "Year" and "Major." Change the displayed data column title here. Question: Do you want to change the above default titles to some other words more descriptive of your database?
5.10 Display Control for Listing Table This segment allows you to customize how the listing table should be displayed. You customize the number of columns, and whether and how listings should be filtered by beginning characters. Within the template "index.htm," this segment looks like this (comment lines abbreviated): //Display Control for Listing Table //================================= //Additional table columns A-E, to display more data ... // IMPORTANT: This only works if "dirListingOnlyNoMap" ... ... var addColA=true //add a column of data to ... var colAIndex=iNumStreet //for this column, display ... var colATitle="No., Street" //for this column, use this ... var colAMinWidth=100 //set column width at least ... // var addColB=false var colBIndex=iZip var colBTitle="ZIP" var colBMinWidth=50 // var addColC=true var colCIndex=iTel1 var colCTitle="Tel #1 " var colCMinWidth=80 // var addColD=true var colDIndex=iEmail var colDTitle="Email" var colDMinWidth=100 // var addColE=true var colEIndex=iWebsite var colETitle="Website URL" var colEMinWidth=100 // //Segmentation of listing: parameters var enableCatNameRanges=true //Set to true to display the controls/links that ... // Question: Do I want to allow the user to ... var showCharRange=["!-1-A-E","F-L","M-S","T-Z..."] //breakpoints and titles of segment/range (name or ... ... var legalAbbrev=["Ltd","Pte","Pty","Inc","Limited","SA","Co"] // Array of corp name endings or abbreviations to ... ... By default, the SmallMap program displays only three columns of data - "Category>Subcategory", "Grid", and "Name" -in the listing table. But the end user may be able to view up to another five more columns - provided the Web Publisher has activated the necessary variables described below. When the Web Publisher has set the cookie's "dirListingOnlyNoMap" (Chapter 5.8) to false, SmallMap will display map images. Further, if the Web Publisher has set the variable "enableControlShowingDirListingOnlyNoMap" (Chapter 5.11 next) to true, SmallMap will display this link below the listing table: "Display more columns in table, but no map." The end user will be able to click "Display more columns in table, but no map" to display more columns of data, provided the Web Publisher has also enabled the features below. The text of this link will toggle between the self-explanatory:
See also Chapter 1.9 Displaying More Columns of Data. "addColA," "addColB," "addColC," "addColD," and "addColE" The variables "addColA" to "addColE" let the Web Publisher determines whether to display additional five columns in the listing table. These additional columns are displayed only when the cookie's "dirListingOnlyNoMap" is set to true, ie, when end users click the "Display more columns in table, but no map" link below the listing table. You can set each to true or false individually. "colAIndex," "colBIndex," "colCIndex," "colDIndex," and "colEIndex" The variables "colAIndex" to "colEIndex" hold the index numbers that point to the data fields to be displayed for these additional columns. We recommend that you use a reference variable, such as iNumStreet, rather than a number such as 9. These will take effect only if the corresponding "addColX" is set to true. "colATitle," "colBTitle," "colCTitle," "colDTitle," and "colETitle" The variables "colATitle" to "colETitle" let you set the listing table column header, such as "Website URL," for each of the additional column to be displayed. "colAMinWidth," "colBMinWidth," "colCMinWidth," "colDMinWidth," and "colEMinWidth" The variables "colAMinWidth" to "colEMinWidth" lets you set the minimum width of each of the additional column to be displayed, so that a column, such as that containing telephone numbers, is not unnecessarily wrapped around, making the table difficult to read. You will need to experiment with these figures to make your listing tables more pleasing to the eyes. In general, do not set large numbers, as your listing table will be forced to become very wide, interfering with the rest of the Web page. "enableCatNameRange" The variable "enableCatNameRange" determines whether the below variable (showCharRange) will take effect. Set this to false to hide the character ranges for Category and Name. Question: Do I want to allow the user to filter the listing by category or alphabetic ranges? See also Chapter 1.8 Finding Items, Refining Your Search. "showCharRange" The array variable "showCharRange" sets the alphanumeric ranges with which the end user can limit the listing. For example, clicking on "F-L" in the Category column heading will limit the display of clients/shop to those whose categories start with letters F to L only. Question: If database contains hundreds of names, where can I set the break-points to separate them into segments? See also Chapter 1.8 Finding Items, Refining Your Search. For non-English Websites, the Web Publisher may want to modify the alphanumeric ranges to accommodate the different language. They key is the first character of each range. In the template, for example, SmallMap will divide the range at the characters "!", "F", "M", and "T.". The rest of each character range is for information only. The first characters of each range must have their ASCII code or Unicode in numerical order. "legalAbbrev" The array "legalAbbrev" contains common corporate name ending that should be temporarily hidden in the listing table. For example, "Sunshine Transport Limited" is automatically abbreviated to "Sunshine Transport" in the listing table, although the full name is retained in the name card. This helps to keep the listing table columns tidy. Web Publisher can add any other common corporate name ending abbreviations to the array "legalAbbrev." You do not need to include any variation ending with period (.), such as "Ltd.", as SmallMap will automatically look for them. Questions: What corporate name-end abbreviations do I want to hide in the listing table?
5.11 Enabling or Disabling Features This long segment allows the Web Publisher to activate or deactivate a broad spectrum of SmallMap functionalities. You can enable/disable or display/hide certain features by simply setting these variables to true or false. Within the template "index.htm," this segment looks like this (comment lines abbreviated and skipped): //Enabling or Disabling Features //============================== var enableControlShowingDirListingOnlyNoMap=true var enable9GridButtons=true var enableFindOnlyCheckboxes=true var enableTrackSimilarFind=true var enableLargeMap=2 var enableTableOutput=true var enableNameCardOutput=true var enableSummaryReport=true var enableCriteriaReport=true var enableOnlineManual=true var onlineManualURL="smallmap.com/manual/m1enduser.htm" var enableGeneralLinksToMapEngines=1 //Individualized links to Web map search engines, inside ... var enableMapEngine1=true var enableMapEngine2=true var enableMapEngine3=true var enableMapEngine4=true var mapSearchIncludeName=true "enableControlShowingDirListingOnlyNoMap" Set the variable "enableControlShowingDirListingOnlyNoMap" to true to let the end user see the "Display more columns in table, but no map" link, or the flip side of the same coin: "Display map with table, but fewer columns of data" link. See also
The variable "enableControlShowingDirListingOnlyNoMap" interacts with one of the cookie variables, "dirListingOnlyNoMap." The two variables are not the same, and may be easily confused with each other. This "enableControlShowingDirListingOnlyNoMap" controls the display/hiding of the link "Display more columns in table, but no map" (or "Display map with table, but fewer columns of data") below the listing table. When you set "enableControlShowingDirListingOnlyNoMap" to false, that link becomes invisible, and the end user loses the option to toggle between showing more or fewer table columns, ie, the end user does not get to change the cookie variable "dirListingOnlyNoMap." The question is: Should I give end user the option to switch between seeing and hiding the map (but seeing more columns of data)? When "enableControlShowingDirListingOnlyNoMap" is set to false, you can then set the cookie-related "dirListingOnlyNoMap" to true (displaying no map) or to false (displaying map), and the end user will have no choice but to accept your setting. "enable9GridButtons" Set the variable "enable9GridButtons" to true to allow the end user to see the 9-button map navigation control, whenever the map image focuses on any grid. This variable is overridden by "dirListingOnlyNoMap." The 9-button navigation tool is hidden when "dirListingOnlyNoMap" is set to true. The question: Is the 9-grid button navigation tool useful for my end users? See also Chapter 1.12 Navigating By Index Map, Grid Map, Grid Buttons. "enableFindOnlyCheckboxes" Set the variable "enableFindOnlyCheckboxes" to true to allow the end user to choose the scope of text search, whether to look for the Find text under the database's Category/Subcategory, Name, Address, and All fields. The Address option includes street name and number, city, state, ZIP code, and grid data. The All option includes all the above, plus the "Description" data field. Set to false if you don't want users to see or use the "Find in" checkboxes. If you set "enableFindOnlyCheckboxes" to false, we recommend you also set the cookie-related "findInAll" to true (default value), to let user search the max number of data fields. Question: Does it add much value to let users specify which data fields to search? See also Chapter 1.8 Finding Items, Refining Your Search. "enableTrackSimilarFind" Set the variable "enableTrackSimilarFind" to true to allow end user the option to automatically update the Find text, according to the item Name being clicked. For example, if the end user clicks "Mae Ping Thai Restaurant," the Find box will be automatically filled with data fields related to this shop, which may be something like "restaurant+thai+b01" or more depending on the checkboxes you check. A new results table will be generated reflecting this new branching of your search (while up to 20 pieces of previous search text are remembered in the cookie). Set to false if you don't want users to see or use the "Track similar ..." checkboxes at all. If you set this to false, the row of checkboxes will become hidden, and all checkboxes-related values are automatically set to false. That is, any click of names/items will not change the Find text; the results table will stay the same. Setting to true allows the end user to automatically update the context of search, and can be a powerful feature. But it can also be annoying or even disorientating when the user is not expecting a constantly-updating table. Question: Does it add much value to let users' Find box text to track or automatically update according to the latest clicked item? See also Chapter 1.8 Finding Items, Refining Your Search. "enableLargeMap" Set the variable "enableLargeMap" to 1, 2, or 3 to display two inconspicuous links that allow the end user to open a new window that display a full-size version of your map. Both these links are identical in functions: One is located below the listing table, the second is located on the upper left corner of the index map. Set this to 0 to hide both links to open large map window. Set this to 1 only if you have prepared the full-size image. Setting to 1 will let the end user open your large map as a single image, in a new window in which the HTML document is created on-the-fly by SmallMap. See the generateLargeMapHTML() function for the script that creates this window. You specify the name of the large map image through the variable "largeMapNameAndExt" under the code segment "Map-related Settings." Set this to 2 only if you have prepared the single-grid map images (not 9-grid images). Setting this variable to 2 will have similar effects as the above. But when "enableLargeMap" is set to 2, the new window created on-the-fly will build the Web page from a mosaic of single-grid map images. Setting "enableLargeMap" to 3 will let user open a pre-designed HTML file, which can include a single map or a mosaic of small maps, depending on your design. You could add title, captions, artworks, and ads, etc. The Web Publisher must have prepared this second HTML file for this setting. You set the name of the second HTML file through the variable "largeMapHTML" under the code segment "Map-related Settings." The question is: Do you want to allow end user to open a large map in a new window? As a single large map, or as a mosaic of subdivided maps? See also Chapter 1.13 Viewing Large Maps. "enableTableOutput" and "enableNameCardOutput" Set the variable "enableTableOutput" to true to display the "Output" of table link at the bottom of listing table. Set the variable "enableNameCardOutput" to true to display the "Output" of name card link at the lower-right of a name card. Clicking the link will open a new window displaying the results (listing table or name card) for printing and saving. The instruction to save this new window's HTML document is displayed at the very bottom of that Web page. See also Chapter 1.10 Outputting Table and Name Card to Print and Save. There are several ways to save that Web page:
Question: Do I want to make it convenient for end users to print the name card, or print search results table, which could contain my entire database? Warning: Confidential information should not be included in "smallmap.js." Even if you hide this "Output" link, your data can still be retrieved simply by viewing "smallmap.js" in a text editor. "enableSummaryReport" and "enableCriteriaReport" Set the variables "enableSummaryReport" and "enableCriteriaReport" to true to display the "Summary" or "Search Criteria" information sections below the listing table. Together, they report the search scopes and constraints, and help avoid confusion when interpreting the listing table. The "Summary" section reports the total number of listings, current sort order, and any tracking of similar listings. The "Search Criteria" section reports the text being searched for, the data fields to search for (Find in ...), and any alphabetic range to look for Category and Names. Question: Will "Summary" and "Search Criteria" help avoid confusion (or just clutter up my screen)? See also Chapter 1.8 Finding Items, Refining Your Search, near the end of that section. "enableOnlineManual" and "onlineManualURL" Set the variable "enableOnlineManual" to true to display a link to the online manual for end user/visitors, located at a URL specified by "onlineManualURL." Default URL is SmallMap.com's Manual Chapter 1 for end users "smallmap.com/manual/m1enduser.htm". If the Web Publisher has substantially modified SmallMap and has written a new manual, change "onlineManualURL" to point to that new manual. If the Web Publisher has no new manual, and does not want a link back to SmallMap's manual, then set "enableOnlineManual" to false to hide that link. The questions are: Do I want to let end users link to an online manual as specified at onlineManualURL? Will it be more helpful than confusing to the visitor? Where's my own online manual chapter for end users? Or is my SmallMap so minimally modified that my visitors can safely read the SmallMap.com manual on end users? "enableGeneralLinksToMapEngines" As a useful feature, the Web Publisher may want to help the end user quickly open one of the major map and direction Web sites, such as MapQuest or Yahoo! Maps. SmallMap can display five links to such Web sites near the bottom of the SmallMap Web page, under the heading "Map Search Websites." These are general links to the home page of these Websites, and will be opened in their own new windows. In the template SmallMap, the five external map and direction Web sites are: Google Maps, Map Quest, Yahoo! Maps, MapsOnUs, and MSN MapBlast. These are external links and are not affiliated with SmallMap.com in any way. We have tried to include a broad selection of competing services. Please read their terms of use and privacy policies before use. SmallMap.com is not responsible for your decision to use their services in anyway. Set the variable "enableGeneralLinksToMapEngines" to 0 to hide links to external Map search Web sites. Set it to 1 to place links at the end of left table, below Summary and Criteria. Set it to 2 to place them below the map image, above "Show Help." The five map and direction URLs are defined in the "drawGeneralLinksToMapSearch()" function. You can comment out individual Web search engines, as listed in this function. Question: Does it add much value to let my end users easily open external Web map search home page? "enableMapEngine1," "enableMapEngine2," "enableMapEngine3," and "enableMapEngine4" In addition to accessing the Web Publisher's own map images, end users may be able to access third-party map and direction Web sites. Given enough address details in the database, SmallMap can automatically generate links to four major map and direction Web sites. Set any of the above variables to true to display, in the name card, individualized links to particular map search engines, eg. maps.google.com. Note these are unrelated to "enableGeneralLinksToMapEngines" which opens the general home page of the map and direction services. Activate this only if you have adequate address/city/state info in your mini database to take advantage of these map search engines, and that your community is located in a country served by these map search engines. Changes: If these map and direction Websites redesign their query forms and query fields, the relevant scripts within SmallMap may also need to be updated for these links to remain effective. Check back with this manual or Contact us for further updates. Question: From name cards, which map search engines do I want user to be able to conveniently search the shop's individual location? Note that SmallMap respects the rights of these external map and direction Websites. By opening their Web pages fully, in a window and not in frame, these Websites are given full exposure for their URL and full opportunity of earning ad revenues. By trying and using SmallMap, you the Web Publisher has agreed to SmallMap Software License Agreement that you will respect the rights of such third-party Websites in any modifications you make to the SmallMap program. Also see Chapter 1.11 Linking to Map and Direction Websites. "mapSearchIncludeName" Set the variable "mapSearchIncludeName" to true if you are looking for mostly commercial shops/names, such as "Hector's Auto," which names are likely to be stored in the map search engines' database. Set to false if your database contains private entities, such as Hector Jones, whose names are unlikely to be stored in map search database (and may confuse the map search engine). Question: Is this a commercial listing where submitting specific shop name will help find the place on map and direction Websites?
These variables and arrays determine the background and foreground (text) colors of a shop or client's name card. The code looks like this under Section I.A. of the template "index.htm" (comment lines abbreviated): //Name Card Colors //================ var ncColors=[["004080","f0e0ff"], ["205020","e0f0e0"], ["406080","f0e080"], ["ffc040","404080"], ["d0e0d4","804080"], ["ffefa0","402040"], ["004060","efd0d0"], ["ffffa0","404080"], ["404000","f0b0b0"]] //Pairs of colors for random selection for "Name Cards" // When you click a shop/client name, its "name ... // You can specify the name card's exact background ... // Or without individually specifying the colors, ... var nameCardColorRandom=true //Set nameCardColorRandom to true to randomly select a ... // Set to false to turn off random color, in which ... // Questions: Allow the program to randomly select ... "ncColors" The "ncColors" array contains nine pairs of varying colors that are likely comfortable to view. Each pair contains values that mean ["name card background color","text or foreground color"]. These background and text colors should be contrasting colors. Web Publisher may replace all pairs with their own colors, or add more pairs. These color values allow Web Publisher to avoid monotonous-looking colors for all name cards, and to avoid entering hundreds of individual pairs of color for all shops or clients.
See also
"nameCardColorRandom" If the variable "nameCardColorRandom" is set to true, SmallMap will randomly select a pair of colors from "ncColors" when any shop/client name card is displayed. This is a controlled randomization of color pairs, to avoid generating text and background colors that yield truly random but uncomfortable color contrast. Set "nameCardColorRandom" to false to disable this randomized choice of color pair. When disabled, SmallMap will use only the first pair of colors for all name cards. So be sure to customize the first set to be your most representative colors. Questions: Allow the program to randomly select a pair of background and text colors from ncColors for name card of all clients whose database record do not specify their colors? Overriding random colors with desired colors for individual shop/client The Web Publisher can input specific and desired colors for any selected shops/clients using the "cardBgcolor" and "cardTextcolor" fields in the mini database "smallmap.js." Such individually specified colors will override the general, randomized colors specified above, and give the shop or client its unique and characteristic colors.
5.13 Page Format, Color Variables For Style Sheet How do you want your SmallMap Web page to look in general? This segment under Section I.A. in "index.htm" lets you specify color scheme, various fonts, font size, font colors, inside and outside of the table, widths, text box colors, etc. In the template "index.htm," the code looks like this (comment lines and some variable values abbreviated): //Page Format, Color Variables For Style Sheet //============================================ //for drawStyleSheet(), and Quick Help section var leftTableWidth=340 //Default width of listing table in left column, ... var altLeftTableWidth=420 //Alternative width of listing table that ... var colorHighlight1="ff0000" ... var colorHighlight2="ff8080" //Highlight color for text OUTSIDE the table, ... ... var colorScheme=3 //You can specify a different colorScheme. 0 ... //Questions: How do I quickly change the overall... //Style sheet formating variables ... colorBackground=["004060","004060","006040","502050","406000",...] colorText= ["efffff","efffff","efffff","ffffff","ffffef",...] colorTitle= ["f8f8f0","f8f8f0","f8c0e8","ffffb0","f8f0f8",...] colorButtonBackground=["004060","004060","006040","200040",...] colorButtonText=["efffff","efffff","efffff","ffefff","ffffef",...] colorTableBackground=["f8f8f0","f8f8f0","f8f0f8","f0f8f8",...] colorTableHeaderBackground=["d8d8d0","d8d8d0","d8d0d8",...] colorTableText=["000040","000040","004000","000040","004000"...] colorLinkText= ["002080","002080","008020","200080","208000",] colorHoverText=["ffdfbf","ffdfbf","ffbfdf","dfffbf","dfbfff",...] colorHoverBackground=["6f8fbf","6f8fbf","6fbf8f","8f6fbf",...] fontAll=["arial,helvetica, sans-serif","arial,helvetica, ...] fontSize= [9,9,9] //keep font small, as many end ... fontTabSize= [8,8,8] //test with 800x600 monitor if ... // font size can be larger if no map images are ... "leftTableWidth" and "altLeftTableWidth" The variable "leftTableWidth" sets the minimum width of the data table on the left to 340 pixel in the template version of SmallMap. The "altLeftTableWidth" provides an alternative width that will take effect if screen monitor width is greater than 900 pixels. These are customizable, but for practical reason should probably be left alone. See also Chapter 6.1 Customer Images. "colorHighlight1" The variable "colorHighlight1" is the highlight color for text inside the listing table (mostly) to make active criteria more visible. This variable is initially set to a bright red, "ff0000" in the SmallMap template. Do not enter the character "#" as you would normally do for Web colors. The Web Publisher may change this color, but you should ensure it is a good contrasting color to the listing table's background color. Question: What colors do you want to highlight search criteria and results inside the listing table? You can see examples of both "colorHighlight1" (red) and "colorHighlight2" (pink) in the two figures in Chapter 1.8 Finding Items, Refining Your Search. "colorHighlight2" The variable "colorHighlight2" gives the text in the Find box (and other text outside of the listing table) a pinkish red in the template SmallMap to draw attention to the text. This is to alert the user that any search results are constraint by parameters including the text box, etc. Without this highlight, end users may not notice that the search results are constraints, and is mistakenly frustrated with the search function. This color is initially set to pinkish red (ff8080, also do not enter # in front.) You can set this to 1 if you want to use colorText[colorScheme], the text color of other buttons and text boxes. If you set it to other colors, make sure it is a color that nicely contrasts the Web page's background color outside of the listing table. Question: What colors do you want to highlight search criteria outside listing table and in Find box? "colorScheme" and style sheet formating variables The variable "colorScheme" is a key to a whole set of style, color, font variables in the SmallMap Web page. The value becomes the index number for all the "Style sheet formatting variables" a few lines below (from "colorBackground" to "fontTabSize.") Questions: How do I quickly change the overall look of the page (fonts, colors, etc)? In the template, "colorScheme" is set to 3, which means the use of colorBackground[3] or "502050", colorText[3] or "ffffff", ..., etc. Where the formatting array value is missing, as in fontSize[3], default value is index 0, ie fontSize[0] or font size 9. Note index 0 points to the first item, and index 3 points to the fourth item in any array. Web Publisher can customize several aspects of these variables. First, you can change "colorScheme" to any number, provided the item is available in the color and font arrays. Second, you can add more array items, eg, "colorBackground[9]" to add your own color schemes. Third, you can change the existing values, eg, changing "colorScheme[4]" from "406000" to "808000." We have set the values associated with "colorScheme" 1 to be redundant; it is a duplication of "colorScheme" 0 in our template file. This is to give you the freedom to experiment with "colorScheme" 0, yet always have a backup demonstration set. There are many practical limitations to what you can customize. You will have to ensure the colors are not only pleasant, but also clearly contrasting for background and font colors. Some colors are also used for borders, and need to be checked to make sure they are pleasant to the eyes. Font size should not be too large, because wrapping text are difficult to read, and push the rest of the page out of view. Most Web visitors are still sing 800x600px monitors, and do not have the large-screen luxury of the Web designers. Large fonts can appear messy onscreen.
This is a short segment for you to specify which folders you have created to place any map images, and any images related to clients and their products. The "smallmap.zip" template you have downloaded by default creates the "mapimages" and "custimages" subfolders, and place sample images here. For the Sample Town template, this segment of code in "index.htm" looks like this (comment lines abbreviated): //Image Directories //================= var mapFolder="mapimages/" ... var custImgFolder="custimages/" ... You can rename your folders to something other than "mapimages" or "custimages". But you must also change the names in this code segment within "index.htm." Remember to include the slash "/" after the folder name. The questions are: Under which folder are map images located on my Website? Under which folder are customer images (if available) located on my Website?
See also
This segment lets the Web Publisher specify how any map images should be presented, in terms of width, number of columns, cut-off points for each grid, etc. We will discuss this segment that also involves graphics and images later in the next Chapter: Chapter 6. "Preparing Map Images and Customer Images."
5.16 Web Publisher's Copyright and Credit Statement Web Publisher must customize this function named "drawCredit()," which generates a paragraph describing the Web Publisher's community, project, as well as URLs, emails, and contacts. This paragraph is displayed at the bottom of the rendered SmallMap Web page. If you do not modify this, SmallMap Web page would print the sample information. Within the "drawCredit()" function, you should only modify the first half, consisting of text about your project (red colored text in example below). Unless you are familiar with JavaScript, you should leave the URL, email and contact lines alone, as the details will be filled in automatically with information you have entered earlier. You must make sure that each line is in the below format, ending in a double quote ("): s+="..." which means the string "s" appended with the text "...". The line starts with the name of the string (s), followed by plus and equal signs (+=), follow by pieces of text you want to add on, enclosed within double quotes ("...your text ..."). There must be an ending double quote (") every line. You can add more lines, but it is advisable to keep your statement brief.
//Web Publisher's Copyright and Credit Statement
//==============================================
//Registered and trial users of SmallMap may modify the text in ...
// It appears below "Summary" and "Search Criteria."
function drawCredit() { //draw Web Publisher contacts and ...
var s="<table border=0 width=95% cellspacing=0 ...
s+="<span class=small>"+b2+b2+b2
//
//You probably want to customize the text block just below
//
s+="\nCopyright © 2005 <a href='http://"+webPubURL+"' ...
s+="This is a demonstration and a template of the SmallMap ...
s+="The shops and contacts are fictitious. But to ...
s+="A Web publisher who customizes SmallMap would probably ...
s+="the points of interest for travellers to our friendly ...
s+="Please visit our home page to see the wonderful people ...
//
//
//The portion below should not be disturbed unless you ...
s+=b2+"For more information, please contact:"
s+="<br />"
s+=(webPubContact==""?"":"<br />Contact person: "+ ...
s+=(webPubEMail==""?"":"\n<br />Email: <a href='mailto:"+...
s+=(webPubTel==""?"":"\n<br />Tel: "+webPubTel)
s+="\n<br />"+drawHome(1)
s+=S2+b2+"<br />"
//
//The portion below should not be disturbed unless you ...
s+=ahj+"deleteCookie()' title='Forget search and ...
s+="/"+ahj+"viewCookie()' title='View cookie details'>"+...
s+="Remember for "
var s1=ahj+"cookieDay="
var s2=";setCookie()' title='Remember search and display ...
s+=s1+0+s2+"this session only'>" + ...
s+=s1+1+s2+"one day only'>" + ...
s+=s1+"altCookieDay"+s2+altCookieDay+" days'> " + ...
s+="<br />"+drawHome() + (history.length>0?S4+ahj+...
s+=b2+"</td></tr></table>"
document.write(s)
}
5.17 Section I.B: Not-for-Customization Global Variables This section in the SmallMap main program file "index.htm" is not meant to be customized unless you are familiar with JavaScript and dynamic HTML. It defines more generic and potentially confusing variables and set their initial values.
5.18 Section II: Cookie and Database Functions This section in the SmallMap main program file "index.htm" is not meant to be customized unless you are familiar with JavaScript and dynamic HTML. It contains the setCookie(), getCookie(), deleteCookie(), viewCookie(), cleanDatabase(), filterDatabase(), sortDatabase() functions, which work internally to figure out the listing you are looking for. The first four manipulate the saving and accessing of cookie data. The getCookie() function itself contains useful notes about what the cookie contains. Uncommenting the "viewCookie()" line within "getCookie()" can be helpful in debugging. The function cleanDatabase() is executed upon loading after reading "smallmap.js", and deals with missing data, replacing them with default or dummy values. The function filterDatabase() is executed after SmallMap figures out what you want to display, and filters for items that fit your criteria. The function sortDatabase() is executed just before drawing the listing table, to sort the items according to your criteria.
See also
5.19 Section III: Functions To Draw Tables, Index Map, Grid Maps, Help Section This section in the SmallMap main program file "index.htm" is not meant to be customized unless you are familiar with JavaScript and dynamic HTML. This section contains the functions that help to output your results to the screen: drawSortedTable(), drawMapSections(), drawHelp(). The function drawSortedTable() is a long function containing many sub-functions. It draws the left side of the screen, the title, subtitle, Find box, any navigation buttons, name card, table of listing, and the summary at the bottom of the table. The function drawMapSections() is also extensive, and puts together the index map of grid map image area, if any, on the upper right of the screen. The function drawHelp() puts together the Quick Help Section that end users can see by clicking "Show Help" just below the map.
5.20 Section IV: Other Functions This section in the SmallMap main program file "index.htm" is not meant to be customized unless you are familiar with JavaScript and dynamic HTML. This section contains may minor but crucial functions. Most of them support SmallMap at run time, provide interactivity and navigation, help save information into the cookie, help draw links and the style sheet, etc.
They are:
drawSmallMapCredit(), findIn(f,e), trackIt(f,e), getGrid(uGrid), getCat(i,type), getName(showAlpha,i), cleanName(nam), setFind(f,v), cleanText(v), getFindText(n), tellItToSortBy(sortByThis), clickGo(evt,f), statGrid(i), statCat(i), statName(i), showMap(target), setGridBtns(xChange,yChange), calcTargetMapFocus(sGrid,xMove,yMove,edge), calc9Grids(sGrid,type), generateLargeMapHTML(), drawLargeMapLink(typ), drawGeneralLinksToMapSearch(), reportFindInFields(), outputNewDoc(typ), initialize(), drawHome(typ), drawStyleSheet(), doOnLoad() The function doOnLoad() helps to set up some of the text boxes and checkboxes. You must not alter the text in "drawSmallMapCredit()" according to the terms of the SmallMap Software License Agreement.
5.21 Section V: Execute Style, Cookie, Database Housekeeping Functions This section in the SmallMap main program file "index.htm" is not meant to be customized unless you are familiar with JavaScript and dynamic HTML. While all the functions have been defined above, the operation does not start until the Web browser has reached this part of "index.htm." At this point, the major functions start executing. This section looks like this:
//==================================================================
// Section V: Execute Style, Cookie, Database Housekeeping Functions
//==================================================================
if(NN4) document.write("<title>"+"Index page "+mapTitle+"</title>")
else document.title="Index page "+mapTitle
initialize()
drawStyleSheet()
getCookie()
cleanDatabase()
filterDatabase()
sortDatabase()
You could customize the HTML document title "Index page ..." carefully, but the other functions should be left alone.
The HTML body is a basic component of the HTML file. In SmallMap, this section contains a form as well as JavaScript code. We suggest two insertion points where Web Publisher may be able to insert small-size ads, such as text-based ads. One is to be displayed near the bottom of the page, on the left column, below the listing table, "Summary," and "Constraints." Depending on the length of listing table, this ad may appear high up of a short page, or far down a long page. The second insertion point is to be displayed on the right column below the map, but above the Help section. Depending on the map image size and screen height, this ad will probably be close to the bottom or just below the bottom of the screen before there is any scrolling, but should be easy to see as end user is likely to scroll by a screen or two. You could modify SmallMap to insert ads elsewhere. But it is generally not a good idea to place ads in awkward places that irritate the end users. We strongly recommend that Web Publisher make it a priority to quickly answer the end users' needs and questions, always give them a clear overview, and pleasant layout. Satisfied customers will return more frequently.
|
|
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 Recent News |