Accessing Joust Properties and Methods

The Menu Object

Note that properties for controlling menu behaviour are already described inMenu Behaviour and are not duplicated here.

Properties

theMenu.lastPMClicked
This is a property that contains the ID of the last expand/collapse image clicked by the user (-1 if nothing has been clicked yet). This is only set when an expand/collapse icon is clicked, not when any other part of the entry is clicked (unless expandOnLink is set).
theMenu.selectedEntry
This is a property that contains the ID of the last entry clicked by the user (-1 if nothing has been clicked yet). This is only set when an entry with a link is clicked, not when an expand/collapse icon is clicked (unless toggleOnLink is set).
theMenu.firstEntry
This is a property that contains the ID of the first entry in the menu (-1 if there are none).
theMenu.entry[entryID]
The entry property is an array of menuEntry objects. These exist, initially, in the order that you create them with addEntry and addChild calls. This does not necessarily correspond to the order in which they are displayed. If you delete an entry, it's space in the array is set to null but the array will not be compressed. The space will be reused if you later add new entries. See below for more details of the menuEntry object.

Methods

theMenu.addEntry (addTo, type, text, url, status[, insert])
Adds a new entry to the menu after the entry specified by addTo. Returns the ID of the new entry. In addition to the required parameters (described in more detail in "Defining the Menu), there is an optional insert parameter. If this is present, and true, the new entry is inserted before the entry specified by addTo.
theMenu.addChild (addTo, type, text, url, status[, insert])
Adds a new child to the entry specified by addTo. The new entry is added after the last existing child. Returns the ID of the new entry. In addition to the required parameters (described in more detail in "Defining the Menu), there is an optional insert parameter. If this is present, and true, the new entry is inserted before the first existing child.
theMenu.rmvEntry (entryID)
Removes the entry specified by entryID and all its children. You must ensure that entryID is valid. If it isn't, a JavaScript error will be generated. You must refresh the menu after calling this.
theMenu.rmvChildren (entryID)
Removes all the children of the entry specified by entryID. If you supply -1 for entryID, all entries will be removed. Again, you must ensure entryID is valid otherwise you will get a JavaScript error. You must refresh the menu after calling this.
theMenu.selectEntry(entryNo)
Sets the selected state of the entry specified by entryNo to true. If there is a currently selected entry, it will be unselected.
theMenu.setEntry(entryNo, state)

Sets the open state (true or false) of the entry specified by entryNo. If state is true, setEntry will make sure all parents of the entry are open as well. Returns true if the menu has been changed and needs refreshing.

theMenu.setEntryByURL(theURL, state)

Sets the open state (true or false) of the entry that links to the URL specified by theURL. theURL must exactly match the URL used when the entry was defined. If state is true, setEntry will make sure all parents of the entry are open as well. Returns true if the menu has been changed and needs refreshing.

theMenu.setAll(state, startAt)
Sets the open state (true or false) of the all sub menus of the entry specified by startAt. If startAt is -1 or is omitted this will set the open state of all entries in the menu to state. This function will refresh the menu if necessary.
theMenu.openAll()
Opens all expandable entries and refreshes the menu if necessary.
theMenu.closeAll()
Closes all expandable entries and refreshes the menu if necessary.
theMenu.findEntry(value [, property, [matchType, [startPos]]])

Searches the menu for an entry. Returns -1 if no matching entry was found.

Parameter Description
value The value you are looking for. This should be the same data type as the property being searched on.
property A string value containing the name of the MenuEntry property that you want to match. If no property is supplied, "url" is assumed.
matchType This can take three values; "exact", "left" and "right". If anything else is supplied, "exact" is assumed. This determines how string values of different lengths are compared. If matchType is not "exact", findEntry will align the strings as indicated by matchType and will attempt to match the shortest string with the corresponding segment of the longer string.
startPos Determines the entry to start searching from. The default is 0.

findEntry searches through all menu entries until it finds one where the specified property contains the value specified. In addition to the standard properties described below, findEntry will also search any custom properties that you have added to the entries. findEntry searches through the entries in ID order, starting at the ID specified by start. This will generally be the order in which you have added the entries to the outline but, if you have removed entries along the way, it may not.

You can, for example, find the entry for the current page with

var entryID = parent.theMenu.findEntry(thisURL, "url");

where thisURL is the URL of the current page. If using an exact search, the URL supplied must exactly match the URL used define it entry. A more generic approach would be to use the location.pathname JavaScript property with a right search:

var entryID = parent.theMenu.findEntry(location.pathname, "url", "right");

Or, you could find all entries that match a particular condition:

var eID = parent.theMenu.findEntry(true, "isopen", "exact", 0);
while (eID >= 0) {
    // Do something with entry ID
	alert('The entry titled "' + parent.theMenu.entry[eID].text + '" is open.');
    // Then find next match
    eID = parent.theMenu.findEntry(true, "isopen", "exact", eID + 1);
}

Click here to try it.

theMenu.refresh()
Refreshes the menu. On browsers that do not have DHTML, this is the same as reload. On browsers that use DHTML, this shows/hides and repositions existing entries. If you have modified the menu in some way to add or remove entries, you will need to use reload to make them visible.
theMenu.reload()
Reloads the menu. On browsers that do not have DHTML, this is the same as refresh. On browsers that use DHTML, this method completely rebuilds the menu, and is required if you have added new entries with addEntry or addChild.
theMenu.scrollTo(entryID)
Scrolls the menu frame to make the specified entry visible. In general, this will only scroll enough to make the entry visible but, on some older browsers, it may scroll the specified entry to the top of the frame. On DHTML browsers scrollTo will attempt to scroll far enough to make the entry and all it's children (if any) visible.
theMenu.itemClicked(entryID)
This function performs onClick processing for the specified item. This includes selecting the entry and executing any custom onClick event. This is just like the user clicking on the entry except that it will not load the entries URL into the text frame.
The Joust Outliner