Skip to content

Template Technical Overview

Jump to bottom
benloh edited this page Dec 21, 2024 · 6 revisions

How templates are defined in code.

AUDIENCE: Developers-only.
See Edit Template if you are a researcher wanting to edit templates.

TABLE OF CONTENTS

Templates Technical Overview

Templates define preferences and custom node/edge fields

Templates define four key parameters for projects:

  1. Project-specific options -- e.g. requireLogin, allowLoggedInUserToImport
  2. Node field definitions, including selectable node types and corresponding colors
  3. Edge field definitions, including selectable edge types and corresponding colors
  4. Header labels to use when exporting and importing

Each project has its own template definition file called *.template.toml. e.g. a project called tacitus.loki is associated with a template tacitus.template.toml.

The .toml template files can be edited manually using any text editor. But it is generally easier to use the built-in Edit Template editor.

New Projects are created from a Default Template

Templates are defined in three places:

  • a project-specific *.template.toml file, e.g. tacitus.template.toml
  • _default.template.toml
  • template-schema.js.

<project>.template.toml

The <project>.template.toml file is associated with a specific project. It defines the parameters used by the project. It is initially derived from a _default.template.toml, but usually has been modified by a researcher/advanced user to work with a specific project.

_default.template.toml

_default.template.toml is used as the starting point for any new template file. If a dataset is requested that does not already have a template file, it is cloned from _default.template.toml. So you can use this to define a starting point for projects. Use this to set stuff like default node and edge types, common feature parameters etc. The defaults established in the _default.template.toml file can differ from those set by template-schema.js, and will in fact override definitions in template-schema.js when creating a new project template file.

  • Administrators might want to modify this to establish a baseline for all projects and then commit it to the repo for all projects.

  • Curriculum designers can modify this for their local projects. They should not commit this to the repo unless the intent is for ALL Net.Create users across all organizations to use these defaults.

  • The file can be found at ./app-templates/_default.template.toml.

template-schema.js

Caution

This should not be touched by anyone but developers!!!

template-schema.js defines the core format of the template toml file. It lists ALL available parameters, sets some json-editor-specific settings, and has help text. This is the source of truth for templates. The _default.template.toml file is generated from the template-schema.js via a developer console method ncRegenerateDefaultTemplate() call.

