Embedding
Nodemap XML
Node content
Settings XML
Javascript
Audio
Home > Archive > Developers/reference > API Reference > Nodemap XML
The nodemap XML file describes the hierarchical structure that SpicyNodes visualizes. This file is itself a nested hierarchy of nodes, their attributes, and descriptive text or CDATA sections. Just as any XML file includes one and only one root node, similarly any SpicyNodes nodemap includes one and only one home node.
SpicyNodes can be seen as a tool for interactive representations of XML files in a radial fashion. In fact, SpicyNodes can draw each valid XML file that has at least one node. If this XML file’s nodes contain attributes and values that are supported by SpicyNodes, such as label, color, source, and others, then the results become interesting and inviting.
With the exception of very small nodemaps, the radial layout presents only a subset of nodes contained in a nodemap. The subset consists of nodes that are directly attached, i.e., those that have a parent-child relation in the XML file as well as those nodes that lay on the path to the home node. In other words, the disply forms a list of ancestors within the current selection. This separation enables SpicyNodes to represent very large nodemaps with thousands of nodes, while the subset of simultaneously visible nodes is small enough to easily fit even a small display area.
After registering for a SpicyNodes account, a new sample nodemap is automatically created. You can modify it online or download it to your hard drive.
Most developers opt for manually creating and editing the nodemap XML file, as this approach allows for flexibility without unnecessary complexity. Nevertheless, in order to correctly modify the file, you should be familiar with XML syntax – Extensible Markap Language (XML) 1.0. There are a variety of commercial XML editors (e.g., oXygen, and EditiX) that you can use.
The nodemap XML file can be also manipulated through the SpicyNodes web-based "Edit Nodes" mode; by editing it manually and then importing or using the "Code View"; and if hosted on your server, by generating it at runtime, such as with database content.
The following is a source of a simple nodemap:
<node label="Recreation and Travel">
<![CDATA[This area lists arts and culture resources, recreational activities, information for visitors, and how to get around the city.]]>
<node label="Arts and Culture">
<![CDATA[ Find places and events where you can enjoy music, paintings, film, and other arts.]]>
<node label="Art classes">
<![CDATA[ Learn how to paint, sculpt, or do crafts.]]>
</node>
<node label="Cultural Centers">
<![CDATA[ These facilities showcase ethnic art]]>
</node>
<node id="#1" label="Movies">
<![CDATA[ Attend first-run movies and film festivals.]]>
</node>
</node>
<node label="Recreation">
<![CDATA[ Play or attend sports, games, social activities.]]>
<node label="Recreation programs">
<![CDATA[ Find a free or low-cost.]]>
<node label="Kids and Family">
<![CDATA[ These offer after-school and weekend games and sports.]]>
<node href="#1"/> ← Link to node "Movies"
</node>
<node label="Senior Programs">
<![CDATA[ Seniors over the age of 60.]]>
</node>
<node label="Therapeutic Recreation">
<![CDATA[ Enroll children with disabilities or adults with developmental disabilities. ]]>
</node>
</node>
</node>
</node>
In this example, we’ve indicated the home node with label="Recreation and Travel". Several CDATA sections are node descriptions that will appear in the layout under node labels. A node can have only one CDATA section. The home node has two children - "Arts and Culture" and “Recreation". Under "Kids and Family" there is an internal link node node href="#1", which means that after clicking this link node on the layout, the selection will move to the node "Movies", which contains the referenced attribute id="#1". Links are explained in more detail in the Escaping the hierarchy section, below. The complete list of node attributes and values can be found in the Nodemap Contents and Options chapter.
As a SpicyNodes registered user, you can navigate nodemaps with the online “Preview" and “Live view" via the spicynodes.org site. Also, from your account you have access to a sample embedding HTML code that allows you to include the SpicyNodes player in any of your HTML pages. You can find a detailed explanation of the embedding code in the Embedding chapter. It will help you modify or generate your own embedding code suitable for more advanced features, such as JavaScript connection.
XML files have strictly hierarchical structures. The same applies to SpicyNodes nodemaps. However, special href and id attributes added to nodes allow you to escape the hierarchy at runtime. A node containing the href attribute is called a link node. A node containing the id attribute can be considered as a linkable node.
Each node of the nodemap can be referenced by one or more link nodes. A linkable node has to contain a unique identifier, id, that differentiates it from all other nodes in the same nodemap. A link node has to point with an href attribute to an identifier that exists in the same nodemap. For example:
<node label="Earth">
(…)
<node id="#1" label="Africa"/>
(…)
<node id="#6" label="Asia"/>
(…)
<node id="#315" label="Europe"/>
(…)
<node id="#2" label="Portugal"/>
(…)
<node id="#3" label="France"/>
(…)
<node label="European countries">
<node href="#2"/>
<node href="#3"/>
(…)
</node>
(…)
<node label="Cheese producers">
<node href="#3"/>
(…)
</node>
(…)
<node label="Continents">
<node href="#1"/>
<node href="#6"/>
(…)
</node>
(…)
</node>
These are a few portions of a larger nodemap. All nodes that contain href attributes link to nodes with corresponding id attributes. During navigation, after clicking on the first child of “Cheese producers", the layout will change to “France" (node id="#3" label="France"). The same will happen after clicking the second child under “European countries". After each of these actions, the layout will also move to a distant context related with “France", possibly displaying a distant subset of nodes. The abstract link nodes in a nodemap can be compared to wormholes in the cosmic space – entering them, you can instantly travel to very distant areas.
When using linking nodes, it is important to remember that each id attribute has to be unique for the whole nodemap and that each href attribute has to have one and only one corresponding id.
SpicyNodes nodemaps allow you to provide additional, hidden information enclosed in a metadata tag. The contents of metadata are ignored in the generated layout. The medatada tag can contain various information, such as nodemap author, modification dates, descriptions, keywords, etc. If you are using a premium SpicyNodes account, the metadata section contains the membershipkey value that is essential to activate premium account options.
Because an XML file allows only one root node, the metadata section and the nodemap are enclosed in a nodemap root node. The nodemap node can have up to two child nodes, of which one is the metadata root and the other is the nodemap root (or home) node.
The following is an example of a nodemap containing a metadata section with a membership key value:
<nodemap>
<metadata>
<author value="Jackson"/>
<modification value="2010-05-12 23:12:57"/>
<membershipkey value="http://spicynodes.axxxxxxxx.basic.s3.amazonaws.com/basic.gif?x-amz-security-token=%7BUserToken%axxxxxxxxxxxxxxxxxxxxxxxxxx2&Signature=axxxxxxxxxxx&Expires=2291787600"/>
</metadata>
<node label="This is the home node">
<node label="This is the first child node"/>
(…)
</node>
</nodemap>
You can enclose the root node of the nodemap in a nodemap node without providing the metadata section. It’s important to note that the nodemap node (root of XML file) will never be considered a root (or home) node of the contained nodemap.
There is no limit to the number of nodes in a nodemap nor the maximum number of siblings one node can have. However, as a nodemap author, you have to decide whether a layout having tens of simultaneously visible nodes is still legible or if a nodemap having tens of thousands of nodes is still processed fluently by the client system. Runtime performance and legibility are difficult to calculate, because they depend upon applied visual style, the nodemap structure, display resolution, and CPU strength.
In most cases, up to 20-30 simultaneously visible nodes are safe for overall legibility. In addition, nodemaps consisting of up to 5K nodes are safe for nodemap processing.
