Template Technical Documentation

Template Technical Documentation

• Template Validation
• Where Template-Related Items are Defined

Template Validation

Template validation is used to ensure that the template only contains fields and parameters that have been properly specified. This is especially important for hand-editted templates. If you need to support template definitions that cannot be validated, you can turn off validation for the server [NOT RECOMMENDED!!!].

How template validation works

By default template files are validated whenever you start the server with ./nc.js --dataset=<projectname>

Any errors will be reported in the console.

You can use a validation script, nc-validate.js to assess a template file and fix.

Validating a Template File

If you encounter an error, run the nc-validate.js script to generate a report of the errors.

​ ./nc-validate.js <projectname> -vv

e.g. ./nc-validate.js tacitus -vv

Review the errors and edit the <projectname>.template.toml file to fix the error. Re-run the validator until the errors are cleared. Then restart the server.

The default template can be validated by calling nc-validate.js without a template, e.g.

./nc-validate.js -vv

Disabling Validation

If you are hand-editing a template file (or using an ancient version of a template file), at some point you might find there are too many validation errors to fix easily. You can disable validation if that happens.

Note

Disabling validation will disable validation for all graphs on the server.

1. Edit server-database.js
2. Change the line const USE_VALIDATOR = true; to const USE_VALIDATOR = false; (around line 14)
3. Quit (if necessary) and restart the server

Where Template-Related Items are Defined

There are multiple levels of template definitions:

1. server-template-schema.js defines template fields for validation
2. _default.template.toml section on [_ui.*] defines the fields that can be set in the Settings Panel for newly created projects
3. <yourproject>.template.toml section on [_ui.*] defines the fields that can be set in the Settings Panel for your current project
4. <yourproject>.template.toml section on [nodeDefs] and [edgeDefs] defines the fields that actually used in your current project
5. Settings Panel can rename and show/hide fields that are used in your current project

Permissions	Developers	Researchers	Teachers
server-template-schema.js	recommended	-	-
_default.template.toml	recommended	ok	-
<yourproject>.template.toml section on [_ui.*]	ok	ok	-
<yourproject>.template.toml section on [nodeDef/edgeDef]	ok	recommended	-
Settings Panel	ok	ok	recommended

• "recommended" -- where this user SHOULD make the change
• "ok" -- you can do this, but it's probably not best practice, do it with caution
• "-" -- don't do it!

Generally speaking,

• "developers" should define the validated server-template-schema.js and starting default templates. Define a base set of fields that everyone will rename and show/hide.
• "researchers" should be able to just use default values. Only edit values if you need to tweak an existing project. If the default template is not providing the right settings, or if we need to establish a few different defaults, then we should revisit this.
• "teachers" should only ever turn things on and off in the Settings Panel.