I have a few short­cuts that show me the sta­tus of my devices on the net­work. For exam­ple, I can see the cur­rent data from my solar pan­el sys­tem. Unfor­tu­nate­ly, Apple Short­cuts has very lim­it­ed graph­ic options for this. Show­ing the results as a wid­get just was­n’t pos­si­ble, so the best I could do was this:

Simon B. Støvring, devel­op­er of Script­able and Rune­stone, has released a beta ver­sion of his new app, Can­vas­es. It solves the prob­lem of dis­play­ing Short­cut data as a wid­get. The result is much nicer and eas­i­er to read.

How it works

Every­thing I describe here is based on the 2018 beta build. Since Simon B. Støvring releas­es new updates in Test­Flight almost dai­ly, the build num­ber may change quick­ly. There­fore, changes in lat­er betas or the final release are pos­si­ble.

The Canvas definition

The wid­get is defined in the Can­vas­es app. This includes the visu­al design, lay­out ele­ments, and place­hold­ers that are lat­er filled with results from a linked short­cut. For my exam­ple, it looks like this:

The left pan­el shows the cur­rent struc­ture of the wid­get. The mid­dle pan­el shows a pre­view. The right pan­el shows the dif­fer­ent ele­ments that can be used in a wid­get. Click­ing on an ele­ment adds it to the end of the tree in the left pan­el. Then, you can move it to the desired posi­tion.

Each ele­ment has its own prop­er­ties, such as fore­ground and back­ground col­or, as well as spac­ing. These prop­er­ties allow the short­cut to con­trol how some­thing is ren­dered. For exam­ple, the short­cut can change the text col­or from black to red once a cer­tain val­ue drops below a thresh­old.

The shortcut

To retrieve cur­rent data from my solar pan­el sys­tem, I access an inter­nal ser­vice. The result of that call is stored in a dic­tio­nary. I read the raw data from the dic­tio­nary and process it fur­ther. I go through the dic­tio­nary entry by entry. Here, the raw val­ue is shown under the key pv_feed_in_w. This val­ue is in watts. Before writ­ing it into the vari­able togrid, I con­vert it to kilo­watts by divid­ing it by 1000 and round­ing to three dec­i­mal places.

In order to dis­play the val­ue of the vari­able in the wid­get, it must be passed to the Can­vas. The short­cut uses the Can­vas action Update View to do so.

This action sets the “Text” prop­er­ty of the place­hold­er “grid” in the Can­vas def­i­n­i­tion named “PV” to the con­tent of the short­cut vari­able togrid.

This method writes each dic­tio­nary entry into a vari­able, which is then dis­played as text in the wid­get. The bat­tery charge lev­el in per­cent is the one excep­tion; it is shown in the wid­get using the Progress ele­ment. The col­or of the ring is set to red below 11% and green above 11%.

Not all the wid­get’s con­tent is derived from vari­ables. In this exam­ple, icons and units are fixed in the Can­vas and are not set by the short­cut. Once all the vari­able val­ues have been passed to the Can­vas, all that’s left to do is add the wid­get to the home screen or desk­top. After that, the wid­get is updat­ed with new solar sys­tem data every time the short­cut runs.

I was sur­prised to find that run­ning the short­cut on one Apple device updates the wid­gets on all my devices. This is because the data is saved into the Can­vas def­i­n­i­tion and synced through iCloud. This means the wid­gets on oth­er devices receive the new data after iCloud syncs the file.

Layout elements

A wid­get’s lay­out is pri­mar­i­ly com­posed of the Stack lay­out ele­ment. Con­tent can be arranged hor­i­zon­tal­ly, ver­ti­cal­ly, or with over­lap­ping ele­ments (Depth). In this exam­ple, the lay­out looks like this:

A Stack with the depth prop­er­ty is used to show the per­cent­age inside the progress ring.

