ZoomCharts Documentation
Version: 1.21.1 (2025-02-07)
Switch to Version 2.0 (BETA)

NetChart data

Data format

A typical net chart data object looks like this:

{
    "nodes":[
        {"id":"n1", "loaded":true, "style":{"label":"Node1"}},
        {"id":"n2", "loaded":true, "style":{"label":"Node2"}},
        {"id":"n3", "loaded":true, "style":{"label":"Node3"}}
    ],
    "links":[
        {"id":"l1","from":"n1", "to":"n2", "style":{"fillColor":"red", "toDecoration":"arrow"}},
        {"id":"l2","from":"n2", "to":"n3", "style":{"fillColor":"green", "toDecoration":"arrow"}},
        {"id":"l3","from":"n3", "to":"n1", "style":{"fillColor":"blue", "toDecoration":"arrow"}}
    ]
}

Each node object must have the following fields:

Optional node fields:

Each link object must have the following fields:

Optional link fields:

The entire data object itself may also contain an error member instead of nodes and links. This is used to signify that the loading operation failed. The error member should contain a string describing the error.

Data sources

NetChart has an internal cache with loaded data for nodes. When NetChart is first initialized, or when the data is reloaded through a call of reloadData(), the cache is first filled with either preloaded data or random data, whichever is specified. If both are specified, random data is used and preloaded data is ignored. If none are specified, the cache remains empty. A call to replaceData() will also result in the data cache containing only the specified data, but not preloaded/random.

Afterwards, when a node is needed that is not in the cache, or a node with .loaded=false needs to be shown, NetChart will issue a data request for that node either to the data URL or the data function. If both are specified, data function is used and data URL is ignored. If neither is specified, an error is generated.

Last but not least, the AddData() and RemoveData() API functions may be called at any time to manually add or remove data to the cache.

Preloaded data

Preloaded data is simply specified in the preloaded setting. For example:

chart = new NetChart({
    data:{
        preloaded: {
            nodes: [...],
            links: [...]
        }
    }
});

Multiple data sources

It is possible to set multiple data sources for various reasons. To do that specify that data is array instead of object.

chart = new NetChart({
    data: [
    {
        id: "preloaded-data",
        preloaded: {
            nodes: [...],
            links: [...]
        }
    },
    {
        id: "data-from-url",
        url: //URL to your data
    }
    ]
});

Random graph

Random graph is generated from pseudo-random data, but the seed for the PRNG is fixed, so the graph will also always be the same. This is useful for testing or demos. There are several properties governing the generation of the random graph: random, randomGridLinkProbability, randomNodes, randomLinks, randomTreeDensity. Random graph generation is triggered by setting randomNodes to any positive value. For example:

chart = new NetChart({
    data:{
        randomNodes: 10,
        randomLinks: 15
    }
});

Data function

The data function has three parameters - an array of node IDs, a success callback and a failure callback. The array of node IDs can be empty, which means that ALL nodes need to be fetched. The callbacks can be called later (for example, in a response to an AJAX request), or they can be called immediately. The callbacks are only valid for a single call, and after one is called, the other may not be called.

Data URL

If data URL is used, it will have a parameter nodes attached to it, which will contain a comma-separated list of URL-encoded node ids. The returned data must be in JSON format.

Dynamic data loading and the .loaded flag

Every node has a .loaded flag which can be either true or false. If the flag is true, that means that all data for this node is loaded and NetChart will not request more data for it. If the flag is false, NetChart will request data for it when the node needs to be shown, and keep re-requesting it until it gets set to true. As long as the flag is false, the node will also have a loading indicator drawn on it.

This can be used to load the node data incrementally. Each time when a request returns data for a node which is already in cache, the cached data gets extended with the new data. Thus, the final node data in the cache will contain all the fields from all the requests. The same applies to links, except that changing the link from and to properties is not allowed.

For example if first request returned node:

    {"id":"nJoe", "name":"Joe-needsMoreLoading","balance":null}

and the second one returned:

    {"id":"nJoe", "name":"Joe", "balance":1000}

the resulting data is:

    {"id":"nJoe", "name":"Joe", "balance":1000}

There is an exception to this - if a cached node has .loaded=true, and incoming data contains that same node with .loaded=false, the cached node will be considered authoritative and will not be extended with the incoming incomplete data. If the incoming node also has .loaded=true, the cached node will be extended.

Links are loaded together with nodes. That is, for every node that is requested, all links from that node also should be returned. Therefore, for any known link at least one of the endpoints will be fully loaded. The other endpoint however might not be loaded. In that case a "dummy" node is added to the data cache. It will be returned when requested by ID or otherwise, but it will have .loaded=false. Data sources can also add nodes with .loaded=false.

If less than all of the requested nodes are returned, NetChart will issue another request for the remaining nodes. If any nodes that were not requested are returned, they will be added to the cache - this can be used to optimize network request count.

In any case, a response must return at least one node from those that were requested and at least one of those nodes must have .loaded=true set. If this requirement is not met, an error will be issued and the response will be discarded.

X