Scenario
An external GPS Exchange Format ('GPX') file has been previously and successfully parsed and the results are now displayed in a 5-item menu, none of which cause actual importation.
This is the analysis phase of the importation process.
Items 1-3 enable you to preview the results at individual waypoint, route and track level!
If these results suggest data loss or room for improvement, then you may manipulate the processing of the XML/GPX tags as you see fit (using XML tag conversion via ALIAS ).
Item 4 summarizes these (user-defined) XML tag conversions .
Item 5 completes the 'dress rehearsal' by then simulating a virtual 'export' operation.
(1) Waypoints
Press Waypoints to view a summary of the waypoints contained in the importing file.
Only tags with non-null values are displayed.
To import an individual waypoint long press it. It will be destructively imported, overwriting the data of any identically-named waypoint. It will be given the currently assigned id0/id1 key-value defaults.
To import all waypoints, use the hardware menu from the initial File Analysis screen.
(2) Routes
Press Routes to view a summary of the routes contained in the importing file.
Only tags with non-null values are displayed.
Short press a route to see the summary of points within the route.
To import an individual route long press it. It will be destructively imported, overwriting the data of any identically-named route. It will be given the currently assigned id0/id1 key-value defaults.
To import all routes, use the hardware menu from the initial File Analysis screen.
(3) Tracks
Press Tracks to view a summary of the tracks contained in the importing file.
Only tags with non-null values are displayed.
Short press a track to see the summary of segments within the track.
Short press a segment to see the summary of points within the segment.
To import an individual track long press it. It will be destructively imported, overwriting the data of any identically-named track. It will be given the currently assigned id0/id1 key-value defaults.
To import all tracks, use the hardware menu from the initial File Analysis screen.
(4) Logged Data
Press Logged Data to view selected data logged during the input file parse. The red lines are headings:
(Import) Alias tag conversion: ACTIVE|INACTIVE
If 'Settings' preference XML tag conversion (Import) is checked then Alias tag conversion is active and the 'S1' values of aliases having the reserved binder name #tagAlias_In will be compared for a match with the name of the currently-parsed tag. If a match is found the tag name will be transformed to its alias (ie: 'S2' value) and its data treated accordingly.
[NB: A tag may be ignored completely by specifying a blank alias. This will appears in the log as '<*null*>]
The detail line shows the original tag name, and, to the right of the arrow, the new tag name and a count of the transformations. (More information on tag conversion below.)
(Import) Explicit tag rejection: ACTIVE|INACTIVE
[Optional. Tags specified here get rejected anyway!] If 'Settings' preference XML tag rejection (Import) is checked then Explicit tag rejection is active and the 'S1' values of aliases having the reserved binder name #tagReject_In will be compared for a match with the name of the currently-parsed tag. If a match is found the tag name will be ignored (along with any other tags it encloses ) and the information logged here.
The detail line shows the rejected (outer) entity together with the count.
Note: The test for explicit tag rejection takes place only when normal processing (including tag conversion via alias ) has failed to recognise the current tag. By explicitly rejecting a non-architected, or otherwise unknown tag, the event will be noted here, rather than in the Lost/Unknown section. (This is its entire purpose - keeping the last part of the log clean, so that any surprises in the format of your data may be easily spotted.)
(Import) Lost/Unknown tags:
GPX is an open architecture. This app supports only a subset. Non-architected ('private') tags and others not handled by the SAX XML parser, nor by explicit rejection, show up here, together with their counts.
[Using XML tag conversion via ALIAS during Import , described below, provides a means for dealing with tags that have ended up Lost/Unknown.]
(5) Normalizing a GPX file without Importing it
The last item in the list (Simulator) completes the simulation of the entire Import/Export process. Use it to determine compatibility of your (probably unique) GPX files with this app.
Select item (5) to reverse the (importation) parsing process and create a new XML-format GPX file. [If input file name is abc.gpx then output filename will be out_abc.xml and written to the SD card root directory.]
Inspect this file - it will only contain the XML tags for which support is provided by this app. Tags not supported by the GPX architecture or otherwise unknown to this app will be lost unless you implement XML tag conversion...
XML tag conversion via ALIAS during Import Example 1
Assume you are importing a GPX file with waypoints containing critical data enclosed by XML tags <gold> and </gold>
This tag is not recognised by this application (nor its database structure) so we will use one of the user-defined fields, user3 to store the data instead.
Step 1: Use 'settings' ('spanner' icon on main screen) to check the preference XML tag conversion (Import)
Step 2: [See Manage user-defined key-value pairs (the 'face' icon on the main screen).]
Set up a new alias as follows:
S1 ('String 1') value = gold
S2 ('String 2') value = user3
Description = #tagAlias_In
NB: #tagAlias_In is a reserved binder name and applies to waypoints, routes and tracks. Select it from the spinner then long press to paste it into the input field.
Now, during import, all data enclosed by <gold> tags will be stored in the user3 database column. Verify this by viewing the parsed waypoints (first item on menu).
XML tag conversion via ALIAS during Import Example 2
Assume you are importing a standard GPX file with waypoints containing descriptive information enclosed by XML tags <desc>...</desc> and <cmt>...</cmt>
For whatever reason, you have decided to interchange the data - but for routes only.
Set up a new alias as follows:
S1 ('String 1') value = desc
S2 ('String 2') value = cmt
Description = #tagAlias_In_RTE
then another, as follows:
S1 ('String 1') value = cmt
S2 ('String 2') value = desc
Description = #tagAlias_In_RTE
NB: #tagAlias_In_RTE is a reserved binder name. Select it from the spinner then long press to paste it into the input field.
Now, during import, all data enclosed by <desc> tags will be stored in the 'comment' database column and vice-versa. This will occur only for routes (including routepoints).
[You would use #tagAlias_In_WPT and #tagAlias_In_TRK for just waypoints and tracks (including segments and track points) respectively. You would use #tagAlias_In to apply such changes to all three.]
XML tag conversion via ALIAS during Export
(Tag conversion during import and tag conversion during export are disparate processes.)
Once you have imported the data enclosed by XML tags <gold> and </gold> into the user3 columns (Import example 1 above) it is perhaps natural that you would wish to reverse the process during export:
Step 1: Use 'settings' ('spanner' icon on main screen) to check the preference XML tag conversion (Export)
Step 2: [See Manage user-defined key-value pairs (the 'face' icon on the main screen).]
Set up a new alias as follows:
S1 ('String 1') value = user3
S2 ('String 2') value = gold
Description = #tagAlias_Out
NB: #tagAlias_Out is a reserved binder name. Select it from the spinner then long press to paste it into the input field.
Now, during export, all data in the user3 database columns will be output to GPX enclosed by <gold> tags. Verify all of this by using the Simulator (last item on menu) and inspecting the output file.
Notes on XML tag conversion
(1) Do not confuse tag conversion via alias with value conversion via alias. The former takes place here. The latter takes place during actual import. For example, it is only during actual import where map symbol (<sym>) values can be transformed via further alias definitions.
(2) Do not employ tag transformation against outer tags such as <gpx> <wpt> <rte> <rtept> <trk> <trkseg> <trkpt> etc!