iOS Widgets for Untis using Scriptable to display the most important information about school life directly on the homescreen.
Untis is a service used by many students (mainly in Austria and Germany) to keep track of their school-life, especially for checking the timetable. There is a mobile app, but it does not provide any proper widgets, at least on iOS. That's why I decided to create those widgets myself, so I could have the most important information directly on my homescreen. It also sends notifications about important changes in the timetable or new grades!
If you have encountered an issue with the widget, open an issue in this repository (in the issue tab).
Please attach the log from running the script!
It can be obtained by opening the script via the three dots, running it, opening the log at the bottom. Copy-paste it and add it to the issue surrounded by three backticks (```) for readability.
Untis does not support 3rd-party software, therefore this project may not work as flawless as we would like.
Also, Scriptable is rather limited - another reason why not everything may be perfect.
As I have graduated from school already, I am not using the widget anymore and will not implement new features. However, I am happy to help where possible and PRs are welcome!
Installation.mp4
-
Before installing the script, you need to install Scriptable from the App Store.
-
You can download the latest version of the script here.
Alternatively, you can head over to the releases page to download a specific release. -
After downloading the file, click share, and select scriptable. Now click
Add to My Scriptsat the bottom. -
Click the play button at the lower right (or click the script in the overview) to run the script, and select
💻 Show Widget. This will start the setup process.
You will be asked for the url, which you can find when selecting you school here. You might have to click the "switch school" button to get to the correct page.
The url should look something like this:https://<server>.webuntis.com/WebUntis/?school=<schoolname>#/basic/login. (with<server>and<schoolname>replaced) -
Now you can add an iOS widget for Scriptable and select the script in the options.
-
The widget should update automatically and display the information. 🥳 (might take a few seconds)
-
If you want to customize the widget (e.g. color the lessons), see the configuration section.
The script will check for updates every few hours.
Regular updates will be downloaded and installed automatically.
If you want to update manually, you can do so by running the script and selecting 🔄 Update Script in the menu.
When there is a breaking change, you will be notified and asked to update manually.
Check the releases page for more information about the changes.
The script allows you to display data for one WebUntis account in a widget, and will notify you about important changes.
You can set what information (views) should be displayed for each widget.
To safe battery and bandwidth, the data is updated at the start of every lesson and every few hours outside of school-hours.
The fetched data is cached for some time, so the script takes less time, bandwidth and battery to run.
Many things can be configured via the visual config editor or the configuration file untis-config.json in the scriptable folder, check the configuration section for details.
You will be notified about the following changes/events:
- Lessons (canceled, shifted, teacher changed, ...)
- Exams (upcoming)
- Grades (added)
- Absences (added)
Please understand that the notifications can only be sent as soon as the script runs the next time.
Shows the upcoming lessons, meaning their subject, when they begin and some special information. Lessons can be colored, and if there is enough space, the long subject-names and end-times are displayed. After a school day has ended, a summary of the next day is displayed. (list of subjects)
Shows the upcoming exams, meaning their subject and date. By default, exams are colored according to the subject configuration. The widget displays as much information as fits. You can configure how many days ahead the exams should be displayed and set a maximum count.
Displays the recent grades you received. (subject + mark) By default, grades are colored according to the subject configuration. The widget displays as much information as fits. You can configure how long grades should be displayed and set a maximum count.
Lists open (unexcused) absences with their date and duration. It also shows who created the absence, if there is enough space.
When long-pressing the widget, you see the iOS widget configuration.
In the Parameter field, you can enter the configuration for the widget.
The configuration is a list of the views you want to be displayed, separated by a comma.
For larger widgets, you can create multiple columns by separating the views with a pipe (|).
Example: lessons,exams or lessons|exams,grades,absences
The config editor is a UI utility, so you don't have to deal with the configuration file directly.
You can open it by running the script and selecting ⚙️ Open Settings in the menu.
It will open up a list with settings categories. The top row shows you where you are in the menu, below there are the categories and settings.
Clicking a category will open it, clicking a setting will open a dialog to edit it.
If you change a value, the default will be displayed below it in gray.
You can use the ↩️ button to reset a setting to its default value.
The subjects config allows you to configure e.g. the colors of the lessons.
It is accessible in the config editor under 📚 Subjects Config.
You will now see a list of all subjects you have configurations for, listed by their short name. (might be empty)
You can delete a subject config by clicking the trash emoji (🗑️).
By clicking a subject, you can open its specific configuration.
Here are the configuration options:
color: The color of the lesson. You can either enter a hex code (like#ff0000) at the top, or select one from the palette. To find the perfect color, you can use this website. Darker, less saturated colors are recommended, as this makes it easier to read the white text on the background.short name: The short name of the subject to display.long name: The name of the subject to display if there is enough space (and the option is enabled).ignore infos: A list of lesson infos to ignore. This can be useful if there is lesson info which is always there. This should be a comma-separated list of the infos to ignore, wrapped in double quotes. ("infoName"or"info1", "info2")
At the top you can add a new subject configuration. You will have to enter the short subject name (the one displayed in webuntis.)
If you want to only apply the configuration when a specific teacher is teaching the subject, you can enter the teacher name as well.
This can be helpful when there are subjects which are combined in WebUntis.
Some subjects may be combined in Untis. For example, geography and history may be combined.
In the teachers section of a subject, you can create configs for specific teachers.
When this teachers now teaches this subject, the configuration of the teacher will override the one from the subject.
The configuration file untis-config.json is located in the scriptable folder.
A default configuration file is created when the script is run for the first time. Check it out to see what's possible!
Changes to the configuration file are applied when the script is run again.
For quite some time, all the code was in one file.
I was aware of how unpleasant this is and always wanted to split it up.
But I thought that this would kind of defeat the point of scriptable, since a bundled file is not really as readable.
In the end I decided to still split it, as this makes the source code way easier to read and maintain.
I tried to bundle it using webpack, but ran into some problems: The emitted code would not await the result, therefore Scriptable exited before the code was executed.
That's why I switched to rollup, which worked perfectly. The emitted code even is quite readable now, nearly as much as if it was written directly in javascript.
The config editor is a handy utility which makes the widget easier to use for people, who are not into editing config files.
But of the limitations of scriptable, and as the implementation had to be quite generalizable, the code is a little complex.
I am quite happy with the result, even though it has a few flaws, which I might address in the future.
Currently there seems to be an issue with github (similar to this one), where emojis in headers break anchor links.
Therefore the links to headers in this readme may not work.