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",
    "version": "1.0.0",
    "author": "-",
    "description": "My cool widget!",
    "aspectRatio": "auto-height",

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

    "settings": [
        {
            "name": "font",
            "label": "Font",
            "type": "font",
            "defaultValue": "Normal"
        },
        {
            "label": "Colors",
            "type": "divider"
        },
        {
            "name": "theme",
            "type": "color-theme",
            "presets": ["auto", "light", "dark", "custom"],
            "colors": [
                {
                    "name": "backgroundColor",
                    "autoColor": "darkmuted",
                    "presets": { "auto": "darkmuted", "light": "#ffffff", "dark": "#000000" }
                  },
                {
                    "name": "borderColor",
                    "autoColor": "darkvibrant",
                    "presets": { "auto": "darkvibrant", "light": "#ffffff00", "dark": "#00000000" }
                  },
                {
                    "name": "titleColor",
                    "autoColor": "lightmuted",
                    "presets": { "auto": "lightmuted", "light": "#000000", "dark": "#ffffff" }
                  },
                  {
                      "name": "timeColor",
                      "autoColor": "lightvibrant",
                      "presets": { "auto": "lightvibrant", "light": "#000000", "dark": "#ffffff" }
                    },
                {
                    "name": "shadowColor",
                    "autoColor": "darkmuted",
                    "presets": { "auto": "#00000033", "light": "#00000033", "dark": "#00000033" }
                  }
            ]
        },
        {
            "type": "divider"
        },
        {
            "name": "shadow",
            "label": "Shadow",
            "type": "shadow",
            "defaultValue": true
        }
    ]
  }

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.

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: 1px solid var(--borderColor);
    font-size: 0.8em;
    padding: 1em;
    height: 100%;
}

.title {
    color: var(--titleColor);
    opacity: 0.5;
    font-size: 0.7em;
    text-transform: uppercase;
    margin: 0 auto 1em auto;
}

.time {
    color: var(--timeColor);
    font-size: 0.9em;
    font-weight: bold;
    text-align: center;
}

Notes:

The CSS contains five different 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 {
            // This gets converted to a variable in the template section
            // below. We set a default value of zero.
            timeSpentToday: 0
        }
    },

    // Everything in this function fires automatically when the page loads
    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 theme colors, and assign them to css variables
        this.fetchColorTheme('theme', colors => {
            this.addCssVariables(colors)
        })
    },
    template: /*html*/ `
        <div class="widget-container" :style="{'--shadow': this.settings.shadow.boxShadow, 'font-family': settings.font}">
           <div class="title">My computer usage today</div>
           <div class="time">{{timeSpentToday}}</div>
        </div>
    `
}

Notes:

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

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