Using Templates 2020

This is outdated documentation from version 1.3 circa 2020. See Using Templates for current documentation.

Using Templates (v1.3)

(User-Guide -- the "Using Templates" section should be removed from User Guide and linked here)

[This should be rewritten for developers, advanced users, and novice users]

Use the template to set:

• The name of the database to be displayed in the (?) popup
• A short description of the database to be displayed in the (?) popup
• Whether a user needs to login to view the graph. To hide the graph until the user is logged in, set requireLogin to true. If requireLogin is missing or false (default), then the graph is always visible. IMPORTANT: In JSON, "false" with quotes evaluates to true. So the entry should be:

"requireLogin": true   // NOTE no quotes around 'true'

or

"requireLogin": false  // NOTE no quotes around 'false'

You can define 8 aspects of the node and edge forms:

1. The form field label, e.g. "Notes" or "Signifcance"
2. The type options for both nodes and edges, e.g. "Person", 'Group", etc.
3. The color of the node type, e.g. red for "Person"
4. Whether the field should be shown or hidden on both the Node Panel and the Node Table and Edge Table views.
5. The order of the options fields are defined by the order they appear in the template.
6. The duplicate node warning message "You’re entering a duplicate node. Do you want to View the Existing node, or Continue creating?"
7. The source node is locked warning message "This node is currently being edited by someone else, please try again later."
8. The edge is locked warning message "This edge is currently being edited by someone else, please try again later."

Default Template

New projects are started using the default template. You can modify the default template at build/app/assets/templates/_default.toml.template. Be sure to commit any modifications you want to make permanent.

When starting a project, if a template is missing, the system will load the default template. e.g. if staring tacitus.json and there is no tacitus.template.toml file, it will load _default.toml.template.

Labels

Set the label parameter of the field to define custom labels for the form. (Note the node field label itself has a label field).

e.g.

    "label": {
                "label":    "Node Title",
                "help":     "A short title for the node",
                "_cmt4":    "/// `Label` is always required and cannot be hidden"
             },

Node/Edge Types

Node type options and Edge type options are defined as an array. Each type can have as many options as you want.

Node types have an additional color parameter that will be used to set the color of the node circle on the graph.

Colors are defined as hex: #AABBCC

Note there is a default option with an id of "" to catch node types that have not been defined. These will be displayed as light gray.

Options can only be defined for node type and edge type fields. They will be ignored on other fields.

e.g.

    "type":  {
                "label":    "Type",
                "help":     "Multiple people are a 'Group'",
                "hidden":   false,
                "options": [
                  {
                    "_comment": "Default color when nothing is selected",
                    "id":       "",
                    "label":    "",
                    "color":    "#EEEEEE"
                  },
                  {
                    "id":    "person",
                    "label": "Person",
                    "color": "#66CCFF"
                  },
                  ...
                ]
              }

Hiding Fields

Set the hidden parameter of the field to true to hide the form element. The default is false.

e.g. this will hide the "info" field:

    "info":     {
                  "label": "Approximate Date of Interaction",
                  "help":  "",
                  "hidden": true
                },

Update

The "Update" definition in the template does not actually create a new field. It is a hack that is only used to show or hide the tooltip in the graph. The actual data is read from node.meta.updated, which is automatically generated by the system.

As such, only the following parameters are valid:

• displayLabel
• includeInGraphTooltip

All other parameters are ignored.

Tips

• If you edit the template, always check the web console as you load the app to make sure there aren't any errors. The system should report errors in the template.

• To load an edited template, you need to restart the app.

• Locked Out -- If you are inadvertently locked out of editing templates (e.g. someone was in the middle of editing a template when they lost their connection), you can either: a). Reload the server (use the terminal to quit and restart NetCreate), or b). Use the ncUnlockAll() command in the web console to reset the template locking. You'll need to reload the page after running this. USE CAUTION when doing this as you may inadvertently interrupt someone legitimately editing the template.