Scriptable Tutorial Part 2 – Files

In the first part of the tutorial , we looked at how to create an iOS widget with Scriptable. This tutorial will now deal with the topic of persistence. How do you proceed if a script has to temporarily store data?

Unfortunately, Scriptable does not allow you easy access to databases or property storage. Technologies that you may know from the web cannot be used in Scriptable. Fortunately, there is an easy way out. You can use the Scriptable API to create files in the file system of the smartphone, these files are retained even after a script has been executed and can thus be read in again the next time the script is used.

The sample application – Instagram Followers v2

In the first part of this tutorial we created a widget that shows the current number of followers for an Instagram account. We want to expand this in the second part of the tutorial. In addition to the current number of followers, the increase in followers for yesterday, last week and last month should be shown. This is what the result will look like in the end:

APIs used

Compared to the first tutorial , we only need one more class from the Scriptable API:

FileManager : Class that provides all methods for reading and writing files.

Excerpts from the code

The FileManager provides two different methods to access the file system:

.local: Creates a file in the local file system in the context of the Scriptable App
.iCloud: Creates a file in the iCloud area of the Scriptable App

Both methods return an instance of the FileManager. We will work with the iCloud variant below. This has the charming advantage that we can check the files created by the widget directly via the PC. If files were stored in the local file system of the smartphone, this would not be possible without further steps.

Reading and writing files is completely identical for both variants, there is only one exception. If a file has to be accessed from the iCloud, it may not be available locally yet. In this case, the file must first be downloaded from iCloud. This is done via the method

downloadFileFromiCloud: File name or the path to a file must be provided here.

If you only use the widget on one device, it is ensured after creation that the file is available locally and in the iCloud. However, if you want to use widget with two or more smartphones, the file would not be available on the second smartphone immediately and a downloadFileFromiCloud would be required before the first access.

How do you create a new file? First of all, we don’t want to store the follower statistics directly in the main directory of Scriptable, but rather use a separate subdirectory for our widget. This directory is created as follows:

let dir = fm.documentsDirectory();
var path = fm.joinPath(dir, "insta/");
if (!fm.fileExists(path)) {
   fm.createDirectory(path, false);
}

The following filemanager methods are used:

.documentsDirectory: Returns the path of the Scriptable App.
.joinPath: Method to add your own directories to the path.
.fileExists: Checks whether a directory or a file already exists.
.createDirectory: Creates a directory.

Now that we have a storage location, we only have to create a file in it. This is done as follows:

path += accountName + ".json";
fm.writeString(path, JSON.stringify(followers));

First, in this example, we add a file name to the path used. We use the name of the Instagram account for our widget. Theoretically, the widget could be set up on one device for more than one account. Using the file name ensures that the different widgets do not overwrite each other’s data.

Important: .writeString creates the file to be written. If the file already exists, it will be overwritten!

We can read the file analogously to the write access as follows:

var jsonString = fm.readString(path);

Before reading the file, it should always be checked with .fileExists whether the file really exists, otherwise an exception will occur.

Doing statistics

Now that you have the basics of reading and writing files, here’s just a brief outline of how statistics are recorded.

Each recorded number of followers is stored in a data object with a timestamp. This data object is saved as JSON in a file when the widget is terminated and is then read in again accordingly when the widget is started. The available database of follower data grows over time. Of course, this also means that when the widget is started for the first time, no changes to the previous day can be displayed; this will only work on the following day. The same applies of course to the weekly and monthly statistics, which will only be available with a corresponding time delay.