Navigate

The MC.Navigate method is a powerful and frequently usedmethod in pASP. It is designed to help examine the structure of a mobile channel, as represented in CDF, at run time. To understand the method behavior a brief discussion of the background and terminology is helpful.

The basic operand of the Navigate method is an element, the smallest unit of information in a CDF file. Every element has a tag and, optionally, a value. The MC.Tag and MC.Value methods of pASP may be used to retrieve these strings for any element. The elements are organized into a tree structure as specified by Extensible Markup Language (XML) as the CDF file is parsed. Using the Navigate method, you can move to specific elements within the tree and between elements with certain relationships.

The following discussions refer frequently to the sample CDF file and its associated parse tree, which are provided at the end of this document. The parse tree shows the internal representation of the sample CDF file. Each line of the parse tree is equivalent to an element, and all start with the element tag. Elements at the same level of indentation are siblings. In the CDF file, for example, the BASE element is a child of the top-level CHANNEL element. The first HREF element is a sibling of the BASE element. The INTERVALTIME element is a child of the SCHEDULE element.

Many elements have default values. The default values are indicated in the parse tree by an “= [string]” expression following the tag of the element.

To determine the default value of an element

1. If the specified element has a string directly associated with it, the string is the default value.
   
   
2. If there is no direct string, but there is a child VALUE element, the child’s value becomes the default value.
   
   
3. If no VALUE element is provided, but a child HREF element is found, its value becomes the default value.
   
   
4. If none of these can be found, the VALUE is empty.

For example, the value of the first ID tag has a direct string, the TITLE tag has an explicit VALUE element, so this is used, and the value of first LOGO tag is its HREF element. The SCHEDULE tag has no direct string, VALUE or HREF children, so its value is empty.

The Navigate method has the following syntax:

NewElem = MC.Navigate(StartElem, NavAction, [,Match])

The method returns a new element, or 0 if the command could not find the specified element. The following code example shows how to test this return value using standard VBScript comparisons. Other standard VBScript comparisons may be used.

  IF NOT NewElem THEN
     ' not found
  END IF

The StartElem parameter is the starting element from which to base relative movement commands. If you are using the absolute movement command “Jump,” you must use “ ” for the StartElem parameter. But in all other cases, StartElement must be a valid element returned from a previous Navigate method.

The NavAction parameter is one of the following strings:

• “Jump”

The “Jump” action is the first command used to get a starting element. It is equivalent to the MC.Locate command. The StartElem parameter must be an empty string. The “Jump” action navigates directly to a specific element in the CDF as identified by the supplied identifier. For example, the statement

NewElem = MC.Navigate("", "Jump", "D1")

jumps to the first data item element in the example CDF file. The NewElem parameter is the ITEM parent element to the ID element, or “D1” in the example CDF file.

• “First”

The “First” action moves to the first element at a specified level. For example, from the ID element of the first LOGO element in the example CDF file, a “First” action moves to the STYLE tag of that LOGO. More practical scenarios are to use this action to go back to the beginning of the list of ITEM elements under a subchannel.

NewElem = MC.Navigate(StartElem, "First")

• “Out”

The “Out” action moves from the current element to the parent element.  For example, from the TITLE element in the example CDF file, an “Out” action results in the movement to the top-level channel element.

NewElem = MC.Navigate(StartElem, "Out")

• “In”

The “In” action moves to first child element beneath the current element. For example, from the first USAGE element in the example CDF file, the “In” action results in a movement to the VALUE element.

NewElem = MC.Navigate(StartElem, "In")

• “Prev”

The “Prev” action moves to the previous sibling element. If it does not find a previous sibling element, it returns 0; it does not move to the parent element. For example, from the BASE="http://mySite/" ID="34droad"element in the example CDF file, the “Prev” action moves to the HREF="mctp://mySite/34droad/34droad.cdf" element  Because there are no more siblings at this level, calling “Prev” again returns 0.

NewElem = MC.Navigate(StartElem, "Prev")

• “Next”

The “Next” action moves to the next element at the same level. As with the “Prev” action, if it finds no such sibling element, it returns 0. For example, from the first LOGO tag in the example CDF file, the “Next” action results in a move to the second LOGO element.

NewElem = MC.Navigate(StartElem, "Next")

• “Match”

The “Match” action attempts to find a sibling element with a tag matching the specified match string. It traverses as many siblings as it needs to until it either finds a match or can find no more siblings. If the “Match” action starts from a matched element, it returns the current element. To match beyond the current element, the “Match” action must follow a “Next” action.

NewElem = MC.Navigate(StartElem, "Match"," TagToMatch")

• “InMatch”

The “InMatch” action is the same as “Match” except it begins its search at the first child of the current element. This can be useful when looking for specific subtags that modify the enclosing element. The following code example shows how to look for the USAGE tag for a specific item.

UsageElem = MC.Navigate(StartElem, "InMatch", "USAGE")
IF UsageElem Then
   UsageVal = MC.Val(UsageElem)
   ' Test for specific usage...
End If

The only actions that use the optional third parameter are “Match” and “InMatch.”