iOS 12 Shortcuts for the Beginner

Creating Shortcuts A Narrative Guide for the Befuddled Beginner iOS 12 introduced shortcuts: a way for you to combine a set of steps to accomplish a task. People who program would call this a script. In fact an app or software program is nothing more than a very sophisticated set of steps designed to accomplish a task. If you ever wanted to learn programming, you can start right now to create shortcuts. It's a great way to get your feet wet and find out if computer programming is for you.

First Things First: Terminology

Every technical thing has its own, sometimes confusing terminology and it's no different with shortcuts. The most important term to understand is an Action. An ACTION is one of the steps iOS takes. An action can be snapping a photo, retrieving a contact, archiving a file or even speaking something out loud. When you choose an action, you are adding one of these steps to your shortcut. For example, if you wanted to record a voice memo, your shortcut might have two actions, one to start recording and one to play the memo back. You are probably wondering at this point what about the action to stop the recording? This is where I can reveal another important concept about actions. Actions have their own settings. The record action has stop already integrated in to it as part of that action. When you choose the record action, you'll also choose whether you want it to stop when the user taps, or after a specific length of time. To relate this to other programming concepts, an action might also be called a function, a procedure or a method. Other programming languages use these terms. But for shortcuts, Apple calls the steps actions. As for the settings that belong to an action, these can also be thought of as properties, configurations or customizations. I'll stick with the term PROPERTIES. Most actions need INPUT and produce OUTPUT.For example the input to speak something out loud is a phrase for that action to voice. The input for the play sound action is a sound and the input for the archive files action is a list of files. Output is a bit more tricky. The action "get location" outputs your current location, whereas the output from "get maps URL"outputs a web address to a map showing the current GPS coordinates. The output for get phone number is a list of phone numbers obtained from the specified contact. It is not, as you might expect a single number unless only one is stored in that contact. Sometimes in order to produce output, an action needs input. To output that list of phone numbers, the action needs a specific contact as input. For example to speak phone numbers out loud, your shortcut would first get a contact. Next it would get the phone numbers from that contact, and lastly, it would speak those numbers. For another example, if you wanted to speak your current location, you'd first get the location and your next action would be to speak it. Now we understand actions, properties, input and output, let's talk about VARIABLES. A variable is a place in memory that is given a name and holds information that varies. You might name a variable "Sam" and get Sam's contact information and stash it there. But the Sam fvariable could just as well hold the contact information for Fred. In many programming languages variables have types, but iOS mostly hides that information away so you rarely need to worry about it. A location, a weather forcast and a contact are all different types of information, but once they are saved in variables they are available for you to use later in your script.

Why use variables?

It is the same reason you save any sort of information. If for example you wanted to send a friend the artists for the last five songs you played you'd want to get and store them in variables, then paste those variables in to your email. Perhaps you played those songs over a speaker at a party and everyone wants those songs' artists and names. You'd want to use variables to store all that information so it could be easily pasted to multiple emails. Basically a variable is a lot like a clipboard, only you can have multiple clipboards to hold all the information you need your shortcut to use later on.

The Mysterious Magic Variable

iOS makes variables way easier to deal with than most scripting languages. It has the concept of magic variables. Each time an action generates output, that output is stored in a magic variable. This means you don't have to even create a variable to get at that action's input. For example, I want to share my current location with my husband. My shortcut first gets my current location. It automatically saves that in a magic variable. Next I get the maps url for that location so he can see where I am in context. That too becomes a magic variable. The next action sends a message to my husband. The properties for that action are his phone number in the to field and in the text field I have a message reading "here is where I currently am". That is followed by the first magic variable, the one that shows my location as text, for example "Kaiser Hospital" or "10 Airport Dr" or "Highway 880 and Montague". It is followed by a new line and then the content of the magic variable for the maps URL. My sighted husband is on Android, so he can pull up the map on his phone to see exactly where I am, or if he's busy, just glance at the text to get an approximation.

The mechanics

