Contents - Index

CustomFormat (function)

CustomFormat(sSection,[sOptions]) : string

You can generate your own custom HTML formats for SplitsScreen, Condensed print, View Offline, and File=>Export=>HTML.

To populate the drop down boxes with the custom formats you need to save a macro with a name starting with "HTML_" (without the quotes) in your GSAK "Macros" folder. If you can't find this folder us "Tools=>Folder finder"

The Customformat() function has been purpose built to help you easily generate these custom HTML pages which closely resemble the look and layout of the standard GSAK HTML display (two columns, side by side). You can of course generate your custom HTML pages from scratch, but using the CustomFormat() function will make it a lot easier for users with limited HTML knowledge and don't want to write a lot of macro code.


sSection = The section of HTML code to generate
sOptions = Optional. If no options are included then custom formats will respect the setting you have via Tools=>Options=>HTML. Any option you specify here will override the corresponding setting in the GUI options. All GUI options have a corresponding macro version that you can use to override the GUI setting. In addition there are a few extra options that are not available via the GUI

All options are in the form OptionName=Value. If a section supports multiple options each must be separated by a space.

All custom formats should use the "OpenDoc" section . This opens the HTML document and sets up the required Java script and CSS required for other sections.

You should also use "OpenTables" so that sections are neatly placed in tables. If your format is to be displayed on a device that only has a small width screen (nettop for example) then use only OpenLeftCol. This will then place all your section is the one column, rather than having then split side by side. 

OpenDoc - This sets up the start up or "Header" HTML code. Use the option  "Color=#FFFFFF"  to override the body background color.
OpenTables - This generates the table code (tables are used for the main body and  left and right columns ). Use the option "Border=#FFFFFF" to override the border color
OpenLeftCol - This generates the table code for the left hand column. Use the option  "Color=#FFFFFF"  to override the column background color.
Header - This section generates the "Header" information (Cache name, size, type, attributes, etc). Use the option "Attributes=Yes|No" to override the default generation of attributes. Use the option "ShowUtm=Yes|No" to override the default setting for showing the coordinates in UTM format (in addition to the configured format)
Cache photos - This generates the code to display the cache photos (note that cache photos are currently only provided when you populate your database using the Groundspeak api, they are not provided when you load a GPX file from a PQ or the cache page). This section supports Title options.
Description - This generates the description section of the cache (it includes both the short and long description). Use the option "RemoveAdditional=Yes|No" to override the corresponding GUI option. 
Custom URLs - This generates the custom URL section. This section supports title options. 
GC Note - This generates the Geocaching.com note section. (note that Geocaching.com notes are currently only provided when you populate your database using the Groundspeak api, they are not provided when you load a GPX file from a PQ or the cache page). This section supports Title options
Trackables - This generates the trackable section. This section supports title options. 
Child waypoints - This generates the child waypoints section. This section supports title options. 
User data - This generates the user data section. This section supports title options. 
Custom Data - This generates the custom data section. This section supports title options. 
Hints - This generates the hints section. Use the option "Decode=Yes|No" to override the default setting. This section supports title options. 
Special tags - This generates the special tags section. This section supports title options. 
CloseLeftCol - This generates the code to close the left column (as opened by the OpenLeftCol section).
OpenRightCol - This generates the table code for the right hand column. Use the option  "Color=#FFFFFF"  to override the column background color.
Google map - This generates the code to display the Google map. Use option "MapHeight=nnn" to override the hight of the map in pixels. Use the option "IconSet=n" to override the cache icon set. 
GSAK notes - This generates the GSAK notes section. This section supports title options. 
Logs - This generates the log section. Use "Numlogs=nnn" To limit the number of logs displayed. This section supports title options. 
CloseRightCol - This generates the code to close the Right column (as opened by the OpenRightCol section).
CloseTables - This generates the code to close the tables (as opened by the OpenTables section).
CloseDoc - This generates the code to close the html document  (as opened by the OpenDoc section).
NearBy - This generates the Near by caches section, but is only valid when creating a custom format for  "File=>Export=>HTML" (the calculation of the nearest caches is far to expensive to include for each cache in the split screen). Use option "Max=nn" to override the number of caches to list.  This section supports title options. 
Clean - This is not really a section, but is provided for low level use of database data in your custom HTML. When placing something like the cache name or placed by in the HTML you should never just use code like :
 

$_HTML = $_HTML + $d_name


The reason being that the cache name could contain characters ("<", ">", "&", etc) that will mean your generated HTML code is invalid. Using "Clean" ensures that such data is correctly encoded. For example & is converted to &amp;

This is automatically done when you use any of the other "sections" as given above. However, if you are generating your own data then you should be using the code like:
 

$_HTML = $_HTML + CustomFormat("Clean",$d_name)

 
All sections that show a title bar have the following options:

ShowTitle=Yes|No - allows you omit title bar if not required
TitleColor=#FFFFFF - change the title bar color

Other section specific options that correspond to the GUI options:

To get an exact duplication of the standard "Full display" format that respects all your GUI settings, the custom format macro would be:
  

