Settings

Creating Settings

Defining the json provided by the "settings url" can be complicated! (or it seems so to me at least). But lets break it down using the settings from our own twitter app as an example. If this document falls out of date, the latest settings for the twitter app can be found at: http://furious-ice-1158.herokuapp.com/settings.json

{
  "config_options": {
    "content": [
      {
        "repeats": false,
        "fields": [
          {
            "field_name": "Timeline Source",
            "key": "source",
            "field_type": "String",
            "required": true,
            "default_value": "nowspots"
          },
          {
            "field_name": "Timeline Source Type",
            "key": "source_type",
            "field_type": "Drop-down",
            "possible_values": [
              {
                "name": "Username",
                "value": "username",
                "fields_to_hide": []
              },
              {
                "name": "Search term",
                "value": "search",
                "fields_to_hide": [
                  "include_retweets",
                  "exclude_replies",
                  "filter",
                  "badge_location",
                  "headline"
                ]
              }
            ],
            "required": true,
            "default_value": "username"
          },
          {
            "field_name": "Include native retweets?",
            "key": "include_retweets",
            "field_type": "Boolean",
            "required": false,
            "default_value": false
          },
          {
            "field_name": "Exclude @ replies?",
            "key": "exclude_replies",
            "field_type": "Boolean",
            "required": false,
            "default_value": false
          },
          {
            "field_name": "Filter by word or hashtag",
            "key": "filter",
            "field_type": "String",
            "required": false,
            "default_value": ""
          }
        ]
      }
    ],
    "settings": [
      {
        "repeats": false,
        "fields": [
          {
            "field_name": "Destination Url",
            "key": "destination_url",
            "field_type": "String",
            "required": false,
            "default_value": ""
          },
          {
            "field_name": "Badge Headline",
            "key": "headline",
            "field_type": "String",
            "required": false,
            "default_value": ""
          },
          {
            "field_name": "Badge Location",
            "key": "badge_location",
            "field_type": "Drop-down",
            "possible_values": [
              {
                "name": "Bottom",
                "value": "bottom",
                "fields_to_hide": []
              },
              {
                "name": "Top",
                "value": "top",
                "fields_to_hide": []
              },
              {
                "name": "Hidden",
                "value": "none",
                "fields_to_hide": [
                  "headline"
                ]
              }
            ],
            "required": false,
            "default_value": "bottom"
          }
        ]
      }
    ],
    "style": [
      {
        "repeats": false,
        "fields": [
          {
            "field_name": "Post Background Color",
            "key": "post_background_color",
            "field_type": "Color",
            "required": false,
            "default_value": "ffffff"
          },
          {
            "field_name": "Divider Color",
            "key": "divider_color",
            "field_type": "Color",
            "required": false,
            "default_value": "bbbbbb"
          },
          {
            "field_name": "Text Color",
            "key": "text_color",
            "field_type": "Color",
            "required": false,
            "default_value": "000000"
          },
          {
            "field_name": "Link Color",
            "key": "link_color",
            "field_type": "Color",
            "required": false,
            "default_value": "3d627d"
          }
        ]
      }
    ]
  }
}

There's a lot here, but it's manageable.

First note that for each setting that you'd like included in the query string there's a corresponding field. These fields are organized into groups depending on which tab they'll be displayed on in the nowspots.com spot composer. The tabs are not currently dynamic and the field must match one of these three values:

content 
settings
sytle

In addition, each of the above field groups is an array of unnamed field groups. This allows for additional flexibility detailed below.

Next lets note that each field is generally comprised of five different values:

field_name
key
field_type
required
default_value

field_name is the text used to label the field in the composer.
key is the operational identifier used in the query string.
field_type is the form input type used in the composer. possible values are: Color, Boolean, Drop-down, String.
required will prevent the user from saving and give an error message if the required is true and the field is empty.
default_value defaults the input field in the composer to the given value.

If your field has a field_type of "Drop-down" then you need to define another value for the field possible_values

"possible_values": [
          {
            "name": "Bottom",
            "value": "bottom",
            "fields_to_hide": []
          },
          {
            "name": "Top",
            "value": "top",
            "fields_to_hide": []
          },
          {
            "name": "Hidden",
            "value": "none",
            "fields_to_hide": [
              "headline"
            ]
          }
        ],

Each value has a name (for display), value (the value to passed to the app via the query string) and fields_to_hide, which is included so that you can display form elements in the composer based on the value selected. The values in fields_to_hide must match the key of the fields you'd like to hide.

The last thing to note is that each unnamed field group has a boolean value with the key repeats. By setting this to true, the composer will allow the user to add multiple items defined by that field group. If the app I was creating displayed a list of names in different colors, I could allow the user to define the names in the composer with the below json fragment:

{
  "repeats": true
  "fields": [
      {
        "field_name": "Name",
        "key": "names[]",
        "field_type": "String",
        "required": true,
        "default_value": ""
      },
        {
        "field_name": "Name Color",
        "key": "name_colors[]",
        "field_type": "Color",
        "required": true,
        "default_value": "#cecece"
      },
  ]
}

Which would produce a query string fragment that looked like this:

names[]=John&names[]=Erica&names[]=Jimmy&name_colors[]=#0000bb&name_colors[]=#bb0000&name_colors[]=#00bb00