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" }
    ]
  },