So how do you make all this happen? Because I have only an iPHONE SE (the iPHONE with the smallest screen) I will describe how to create shortcuts from the perspective of a VoiceOver user on this phone. Please chime in if you use zoom and/or an iPAD because the screen layout is different. First, if you don't have the Shortcuts app you will be able to create Siri shortcuts with Siri suggestions. That's covered pretty thoroughly in other posts here, so I'll asume you've downloaded the free shortcuts app and are running it. Of course the shortcuts you create within this app will also be available to Siri if you choose to make it so. The shortcuts app has a gallery, which is a set of shortcuts Apple provided for you to experiment with and customize. It also has the library, which is the list of your specific shortcuts. You are on the library screen when you launch the app. In the library, you'll find a list of shortcuts you either created from Siri suggestions, shortcuts you acquired from the gallery or shortcuts you created or are in the process of creating. You can always stop mid-creation and do other things; your work in progress is waiting for you to resume tweaking it. Choose the Create Shortcut button to do just that. You are placed in a screen divided in to three sections. The Create Shortcuts Screen At the top are buttons to control the entire shortcuts. There is the name of the shortcut, which unless you change it is called "untitled Shortcut" followed by a numnber. If you are working on several shortcuts at a time this one might be called "Untitled Shortcut 3". There's also a Done button which takes you back to the library screen. Below that are buttons for Undo, Redo, share, Run Shortcut and Shortcut Settings. We won't worry about undo and redo for now. The Run Shortcut Button You use this to test out your shortcut in progress, and when it's finished you can also run it from here. But when it's finished you'll want to run it from somewhere more convenient, like a wigit on your lock screen or using Siri. Here, you primarily use this button to make sure the shortcut is doing what you want. The Shortcuts Settings Button This opens a properties screen for the entire shortcut. Here is where you can add it to Siri, change the Siri phrase that activates it, share it, add it to one of your home screens or add it to a lock screen widgit. Here is also where you can give it a meaningful name, like "Set Low Power and Do Not Disturb". There is also an "import questions" button which is used when you want to import the shortcut on to another iDEVICE.

Shortcut Sharing

There are two places to share a shortcut. The Share button on the shortcut screen opens up a standard share sheet where you can air drop it, add it to notes, open it in another app or save it to dropbox. Whichever apps have tied in to a share sheet would potentially be able to have this shortcut shared with them. This isn't that practical yet, because an app like VoiceDream Reaeder really cannot do much with a shortcut, but airdrop for example, can be handy if you want to share it with a friend. Google drive, can be useful for backing it up. The Share button you find in Shortcut settings is slightly different. This button lets you put the shortcut on iCloud and gives you a public link you can share. In this way other iOS 12 users can access your shortcut the same way they would grab it from the gallery. It also has a standard share sheet which lets you do the other kinds of sharing I discussed in the previous paragraph. On Shortcut settings, there is also an "add to share sheet" button. This lets your shortcut become part of a share sheet so input from other apps can be opened in your shortcut. When you add your shortcut to the share sheet you are sharing it with other apps which might want to access it in the future. When you just choose "Share" you are sharing the shortcut right now with another app or person. The Shortcut's content Below the buttons that control the entire shortcut is the list of actions currently included in your shortcut. Each action is displayed with its name and its properties immediately below it. For example, the "Record audio" action has properties for the audio quality, when to start (immediately or after the user taps) and when to stop (after a tap or a specific length of time.) You tap on any of these properties (of course double-tap with voiceover) to change them, and you doubletap with voiceover on the action itself to get a longer description of how it works. Some actions will have several properties, and some will have none. You can adjust the properties and run the shortcut as many times as you want to experiment with the results. For example if you get a weather forecast you can have it be hourly or daily. That will change how the shortcut behaves.

Moving actions Around

The order in which steps are performed is important. If you bake muffins, you need to mix the ingredients before you pop the batter in to muffin tins, and though you can preheat the oven ahead of time, you can't put the muffins in the oven until you've finished putting the batter in the pan. The same is true for shortcut actions. If you speak a weather forecast before you get it, nothing will be spoken. If you send email before you've given it an email address, nothing will be sent. In the Word of the day shortcut, the first step is to retrieve the Word from an RSS feed. If actions are not in the right order it is easy to drag them around. Double-tap and hold, wait for the sound and then drag an action up and down until everything is correctly ordered. The Actions Controller The final section on the shortcuts screen is taken up with the Actions Controller. This is basically a very long list of all the actions iOS 12 offers you. It is broken in to cattegories with a search field at the top. Most frequent actions are shown first and you can expand any cattegory to show everything. The actions controller itself can be minimized, fill half the screen or the entire screen: double-tap on the Actions controller to toggle between these three states. Note that Voiceover hints refers to the actions controller as the "actions drawer". Drawers are popular on Android and I am glad to see iOS making use of this user interface, which opens to show more possibilities, or closes to give you more screen real estate.

Time to experiment

Before you create your own shortcuts, it's a good idea to grab a few from the gallery to examine them in detail. I experimented with the Word of the Day Shortcut, which grabs the most current word from the Merriam-Webster RSS feed and displays it onscreen. I changed it so it spoke the word of the day instead. Take a shortcut that appeals to you and try adding actions, or changing the properties of an action that's already part of the shortcut. See what happens too if you change the order in which actions activate.

