Lesson 2: Settings people can change

Give your script settings, step by step. Numbers with limits, a switch, a colour, the price it reads, a list of choices, and groups.

Lesson 2 of 18. A setting lets you, or anyone who uses the script, change it from the settings panel without opening the code. In the language a setting is an input. In this lesson you add settings to a small channel indicator one step at a time.

A number with limits#

Cuprel

indicator "Channel"
    edition = 1
    display = price

input length: int = 20, name = "Length", min = 2, max = 500
input width: float = 1.5, name = "Width", min = 0.1, step = 0.1
let middle = tech.sma(close, length)
let band = width * tech.atr(length)
plot(middle + band, name = "Upper", color = color.blue)
plot(middle - band, name = "Lower", color = color.blue)
plot(middle, name = "Middle", color = color.gray)

input length: int = 20 declares a setting called length. int is a whole number; float is a number with decimals.
name = "Length" is the label in the settings panel.
min and max are the smallest and largest value the panel accepts. step is how much the arrows in the field add or take away.
Inside the script length and width are plain numbers. When you change a setting, the script runs again from the first bar with the new value.

tech.atr(length) is the average true range, the usual size of a bar. The channel is the average plus and minus width times that size.

A switch, a colour and the price it reads#

Cuprel

indicator "Channel"
    edition = 1
    display = price

input src: source = close, name = "Source"
input length: int = 20, name = "Length", min = 2, max = 500
input width: float = 1.5, name = "Width", min = 0.1, step = 0.1
input show_middle: bool = true, name = "Show the middle line"
input band_color: color = color.blue, name = "Band colour"
let middle = tech.sma(src, length)
let band = width * tech.atr(length)
plot(middle + band, name = "Upper", color = band_color)
plot(middle - band, name = "Lower", color = band_color)
plot(if show_middle then middle else na, name = "Middle", color = color.gray)

A source input lets the member choose which price the average reads: close, open, high, low, hl2 (the middle of the bar) and the others listed in Inputs.
A bool input is a switch, true or false. if show_middle then middle else na draws the middle line only while the switch is on: na means "no value", and a plot draws nothing where its value is na.
A color input opens a colour picker.

A list of choices#

Cuprel

indicator "Channel"
    edition = 1
    display = price

input kind: text = "SMA", name = "Average", options = ["SMA", "EMA"]
input length: int = 20, name = "Length", min = 2, max = 500
input width: float = 1.5, name = "Width", min = 0.1, step = 0.1
let sma = tech.sma(close, length)
let ema = tech.ema(close, length)
let middle = if kind == "SMA" then sma else ema
let band = width * tech.atr(length)
plot(middle + band, name = "Upper", color = color.blue)
plot(middle - band, name = "Lower", color = color.blue)
plot(middle, name = "Middle", color = color.gray)

options = [...] turns a setting into a dropdown. The default must be one of the choices. Both averages are worked out on every bar and the dropdown only chooses which one is drawn: a function such as tech.ema keeps its own memory from bar to bar, so it is written on a line of its own, not inside the if.

Groups and tooltips#

Cuprel

indicator "Channel"
    edition = 1
    display = price

group "Average"
    /// How many bars the average and the band look at
    input length: int = 20, name = "Length", min = 2, max = 500
    input src: source = close, name = "Source"
group "Band"
    input width: float = 1.5, name = "Width", min = 0.1, step = 0.1
    input band_color: color = color.blue, name = "Colour"
let middle = tech.sma(src, length)
let band = width * tech.atr(length)
plot(middle + band, name = "Upper", color = band_color)
plot(middle - band, name = "Lower", color = band_color)
plot(middle, name = "Middle", color = color.gray)

group "Average" puts the inputs indented under it together under that heading. A line that starts with /// just above an input is its tooltip, the short help shown beside the field.

Try changing#

In the first program, change max = 500 to max = 50, save, and open the settings: the field stops at 50.
In "A switch, a colour and the price it reads", give show_middle the default false: the middle line stays hidden until the switch is turned on.
In "A list of choices", add a third choice: write options = ["SMA", "EMA", "WMA"], add let wma = tech.wma(close, length) and choose with if kind == "SMA" then sma else if kind == "EMA" then ema else wma.
In "Groups and tooltips", move input src under group "Band" and look at the settings panel again.
Add the tooltip line /// The colour of both band lines just above input band_color.

Checkpoint#

You can declare int, float, bool, color, source and text inputs.
You can limit a number with min, max and step, and offer choices with options.
You can show a plot only while a switch is on, with if ... then ... else na.
You can arrange the settings with group and give an input a tooltip with ///.