device_calendar 3.0.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 96

Device Calendar Plugin #

pub package Build Status

A cross platform plugin for modifying calendars on the user's device.

Features #

  • Ability to request permissions to modify calendars on the user's device
  • Ability to check if permissions to modify the calendars on the user's device have been granted
  • Retrieve calendars on the user's device
  • Retrieve events associated with a calendar
  • Ability to add, update or delete events from a calendar
  • Ability to set up recurring events (NOTE: deleting a recurring event will currently delete all instances of it)
  • Ability to add, modify or remove attendees and receive if an attendee is an organiser for an event
  • Ability to setup reminders for an event

Android Integration #

The following will need to be added to the manifest file for your application to indicate permissions to modify calendars a needed

<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />

If you have Proguard enabled, you may need to add the following to your configuration (thanks to Britannio Jarrett who posted about it here)

-keep class com.builttoroam.devicecalendar.** { *; }

If you want to enable Proguard, please refer to the guide at Android Developer page

IMPORTANT: Since version 0.1.0, this version has migrated to use AndroidX instead of the deprecated Android support libraries. When using version 0.10.0 and onwards for this plugin, please ensure your application has been migrated following the guide here

iOS Integration #

For iOS 10 support, you'll need to modify the Info.plist to add the following key/value pair

<key>NSCalendarsUsageDescription</key>
<string>INSERT_REASON_HERE</string>

Note that on iOS, this is a Swift plugin. There is a known issue being tracked here by the Flutter team, where adding a plugin developed in Swift to an Objective-C project causes problems. If you run into such issues, please look at the suggested workarounds there.

Changelog #

3.0.0 21st January 2020 #

  • BREAKING CHANGE Properties for the attendee model in attendee.dart file have been changed:
    • Boolean property isRequired has been replaced to AttendeeRole enum
    • New arugment added for AttendeeRole property
  • BREAKING CHANGE Package updates:
    • [Android] Updated Gradle plugin to 3.5.2 and Gradle wrapper to 5.4.1
    • [iOS] Updated Swift to 5
  • name and isOrganiser (read-only) properties have been added
  • Attendee UI update for the example app
  • Ability to add, modify or remove an attendee

2.0.0 17th January 2020 #

  • BREAKING CHANGE The recurrence models in recurrence_rule.dart file have been chaged
  • BREAKING CHANGE All articles used in property names or arugments have been removed (i.e. enum DayOfTheWeek to DayOfWeek)
  • Recurrence fix for monthly and yearly frequencies
  • UI update for the example app
  • Add support for all day events

1.0.0+3 9th January 2020 #

  • Flutter upgrade to 1.12.13
  • Added an URL input for calendar events for issue 132

1.0.0+2 30th August 2019 #

  • Fix home page URL

1.0.0+1 30th August 2019 #

  • Add integration tests to example app. Note that this is more for internal use at the moment as it currently requires an Android device with a calendar that can be written to and assumes that the tests are executed from a Mac.

1.0.0 28th August 2019 #

  • BREAKING CHANGE retrieveCalendars and retrieveEvents now return lists that cannot be modified (UnmodifiableListView) to address part of issue 113
  • Support for more advanced recurrence rules
  • Update README to include information about using ProGuard for issue 99
  • Made event title optional to fix issue 72
  • Return information about the organiser of the event as per issue 73
  • Return attendance status of attendees and if they're required for an event. These are details are different across iOS and Android and so are returned within platform-specific objects
  • Ability to modify attendees for an event
  • Ability to create reminders for events expressed in minutes before the event starts

0.2.2 19th August 2019 #

  • Add support for specifying the location of an event. Thanks to oli06 and zemanux for submitting PRs to add the functionality to iOS and Android respectively

0.2.1+1 5th August 2019 #

  • Fixing date in changelog for version 0.2.1

0.2.1 5th August 2019 #

  • [Android] Fixes issue 101 where plugin results in a crash with headless execution

