Everyone is talking about the fine “Scriptable” tool. With this you can implement your own scripts for iOS without having to deal with Apple’s programming languages or infrastructure. All you need is a knowledge of JavaScript.
In this tutorial I will show you how you can implement a first widget with Scriptable. In particular, I will go into how you can implement the script on a Windows PC or Mac and then test it directly on your smartphone with little effort.
I assume knowledge of JavaScript, so this is not about learning JavaScript, but rather getting to an initial result as quickly as possible with existing knowledge.
The sample application – Instagram Followers
Since there are countless examples for calendar, weather and time on the internet, I (hopefully) came up with something new. The goal is a widget that shows how many followers are currently following an Instagram account.
The program code, which you can then simply try out as described below, can be found here:
https://github.com/bestmacfly/Sriptable-Instagram-Follower-Widget
In the end, this is what the finished result will look like:
First steps
First you download Scriptable from the App Store. After starting the app, you will be presented with some sample scripts, but we want to start implementing our own widget right here. Therefore, create a new script directly via the + symbol:
You land directly in the window for the source code of the new script. We ignore this for now, who would want to implement program code with the smartphone keyboard?
At this point, however, the area at the bottom left is interesting:
Here you can adjust the settings for the script, at this point we are particularly interested in the name of the script, this could look like this, for example, just adjust it as you like:
Editing of the script via a PC
The best way to do the development work is to use a PC with a corresponding development environment. In my case, Windows and VSCode (Windows and VSCode can of course be exchanged by your preferences). The way described here should work independently of the operating system and IDE.
The exciting question now: How do we get the script created above onto the PC, and how can we transfer the script created above back to the smartphone?
By default, Scriptable stores a folder in your iCloud and saves all scripts there. You can conveniently access your iCloud from your PC, all you have to do is install the appropriate tools from Apple on the PC. Under Windows you can find this in the Microsoft Store.
After the installation you will find a new folder iCloud Drive in Explorer and here the subfolder Scriptable. This now also contains the script that we created earlier via Scriptable:
You can now edit and change the script with the development environment of your choice; when you save, the script is automatically transferred back to the smartphone via the iCloud.
Different opinions about iDrive are circulating on the Internet – the synchronization would not always work properly. If you have problems with iDrive, you can always switch to an alternative such as Google Drive or Dropbox. In the general app settings of Scriptable you will find the option File Bookmarks to add further folders to Scriptable:
Here you can easily add a file from another service (or an entire folder) to Scriptable. So you can do your work without iDrive completely.
Implementation of the widget – APIs used
You can use normal JavaScript to implement the widget. JavaScriptCore is available as a script environment. This is Apple’s JavaScript environment, which is currently based on ECMAscript 6 and also has an Apple-specific API (which is of no interest to us at this point).
What is more exciting for the implementation of the widget is Scriptable’s own API, which you can access here: https://docs.scriptable.app/
The following scriptable classes are interesting for this example:
- Request: Class for sending http requests. It is used in the widget to call up the profile page of the Instagram user.
- Font: Access to the available iOS fonts
- Color: Access to colors.
- Image: Provision of image data. The profile picture (avatar) of the Instagram user is kept in the widget.
- ListWidget: The class that holds the data of the current widget. In principle, this is the canvas that you just have to paint.
- WidgetImage: Image class for images in widgets, which can be used to manipulate the image (e.g. the display size).
- WidgetText: Text class for text displayed on widgets in order to influence the text that is displayed.
- Script: General scripting class. At the end you pass your widget to Scriptable via this.
Also important: Every script can have an input parameter. In our case, we use the input parameters to request the Instagram account name. Unfortunately, only one input parameter is currently possible, which cannot be further named, which makes the whole thing a bit cumbersome for the end user.
Excerpts from the code
As described above, you can find the complete and functional code here:
https://github.com/bestmacfly/Sriptable-Instagram-Follower-Widget
I would like to go into the scriptables-specific passages in a little more detail. You have access to the input parameters via the always available object args:
let account = args.widgetParameter;
if (!account)
account = "YOUR DEFAULT ACCOUNT"In our case, the Instagram account name is expected here. Attention: The parameter is possibly not available, therefore in the above example a default account is defined, which you have to adjust accordingly when trying out.
The profile page is then called via the request class and the HTML source text of the profile is supplied via the loadString method:
let req = new Request(url);
let html = await req.loadString();Extracting the number of followers from the HTML is classic JavaScript. Reading out the profile picture is also interesting. Once the URL to the profile picture has been determined from the HTML, the picture is loaded via the request object as above, this time using the loadImage method:
let req = new Request(url)
let image = await req.loadImage()As a return value you will receive an object of the type Image, which you can then use directly in the widget to be displayed.
Now all the necessary information has been collected (number of followers and avatar), which we now have to put into a widget. The widget object is used for this, here is a longer code excerpt:
let widget = new ListWidget();
widget.backgroundColor = Color.black();
if (avatar) {
const wimg = widget.addImage(avatar)
wimg.centerAlignImage();
wimg.imageSize = new Size(60, 60)
}
widget.addSpacer()
let wFollowers = widget.addText(followers);
wFollowers.font = Font.mediumRoundedSystemFont(detailFontSize)
wFollowers.textColor = detailColor;
wFollowers.centerAlignText();First, the appearance of the widget can be adjusted using various attributes, in our case the background is set to black. A HEX code for the color is not used, but we use the Color class, which is used for all color operations.
The previously loaded avatar can be added to the widget using the addImage method. Important: .addImage returns an object of the WidgetImage type, which you can use to influence the appearance of the image (in the example, the size is reduced and the image is centered). The attributes are adjusted after the image has been added to the widget.
This also applies to text to be formatted. The number of followers is first added to the widget. The returned object of the WidgetText type is then used to influence the display (font, size, etc.).
Finally, the widget has to be returned to Scriptable and displayed. Furthermore, the termination of the script must be communicated:
Script.setWidget(widget);
widget.presentSmall();
Script.complete();PresentSmall is interesting here: iOS provides three different sizes of widgets, this example is based on the smallest variant. Theoretically, you can have your script displayed dynamically in small / medium or large with different information depending on the desired size. The widget size required by the user can be queried at any time via config.widgetFamiliy.
Testing and debugging
After each saving, the script is available to you directly within Scriptable. By clicking on the script, it is executed and the widget is displayed.
Unfortunately there is no debugger available from Scriptable. In the development environment on the PC, on the other hand, no debugging can take place, since the scripts cannot run here. Therefore, in the event of an error, only the classic console output remains; log outputs can be generated using console.log. If you execute your script directly via Scriptable, you can then see the console output:
By pressing 3 in the example above, you then have access to the specific log outputs.
Last but not least: setting up the widget on the home screen
After you are satisfied with the output of the script, all you have to do is add the widget to your home screen. So add a new widget to the appropriate place on your home screen and select Scriptable:
Then select the small variant of the widget and finish adding. The following appears on the home screen:
As long as the widget is still “wobbling”, you press the widget once, you will then get into a configuration dialog. In this you select your script and now also define the script parameter with your account name.
You have now completed the setup and the widget should now do its work on your home screen. Incidentally, you cannot control when the content of the script is updated. Usually this happens every 5 minutes. However, if your smartphone is in power-saving mode, iOS will reduce the frequency of execution accordingly.
In conclusion
The widget is only intended as a first example here. You have many other options for implementing great ideas with Scriptable. For example, automation scripts can be implemented through the possible Siri integration, just play around a little. Great suggestions can be found here:
On this page you will find countless example scripts that you can use directly and use as suggestions.
The following page is available for all kinds of questions:
Hundreds of examples can also be found here, just waiting to be tried out. You will also be happy to help with problems here.
If you like my little scriptable tutorial, I would be happy about a small tip:
https://www.paypal.com/paypalme/markmescher/2,99
You are of course free to decide how big the coffee should be 🙂
If you have any suggestions for this tutorial, I look forward to your comments!
You are also welcome to read the second part of this tutorial …