Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/eddyverbruggen/nativescript-calendar
:date: NativeScript plugin to Create, Delete and Find Events in the native Calendar
https://github.com/eddyverbruggen/nativescript-calendar
agenda calendar event nativescript
Last synced: 2 months ago
JSON representation
:date: NativeScript plugin to Create, Delete and Find Events in the native Calendar
- Host: GitHub
- URL: https://github.com/eddyverbruggen/nativescript-calendar
- Owner: EddyVerbruggen
- License: mit
- Created: 2015-12-22T06:11:34.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-01-14T01:06:23.000Z (almost 2 years ago)
- Last Synced: 2024-10-16T22:36:24.860Z (3 months ago)
- Topics: agenda, calendar, event, nativescript
- Language: TypeScript
- Homepage:
- Size: 12.2 MB
- Stars: 46
- Watchers: 5
- Forks: 11
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# NativeScript Calendar Plugin
[![Build Status][build-status]][build-url]
[![NPM version][npm-image]][npm-url]
[![Downloads][downloads-image]][npm-url]
[![Twitter Follow][twitter-image]][twitter-url]
[build-status]:https://travis-ci.org/EddyVerbruggen/nativescript-calendar.svg?branch=master
[build-url]:https://travis-ci.org/EddyVerbruggen/nativescript-calendar
[npm-image]:http://img.shields.io/npm/v/nativescript-calendar.svg
[npm-url]:https://npmjs.org/package/nativescript-calendar
[downloads-image]:http://img.shields.io/npm/dm/nativescript-calendar.svg
[twitter-image]:https://img.shields.io/twitter/follow/eddyverbruggen.svg?style=social&label=Follow%20me
[twitter-url]:https://twitter.com/eddyverbruggen
The Calendar plugin allows you to manipulate events in the user's native Calendar. You can find, create and delete events in either the default or a custom calendar.
If you're looking for an awesome in-app UI for the native calendar, then [check this out](http://docs.telerik.com/devtools/nativescript-ui/Controls/NativeScript/Calendar/overview).
## Installation
From the command prompt go to your app's root folder and execute:
#### NativeScript 7
```
tns plugin add nativescript-calendar
```
#### NativeScript 6
```
tns plugin add [email protected]
```
## iOS runtime permission reason
You probably have seen a permission popup like this before (this plugin will trigger one as well, automatically):
iOS 10+ requires not only this popup, but also a _reason_. In this case it's "Custom message from App_Resources".
You can provide your own reason for accessing the calendar by adding something like this to `app/App_Resources/ios/Info.plist`:
```xml
NSCalendarsUsageDescription
My reason justifying fooling around with your calendar
```
_To not crash your app in case you forgot to provide the reason this plugin adds an empty reason to the `.plist` during build. This value gets overridden by anything you specified yourself. You're welcome._
## TypeScript Usage
Of course you can use this plugin with TypeScript, just import the plugin and use
the functions summed up below like this:
```typescript
import * as Calendar from "nativescript-calendar";
// example for listCalendars:
Calendar.listCalendars().then(/* .. */);
```
## Usage
If you want a quickstart, [clone our demo app](https://github.com/EddyVerbruggen/nativescript-calendar-demo).
### createEvent
```js
var Calendar = require("nativescript-calendar");
// Only the `title`, `startDate` and `endDate` are mandatory, so this would suffice:
var options = {
title: 'Get groceries',
// Make sure these are valid JavaScript Date objects.
// In this case we schedule an Event for now + 1 hour, lasting 1 hour.
startDate: new Date(new Date().getTime() + (60*60*1000)),
endDate: new Date(new Date().getTime() + (2*60*60*1000))
};
// You can however add lots of properties to enrich the Event:
options.location = 'The shop';
options.notes = 'This event has reminders';
// iOS has a separate 'url' field, but on Android the plugin appends this to the 'notes' field.
options.url = 'http://my.shoppinglist.com';
// You can also override the default reminder(s) of the Calendar (in minutes):
options.reminders = {
first: 30,
second: 10
};
// You can make this Event recurring (this one repeats every other day for 10 days):
options.recurrence = {
frequency: "daily", // daily | weekly | monthly | yearly
interval: 2, // once every 2 days
endDate: new Date(new Date().getTime() + (10*24*60*60*1000)) // 10 days
};
// Want to use a custom calendar for your app? Pass in the 'name'.
// If the name doesn't yet exist the plugin will create it for you.
options.calendar = {
name: "NativeScript Cal",
// the color, in this case red
color: "#FF0000",
// Can be used on Android to group the calendars. Examples: Your app name, or an emailaddress
accountName: "My App Name"
};
Calendar.createEvent(options).then(
function(createdId) {
console.log("Created Event with ID: " + createdId);
},
function(error) {
console.log("Error creating an Event: " + error);
}
);
```
If you want an 'all day event', make sure you set the dates to midnight like this:
```js
var d = new Date();
d.setHours(0);
d.setMinutes(0);
d.setSeconds(0);
// this will create an 'all day event' for tomorrow
var startDate = new Date(d.getTime() + (24*60*60*1000));
var endDate = new Date(d.getTime() + (2*24*60*60*1000));
// .. now use these properties in the options object
```
### findEvents
```js
var options = {
// when searching, dates are mandatory - the event must be within this interval
startDate: new Date(new Date().getTime() - (50*24*60*60*1000)),
endDate: new Date(new Date().getTime() + (50*24*60*60*1000))
};
// if you know the Event ID, set it here:
options.id = '123456';
// you can optionally pass in a few other properties, any event containing these will be returned:
options.title = 'groceries';
options.location = 'foo';
options.notes = 'bar'; // iOS only
Calendar.findEvents(options).then(
function(events) {
console.log(JSON.stringify(events));
},
function(error) {
console.log("Error finding Events: " + error);
}
);
```
The returned 'events' object is an array of JSON events with these properties:
```js
id
title
location
notes
url
startDate
endDate
allDay
calendar {id, name}
reminders {minutes}
recurrence {frequency, interval, endDate}
attendees {name, email, url, status, role, type}
```
### deleteEvents
Usage is largely the same as findEvents, only the result is a bit different ;)
```js
var options = {
// when searching, dates are mandatory - the event must be within this interval
startDate: new Date(new Date().getTime() - (50*24*60*60*1000)),
endDate: new Date(new Date().getTime() + (50*24*60*60*1000))
};
// if you know the Event ID, set it here:
options.id = '123456';
// you can optionally pass in a few other properties, any event containing these will be deleted:
options.title = 'groceries'; // events _including_ this string will be included in the selection
options.location = 'foo';
options.notes = 'bar'; // iOS only
Calendar.deleteEvents(options).then(
function(deletedEventIds) {
console.log(JSON.stringify(deletedEventIds));
},
function(error) {
console.log("Error deleting Events: " + error);
}
)
```
### listCalendars
```js
Calendar.listCalendars().then(
function(calendars) {
// a JSON array of Calendar objects is returned, each with an 'id' and 'name'
console.log("Found these Calendars on the device: " + JSON.stringify(calendars));
},
function(error) {
console.log("Error while listing Calendars: " + error);
}
)
```
### deleteCalendar
##### TypeScript
```typescript
import * as Calendar from "nativescript-calendar";
Calendar.deleteCalendar({
name: "My Calendar name"
}).then(id => {
// id is null if nothing was deleted
console.log(`Deleted Calendar with id ${id}`);
});
```
## Breaking changes in 2.0.0
See [CHANGELOG.md](CHANGELOG.md).