0.2.0 30th July 2019 #

  • BREAKING CHANGE [Android] Updated to use Gradle plugin to 3.4.2, Gradle wrapper to 5.1.1, Kotlin version to 1.3.41 and bumped Android dependencies
  • Add initial support for recurring events. Note that currently editing or deleting a recurring event will affect all instances of it. Future releases will look at supporting more advanced recurrence rules
  • Remove old example app to avoid confusion

0.1.3 5th July 2019 #

  • [iOS] Fixes issue 94 that occurred on 32-bit iOS devices around date of events. Thanks to the PR submitted by duzenko

0.1.2+2 28th May 2019 #

  • Non-functional release. Minor refactoring in Android code to address issues found in Codefactor and fix build status badge in README

0.1.2+1 17th May 2019 #

  • Non-functional release. Fixed formatting in changelog and code comments
  • Added more info about potential issues in consuming the plugin within an Objective-C project

0.1.2 - 16th May 2019 #

  • [Android] An updated fix to address issue 79, thanks to the PR submitted by Gerry High

0.1.1 - 1st March 2019 #

  • Fixed issue 79 where on Android, the plugin was indicating that it was handling permissions that it shouldn't have

0.1.0 - 26th February 2019 #

  • BREAKING CHANGE Migrated to the plugin to use AndroidX instead of the deprecated Android support libraries. Please ensure you have migrated your application following the guide here
  • BREAKING CHANGE Updated Kotlin to version 1.3.21
  • BREAKING CHANGE Updated Gradle plugin to 3.3.1 and distribution to 4.10.2

0.0.8 - 26th February 2019 #

  • This was a breaking change that should've been incremented as minor version update instead of a patch version update. See changelog for 0.1.0 for the details of this update

0.0.7 - 16th November 2018 #

  • Fixes issue ##67 and ##68. Thanks to PR submitted by huzhiren.

0.0.6 - 18th June 2018 #

  • [iOS] Fix an issue when adding/updating an event with a null description

0.0.5 - 14th June 2018 #

  • [Android] Fixed an issue with retrieving events by id only

0.0.4 - 12th June 2018 #

  • Reordering changelog
  • Creating new example for the Pub Dart Example tab
  • Moving existing example to the example_app GitHub folder

0.0.2 - 0.0.3 - 7th June 2018 #

  • Fixing incorrect Travis build links

0.0.1 - 7th June 2018 #

  • Ability to retrieve device calendars
  • CRUD operations on calendar events

example/README.md

device_calendar_example #

Demonstrates how to use the device_calendar plugin.

Getting Started #

For help getting started with Flutter, view our online documentation.

Attendees Parameters #

Examples below present on how to initialise an Attendee model in Dart:

  • A required attendee:

      Attendee(
          name: 'Test User 1',
          emailAddress: 'test1@example.com',
          role: AttendeeRole.Required);
    
  • An optional attendee:

      Attendee(
          name: 'Test User 2',
          emailAddress: 'test2@example.com',
          role: AttendeeRole.Optional);
    

Recurrence Rule Parameters #

Examples below present sample parameters of recurrence rules received by each platform and required properties for the RecurrenceRule model in Dart.
Please note that receiving monthly and yearly recurrence parameters are slightly different for the two platforms.
You can find more standard examples at iCalendar.org.

Daily Rule #

Daily every 5 days and end after 3 occurrences

  • Recurrence parameter example (Android and iOS):
    FREQ=DAILY;INTERVAL=5;COUNT=3

  • Dart example:

      RecurrenceRule(
          RecurrenceFrequency.Daily,
          interval: 5,
          totalOccurrences: 3);
    

Weekly Rule #

Weekly on Monday, Tuesday and Saturday every 2 weeks and end on 31 Jan 2020

  • Recurrence parameter example (Android and iOS):
    FREQ=WEEKLY;BYDAY=MO,TU,SA;INTERVAL=2;UNTIL=20200130T130000Z

  • Dart example:

      RecurrenceRule(
          RecurrenceFrequency.Weekly,
          interval: 2,
          endDate: DateTime(2020, 1, 31),
          daysOfWeek: [ DayOfWeek.Monday, DayOfWeek.Tuesday, DayOfWeek.Saturday ]);
    

