iOS Workdays - Implementation of Filtering Legal Holidays Calendar Reminders#
Background#
Before the May Day holiday, when the author had to work on a Saturday, the alarm did not ring, and I almost overslept in the morning. The author's alarm was set for Monday to Friday, but the iPhone does not have a setting for legal holidays or compensatory days off... The author wanted to solve this pain point, dreaming that if it could be done and published to the store, I would reach the pinnacle of life and win big...
After some daydreaming, I went back and continued my research on implementing alarms for legal holidays. I found a lot of information and realized that I didn't need to dream anymore. First, iOS apps are not allowed to add alarms to the Clock app... Secondly, iOS does not have a judgment for legal holidays... So there was no need for daydreaming. However, I did find iOS Custom Alarm - Chinese Legal Holidays (Upgraded Version), which allows filtering of legal holidays through custom alarms using Shortcuts. The principle is: set an alarm, and then through the automatic execution of Shortcuts, check if the day is a holiday using a subscribed calendar maintained by others or a locally maintained calendar before the alarm time each day, and then decide whether to turn the alarm on or off. I have to say, it's really excellent.
Although the author's dream of getting rich was dashed... I thought of another idea. Although iOS apps cannot directly add alarms, they can directly add calendar reminders, such as for scheduled live broadcasts or flash sales, which actually just add events to the calendar and pop up reminders at specified times. So, could calendar reminders be used to implement reminders for legal workdays... For example, reminding to clock in every workday. Or just reminding about compensatory workdays, setting an alarm reminder the night before each compensatory workday.
Implementation#
Adding calendar reminders on the iPhone is quite simple, but the difficult part lies in judging the legal holidays in China. How can we filter out legal holidays and achieve reminders only on pure workdays?
Step 1: Create Recurring Events from Monday to Friday#
After some research, I found that there is an EKRecurrenceRule option in calendar reminders. Could this be used to implement it?
What is EKRecurrenceRule?
Official explanation:
A class that describes the recurrence pattern for a recurring event.
My understanding:
The repetition rules for recurring events. Simply put, it defines a repetition rule, such as repeating weekly, daily, or every few days, and then adds events according to this rule.
Seeing this, I felt a bit disheartened. For legal holidays in China, the repetition rules... cannot be found for lunar calendar holidays except for May Day, National Day, and New Year's Day... What to do? I thought, since I've come this far, let's just create a Monday to Friday event, which counts as completing half the requirement. The workday part is done, and the remaining part of filtering legal holidays and compensatory days can be looked at slowly; it's not like I won't do it 😂
Let's first look at setting up a recurring calendar event for every Monday to Friday.
Add Calendar Event
The steps to add a calendar event are as follows:
- Obtain read and write permissions for the calendar.
- Create a separate calendar.
- Generate the rule for Monday to Friday.
- Generate the calendar event based on the title, location, rule, and time.
- Add the event to the calendar, checking if the generated event has already been added; if it has, do nothing; if not, add it.
Let's look at each step:
-
Obtain read and write permissions for the calendar.
First, you need to add
Privacy - Calendars Usage Descriptionpermission in the plist, and then use the following code to request permission.lazy fileprivate var store = EKEventStore() // MARK: utils // Request calendar permission func requestEventAuth(_ callback:((Bool) -> Void)?) { store.requestAccess(to: EKEntityType.event) { granted, error in callback?(granted) } } -
Create a separate calendar.
This is to ensure that it does not conflict with other calendars and is convenient to hide or remove. It is recommended to define a separate calendar for each custom calendar event.
It sounds a bit convoluted. Open the iPhone, open the calendar, and then click the calendar button in the middle at the bottom to see all your calendars. As shown in the picture below, "Custom Events Calendar" is the calendar I created. All the calendar events I added will be in this calendar. If you don't want to see these events, you can simply uncheck the box in front, and the custom calendar events will not be displayed in the calendar. Or if you want to delete all events in this calendar, you just need to delete this calendar; there's no need to delete each event one by one. Click the prompt button on the right, and then scroll to the bottom to find the delete calendar button.
Ps: Silently complaining, I don't know why the reminders for scheduled flash sales and live broadcasts are not created in a separate calendar... After I scheduled them, I felt annoyed because I had to manually delete the events each time.
The code to create the calendar is as follows. Note the setting of the calendar's source; the source determines where the added calendar will be displayed.
// Create a new calendar func createNewCalendar() { guard let calendarId = MKCalendarReminderUtil.userDefaultsSaveStr(kCustomCalendarId), let _ = store.calendar(withIdentifier: calendarId) else { // Indicates that the current calendar has already been created locally return } let calendar = EKCalendar(for: EKEntityType.event, eventStore: store) for item in store.sources { if item.title == "iCloud" || item.title == "Default" { calendar.source = item break } } calendar.title = "Custom Events Calendar" // Custom calendar title calendar.cgColor = UIColor.systemPurple.cgColor // Custom calendar color do { try store.saveCalendar(calendar, commit: true) MKCalendarReminderUtil.saveToUserDefaults(kCustomCalendarId, valueStr: calendar.calendarIdentifier) } catch { print(error) } } -
Generate the rule for Monday to Friday.
Use
EKRecurrenceRuleto generate the rule for repeating every Monday to Friday. The usage ofEKRecurrenceRuleis as follows, where the parameters of the initializerEKRecurrenceRule(recurrenceWith:interval:daysOfTheWeek:daysOfTheMonth:monthsOfTheYear:weeksOfTheYear:daysOfTheYear:setPositions:end:)are as follows:- recurrenceWith: EKRecurrenceFrequency, represents the repetition frequency, which can be set to daily, weekly, monthly, or yearly.
- interval: Int, represents the repetition interval, how often it repeats, cannot be 0.
- daysOfTheWeek: [EKRecurrenceDayOfWeek], which days of the week to repeat. After setting this, it can be effective for all frequencies except daily.
- daysOfTheMonth: [number], number values from 1-31, can also be negative, where negative values indicate counting from the end of the month, e.g., -1 is the last day of the month. Only effective when the monthly frequency is set.
- monthsOfTheYear: [number], number values from 1-12, only effective when the yearly frequency is set.
- weeksOfTheYear: [number], number values from 1-53, can also be negative, where negative values indicate counting from the end of the year. Only effective when the yearly frequency is set.
- daysOfTheYear: [number], number values from 1-366, can also be negative, where negative values indicate counting from the end of the year. Only effective when the yearly frequency is set.
- setPositions: [number], number values from 1-366, can also be negative, where negative values indicate reverse calculation, filtering other rules' filters, effective after setting daysOfTheWeek, daysOfTheMonth, monthsOfTheYear, weeksOfTheYear, daysOfTheYear.
- end: EKRecurrenceEnd, the end date for repetition.
// Generate the repetition rule func generateEKRecurrenceRule() -> EKRecurrenceRule { let monday = EKRecurrenceDayOfWeek(EKWeekday.monday) let tuesday = EKRecurrenceDayOfWeek(EKWeekday.tuesday) let wednesday = EKRecurrenceDayOfWeek(EKWeekday.wednesday) let thursday = EKRecurrenceDayOfWeek(EKWeekday.thursday) let friday = EKRecurrenceDayOfWeek(EKWeekday.friday) // Set the repetition frequency to weekly, with an interval of repeating every week, repeating on Monday, Tuesday, Wednesday, Thursday, and Friday. let rule = EKRecurrenceRule(recurrenceWith: EKRecurrenceFrequency.weekly, interval: 1, daysOfTheWeek: [monday, tuesday, wednesday, thursday, friday], daysOfTheMonth: nil, monthsOfTheYear: nil, weeksOfTheYear: nil, daysOfTheYear: nil, setPositions: nil, end: nil) return rule } -
Generate calendar events based on title, location, notes, rule, and time.
When generating calendar events, pay attention to the duration of the event and whether to add alarm reminders. This alarm reminder is not the usual alarm; it is a schedule reminder. For example, if an alarm reminder is set for the event, it will ring and pop up in the notification bar when the alarm time is reached.
// Generate calendar event func generateEvent(_ title: String?, location: String?, notes: String?, timeStr: String?) -> EKEvent { let event = EKEvent(eventStore: store) event.title = title event.location = location event.notes = notes // Event time if let date = Date.date(from: timeStr, formatterStr: "yyyy-MM-dd HH:mm:ss") { // Start let startDate = Date(timeInterval: 0, since: date) // End let endDate = Date(timeInterval: 60, since: date) // Calendar reminder duration event.startDate = startDate event.endDate = endDate event.isAllDay = false } else { // All-day reminder event.isAllDay = true } // Add repetition rule let recurrenceRule = generateEKRecurrenceRule() event.addRecurrenceRule(recurrenceRule) // Add alarm (how many seconds before it starts); if positive, it means how many seconds after it starts. let alarm = EKAlarm(relativeOffset: 0) event.addAlarm(alarm) if let calendarId = MKCalendarReminderUtil.userDefaultsSaveStr(kCustomCalendarId), let calendar = store.calendar(withIdentifier: calendarId) { event.calendar = calendar } return event } -
Add the event to the calendar.
When adding, check if the generated event has already been added; if it has, do nothing; if not, add it. After successfully adding, store the event ID to avoid adding the same event repeatedly.
// Add event to calendar func addEvent(_ title: String?, location: String?, notes: String?, timeStr: String, eventKey: String) { requestEventAuth { [weak self] granted in if granted { // First create the calendar self?.createNewCalendar() // Check if the event exists if let eventId = MKCalendarReminderUtil.userDefaultsSaveStr(eventKey), let _ = self?.store.event(withIdentifier: eventId) { // Event already added return } else { if let event = self?.generateEvent(title, location: location, notes: notes, timeStr: timeStr) { do { try self?.store.save(event, span: EKSpan.thisEvent, commit: true) // After adding successfully, save the calendar key // Save in the sandbox to avoid repeated additions and other checks MKCalendarReminderUtil.saveToUserDefaults(eventKey, valueStr: event.eventIdentifier) } catch { print(error) } } } } } }
To call from outside, use the following code:
let date = Date.beijingDate()
let timeStr = Date.string(from: date, formatterStr: "yyyy-MM-dd HH:mm:ss")
MKCalendarReminderUtil.util.addEvent("Custom Title", location: "Shanghai Oriental Pearl", notes: "Remember to take a photo to clock in", timeStr: timeStr!, eventKey: "Custom Title")
A prompt will first pop up requesting access to the calendar. After clicking allow, it will be successfully added to the calendar, and you can see that there are events from that day onwards for every Monday to Friday.
Clicking on a specific date, you can see all events for that day, and click on the added event.
You can see the event's title, location, duration, repetition frequency, associated calendar, and notes.
At this point, the author has successfully added recurring reminders for Monday to Friday events, which counts as completing half the task. It can barely be used, but it will give incorrect reminders during holidays and compensatory workdays. So there is still the next part: how to incorporate the logic for holidays into the events?
Step 2: Add Legal Holiday Logic#
The author has always thought about adding the logic for legal holidays. Initially, I fell into a misunderstanding, always thinking about whether there is a rule that can automatically filter out holidays and add compensatory workdays, generating recurring calendar events. However, such a rule does not exist.
Referring to the implementation of holiday alarms using Shortcuts, I thought of another way. If there is no direct rule for holidays, can we take two steps? The first step is to create a fixed repetition logic for Monday to Friday; the second step is to obtain holiday and compensatory workday information from somewhere, and based on that information, "add more and subtract less," meaning removing events that fall on holidays from Monday to Friday and adding events for compensatory workdays that do not have calendar events.
Is this plan feasible? Practice makes perfect!
The steps are as follows:
-
Obtain holiday and compensatory workday information.
Where can we get holiday and compensatory workday information? The author searched online and finally found two suitable subscription sources: holiday-cn and Holiday API.- holiday-cn: Automatically scrapes announcements from the State Council daily, returning holiday and compensatory workday information.
- Holiday API: A privately maintained API that supports various API interface accesses, such as passing in months, dates, years, etc.
For the author, holiday-cn is sufficient, so I chose holiday-cn. Of course, if the company supports it, a set of holiday information can also be maintained on the company server to ensure consistency across all ends. It can even maintain a local JSON file on the client side, updating the local data after the holiday information for the next year comes out.
The returned holiday JSON format is as follows, where
nameis the holiday name,dateis the holiday date, andisOffDayindicates whether it is a day off, for example,2021-09-18is a compensatory workday for the Mid-Autumn Festival.{ "$schema":"https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/schema.json", "$id":"https://raw.githubusercontent.com/NateScarlet/holiday-cn/master/2021.json", "year":2021, "papers":[ "http://www.gov.cn/zhengce/content/2020-11/25/content_5564127.htm" ], "days":[ { "name":"New Year's Day", "date":"2021-01-01", "isOffDay":true }, { "name":"New Year's Day", "date":"2021-01-02", "isOffDay":true }, { "name":"New Year's Day", "date":"2021-01-03", "isOffDay":true }, { "name":"Spring Festival", "date":"2021-02-07", "isOffDay":false }, { "name":"Spring Festival", "date":"2021-02-11", "isOffDay":true }, { "name":"Spring Festival", "date":"2021-02-12", "isOffDay":true }, { "name":"Spring Festival", "date":"2021-02-13", "isOffDay":true }, { "name":"Spring Festival", "date":"2021-02-14", "isOffDay":true }, { "name":"Spring Festival", "date":"2021-02-15", "isOffDay":true }, { "name":"Spring Festival", "date":"2021-02-16", "isOffDay":true }, { "name":"Spring Festival", "date":"2021-02-17", "isOffDay":true }, { "name":"Spring Festival", "date":"2021-02-20", "isOffDay":false }, { "name":"Tomb-Sweeping Day", "date":"2021-04-03", "isOffDay":true }, { "name":"Tomb-Sweeping Day", "date":"2021-04-04", "isOffDay":true }, { "name":"Tomb-Sweeping Day", "date":"2021-04-05", "isOffDay":true }, { "name":"Labor Day", "date":"2021-04-25", "isOffDay":false }, { "name":"Labor Day", "date":"2021-05-01", "isOffDay":true }, { "name":"Labor Day", "date":"2021-05-02", "isOffDay":true }, { "name":"Labor Day", "date":"2021-05-03", "isOffDay":true }, { "name":"Labor Day", "date":"2021-05-04", "isOffDay":true }, { "name":"Labor Day", "date":"2021-05-05", "isOffDay":true }, { "name":"Labor Day", "date":"2021-05-08", "isOffDay":false }, { "name":"Dragon Boat Festival", "date":"2021-06-12", "isOffDay":true }, { "name":"Dragon Boat Festival", "date":"2021-06-13", "isOffDay":true }, { "name":"Dragon Boat Festival", "date":"2021-06-14", "isOffDay":true }, { "name":"Mid-Autumn Festival", "date":"2021-09-18", "isOffDay":false }, { "name":"Mid-Autumn Festival", "date":"2021-09-19", "isOffDay":true }, { "name":"Mid-Autumn Festival", "date":"2021-09-20", "isOffDay":true }, { "name":"Mid-Autumn Festival", "date":"2021-09-21", "isOffDay":true }, { "name":"National Day", "date":"2021-09-26", "isOffDay":false }, { "name":"National Day", "date":"2021-10-01", "isOffDay":true }, { "name":"National Day", "date":"2021-10-02", "isOffDay":true }, { "name":"National Day", "date":"2021-10-03", "isOffDay":true }, { "name":"National Day", "date":"2021-10-04", "isOffDay":true }, { "name":"National Day", "date":"2021-10-05", "isOffDay":true }, { "name":"National Day", "date":"2021-10-06", "isOffDay":true }, { "name":"National Day", "date":"2021-10-07", "isOffDay":true }, { "name":"National Day", "date":"2021-10-09", "isOffDay":false } ] }The code is as follows:
fileprivate func filterHolidayInfo(with title: String?, location: String?, notes: String?, timeStr: String, eventKey: String) { guard let url = URL(string: "https://natescarlet.coding.net/p/github/d/holiday-cn/git/raw/master/2021.json") else { return } let task = URLSession.shared.dataTask(with: url) { [weak self] (data, response, error) in guard let data = data else { return } do { if let jsonResult = try JSONSerialization.jsonObject(with: data, options: JSONSerialization.ReadingOptions.mutableContainers) as? NSDictionary, let days = jsonResult["days"] as? [NSDictionary] { // Filter holidays self?.handleHolidayInfo(with: days, title: title, location: location, notes: notes, timeStr: timeStr, eventKey: eventKey) } } catch { print(error) } } task.resume() } -
"Add more and subtract less."
This means removing events that fall on holidays from Monday to Friday and adding events for compensatory workdays that do not have calendar events. Here, it is necessary to check whether there is a current event on a certain date.
// Check if there is a specified event on a certain day fileprivate func eventExist(on tdate: Date?, eventKey: String) -> EKEvent? { var resultEvent: EKEvent? guard let date = tdate else { return resultEvent } let endDate = date.addingTimeInterval(TimeInterval(24 * 60 * 60)) guard let calendarId = MKCalendarReminderUtil.userDefaultsSaveStr(kCustomCalendarId), let eventId = MKCalendarReminderUtil.userDefaultsSaveStr(eventKey), let calendar = store.calendar(withIdentifier: calendarId) else { return resultEvent } let predicate = store.predicateForEvents(withStart: date, end: endDate, calendars: [calendar]) let events = store.events(matching: predicate) for event in events { if event.eventIdentifier == eventId { resultEvent = event break } } return resultEvent } // "Add more and subtract less." fileprivate func handleHolidayInfo(with days: [NSDictionary], title: String?, location: String?, notes: String?, timeStr: String, eventKey: String) { for dayDic in days { if let dayStr = dayDic["date"] as? String, let date = Date.date(from: dayStr, formatterStr: "yyyy-MM-dd"), // Date let isOffDay = dayDic["isOffDay"] as? Bool { // Is it a workday? let interval = date.timeIntervalSince(date) // 1. Check if the retrieved date is earlier than the current date, indicating it is a past date, do not process. // 2. Check if the date is greater than or equal to the current date, then check if it is a holiday, and check if there is an event to be added on that date. // 3. If it is a holiday and there is an event, remove the event. // 4. If it is not a holiday and there is no event, add the event. if interval < 0 { continue } else { if let targetEvent = eventExist(on: date, eventKey: eventKey) { // Event exists if isOffDay { // Holiday do { try store.remove(targetEvent, span: EKSpan.thisEvent) } catch { print(error) } } } else { // Event does not exist if !isOffDay { // Non-holiday, meaning compensatory workday let event = generateEvent(title, location: location, notes: notes, timeStr: timeStr) do { try store.save(event, span: EKSpan.thisEvent) } catch { print(error) } } } } } } }
One thing to note here is that in the generateEvent method, I added the repetition rule. If I don't modify it, there will be issues when calling the method to generate events for compensatory workdays. Therefore, the logic for the event repetition rule should be extracted from the general generateEvent method and placed before the save in the addEvent method.
Finally, after running and debugging, the calling code is as follows:
let date = Date.beijingDate()
let timeStr = Date.string(from: date, formatterStr: "yyyy-MM-dd HH:mm:ss")
MKCalendarReminderUtil.util.addEvent("Custom Title 2", location: "Shanghai Oriental Pearl 2", notes: "Remember to take a photo to clock in 2", timeStr: timeStr!, eventKey: "Custom Title 2", filterHoliday: true)
The final result is as follows:
You can see that the logic for the Mid-Autumn Festival and National Day from Monday to Friday is working well; the previous events have been removed. However, for compensatory workdays, such as September 18 and September 26, the events have not been added? What’s going on? Could it be that adding events failed? After debugging, I found that it was not the case; the events were successfully added, but the compensatory workdays did not have events in the calendar. Hmm...
Looking back at the code for adding compensatory workday events:
// Event does not exist
if !isOffDay { // Non-holiday, meaning compensatory workday
let event = generateEvent(title, location: location, notes: notes, timeStr: timeStr)
do {
try store.save(event, span: EKSpan.thisEvent)
} catch {
print(error)
}
}
The event is being added based on title, location, notes, and time. Oh... the time is wrong; this should be the date of the compensatory workday, not the initial date... So looking at the current date, I should find that the events were all added to that day.
Therefore, this part needs to be modified to retrieve the hour and minute from the passed-in date and concatenate it with the compensatory workday date as the date to be set. The modification is as follows:
// Event does not exist
if !isOffDay { // Non-holiday, meaning compensatory workday
var targetDateStr = dayStr
if let lastComponentStr = timeStr.components(separatedBy: " ").last {
targetDateStr = String(format: "%@ %@", dayStr, lastComponentStr)
}
let event = generateEvent(title, location: location, notes: notes, timeStr: targetDateStr)
do {
try store.save(event, span: EKSpan.thisEvent)
} catch {
print(error)
}
}
Finally, after debugging and running, success hinges on this moment, haha, bingo, perfect.
Code repository: MKReminderUtil
Summary:#
Using this method to generate calendar reminders, one more point to consider is how to update when the holiday data changes. The author feels that it would be better to maintain a set of holiday data on the server. When returning holiday data, also return the corresponding version number. This way, after requesting, compare the version; if the holiday data has not been updated, no action is needed. If there is an update, silently create the calendar for the next year based on the updated data.