All ele­ments offer addi­tion­al prop­er­ties, such as font (for text ele­ments), col­or, and spac­ing. These prop­er­ties can usu­al­ly be set through the short­cut, and they are avail­able for almost every ele­ment. While fine-tun­ing these set­tings can be com­plex, the defaults are usu­al­ly suf­fi­cient.

The Grid for repeating views

The Grid is a spe­cial lay­out ele­ment. As its name sug­gests, it arranges its ele­ments into a set num­ber of columns. The lay­out tree looks like this in the fol­low­ing exam­ples:

The only dif­fer­ence in how it looks is the num­ber of columns (high­light­ed in red in the first exam­ple).

A Grid is spe­cial because it can be filled with repeat­ing con­tent of the same type. For exam­ple, this can be done through a loop in the short­cut. To illus­trate how this works, con­sid­er a sim­ple exam­ple: read­ing key/value pairs from a data source, in this case a short­cut dic­tio­nary. In this sce­nario, the keys are a few dairy prod­ucts, each with a true/false val­ue indi­cat­ing whether they need to be pur­chased.

The wid­get’s out­put should end up look­ing like this:

For the Can­vas def­i­n­i­tion, the Grid needs a Stack that serves as a tem­plate with place­hold­ers for the check­box and text for the prod­uct.

In the­o­ry, you could query the dic­tio­nary for each row in the short­cut and define a sep­a­rate Stack each time. How­ev­er, this method is not very flex­i­ble if a prod­uct is added or removed. It’s sim­pler to query the dic­tio­nary only once.

For the short­cut to work prop­er­ly, each ele­ment must have a name. You also need to acti­vate the “Tem­plate Chil­dren” option in the Grid’s prop­er­ties (1).

The “Edi­tor Shows” switch (2) deter­mines if the pre­view shows the tem­plate’s place­hold­ers or the data from the last time the short­cut was run using the “Cre­at­ed Chil­dren” option. This option is unavail­able if the short­cut has­n’t run yet, and the “Clear Cre­at­ed Chil­dren” row (4) is also hid­den.

Enabling “Tem­plate Chil­dren” trans­forms the ele­ments in the Grid into a tem­plate. The tem­plate can then be filled with data from the dic­tio­nary using a loop.

Since the dic­tio­nary must be processed in a loop, all keys are first read into a list, which is then looped over (1). In each iter­a­tion of the loop (2), a new view is cre­at­ed from the tem­plate (3) defined in the Can­vas and its place­hold­ers are filled with data.

In step 4, the key of the cur­rent loop item is read using Repeat with Each Item. It is then writ­ten as text into the place­hold­er item in the copy of row that was just cre­at­ed inside the Grid list.

The val­ue of the key/value pair must also be writ­ten into the cor­re­spond­ing place­hold­er, check. The tem­plate defines the ele­ment check, which dis­plays an emp­ty or checked check­box depend­ing on the val­ue. First, the val­ue of the cur­rent key is fetched (5) and passed as a true/false val­ue into the If action (6).

Sim­i­lar to pass­ing the cur­rent key, this fills a place­hold­er. How­ev­er, here the prop­er­ty is not Text; it is Sym­bol. In the “true” case (7), the sym­bol checkmark.square is used, and in the “false” case (8), only the sym­bol square is used.

The loop will end after it has processed every entry in the dic­tio­nary and cre­at­ed a view for each one based on the tem­plate. The result is a list of filled rows, called the “chil­dren” of the row tem­plate.

Final­ly, the Grids list in the “GridTest” Can­vas is updat­ed with the result of the loop. Unlike inside the loop, it does­n’t use the Update View Created from Template action. Instead, it uses the reg­u­lar Update View action to fill the children prop­er­ty of list with the list of views from the loop.

You can also build more com­plex wid­gets filled with mul­ti­ple Grids, like Simon’s “Month Cal­en­dar” wid­get, which he uses as an exam­ple on his web­site.

