Anatomy of a Widget

In the Quick Start chapter we learned the basics of building a simple, static widget. Now let's see what a more visually rich and data-driven widget might look like.

There are two things you need to know about me: 1) I run a micro weather station in my backyard and 2) I love the font Chalkduster. There are no existing widgets that combine my two passions. So let's make one. Here's what the final result should look like:

We're using a few more features of widget.json, so this will look a little bigger than the hello world widget.

A few things are new here. We pass along version to let clients know what to expect in the rest of the widget.json payload. The version is currently 1. We'll only change the version with major schema changes that would break existing clients.

You'll notice we're using the data property a lot more now. data is a great way to template in dynamic values without having to touch any layouts. In this case, we only have one layout, but once we start adding more, you'll want to avoid having to touch each one individually.

"data": {
  "content_url": "https://example.com",
  "weather_city": "Seattle",
  "weather_temp": "65°",
  "weather_icon": "https://.../sunny.png"
},

To use the data values, we can use data_ref on text and image objects. These replace the string and url values respectively.

"text": {
  "data_ref": "weather_city",
  "size": 12,
  "font_style": "cool_font",
  "color_style": "city_text_color",
  "justification": "left"
}

We're also taking advantage of more features in the styles object. Instead of defining simple colors, we define a nice linear gradient to represent the year-round perfect blue skies of Seattle.

"styles": {
  "colors": {
    "background_gradient": {
      "color": "linear-gradient(0deg, #76A5D5, #2469AA)"
    },
    "city_text_color": {
      "color": "#FFFFFFAA"
    }
  },
  "fonts": {
    "cool_font": {
      "family": "Chalkduster"
    }
  }
},

linear-gradient(0deg, #76A5D5, #2469AA) might look like a familiar declaration if you've seen CSS gradients. CSS gradients are powerful. widget.json gradients eschew some power for simpler declarations. The full details are in the chapter widget.json Schema, but in general, widget.json gradients only take a degree to rotate, a start color, and an end color.

Colors can be specified in the form of #RRGGBB or #RRGGBBAA.

Also in the styles block, we've defined a named font called cool_font. The fonts you can specify here are left up to the clients and will fallback to system fonts if not available. You probably won't need anything other than Chalkduster, but if you do, Widget Construction Set supports fonts available on iOS.

We've covered most of the local weather widget, but we've left a few topics for the chapter on Widget Layout.