Creating your own Shortcuts

The mechanics are simple, but the process is more challenging. Basically, you find an action in the actions controller, double tap on it and it's added to the list of actions the shortcut will perform. After you've put all your actions in that list, or even while you are still selecting actions you can drag them around to get them in order. You change their properties once they are in the list. For example if one of your actions is to send a message, you'll select the recipient and the text of the message after you've added the Send message action to your shortcut. To add an action simply double tap and you'll hear a sound indicating it's been added. To remove an unwanted action from a shortcut, simply flick up when focused on it and select "Remove action from shortcut".

What About Variables?

Magic variables are the easiest to use. When an action creates output it is automatically stored in a magic variable. To use that variable later, you must select an action that needs input. When you supply that input you are able to choose from a list of existing magic variables. Where this process fails is if your actions are still not in the correct order, and thus no magic variable was created. For example, when I text my location to my husband in a shortcut, I need to have the action to get my current location in the list before the action to send a text. If that's true, then I'll be able to choose from an open variables drawer once I am editing the actual message. If you can't find the variables drawer, flick up on the actual action to get that property to appear. The variable drawer opens automatically if magic variables exist and you are focused on an action's property that is requesting input. There is also a manual way to work with variables. There are three actions "set variable","get variable" and "add to variable". When you set or get a variable, you specify a name for the variable. Set stores the output of the last action in to the variable; get offers the content of the variable as input to the next action. Add to variable retains a variable's existing content or creates a new variable if none is there. It also stores output from the previous action.

Flow Control

For advanced shortcuts you can also use scripting actions to test conditions (if, then else) and repeat shortcuts a specific number of times or until a condition is true or false. Perhaps after exploring this further, I will write a specific guide on how these concepts work specifically with iOS shortcuts, but they won't be useful to you if you have no programming background or have not explored creating simple shortcuts first.

Troubleshooting

Shortcuts won't work perfectly unless you are way smarter than the average bear. When a shortcut fails, ask yourself these questions:

• Have I picked the wrong action? For example did I get a maps URL instead of the text of a location? Did I get a website instead of an RSS feed? Look carefully through the actions to see if one fits your needs better.
• Are the actions in the right order? Think carefully about the steps you want your shortcut to perform. Are you trying to put muffins in the oven before you mixed the batter? Do you even have all the ingredients in the batter?
• Am I getting the expected output to go to the next action as input? Here's where you can test with an action called "Quick look" which will display the output of the previous action. Or simply use the "speak text" action to voice what the output is. You can remove the "speak text" or "quick look" actions once you have things working properly. Looking at the input and output of actions to determine what's not working is called Debugging.
• Am I getting too much output? If you get lengthy results there are actions that will strip out unwanted data. Will any of them work for your needs?
• Am I not getting any output? Check that the previous action actually produces output.
• Has your data been saved? If you need output from an action that occurs several steps before you need the results, it has to be stored in a variable. It's probably already in a magic variable, but did you remember to use it for your current action's input? Remember you can mix text and magic variables in an edit field.
• What about variables? You need to deliberately select a magic variable before it sometimes can be used. At other times, the next action will simply default to using the last action's output as its input. For example, if you put the "Play Sound" action after the "Record Audio" action, the sound it will play will be the audio you just recorded. If you put the sound before the "record audio" action then it will play the default iOS sound. To specify the sound you want it to play you need to adjust its properties.
• Is your data correct? If you got a web or RSS feed url, is it correct? Can you go there nanually with Safari? Did you preceed the problem action with an action that gives expected output?
• Did you find the action's properties? Sometimes they don't appear, you have to flick up on the action after rotoring over to actions to get VoiceOver to show you the context menu for an action, and then you can activate it to make it the current action whose properties you wish to configure. This is confusing, but just persevere, because most actions do have properties you can change.
• Is iOS just being quirky? Actions are still under development and sometimes their results are unexpected. For example the weather forecasts you get from iOS can be more tedious than the ones that come from third-party apps. It might take five minutes to read one of them out loud. Sometimes a maps URL is in Apple maps and sometimes google maps. And of course sometimes you want to do something for which Apple has not supplied an action.

Final Thoughts

Creating shortcuts is like playing an adventure game or solving a puzzle. Not everything works the way you might expect. But it can be amazing loads of fun to experiment and explore. For me, creating shortcuts has turned a boring, two-hour commute in to an end-of-day activity I look forward to. It keeps me awake, engaged and above all happy!