Simple Widget Example

In this example we will create a simple widget that displays the amount of time you've spent on your computer today.

We will use a function in the Utility API to format the time. And we will make the color of the title and time editable in the settings.

Create a new widget

From within the Hologram application, navigate to the developer page and click the "New Widget" button. Name your widget "Computer Time Today", give it an ID of "time-today", and enter your name. Then click "create". Now open your widget files in a text editor.

Update widget.json

Open widget.json and replace the contents with the following:

{
    "name": "Computer Time Today",
    "id": "time-today",
    "author": "-",
    "version": "1.0.0",
    "description": "How much time you've spent on your computer.",
    "aspectRatio": "auto-height",

    "defaultSize": {
        "placementY": "top",
        "placementX": "left",
        "x": 20,
        "y": 15,
        "width": 0,
        "height": 0
    },

    "settings": [
        {
            "name": "font",
            "label": "Font",
            "type": "font",
            "defaultValue": "Normal"
        },

        { "type": "divider" },

        { "name": "backgroundColor", "type": "color", "defaultValue": "darkmuted", "defaultAutoColor": "darkmuted"},
        { "name": "borderColor", "type": "color", "defaultValue": "darkvibrant", "defaultAutoColor": "darkvibrant"},
        { "name": "titleColor", "type": "color", "defaultValue": "lightmuted", "defaultAutoColor": "lightmuted"},
        { "name": "timeColor", "type": "color", "defaultValue": "lightvibrant", "defaultAutoColor": "lightvibrant"},
        { "name": "shadowColor", "type": "color", "defaultValue": "darkmuted", "defaultAutoColor": "darkmuted"},

        { "type": "divider" },
        {
            "name": "borderWidth",
            "label": "Border Width",
            "type": "slider",
            "defaultValue": 20,
            "min": 0,
            "max": 50
        },
        {
            "name": "borderRadius",
            "label": "Corner Radius",
            "type": "slider",
            "defaultValue": "40",
            "min": 0,
            "max": 100
        },
        {
            "name": "shadow",
            "label": "Shadow",
            "type": "shadow",
            "defaultValue": true,
            "defaultBlur": 10,
            "defaultOffset": 0,
            "defaultPosition": 0
        }
    ]
}

Notes:

In the above code you'll notice it contains an aspect ratio. We are using auto-height which automatically sets the height of the container based on its contents. For this widget we could set a fixed ratio since it only contains one piece of data, but auto-height is the simplest way to ensure your widget fits within the container.

You'll also see a variety of settings. All the Hologram settings are described in the Settings and Color Settings pages of the docs.

In the settings object of the file you'll notice we added color controls to titleColor and timeColor. When we create our CSS file below we will use those values as variable names to set the color dynamically.

Update styles.css

Now open your styles.css file and replace the CSS with this:

.widget-container {
    border-radius: 0.4em;
    box-shadow: var(--shadow) var(--shadowColor);
    background-color: var(--backgroundColor);
    border: var(--borderWidth) solid var(--borderColor);
    font-size: 0.8em;
    height: 100%;
}
.widget-container-inner {
    padding: 1em;
}
.title {
    color: var(--titleColor);
    opacity: 0.5;
    font-size: 0.7em;
    text-transform: uppercase;
    margin-bottom: 0.4em;
    margin-top: 1.6em;
}
.time {
    color: var(--timeColor);
    font-size: 0.6em;
    margin: 0.6em 0;
}

Notes:

The CSS contains variables so we can dynamically set those values from the settings page.

Update index.js

Lastly, update your index.js file. Replace everything previously in it with the following code.

The code contains comments that explain it. We will further explain the key points below the code.

export default {
    extends: HologramWidget,
    data() {
        return {
            timeSpentToday: 0
        }
    },
    mounted() {
        // Get the amount of time spent on the computer today
        Hologram.get(this, 'computerUsageTimeToday', (timeToday) => {
            this.timeSpentToday = Hologram.util.humanizeSeconds(timeToday)
        })

        // Load the widget colors and assign them to css variables
        this.fetchAllColors(colors => {
            this.addCssVariables(colors)
        })
    },
    template: /*html*/ `
        <div class="widget-container"
            :style="{'--shadow': this.settings.shadow.boxShadow,
                    '--borderWidth': settings.borderWidth / 100 + 'em',
                    borderRadius: (settings.borderRadius / 100) * 2 + 'em',
                    'font-family': settings.font}">

            <div class="widget-container-inner">
                <div class="title">My computer usage today</div>
                <div class="time">{{timeSpentToday}}</div>
            </div>
        </div>
    `
}

Notes:

Because we are fetching the time as a callback, Hologram automatically updates the time every minute.

You will also notice we've added a style element to our HTML, which set those values from the settings in the widget.json file.

We hope you are impressed by just how easy it is to create a widget in Hologram!