Keep in mind that wid­gets have fixed sizes, so they can’t dis­play an unlim­it­ed num­ber of rows or columns. If there is more data than can fit, the short­cut must han­dle that by lim­it­ing the num­ber of loop runs. Over­all, the com­bi­na­tion of Grids, tem­plates, and loops leaves plen­ty of room for dis­cov­er­ing more ways to solve prob­lems.

Use cases

The Can­vas­es app offers a new way to dis­play short­cut results as a nice­ly designed wid­get. You can use any data source that a short­cut can work with. This includes inter­faces to devices on your net­work, such as my solar sys­tem; inter­net ser­vices for weath­er or sur­vey data; and data col­lect­ed right on the device. For exam­ple, you can dis­play your steps from the last few days from the Health app as a bar chart. The overview of my solar sys­tem is just one exam­ple. Instead of open­ing the PV app or web­site sev­er­al times a day, I can see the cur­rent val­ues right on my desk­top.

How­ev­er, there is one lim­it­ing fac­tor when using wid­gets: the data update rate is lim­it­ed to around 40–50 updates per day. Ini­tial­ly, I planned to use launchd on the Mac to cre­ate a solu­tion that runs the short­cut every five min­utes. How­ev­er, I had to aban­don that idea, also because it isn’t pos­si­ble on iPhone or iPad. 

At least the Automa­tion fea­ture in Short­cuts lets you run a short­cut at a spe­cif­ic time. For exam­ple, you can set it to update activ­i­ty data every day at 11:00 p.m., so you can check how active your day was before going to bed.

Instead of auto­mat­ic updates, you can place a but­ton on the wid­get that, when clicked, starts the short­cut and loads the newest data. The app lets you add a URL to the but­ton ele­ment in the Can­vas def­i­n­i­tion for this pur­pose. On iOS, iPa­dOS, and macOS ver­sions pri­or to 27, this launch­es the short­cut via the fol­low­ing URL:

shortcuts://run-shortcut?name=Shortcut%20Name

Start­ing with sys­tem ver­sion 27, there is also a “Run Short­cut” action that I have not yet test­ed.

When the short­cut is run via the but­ton, the Short­cuts app opens and remains in the fore­ground. As a workaround, you can add an action to hide the Short­cuts app at the begin­ning of the short­cut.

I expand­ed on my exam­ple of a solar sys­tem by adding a but­ton and a time­stamp of the last update.

As an alter­na­tive to the Can­vas­es app, Simon offers Script­able, which can be used to cre­ate wid­gets using JavaScript. For this app there is also a com­mu­ni­ty that offers ready-made scripts like this one: A curat­ed list of awe­some Script­able scripts and wid­gets.
How­ev­er, Simon has cre­at­ed a more acces­si­ble way with the Can­vas­es app through the Short­cuts app. I think a com­mu­ni­ty around the app will form very soon.

Notes

While iOS and iPa­dOS already run quite smooth­ly, the Mac ver­sion still needs work. For exam­ple, at least up until ver­sion 2021, I could­n’t reorder ele­ments in the tree, so I cre­at­ed the exam­ple Can­vas on my iPad. It syncs auto­mat­i­cal­ly, which can take a while, but then it works on the Mac with the match­ing short­cut.

So far, I have only built fair­ly sim­ple exam­ples with­out com­plex lay­outs. I still need to dig deep­er into this top­ic since there are quite a few adjustable para­me­ters that make it slight­ly com­pli­cat­ed.

One thing I haven’t tried yet is using the AI fea­ture to cre­ate a can­vas. Accord­ing to the doc­u­men­ta­tion, pro­vid­ing a sim­ple descrip­tion of what should be dis­played is enough to auto­mat­i­cal­ly gen­er­ate a match­ing Can­vas.

With the Can­vas­es app, you can share a Can­vas along with its match­ing short­cut. This cre­ates a link that, when clicked, installs the Can­vas and then the short­cut via an iCloud link.

Over­all, I think the Can­vas­es app intro­duces new pos­si­bil­i­ties for Short­cuts by allow­ing you to present your data and analy­sis in a visu­al­ly appeal­ing way as a wid­get.