The Settings API gives your plugin a settings screen. Your settings screen can include text fields, checkboxes, dropdowns and tables, and are translated into a JSON file your plugin can read.

The options on your settings screen are stored in anoptions.json file inside your plugin bundle. The actual values the user has chosen are written to thepreferences.json file. You can include a defaultpreferences.json file with your plugin to specify defaults.

For an example of a plugin with settings, see theSay Something with Settings example plugin.

If a plugin has anoptions.json file, users can find your settings screen by clicking theSettings button below your plugin's name on theInstalled screen in the Flashlight app.

If your plugin is completely useless before the user has changed their settings, you can ask Flashlight to open the settings screen when your plugin is first installed. Just add"openPreferencesOnInstall": true to your plugin'sinfo.json.

You can also add a link to the settings screen inside your plugin's webview. Just add a link that looks like this to your html:flashlight://plugin/<plugin name here>/preferences. (This also works outside Flashlight.)

It's probably easiest to look at an example:

{"options": [{"text": "Voice:","type": "dropdown","key": "voice","options": [{"text": "Victoria", "value": "victoria"},{"text": "Alex", "value": "alex"},{"text": "Albert", "value": "albert"},{"text": "Good News", "value": "good news"}]},{"text": "Greeting:","key": "greeting","type": "text"},{"text": "Password:","key": "password","type": "text","password": true},{"type": "hint","text": "The greeting is a bit of text that's always spoken before the rest of your message."},{"type": "checkmark","text": "Speak extra fast","key": "fast"},{"type": "divider"},{"type": "table","text": "Shortcuts:","key": "shortcuts","columns": [{"text": "Shortcut", "key": "shortcut"},{"text": "Full message", "key": "message"}]},{"type": "hint","text": "When you type the name of a shortcut, the full message will be spoken instead."},{"type": "divider"},{"type": "buttons","buttons": [{"text": "Learn about Flashlight", "url": "http://flashlight.nateparrott.com"}]}]}

Place this in your plugin's bundle, and Flashlight will render a settings screen that looks like this:

preferences.json is a dictionary that, for each option inoptions.json, maps itskey property to the control's value. Again, let's look at an example: apreferences.json file that goes with theoptions above:

{  "voice" : "victoria",  "fast" : 1,  "shortcuts" : [    {      "message" : "five, four, three, two, one, zero!",      "shortcut" : "countdown"    }  ],  "greeting" : "hello!"}

You can (and should!) ship apreferences.json file containing your plugin'sdefault preferences.

Sincepreferences.json is inside your plugin bundle, it's straightforward to read:

import jsonsettings = json.load(open('preferences.json'))