xbar plugins can now define Variables in their metadata. End users will be prompted to input the values when they install the plugin.
The new xbar app renders variables like this:
Use cases
Variables are great for:
- API keys or tokens that your plugin needs
- Different style or presentation options
- Letting users decide how many items to show
Defining variables
To define variables for your plugin, use xbar.var
tags.
<xbar.var>type(VAR_NAME=default): description [options]</xbar.var>
type
- the kind of field (can bestring
,number
,boolean
, orselect
)VAR_NAME
- the name of the variable (will become an environment variable when the plugin runs). If you prefix your variable name with"VAR_"
, xbar will nicely format the variable label in the UI Prefix names withVAR_
and use underscores for spacesdefault
- the default/initial value for this variabledescription
- a short label describing the variable[options]
- forselect
types, a comma separated list of option strings
Some examples include:
# <xbar.var>string(VAR_NAME="Mat Ryer"): Your name.</xbar.var>
# <xbar.var>number(VAR_COUNTER=1): A counter.</xbar.var>
# <xbar.var>boolean(VAR_VERBOSE=true): Verbose or not?</xbar.var>
# <xbar.var>select(VAR_STYLE="normal"): Which style to use. [small, normal, big]</xbar.var>
Select options
The [small, normal, big]
in the example above shows the valid options. It is required for select
types.
Using variables in your plugin
The NAME
you use in the metadata will become the environment variable that holds the value input by the user.
# <xbar.var>string(VAR_NAME="World"): Your name.</xbar.var>
echo "Hello, ${VAR_NAME}"
- Remember: Environment variable values are always strings
Values are stored in sidecar JSON files
Variables are stored in JSON files alongside your plugin. The key is the name of the Variable as well as the name of the environment variable. The values are the user’s preferences, usually input through the xbar app.
For example, the variables file for the tail.5s.sh
plugin looks like this:
tail.5s.sh.vars.json
{
"VAR_FILE": "./001-tail.5s.sh",
"VAR_LINES": 15
}
Plugins using Variables are more likely to get featured
When deciding which plugins to feature, we are planning on prioritising plugins that make use of more modern xbar features. It shows they’re recently tested and verified to be working, and it shows that the maintainer(s) are still involved.