# Graph Gear XML Files Vague Specification.

Every graph is defined with a little xml file. Here we'll walk you through what can be in the file. Most of the values are optional. The only required values are: the graph title, the graph bgcolor, the node id, the node text, the edge to and from nodes, and the edge label. See the example "The Smallest Interesting Graph" for the bare minimum.

We start out with the general `<graph>` tag. They usually look something like this:

`<graph title="Some Collaboratives" bgcolor="ffffff" linecolor="cccccc" viewmode="explore" width="600" height="300">`

- title - The title is what you might imagine it to be, the name that will appear for your graph on the widget.
- type - The style of the graph, either directed or undirected. Directed graphs show indications of connection direction - defaults to undirected.
- bgcolor - The background color (expressed as a hexadecimal, like most web colors) for the whole graph.
- linecolor - The color for all of the lines connecting nodes on the graph.
- viewmode - There two view modes right now. The 'explore' mode, which only shows the closest nodes and displays nodes as you navigate and the 'display' mode, which shows everything. The explore mode is nice for very large graphs and display mode is the default.
- width,height - These properties (as you might imagine) set the width ad height of the graph. They default to 725x200px. If you use these you'll want to make sure that the corresponding swfobject sizes are set to the same value.
- animation - Either true or false, enables support for VisualCondition's Twease animation library, with currently limited effects - default to false.
- hidelabel - Either true or false, sets labels to hide unless the user mouses over them (note: nodes without text values are set to hide labels by default - and don't show anything on mouseover) - default to false.
- lock - Either x or y, this locks the force direction to a particular axis (fairly unsupported right now).
- action - Either drag or center, this sets the user interaction style for the graph - defaults to drag (fairly unsupported right now).

The next interesting part of the file are the individuals nodes that actually make up your graph. A typical one probably looks something like this:

`<node id="n1" text="The Collaborative" image="somecollabs/co.png" link="http://www.creativesynthesis.net" scale="200" color="ff0000" textcolor="ffffff"/>`

- id - A reference id (hopefully unique) for each node in the graph. You'll need this when you link nodes.
- type - This is the style of node you want to appear, appropriate values are: CircleNode, SquareNode, CircleTextNode (A circle node with simplified label) and OpenNode (an unmasked node intended for use with transparent png backgrounds) - defaults to CircleNode.
- text - The text that appears on the tags for nodes. This is the 'node content'.
- image - If you'd like, you can load an image for each node in the graph. This takes a little bit of bandwidth, so be careful. This is either a local reference (as in the example) or a fully resolved url.
- link - This is the full resolved url or relative reference to something you want the text to link to.
- scale - This is the size of the node, expressed as a percentage. The default node scale is 100, for a 40x40px node. A value of 200 would produce an 80x80px node, for example.
- color - The color for the node, please note that if you use an image in the node only the border and text tag will be colored.
- textcolor - This is the color of the text in the text tag. Good values are often something like ffffff (white), 000000 (black) or something like that.
- cluster - This is the cluster that the node belongs to, if you have multiple independent graphs on one graphgear. This defaults to "default".

The last important item of a graph file is the actual description of the connections between nodes. Free floating nodes don't tend to do so well. It's also worth noting that the graphs currently don't have any concept of direction (at least in rendering). So at this point it is good enough to specify only one direction (for example, that node1 connects to node2, without defining that node2 connects to node1). These look something like this:

`<edge sourceNode="n1" targetNode="n2" label="A label!" textcolor="555555"/>`

- sourceNode - Theoretically the node the connection is coming from.
- targetNode - Theoretically the node the connection is going to.
- label - A textual label that appears on the line the connection makes.
- textcolor - The color for text on the (above mention) label.

That's it for now.