Skip to content
Open Garphield

The .gph document

setDocument() accepts the same .gph project used by the workbench and Python package. Pass the parsed object:

const project = await fetch("/network.gph").then((response) => response.json());
await graph.setDocument(project);
interface Gph {
info: {
version: 1;
name?: string;
created?: string;
};
datasets: Array<{
id: string;
graph: NodeLinkData;
}>;
config: {
version: number;
layout?: "force" | "levels" | "geo";
bindings?: Binding[];
filterStack?: Filter[];
embed?: { tooltip?: { template?: string } };
[key: string]: unknown;
};
}

Older projects may contain "quality"; the loader accepts it as a compatibility alias for "force", but new projects should emit "force".

The project may also contain positions, saved sets, history, and a story. The embed applies the same validated project-loading path as the workbench.

{
"directed": true,
"multigraph": false,
"graph": { "title": "Dependencies" },
"nodes": [
{ "id": "parser", "label": "Parser", "team": "core" },
{ "id": "renderer", "label": "Renderer", "team": "visuals" }
],
"links": [
{ "source": "parser", "target": "renderer", "weight": 2 }
]
}

Node and edge attributes become fields in the visual source catalogue.

Bindings connect a source to a visual channel:

{
"version": 1,
"layout": "force",
"bindings": [
{
"channel": "color",
"source": { "kind": "field", "id": "field:team" },
"resultType": "cat"
},
{
"channel": "size",
"source": { "kind": "algorithm", "id": "degree" },
"resultType": "num"
}
]
}

Build the document in the workbench, with Project.from_pandas() or Project.from_networkx(), or against the published GPH schema. See the Binding grammar for every channel, result type, source kind, and the field: id rule.

config.embed.tooltip.template sets what the embed’s node popover shows (turn the popover on with chrome=tooltip; see Choose UI components). It is a small, safe Markdown template rendered once per node:

{
"embed": {
"tooltip": {
"template": "### {title}\n`{label}` in **{area}**, {status} on {date}.\n\n[Read the decision]({url})"
}
}
}
  • {field} inserts that node attribute as plain text. Values are never read as Markdown, so data can’t add links, formatting or images. Write \{ for a literal brace.
  • {@id} and {@degree} insert the node’s id and degree. {@fields} on its own line shows a short grid of the node’s attributes.
  • Supported Markdown: headings, paragraphs, line breaks, **bold**, *italic*, `code`, links, one level of - or 1. lists, and images. Raw HTML and other Markdown show as typed.
  • The first heading becomes the card’s title. A leading image becomes a cover; give it the title "thumb" (![alt](url "thumb")) for a small thumbnail instead. A last line of only links becomes the card’s footer.
  • Only http:, https: and mailto: links and http:/https: images are kept. A link or image whose URL is empty or unsafe is removed, and a line whose placeholders are all empty is dropped.
  • Numbers show at most three decimals, with grouping.

Without a template the card shows the node’s label, a few of its fields and a link to its url attribute, if it has one.