Monthly/Yearly SetPosition (Week Number) Rule #

Monthly on third Thursday

  • Recurrence parameter example (Android):
    FREQ=MONTHLY;INTERVAL=1;BYDAY=3TH

  • Recurrence parameter example (iOS):
    FREQ=MONTHLY;INTERVAL=1;BYDAY=TH;BYSETPOS=3

  • Dart example:

      RecurrenceRule(
          RecurrenceFrequency.Monthly,
          interval: 1,
          daysOfWeek: [ DayOfWeek.Thursday ],
          weekOfMonth: WeekNumber.Third);
    

Monthly on last Thursday

  • Recurrence parameter example (Android and iOS):
    FREQ=MONTHLY;INTERVAL=1;BYDAY=-1TH

  • Dart example:

      RecurrenceRule(
          RecurrenceFrequency.Monthly,
          interval: 1,
          daysOfWeek: [ DayOfWeek.Thursday ],
          weekOfMonth: WeekNumber.Last);
    

Yearly on third Thursday of January

  • Recurrence parameter example (Android and iOS):
    FREQ=YEARLY;INTERVAL=1;BYMONTH=1;BYDAY=3TH

  • Dart example:

      RecurrenceRule(
          RecurrenceFrequency.Yearly,
          interval: 1,
          monthOfYear: MonthOfYear.January,
          weekOfMonth: WeekNumber.Third);
    

Yearly on last Thursday of January

  • Recurrence parameter example (Android and iOS):
    FREQ=YEARLY;INTERVAL=1;BYMONTH=1;BYDAY=-1TH

  • Dart example:

      RecurrenceRule(
          RecurrenceFrequency.Yearly,
          interval: 1,
          monthOfYear: MonthOfYear.January,
          weekOfMonth: WeekNumber.Last);
    

Monthly/Yearly By Day of a Month Rule #

Monthly on 8th

  • Recurrence parameter example (Android and iOS):
    FREQ=YEARLY;INTERVAL=1;BYMONTHDAY=8

  • Dart example:

      RecurrenceRule(
          RecurrenceFrequency.Monthly,
          interval: 1,
          dayOfMonth: 8);
    

Yearly on 8th of February

  • Recurrence parameter example (Android):
    FREQ=YEARLY;INTERVAL=1;BYMONTHDAY=8;BYMONTH=2

  • Recurrence parameter example (iOS):
    FREQ=YEARLY;INTERVAL=1

  • Dart example:

      RecurrenceRule(
          RecurrenceFrequency.Yearly,
          interval: 1,
          monthOfYear: MonthOfYear.February,
          dayOfMonth: 8);
    

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  device_calendar: ^3.0.0

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:device_calendar/device_calendar.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
92
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
96
Learn more about scoring.

We analyzed this package on Jan 21, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.0
  • pana: 0.13.4
  • Flutter: 1.12.13+hotfix.5

Health suggestions

Format lib/src/common/calendar_enums.dart.

Run flutter format to format lib/src/common/calendar_enums.dart.

Format lib/src/device_calendar.dart.

Run flutter format to format lib/src/device_calendar.dart.

Format lib/src/models/attendee.dart.

Run flutter format to format lib/src/models/attendee.dart.

Fix additional 5 files with analysis or formatting issues.

Additional issues in the following files:

  • lib/src/models/calendar.dart (Run flutter format to format lib/src/models/calendar.dart.)
  • lib/src/models/event.dart (Run flutter format to format lib/src/models/event.dart.)
  • lib/src/models/platform_specifics/android/attendee_details.dart (Run flutter format to format lib/src/models/platform_specifics/android/attendee_details.dart.)
  • lib/src/models/platform_specifics/ios/attendee_details.dart (Run flutter format to format lib/src/models/platform_specifics/ios/attendee_details.dart.)
  • lib/src/models/recurrence_rule.dart (Run flutter format to format lib/src/models/recurrence_rule.dart.)

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
flutter 0.0.0
meta ^1.1.8 1.1.8
Transitive dependencies
collection 1.14.11 1.14.12
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test
pedantic ^1.8.0+1