To generate a new _default.template.toml file:

  1. Redefine any parameters in the template-schema.js file.
  2. Start Net.Create. (make sure you quit and restart if you've made changes while the app is running)
  3. Go to the developer console.
  4. Type ncRegenerateDefaultTemplate() .
  5. A new _default.template.toml is generated and can be found in ./app-templates/_default.template.toml

See JSON-EDITOR SCHEMA, below, for more information.

JSON-EDITOR SCHEMA

In order to create a UI for managing templates, we rely on the JSON-Editor library.

Defining the UI for editing templates means that we need to develop a specification that defines all the fields that need to be edited. This is done via a schema definition file. Since JSON-Editor user JSON to define the UI, the schema definition file is JSON.

Note

The Net.Create app itself uses a TOML format when loading the template. We use JSON when defining the JSON-Editor Schema, then convert the template to TOML.

The schema is defined in build/app/view/netcreate/template-schema.js. The schema is intimately tied to the internal data structures, so we do not recommend changing the schema.

Any template data that are loaded rely on the schema for validation and formatting.

This is a description of the schema.

General Template Settings

These are general settings that apply to the whole template and are saved at the root level of the data structure.

  • name -- The name of the template. This is displayed in the template editor.
  • description -- A short description of the template. This is displayed in the template editor.
  • citation
    • text -- Text to display when clicking "Cite Node" or "Cite Edge", e.g. "H213 Prokopios Network"
    • hidden -- When true, hides the "Cite Node" and "Cite Edge" buttons.
  • requireLogin -- Users are required to log in before they can view the graph.
  • hideDeleteNodeButton -- When true, the "Delete Node" button is removed for admins. Normally only admins can delete nodes. This will disallow deleting for everyone if you need to prevent deletions.
  • allowLoggedInUserToImport -- When true, any logged in user is allowed to import data. Normally only admins can import data.
  • duplicateWarning -- Warning message to display if user is trying to create a node that already exists
  • nodeIsLockedMessage -- Warning message to display if user is trying to edit a node that someone is already editing
  • edgeIsLockedMessage-- Warning message to display if user is trying to edit a edge that someone is already editing
  • templateIsLockedMessage-- Warning message to display if user is trying to edit a node or edge while the template is being edited.
  • nodeDefaultTransparency -- Default transparency for nodes. You usually want this set to 1.0 otherwise, edges will be displayed behind a translucent node.
  • edgeDefaultTransparency -- Default transparency for edges.
  • searchColor -- Outline color of nodes selected via search.
  • sourceColor -- Outline color of node highlighted during auto complete.

Data Fields

The data fields for each node and edge are defined in nodeDefs and edgeDefsobjects.

Each Node Definition and Edge Definition field has required subfields.

  • type -- Javascript object type, e.g. string, number, boolean, select
  • displayLabel -- Label that is displayed in the Node / Edge Editor and in the Node / Edge table headings.
  • exportLabel -- Label to use for exported csv file field names, e.g. you can have a displayLabel of Id, but export it as ID
  • help -- Help text to display on the Node / Edge Editor form (?) button hover.
  • includeInGraphToolTip -- nodes only -- When true, this data in this field will be displayed when the user hovers over the node on the graph.
  • hidden -- When true (checked), this field will not be displayed in the Node / Edge Editor or Node / Edge table. Also hidden fields will NOT BE EXPORTED.

The select type requires options

Options

Only for fields with type = 'select' you also need to define the options that are availabel. Each option consists of:

  • label -- the text label that is displayed in the menu and saved with the node/edge type
  • color -- hex color string, e.g. #FF0000 is red.

Built-in Fields

In addition to the custom subfields, there are a number of built-in subfields. These are in the template primarily so the author can specify the exportLabel for these fields. These fields are created automatically if they are missing. Their values are automatically set by the system.

  • id
  • source -- edge only
  • target -- edge only
  • created
  • updated
  • revision

Updating _default.template.toml

If you change the template-schema.js the _default.template.toml will no longer reflect the settings in the schema. If you want _default.template.toml to match the settings in template-schema.js, you need to regenerate the _default.template.tom file.

This is easy to do with with a browser.

  1. Start Net.Create (make sure you quit and restart if you've made changes while the app is running)
  2. In a browser window"
    1. load the app
    2. open a developer console
    3. enter ncRegenerateDefaultTemplate()

This will generate a new _default.template.toml file in ./app-templates/_default.template.toml. You can then copy this to any new installs.

Template History

Template Version numbers are tied to version release numbers. e.g. references in the code to a 1.3 template refer to the Release v1.3.

Rough history of changes:

  • v1.0 JSON Template with static Node/Edge field definitions.
  • v1.3 TOML Template replaces JSON Template
  • v1.5 Custom Node/Edge field definitions are introduced.

v1.3 TOML Template Format

See #194

As of version 1.4 (March 2022), the new template format now uses TOML, not JSON. The [TOML](https://toml.io/en/) format is a much more human-friendly file format for settings.

The new template files have an extension of *.template.toml.

TOML files can be edited with any text editor. Visual Studio Code has an extension "Even Better TOML" that will provide syntax highlighting and linting for TOML files.

The old *.template JSON templates are no longer necessary, but you probably want to keep them as reference for converting old projects.

The old template format was much in need of a refresh, having gone through many evolutions and expanded its purpose over time. So in addition to the file format change, we also streamlined some of the configuration fields. This will require you to do some manual conversion of old template files.

Migrating from JSON to TOML

If you are trying to work with a circa v1.3 data set that uses the old JSON template format, here are a few tips:

1. Use Auto-Conversion

If you have a matching <projectname>.template JSON file, the app will automatically try to load the old template format and convert it to the new TOML format, saving the file as <projectname>.template.toml.

  • The app expects the <projectname>.template file to be in the same folder as the <projectname>.loki file, usually in build/runtime
  • The old *.template file will be left on the server so you might want to remove it once you've converted and confirmed that the new template works.
  • This isn't VERY well tested, so there may be some older template variants that will fail the conversion. Please make sure you review the converted file to make sure it makes sense.
  • After conversion, you can use the "Edit Current Template" tool to review and modify the template using the built-in json-editor.
2. Manual Migration

You can of course decide to update the template files by hand. I would recommend starting with the _default.template.toml file and copying over changes from the old template rather than starting from scratch. Here's a summary of the changes in the file format.

  • File format changed from JSON to TOML
  • Extension renamed from *.template to *.template.toml
  • General template and app settings have been moved to the top level so that nodeDefs (formerly nodePrompts) and edgeDefs (formerly edgePrompts) now only contain field definitions and not other settings:
    • duplicateWarning has been moved out of nodePrompts.label to the top level
    • sourceNodeIsLockedmessage has been renamed nodeIsLockedMessage and moved to the top level
    • edgeIsLockedMessage has been moved out of edgePrompts and moved to the top level
    • node defaultTransparency has been renamed nodeDefaultTransparency and moved out of nodePrompts.defaultTransparency to the top level
    • edge defaultTransparency has been renamed edgeDefaultTransparency and moved out of edgePrompts.defaultTransparency to the top level
    • citationPrompts has been renamed citation.
    • citationPrompts.citation has been renamed citation.text
  • nodePrompts are now nodeDefs
  • There are a number of new nodeDef fields:
    • id is now included in the template, mostly to provide a mapping for exportLabel, but also for parity across fields. It is a built-in field and managed by the system.
    • updated is another built-in field managed by the system. The parameters are used for graph tooltips and exportLabels.
    • created is another built-in field managed by the system. The parameters are used for graph tooltips and exportLabels.
  • For each regular nodeDef field:
    • type is now required and defaults to string
    • label is now displayLabel to distinguish it from export label.
    • exportLabel is a new field for setting the field name/header for exported csv files. e.g. use this to name the header ID rather than the Id displayed in the Node and Edge Tables.
    • help is the same
    • includeInGraphTooltip defaults to true if not defined
    • hidden is the same
  • edgePrompts are now edgeDefs
  • There is a new edgeDef field:
    • id is now included in the template, mostly to provide a mapping for exportLabel, but also for parity across fields. It is a built-in field and managed by the system.
  • Each regular edgeDef field now also inlcudes (same as nodeDef fields):
    • type is now required and defaults to string
    • label is now displayLabel to distinguish it from export label.
    • exportLabel is a new field for setting the field name/header for exported csv files. e.g. use this to name the header ID rather than the Id displayed in the Node and Edge Tables.
    • help is the same
    • hidden is the same
    • NOTE that edgeDef fields do not use the includeInGraphTooltip field.
  • For both nodeDef and edgeDef fields set to type = "select"(e.g. node type and edge type), the options definitions no longer require an id field. This was never really used and removing it simplifies the system.

[Old v1.3 (pre-2022) Template Documentation

PROJECT INFO

DESIGN

REFERENCE

Clone this wiki locally