Name Generator: Roster List

Purpose

Provides a way to easily add nodes from an existing roster list when the list is small enough to browse.

Behaviors

Adding Nodes

All possible nodes are visible. Nodes are added to the network by clicking on them, toggling their selected state.

Deleting Nodes

Nodes are deleted from this interface by clicking on them again, toggling their selected state off.

Sorting Nodes

Nodes can be sorted in ascending or descending order, according to the fields specified in options, by toggling the sort buttons.

Filtering

Visible nodes can be filtered to more easily get to a node by typing in the text field.

Protocol

This section describes parts of the protocol specific to the Roster List interface. The protocol (and specifically a stage prompt) shares some of the basic attributes with the standard Name Generator, which are not discussed again here.

For a more complete example, see a demo protocol.

External Data

The data to drive search results can be provided within the "externalData" object of the protocol. That data can then be referenced in the "dataSource" property of an interview prompt. External data items must define a "type" that refers to an entry in the "node" definition of the variable registry.

In this snippet of an example protocol file, we have included a "NameGeneratorList" stage with one prompt that references the "schoolPupils" data source. Each school pupil is a "person" (i.e., variableRegistry.node.person).

{
  "name": "Demo Protocol",
  "externalData": {
    "schoolPupils": {
      "nodes": [
        {
          "type": "person",
          "name": "F. Anita",
          "nickname": "Annie",
          "age": "23"
        },
        {
          "type": "person",
          "name": "H. Barry",
          "nickname": "Baz",
          "age": "31"
        }
      ]
    }
  },
  "stages": [
    {
      "type": "NameGeneratorList",
      "prompts": [
        {
          "id": "7cl1",
          "text": "Which classmates would you also think of as friends?",
          "dataSource": "schoolPupils"
        }
      ]
    }
  ]
}

Sorting and Display Options

To change the behavior of sorting, use values in "sortOptions":

• sortOrder: which attribute to sort by initially; can be sorted in "ASC" (ascending) or "DESC" (descending) order.
• sortProperties: a list of attributes in the data set that can be sorted on.

To change the display of nodes on an interface, use the "cardOptions" object:

• displayLabel: the primary label to display on the node
• additionalProperties: an array of objects that define supplemental information to display on a search result.

Example:

{
  "showExistingNodes": true,
  "prompts": [
    {
      "id": "7cl1",
      "text": "Which classmates would you also think of as friends?",
      "additionalAttributes": {
        "close_friend": true
      },
      "dataSource": "schoolPupils",
      "cardOptions": {
        "displayLabel": "nickname",
        "additionalProperties": [
          {
            "label": "Name",
            "variable": "name"
          },
          {
            "label": "Age",
            "variable": "age"
          }
        ]
      },
      "sortOptions": {
        // sortOrder function accepts array of properties, but here we allow a max of 1
        "sortOrder": [{
          "property": "c5fee926-855d-4419-b5bb-54e89010cea6",
          "direction": "desc"
         }],
        "sortableProperties": [
          {
            "label": "Pupil Name",
            "variable": "name"
          },
          {
            "label": "Pupil Age",
            "variable": "age"
          }
        ]
      },
      "subject": {
        "entity": "node",
        "type": "person"
      }
    }
  ]
}

Interface-Specific API

This interface builds on the Name Generator Interface API.

In addition to the stage properties specified in the name generator API, this interface defines the following parameters within a stage:

Property	Possible Values	Purpose
showExistingNodes Optional	true or false	If set to true, each prompt will display cards for nodes selected from other prompts in this stage. Otherwise, already-selected cards will not appear on a prompt.

In addition to all prompt properties specified in the name generator API, this interface defines the following parameters within a prompt:

Property	Possible Values	Purpose
dataSource Required	A key in the "externalData" registry.	This key identifies a data source to be searched and, subsequently, from which to create nodes
cardOptions Required	An object containing the following structures
cardOptions.displayLabel Required	A field key that exists in the data (identified by dataSource)	This parameter defines the main display lable for nodes and search results in the interface
cardOptions.additionalProperties Optional Default: []	Array consisting of zero or more objects, each with a "label" and "variable" key that refer to a type (identified by dataSource) in the variable registry.	This defines additional labels and values to display on a node (e.g., to disambiguate between nodes sharing the same displayLabel)
sortOptions Optional Default: {}	An object containing the following structures
sortOptions.sortOrder Optional Default:cardOptions.displayLabel in descending order	object with a key that refers to a type defined in the external data and a value of "ASC" or "DESC"	Defines initial sort field and direction
sortOptions.sortableProperties Optional Default: []	Array consisting of zero or more objects, each with a "label" and "variable" key that refer to a field (identified by dataSource) in the data.	This defines which fields are sortable. Contrast this with fields that should be displayed (additionalProperties, above).

See examples above.