Widget Settings
Most widgets have user-configurable settings. Which settings a user can access is specified by the developer in the Widget Config file.
{
"name": "My Widget",
// Etc.
"settings": [
// Settings go here
]
}
You'll find a full list of settings below.
Interacting with settings
All widget settings are injected into to the settings
property of the Hologram object.
this.settings.nameOfSetting
For example, if your create a bool toggle setting with a name of showTime
, as shown here:
{
"name": "showTime",
"type": "bool",
"defaultValue": false
}
You would access it like so:
this.settings.showTime
Sometimes you might need to know when a user has changed a setting in order to dynamically update your widget. Because the settings are part of the widget data object, your can use the Vue watch method:
{
watch: {
'setting.showTime': function() {
// This is called whenever the showTime setting has changed
}
}
}
Fieldtypes
Widgets can define the following fieldtypes that users can interact with when they edit a widget's settings.
Bool
A simple boolean toggle.
{
"name": "showWeather",
"type": "bool",
"defaultValue": false
}
Select
A dropdown with a list of options.
{
"name": "pickANumber",
"type": "select",
"defaultValue": "1",
"options": [
{ "value": "1", "label": "One" },
{ "value": "2", "label": "Two" },
{ "value": "3", "label": "Three" },
]
}
Picker
Like a select field, but for a small number of options. If there are more than 5 options, this field will turn into a select field.
{
"name": "backgroundStyle",
"type": "picker",
"defaultValue": "normal",
"options": [
{ "value": "darker", "label": "Darker" },
{ "value": "normal", "label": "Normal" },
{ "value": "lighter", "label": "Lighter" },
]
}
Text
A plain text field. Can specify a placeholder and default value:
{
"name": "textSetting",
"type": "text",
"placeholder": "API Key",
"defaultValue": ""
}
Textarea
Same as the text field, but allows multiple lines of text. Can specify a placeholder and default value:
{
"name": "textSetting",
"type": "textarea",
"placeholder": "Quotes",
"defaultValue": ""
}
Button
A button which can trigger a method on your widget.
{
"label": "Quote",
"type": "button",
"description": "Changes once a day",
"buttonLabel": "Change Quote",
// Set which method to call on the widget
"onPress": "changeQuoteClick"
},
{
methods: {
changeQuoteClick() {
// This will be called when the button is pressed
}
}
}
Slider
Creates a range slider.
{
"name": "borderRadius",
"label": "Border Radius",
"type": "slider",
"defaultValue": "50",
"min": 0,
"max": 100
}
Font
Displays a font field that allows the selection of Hologram's included fonts. The default value is Normal
, which resolves to the default system font.
{
"name": "font",
"label": "Font",
"type": "font",
"defaultValue": "Normal"
},
To set the user's selected font in your widget, use the following in your HTML:
style="{ 'font-family': settings.font }"
Color Picker
Color picker field type.
{
"name": "backgroundColor",
"type": "color",
"defaultValue": "#51B8C5",
// Set weather or not the color picker should show the opacity slider
"enableOpacity": true
}
Color Theme
Used to set a color theme. Note that if you use autoColor
the colors will be selected automatically based on the dominant colors of whatever wallpaper is active.
{
"name": "theme",
"type": "color-theme",
"presets": ["auto", "custom"],
"colors": [
{
"name": "backgroundColor",
"autoColor": "darkmuted",
"presets": { "auto": "darkmuted"}
},
{
"name": "borderColor",
"autoColor": "darkvibrant",
"presets": { "auto": "darkvibrant" }
},
{
"name": "textColor",
"autoColor": "lightvibrant",
"presets": { "auto": "lightvibrant"}
},
{
"name": "shadowColor",
"autoColor": "darkmuted",
"presets": { "auto": "#00000033" }
}
]
}
The available auto colors you can use are:
-
darkvibrant
-
darkmuted
-
muted
-
vibrant
-
lightvibrant
-
lightmuted
You can optionally create user-selectable color themes. Depending on how many themes you create, they will show up either as buttons or a drop-down menu.
Here's an example:
{
"name": "theme",
"type": "color-theme",
"presets": ["auto", "classic", "aqua", "blackout", "snow", "custom"],
"defaultValue" : "classic",
"colors": [
{
"name": "backgroundColor",
"autoColor": "darkmuted",
"presets": {
"auto": "#1e1e1e",
"classic": "#000000",
"aqua": "#002b31",
"blackout": "#000000",
"snow": "#ffffff"
}
},
{
"name": "borderColor",
"autoColor": "darkvibrant",
"presets": {
"auto": "darkvibrant",
"classic": "#c52020",
"aqua": "#0897aa",
"blackout": "#000000",
"snow": "#83abe0"
}
},
{
"name": "textColor",
"autoColor": "lightvibrant",
"presets": {
"auto": "lightvibrant",
"classic": "#ffffff",
"aqua": "#effdff",
"blackout": "#ffffff",
"snow": "#6089be"
}
},
{
"name": "shadowColor",
"autoColor": "darkmuted",
"presets": {
"auto": "#00000033",
"classic": "#00000033",
"aqua": "#00000033",
"blackout": "#00000033",
"snow": "#00000033"
}
}
]
}
export default {
extends: HologramWidget,
mounted() {
// Get the user defined colors
this.fetchColorTheme(this, (colors) => {
// Add them to the css variables so we can style the widget
this.addCssVariables(colors)
})
},
// ...
}
Shadow
A field that shows slider controls for a shadow.
{
"name": "shadow",
"label": "Shadow",
"type": "shadow",
// Weather or not the shadow is enabled
"defaultValue": true,
// Default blur amount 0-100
"defaultBlur": 10,
// Default offset 0-100
"defaultOffset": 5,
// Default position 0-360
"defaultPosition": 0
}
The setting returns an object
{
enableShadow: true,
blur: 10,
offset: 5,
position: 0,
boxShadow: '5px 0px 10px'
}
Timezone
Allows a user to pick a timezone.
{
"name": "timezone",
"type": "timezone"
}
Divider
Adds divider with an optional label.
{
"label": "Section Name",
"type": "divider",
}
Description
All fieldtypes listed above can optionally contain a field description. Here's an example, using the text field type:
{
"name": "apiKey",
"description": "Enter your valid API key."
"type": "text",
"placeholder": "API Key",
"defaultValue": ""
}
Hidden
All fieldtypes listed above can optionally be hidden. Many of the internal interactions with widgets are based on settings, so it can be useful in some situations to define a hidden field. Here's an example of making a select list hidden:
{
"name": "frequency",
"type": "select",
"defaultValue": "daily",
"hidden": true,
"options": [
{ "value": "daily", "label": "Daily" }
]
},