Models Cross Referencing

About this page

This page discusses the model cross-referencing system added in PR #362. This system replaces the old system which lived entirely in the NetLogo project.

"Cross-Referencing" is displaying a single library model in two different locations in the models library hierarchy. For instance, the AIDS model is a Biology model, so it should appear under "Sample Models > Biology" but it can also be considered a social science model, so it should also appear under "Sample Models > Social Science". Of course, it's cumbersome to try to keep two copies of the model intact, so we maintain a single model and tell NetLogo to show the model in two different places. We do this through the crossReference.conf file.

crossReference.conf

crossReference.conf lives in the models project root. It is a file written in HOCON, a configuration file-format similar to JSON with more flexible syntax. NetLogo reads crossReference.conf to determine how models should be duplicated within the models library hierarchy. The general structure of this file consists of two keys: org.nlogo.models.crossReference.singleModels and org.nlogo.models.crossReference.directories. Both define a list of objects which specify (respectively) single files and directories. Under no circumstances should these keys be changed without corresponding changes in the NetLogo repository.

How to add a single-model cross-reference

To add a single model cross-reference, add a new line in the list defined under the key org.nlogo.models.crossReference.singleModels containing an object (objects start with {, end with } and have key/value pairs). Assuming I have a model at "Sample Models/Foo/Bar.nlogo" and want to reference it as though it were also located at "Code Examples/Bar.nlogo", I would add an entry that looks like the following:

  { source: "Sample Models/Foo/Bar.nlogo", referenceIn: "Code Examples" }

There are a few things to note here:

1. I provide the full path to the model relative to the mdoels library root (including .nlogo/.nlogo3d file extension) under the key source.
2. I provide the path to the directory which will contain the reference under the key referenceIn. Note that I do not provide a file name. Cross-references will always have the same name as their source.
3. While the directory given by referenceIn does exist within the models library in this example, it is not a requirement that this directory exist. If the directory does not exist, the models library will pretend as though it existed for purposes of displaying to the user.
4. This object has a line all to itself.

How to add a directory cross-reference

To add a directory cross-reference, add a new line in the list defined under the key org.nlogo.models.crossReference.directories containing an object (objects start with {, end with } and have key/value pairs). Assuming I have a directory at "Sample Models/Mathematics/Foo" and want to reference all models in it as though it were also located at "Curricular Models/Math", I would add an entry that looks like the following:

  { sourceDir: "Sample Models/Mathematics/Foo", referenceIn: "Curricular Models/Math", recursive: false }

A few things to note:

1. The path referenced by sourceDir must exist (relative to the root of the models project) and must be a directory.
2. I use referenceIn to provide the new path under which all models contained in sourceDir will be referenced. In this example, if Mathematics/Foo contained a model A.nlogo, I would see an entry in the models library for "Curricular Models > Math > A".
3. Just as with single models, there is no requirement that the directory referenced by referenceIn exists within the models library.
4. The key recursive must be present. recursive: false means that only the immediate children will be referenced (subdirectories will not be). recursive: true means that both immediate children and subdirectories will be referenced. Note that when recursive: true will create new directories within the reference directory for each subdirectory in the source directory. For instance, if there was a directory "Sample Models/Mathematics/Foo/Bar" and we had recursive: true, the models library would list entries in that directory under "Curricular Models > Math > Foo > Bar".
5. Directory cross-referencing does not support any kind of filtering or selective referencing (aside from the recursive option discussed under 4). If some models should be referenced but others should not be, use single-model cross-references.

Testing

The cross-references are tested in CrossReferencesTests.scala. This only verifies that the source and sourceDir keys exist and are files. The referenceIn keys are not verified, since they may correspond to paths which don't have directories in the models library.