Name Generator: Roster Search with Autocomplete

Purpose

Provides a way to easily add nodes from an existing roster list which is too large to browse directly.

Behaviors

Adding Nodes

The button in the bottom right hand corner of the interface opens a search panel. Within the search panel, a user should type one or more characters to find relevant results from external data. Search results are displayed as cards in a single-column list.

Nodes are added in batches of one or more by tapping on search result cards and then tapping the "Add" button, which displays a count of the number of selected nodes.

Deleting Nodes

Nodes are deleted from this interface by dragging them into the bin in the bottom left corner.

Searching

Search results are updated in the list as a user types. By default, search results show after typing a single character and do not require an exact match. Configuration options for search are described in Prompts below.

Protocol

This section describes parts of the protocol specific to the Autocomplete 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 "NameGeneratorAutoComplete" stage with one prompt that references the "schoolPupils" data source. Each school pupil is a "person" (i.e., variableRegistry.node.person).

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

Search and Display Options

To change the behavior of searching, use values in the "searchOptions" array:

• fuzziness: how closely to match a result based on user input. 0 requires an exact match; 1 will match anything.
• matchProperties: which attributes of the data set to consider when searching

Note that for 'fuzzy' (inexact) searching, the appropriate fuzziness value will depend to some degree on the data set. A value of 0.4-0.5 is a good starting point.

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:

{
  "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"
          }
        ]
      },
      "searchOptions": {
        "fuzziness": 0.4,
        "matchProperties": ["nickname", "name"]
      },
      "subject": {
        "entity": "node",
        "type": "person"
      }
    }
  ]
}

Interface-Specific API

This interface builds on the Name Generator Interface API. That interface describes the prompts property.

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 name 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 search result (e.g., to disambiguate between nodes sharing the same displayLabel)
searchOptions Optional Default: {}	An object containing the following structures
searchOptions.fuzziness Optional Default:0.5	Number in the range [0, 1] (inclusive)	Defines how exactly search results should match user input. A higher number is less exact (i.e., is "fuzzier")
searchOptions.matchProperties Optional Default: []	Array consisting of zero or more strings. Each value must refer to a key in the appropriate type defined in the variable registry.	This defines which fields should be searched. Contrast this with fields that should be displayed (additionalProperties, above).

See examples above.