Skip to content

Name Generator

Bryan Fox edited this page Nov 16, 2018 · 18 revisions

Purpose

The primary interface for creating nodes in the interview.

Behaviors

Creating Nodes

Nodes are created using the add new node button in the bottom right hand corner of the interface. This button triggers the new node form. By default, the form of the same name as the node type is used, although this can be overridden by the user.

Deleting Nodes

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

Side Panels

Side panels are designed to let this interface display other nodes in containers that visually separate them from the main node list. A user may drag & drop nodes from a side panel into the interface's main area.

Each panel can get its node data from the existing interview, or from external data embedded into the protocol. The "dataSource" property (see below) is required for either scenario.

Additionally, custom panel configurations can be created, that allow the interview designer to filter the nodes shown in the panel by attribute.

Panel Configuration

"panels": [
  {
    "id": "1", // unique within this collection
    "title": "My Network",
    "dataSource": "existing", // Keyword used to reference current interview network
    "filter": {} // An optional filter configuration (see https://github.com/codaco/Network-Canvas/wiki/Network-Query-Builder)
  },
  {
    "id": "2",
    "title": "My Panel Title",
    "dataSource": "locations" // A data source embedded in the protocol file at { externalData: { locations: {} } }
  }
],

Prompts

Strings of text representing a question to the participant, including bold and emphasis markdown support.

const prompts = [
  {
    id: '6cl',
    text: 'Within the past 6 months, who have you felt _particularly_ close to, or discussed important personal matters with?',
    additionalAttributes: {
      special_category: 46,
      close_friend: true,
    },
  },
  {
    id: '6su',
    text: "Within the past 6 months, who has been supportive?",
    additionalAttributes: {
      support_friend: true,
    },
  },
  {
    id: '2we',
    text: "Within the past 2 weeks, who has provided advice?",
    additionalAttributes: {
      advice_friend: true,
    },
  },
];

General Interface API

See General Interface API.

Interface Specific API

In addition to all properties specified in the general interface API, this interface has the following parameters:

Property Possible Values Purpose
subject
Required
An object with entity and type keys, which refer to an entry in the variable registry.

type must equal "node" or "edge" (though no interface yet supports the latter).

entity must be a string matching a node or edge key in the variableRegistry (e.g., see NODE_TYPE_ID).
This object corresponds to a type in the variable registry, and determines which type of node this interface should create.
form
Optional

Default: none
A string matching a key in the protocol's forms object.

If not set, or if no form with that key exists, the interface will not present a form to the user.
This parameter tells Network Canvas which form should be used when creating or editing a node on this interface.
panels
Optional

Default: []
Array consisting of a maximum of two objects. Each supplied object must contain a dataSource property, and may also contain the properties title, and filter. (See "Side Panels" above). This property changes the visibility and behavior of side panels on the Name Generator interface.

An object with dataSource equal to 'existing' allows us to present nodes already created elsewhere in the interview that can potentially be assigned the custom variables associated with the current name generator and prompt.

Any other dataSource property creates a panel that contains nodes from an external data source in the data object of the protocol (identified by that value).
prompts
Required

Default: none
An array of one or more prompt objects (see prompts section above for details) This defines a list of questions (or tasks) for the respondent to complete on this interface. The user may wish to ask one question per interface (therefore providing only one prompt), or ask several questions on a similar theme.

Each prompt also specifies any variables that are to be added to any nodes that are created.

Prompts

In addition to the general prompt properties, the following properties are available:

  • "additionalAttributes": a dictionary-like object which specifies default values to be added to nodes upon creation, if not specified by the user

Example usage

const nameGenerator = {
  "id": "namegen1",
  "type": "NameGenerator",
  "label": "NG Closeness",
  "form": "myCustomForm",
  "subject": {
    "entity": "node",
    "type": "person"
  },
  "panels": [
    {
      title: 'My Network',
      dataSource: 'existing'
    },
    {
      title: 'Some locations',
      dataSource: 'locations'
    }
  ],
  "prompts": [
    {
      "id": "6cl",
      "text": "Within the past 6 months, who have you felt particularly close to, or discussed important personal matters with?",
      "additionalAttributes": {
        "special_category": 46,
        "close_friend": true
      }
    },
    {
      "id": "6su",
      "text": "Within the past 6 months, who has been supportive?",
      "additionalAttributes": {
        "support_friend": true
      }
    },
    {
      "id": "2we",
      "text": "Within the past 2 weeks, who has provided advice?",
      "additionalAttributes": {
        "advice_friend": true
      }
    }
  ]
},