Closed benloh closed 2 years ago
@kalanicraig @jdanish I think the template editing is in a stable enough state for you to give it a whirl. It's definitely still rough around the edges. Please make sure you read the CAVEATS section. But let me know if this is what you had in mind.
In the mean time, I will turn towards figuring out how to handle changes to the options (e.g. combining or spiltting) and fix the edge cases.
Awesome, thanks. Confirming we have seen this and have begun tinkering. Looks awesome.
@kalanicraig @jdanish Template editing is now disabled when editing a node or edge. And node or edge editing is now disabled when editing a template. Please pull the latest to test.
I believe this covers most of the situations. Please let me know if I missed one.
@kalanicraig @jdanish Just FYI there's a known bug in the JSON-to-TOML migration where "type" fields with options (e.g. node type, or edge type) are inadvertently converted to "strings", so the popup menu does not display in the Filters. This is fixed in da520dc1177c40b56995fc49745ce9be9f15a767 in the dev-bl/flatten
branch
?
Node/edge table listings and node labels in graph are greyed out
This is probably a result of default transparency migration problem that Joshua and I were discussing here: https://github.com/netcreateorg/netcreate-2018/pull/198#issuecomment-1024474072
If you change the nodeDefaultTransparency to 1.0 I think this problem should be fixed for now.
But popping up a level, we do need to revisit the use of transparency. I'll create a new issue for that: #199
Is "template name" a no-space name sort of thing? Needs guidance/example akin to Template Description
This can be anything and use spaces. It is only what is displayed on-screen.
The file name is currently determined by the dataset file that you load.
I'm guessing that the two of you will want to tweak some of the defaults and descriptions. Currently these are all set in template-logic.js
. I'll pull out the schema so it can be easier to edit in isolation.
How does delete behavior work? Form suggests that "hideDeleteNodeButton" will hide for all non-admins and hide for regular users but it seems like it just hides/shows for anyone with an access token. The dropdown should probably be "No Delete/Admin Delete/All Users Delete" or similar.
This should be a checkbox. A lot of little details like this to be set in the schema.
The current delete behavior should be this:
http://localhost
you can deletehttp://127.0.0.1
you can deletehttp:/<url>?admin=true
you can deleteSo unless you were accessing the server on another computer AND did not have ?admin=true
, the delete button should not have shown. If that's not the case, then something is broken.
Are you saying that you would like to enable deletion for people other than admins?
On template edit of any kind: if there are no edge colors selected, edges defaults to black. All edges should default to gray.
This might need to get resolved with #199. Currently edges default to black, but the default transparency of 0.5 lightens the line. But all of this needs to get coordinated with the transparency settings in #199. I'll try to change the default.
New template does not auto-create an "unselected" node and edge type. Is this an expected behavior
I'm fixing this right now. See https://github.com/netcreateorg/netcreate-2018/pull/198#issuecomment-1024362990
Issue: Node/Edge vs Template Edit disabling does not work over the network.
Node/Template disabling fixes are in #200. OK to merge.
Branch:
dev-bl/toml
New Features:
To Test
We've added a few node libraries, so you'll need to run
npm ci
.git fetch; checkout dev-bl/toml
npm ci
npm run dev
to load your last used database, or./nc.js --dataset=projectname
to load a specific database.Because the system now uses a new template file, you should see this message in your terminal:
Your dataset should load, converting your old JSON template to a new TOML templamte format. You might find that your colors, node types, and edge types have changed. We'll fix all of this later.
First, let's just test the new template features:
You have 6 template tools you can use. Try each one. Refer to the documentation below starting at "WIKI DOCUMENTATION" (this will be copied over to the wiki).
Test Admin Access
http://192.168.1.1:3000
.?admin=true
to the url, e.g.http://192.168.1.1:3000?admin=true
http://localhost
,http://127.0.0.1
, or using?admin=true
.Other things to test:
displayName
and make sure the tables reflect the new display name.CAVEATS / Known Problems
Editing the template while a Node or Edge is being edited will result in js errors.Fixed as of 1/26/22.exportLabel
values. We will tackle this later.displayLabel
andexportLabel
. Other parameters are hidden.label
andcolor
will affect the graph display as soon as you save the template. Changing an existinglabel
will cause some issues: a) any node/edge that uses the removed label type will still retain the original label, but that label will not be displayed in the Node Editor menu -- it will still be displayed in the Node Table, b) you need to manually select each node/edge and change its type to the new label. This is probably something we want to discuss/revisit -- do we need to add migration/conversion tools so that you can combine two into one for instance?type
(e.g.string
,number
,boolean
,select
) should be done with care. Since existing datasets are not converted, you may end up with errors. Also theselect
type would expectoptions
to be defined.help
should be immediately reflected in the system.WIKI DOCUMENTATION
New Template Format
As of version 1.4 (this version), the new template format now uses TOML, not JSON. The TOML 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.
Editing Templates
IMPORTANT:
http://localhost
,http://127.0.0.1
, or using?admin=true
.*.template.toml
files that are saved on the server.To edit a template:
You can edit the current template in a variety of ways.
"Edit Node Types" / "Edit Edge Types"
Click on the "Edit Node Types" button to edit the node types defined in the current template. Click on the "Edit Edge Types" button to edit the edge types defined in the current template.
"Edit Node Types" and "Edit Edge Types" allows you to quickly edit just the node type or edge type instead of having to edit the whole current template (that's what "Edit Current Template" does). The basic functionality is the same as "Edit Current Template".
You can set:
label
of the node/edge type -- This is what is displayed in the Node Editor.color
of the node/edge typeWhen you are happy with the changes, click "Save". The template will be updated, the graph redrawn, and the changes written to the current template file on the server.
What happens when you change the
label
? Thelabel
field determines what is displayed in the popup menu for Type in the Node Editor or Edge Editor. If you change an existinglabel
:label
will appear in the Node Editor / Edge Editor type menu in place of the old label.label
is not converted. So if you open any existing node / edge that uses the oldlabel
in a Node Editor or Edge Editor, it will open with ablank
type (since the old selection is no longer available for populating the menu). The node / edge will still the original label information (which you can see if you look at the label in the Node or Edge Table). You need to manually select and edit the Node and reselect the new label type to change the type.New "color" setting for Edge Types
"Edit Current Template"
Clicking "Edit Current Template" will open the current template in the json-editor. You can then change any value in the template, and hit "Save" to save the changes.
IMPORTANT:
Missing Properties: Use "Object Properties"
The json-editor only displays properties that have been defined in the
*.template.toml
file. In some cases, if for instance you've imported/converted a JSON file or created a new TOML template file from scratch, you may find that you had inadvertently ommitted a property that you would like to change. These properties will not be available in the editor for modification.In these cases, you CAN actually add the property by clicking on the "Object Properties" button next to the header section. For instance, if you find yourself wanting to set the
searchColor
but it was not included in the current template, and is therefore not visible, you would:This should only allow you to add properties that have been previously defined in the schema.
"Download Current Template"
Clicking "Download Current Template" will allow you to download the currently loaded template to a file on your local hard disk via your browser. The file will have the same name as the template file on the server.
The downloaded file is in TOML format.
You can use this to save backups or as a starting point for defining new templates.
"New Template"
Clicking "New Template" will replace the currently loaded template with a new blank template cloned from the
_default.template.toml
file inbuild/app/assets/templates/_default.template.toml
. If you save the file it will be saved with the name of the current dataset. E.g. if you hadtacitus.json
open, and clicked "New Template" then saved the changes, you would now have atacitus.template.toml
file.The main use model here is if you are creating a new dataset, try some changes, and decide you don't like them and want to start fresh with a new template, you can do so without quitting and restarting the app and deleting the old template file.
"Import Template"
Click "Choose File" and then select a
*.template.toml
file to replace the current template file with a new TOML template file.After you import the template, the editor will be shown. Review it to make sure it's what you want. Make any changes. Then click "Save" to save the template to the server and reload the dataset with the new template.
NOTE: If you don't click "Save", the imported template will not be applied to the current dataset. You can just click "Cancel" to leave your original template as-is.
This is probably the easiest way to create a new dataset and clone the template from another dataset without restarting the server.
"Save" / "Cancel" Buttons
All of the template editors will show a "Cancel" and "Save" buttons once you've started editing.
Saves will overwrite the exisitng
<projectname>.template.toml
file. The previous version will be saved with a timestamp, so it should be relatively easy to revert if you need to. But we'll need to keep an eye on accumulating versions and perhaps figure out a solution for this.SCHEMA
JSON-Editor requires a JSON schema definition in order to properly render the template for editing. The schema is defined in
build/app/view/netcreate/template-logic.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.duplicateWarning
-- Warning message to display if user is trying to create a node that already existsnodeIsLockedMessage
-- Warning message to display if user is trying to edit a node that someone is already editingedgeIsLockedMessage
-- Warning message to display if user is trying to edit a edge that someone is already editingnodeDefaultTransparency
-- Default transparency for nodes. You usually want this set to1.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.Fields
The data fields for each node and edge are defined in
nodeDefs
andedgeDefs
.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 adisplayLabel
ofId
, but export it asID
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.The
select
type requiresoptions
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 typecolor
-- 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 onlytarget
-- edge onlycreated
updated
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
.<projectname>.template
file to be in the same folder as the<projectname>.loki
file, usually inbuild/runtime
*.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.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.JSON
toTOML
*.template
to*.template.toml
nodeDefs
(formerlynodePrompts
) andedgeDefs
(formerlyedgePrompts
) now only contain field definitions and not other settings:duplicateWarning
has been moved out ofnodePrompts.label
to the top levelsourceNodeIsLockedmessage
has been renamednodeIsLockedMessage
and moved to the top leveledgeIsLockedMessage
has been moved out ofedgePrompts
and moved to the top leveldefaultTransparency
has been renamednodeDefaultTransparency
and moved out ofnodePrompts.defaultTransparency
to the top leveldefaultTransparency
has been renamededgeDefaultTransparency
and moved out ofedgePrompts.defaultTransparency
to the top levelcitationPrompts
has been renamedcitation
.citationPrompts.citation
has been renamedcitation.text
nodePrompts
are nownodeDefs
nodeDef
fields:id
is now included in the template, mostly to provide a mapping forexportLabel
, 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.nodeDef
field:type
is now required and defaults tostring
label
is nowdisplayLabel
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 headerID
rather than theId
displayed in the Node and Edge Tables.help
is the sameincludeInGraphTooltip
defaults to true if not definedhidden
is the sameedgePrompts
are nowedgeDefs
edgeDef
field:id
is now included in the template, mostly to provide a mapping forexportLabel
, but also for parity across fields. It is a built-in field and managed by the system.edgeDef
field now also inlcudes (same asnodeDef
fields):type
is now required and defaults tostring
label
is nowdisplayLabel
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 headerID
rather than theId
displayed in the Node and Edge Tables.help
is the samehidden
is the sameedgeDef
fields do not use theincludeInGraphTooltip
field.nodeDef
andedgeDef
fields set totype = "select"
(e.g. node type and edge type), theoptions
definitions no longer require anid
field. This was never really used and removing it simplifies the system.