#***************************************
# HTMLName=Custom full display
# SplitScreen=Yes
# Export=Yes
# Offline=Yes
# Condensed=No
#***************************************
$h = CustomFormat("OpenDoc")
$h = $h + CustomFormat("OpenTables")
$h = $h + CustomFormat("OpenLeftCol")
$h = $h + CustomFormat("Header")
$h = $h + CustomFormat("Cache photos")
$h = $h + CustomFormat("Description")
$h = $h + CustomFormat("Custom URLs")
$h = $h + CustomFormat("GC Note")
$h = $h + CustomFormat("Trackables")
$h = $h + CustomFormat("Child waypoints")
$h = $h + CustomFormat("User data")
$h = $h + CustomFormat("Custom Data")
$h = $h + CustomFormat("Hints")
$h = $h + CustomFormat("Special tags")
$h = $h + CustomFormat("CloseLeftCol")
$h = $h + CustomFormat("OpenRightCol")
$h = $h + CustomFormat("Google map")
$h = $h + CustomFormat("GSAK notes")
$h = $h + CustomFormat("Logs")
$h = $h + CustomFormat("CloseRightCol")
$h = $h + CustomFormat("CloseTables")
$h = $h + CustomFormat("CloseDoc")
$_html = $h

 
Now here is the same format but with a few option changes
 

#***************************************
# HTMLName=Custom full display
# SplitScreen=Yes
# Export=Yes
# Offline=Yes
# Condensed=No
#***************************************
$h = CustomFormat("OpenDoc")
$h = $h + CustomFormat("OpenTables")
$h = $h + CustomFormat("OpenLeftCol")
$h = $h + CustomFormat("Header","ShowUtm=Yes Attributes=No") # also show coordinates in UTM format, don't show attributes
$h = $h + CustomFormat("Cache photos")
$h = $h + CustomFormat("Description")
$h = $h + CustomFormat("Custom URLs","ShowTitle=No") # no need for custom url title
$h = $h + CustomFormat("GC Note")
$h = $h + CustomFormat("Trackables")
$h = $h + CustomFormat("Child waypoints")
$h = $h + CustomFormat("User data")
$h = $h + CustomFormat("Custom Data")
$h = $h + CustomFormat("Hints","TitleColor=#FF0000 Decode=Yes") # display hint title in red and always decode
$h = $h + CustomFormat("Special tags")
If $_HtmlFormat = "Export"
  $h = $h + CustomFormat("NearBy","Max=5")
EndIf
$h = $h + CustomFormat("CloseLeftCol")
$h = $h + CustomFormat("OpenRightCol")
$h = $h + CustomFormat("Google map","MapHeight=800") # increase height of google map to 800 pixels
$h = $h + CustomFormat("GSAK notes")
$h = $h + CustomFormat("Logs")
$h = $h + CustomFormat("CloseRightCol")
$h = $h + CustomFormat("CloseTables")
$h = $h + CustomFormat("CloseDoc")
$_html = $h



Note the use of the NearBy section. This section shows the nearest (Max=) caches and is only applicable when doing "File=>Export=>HTML". If you omit the Max=nn option, then the value as per your export dialog is used. 
 
The system variable $_HTMLFormat has also been included so you can take different action depending on where the code is to be used. This is handy where only minor differences are required to the code depending on where it is used:

SplitScreen - Split screen display
Export - File=>Export=>HTML
Offline - Right mouse click, "View offline in browser"
Condensed - File=>Print
DualScreen - Dual screen display


Note: The condensed print is a little different because the idea is to generate one print out for all the waypoints in your current filter.

All other HTML custom formats are for a single cache only and the whole resulting HTML code for each cache is returned in the system variable $_HTML

To cater for a single HTML file of all waypoints (condensed print), there are 3 system variables

$_HtmlHeader - The header part of the HTML, this will be output at the very start of the file, and only output once
$_HtmlBody - This is the output for each individual waypoint
$_HtmlFooter - The Footer part of the HTML, this will be output at the very end of the file, and only output once.

It doesn't matter what order you allocate values to these variables, but you must update each one with something somewhere in the custom macro.

For example, the following custom format code will generated a summary of just the header information in two columns:
 

#*********************************************
# HTMLName=Custom Condensed
# SplitScreen=No
# Export=No
# Offline=No
# Condensed=Yes
#*******************************************

$_htmlHeader = CustomFormat("OpenDoc","Color=#FFFFFF") 
# if variable does not exist, then this is the first cache
If varexists("$p_" + "CondensedToggle")
  $p_Condensedtot = $p_CondensedTot + 1
  $p_Condensedtoggle = not($p_CondensedToggle)
Else
  $p_CondensedTot = 1
  $p_CondensedToggle = true
EndIf

$h = ""
if $p_CondensedToggle
  $h = $h + "<table align=centre bgcolor='white' border=0 width=100%><tr><td valign='top' width='50%'>"
else
  $h = $h + "<td valign='top' width='50%'>"
endif

$h =  $h +  CustomFormat("Header") 
$h = $h + "</td>"

If not($p_CondensedToggle)
  $h = $h + "</tr></table><hr>"
endif

# last cache calcs here

If $p_CondensedTot = $_count 
  # finish off table if odd number of caches
  If $p_CondensedToggle
    $h = $h + "<td> </td></tr></table>"
  endif
  $result = RemoveVar("$p_" + "CondensedToggle")
  $p_CondensedTot = 0

EndIf
$_HtmlFooter= CustomFormat("CloseDoc") 
$_htmlbody = $h



 
Alpha List         Category List