Widget Settings

Most widgets will have, at minimum, color controls which allow a user to style a widget.

However, there are a variety of other setings that developers can implement as well, such as toggle switches, drop-down menus, sliders, etc. This page describes those settings.

Setting Declarations

Settings are defined in the widget.json file, inside the settings[] array:

{
    "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

Watching for setting changes

Most of the time, when a user makes a setting change it will be dynamically updated in your widget. However, there are cases when you might need to explicitly know when a user has changed a setting in order to dynamically perform some action. 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
}

Date Picker

A date and time picker. The value is returned as unix time. You can also set the default value to a unix time date.

{
    "name": "countdownDate",
    "type": "date-picker"
}

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

Creates a set of horizontal buttons when you have 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, add it as a style property in one of the the <div> elements in your HTML template.

style="{ 'font-family': settings.font }"

If you want the font choice to be global, put it in your widget's main container div.

<div class="some-class" :style="{'font-family': settings.font}">

Color Picker

Color picker field type.

{
    "name": "backgroundColor",
    "type": "color",
    "defaultValue": "#51B8C5",
    "defaultAutoColor": "lightvibrant",
    // Set weather or not the color picker should show the opacity slider
    // This is set to true by default so it doesn't need to be explicity
    // defined unless you want it off.
    "enableOpacity": true
}

Note: The color settings are described in detail on the [Widget Color Settings](widget-color-settings) page.

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'
}

In your template you can use it like so:

<div class="container" :style="{'--shadow': this.settings.shadow.boxShadow}">

Timezone

Allows a user to pick a timezone.

{
    "name": "timezone",
    "type": "timezone"
}

Divider

Adds divider with an optional label.

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

Width

You can change the width of fields to to put them next to each other.

The valid widths are: full, two-thirds, half, third

{

```json
{
    "name": "textSetting",
    "width": "half",
    // ...
},

Hide When or Show When

Sometimes settings are dependent on other settings. For example, let's say you build a clock widget that allows the seconds hand color to be changed, and also allows the hand itself be shown or hidden. Since it makes no sense to allow color changes on a hidden clock hand, you might want the color field to be greyed out when the element is hidden.

Any setting can be hidden by adding a hideWhen object:

"hideWhen": [{ "name": "settingsName", "valueIs": [false]}]

The inverse is possible too. Sometimes you might want to show an element when a condition is met. In that case you can use:

"showWhen": [{ "name": "settingsName", "valueIs": [false]}]

Here's an example of how this option is used:

{
    "name": "addVibrance",
    "label": "Add Color Vibrance"
    "type": "bool",
    "defaultValue": true
}

{
    "name": "vibranceAmount",
    "label": "Vibrance Amount",
    "type": "slider",
    "defaultValue": "50",
    "min": 0,
    "max": 100,
    "hideWhen": [{ "name": "addVibrance", "valueIs": [false]}]
}