ical-generator
ical-generator is a small piece of code which generates ical calendar files. I use this to generate subscriptionable
calendar feeds.
Installation
npm install ical-generator
Quick Start
const ical = require('ical-generator');
const http = require('http');
const cal = ical({domain: 'github.com', name: 'my first iCal'});
cal.domain('sebbo.net');
cal.createEvent({
start: moment(),
end: moment().add(1, 'hour'),
summary: 'Example Event',
description: 'It works ;)',
location: 'my room',
url: 'http://sebbo.net/'
});
http.createServer(function(req, res) {
cal.serve(res);
}).listen(3000, '127.0.0.1', function() {
console.log('Server running at http://127.0.0.1:3000/');
});
Just another example
const ical = require('ical-generator');
const cal = ical({
domain: 'sebbo.net',
prodId: {company: 'superman-industries.com', product: 'ical-generator'},
name: 'My Testfeed',
timezone: 'Europe/Berlin'
});
cal.domain('sebbo.net');
cal.domain();
const event = cal.createEvent({
start: moment(),
end: moment().add(1, 'hour'),
timestamp: moment(),
summary: 'My Event',
organizer: 'Sebastian Pekarek <mail@example.com>'
});
event.summary('My Super Mega Awesome Event');
cal.toString();
ical({
domain: 'sebbo.net',
prodId: '//superman-industries.com//ical-generator//EN',
events: [
{
start: moment(),
end: moment().add(1, 'hour'),
timestamp: moment(),
summary: 'My Event',
organizer: 'Sebastian Pekarek <mail@example.com>'
}
]
}).toString();
API
ical-generator
ical([Object options])
Creates a new Calendar (ICalCalendar
).
const ical = require('ical-generator');
const cal = ical();
You can pass options to setup your calendar or use setters to do this.
const ical = require('ical-generator');
const cal = ical({domain: 'sebbo.net'});
const cal = ical().domain('sebbo.net');
const cal = ical();
cal.domain('sebbo.net');
Calendar
domain([String domain])
Use this method to set your server's hostname. It will be used to generate the feed's UID. Default hostname is your
server's one (require('os').hostname()
).
prodId([String|Object prodId])
Use this method to overwrite the default Product Identifier (//sebbo.net//ical-generator//EN
). prodId
can be either
a valid Product Identifier or an object:
cal.prodId({
company: 'My Company',
product: 'My Product',
language: 'EN'
});
cal.prodId('//My Company//My Product//EN');
name([String name])
Use this method to set your feed's name. Is used to fill NAME
and X-WR-CALNAME
in your iCal file.
url([String url])
Use this method to set your feed's URL.
const cal = ical().url('https://example.com/calendar.ical');
timezone([String timezone])
Use this method to set your feed's timezone. Is used to fill TIMEZONE-ID
and X-WR-TIMEZONE
in your iCal.
const cal = ical().timezone('Europe/Berlin');
method([String method])
Calendar method. May be any of the following: publish
, request
, reply
, add
, cancel
, refresh
, counter
, declinecounter
.
ttl([Number ttl])
Use this method to set your feed's time to live (in seconds). Is used to fill REFRESH-INTERVAL
and X-PUBLISHED-TTL
in your iCal.
const cal = ical().ttl(60 * 60 * 24);
createEvent([Object options])
Creates a new Event (ICalEvent
) and returns it. Use options to prefill the event's attributes.
Calling this method without options will create an empty event.
const ical = require('ical-generator');
const cal = ical();
const event = cal.createEvent({summary: 'My Event'});
event.summary('Your Event');
events([Object events])
Add Events to calendar or return all attached events.
const cal = ical();
cal.events([
{
start: new Date(),
end: new Date(new Date().getTime() + 3600000),
summary: 'Example Event',
description: 'It works ;)',
url: 'http://sebbo.net/'
}
]);
cal.events();
save(String file, Function cb)
Save Calendar to disk asynchronously using fs.writeFile. Won't work in browsers.
saveSync(String file)
Save Calendar to disk synchronously using fs.writeFileSync. Won't work in browsers.
serve(http.ServerResponse response, [String filename])
Send Calendar to the User when using HTTP. See Quick Start above. Won't work in browsers. Defaults to 'calendar.ics'
.
toURL()
Returns a download URL using the Blob. Only supported in browsers supporting this API.
toString()
Return Calendar as a String.
toJSON()
Return a shallow copy of the calendar's options for JSON stringification. Can be used for persistence.
const cal = ical();
const json = JSON.stringify(cal);
cal = ical(json);
length()
Returns the amount of events in the calendar.
clear()
Empty the Calender.
Event
uid([String|Number uid]) or id([String|Number id])
Use this method to set the event's ID. If not set, an UID will be generated randomly. When output, the ID will be suffixed with '@' + your calendar's domain.
sequence([Number sequence])
Use this method to set the event's revision sequence number of the
calendar component within a sequence of revisions.
start([moment|Date start])
Appointment date of beginning as Date object. This is required for all events!
end([moment|Date end])
Appointment date of end as Date object.
timezone([String timezone])
Use this method to set your event's timezone using the TZID property parameter on start and end dates, as per date-time form #3 in section 3.3.5 of RFC 554.
This and the 'floating' flag (see below) are mutually exclusive, and setting a timezone will unset the 'floating' flag. If neither 'timezone' nor 'floating' are set, the date will be output with in UTC format (see date-time form #2 in section 3.3.5 of RFC 554).
timestamp([moment|Date stamp]) or stamp([moment|Date stamp])
Appointment date of creation as Date object. Defaults to new Date()
.
allDay([Boolean allDay])
When allDay == true -> appointment is for the whole day
floating([Boolean floating])
Appointment is a "floating" time. From section 3.3.12 of RFC 554:
Time values of this type are said to be "floating" and are not
bound to any time zone in particular. They are used to represent
the same hour, minute, and second value regardless of which time
zone is currently being observed. For example, an event can be
defined that indicates that an individual will be busy from 11:00
AM to 1:00 PM every day, no matter which time zone the person is
in. In these cases, a local time can be specified.
This and the 'timezone' setting (see above) are mutually exclusive, and setting the floating flag will unset the 'timezone'. If neither 'timezone' nor 'floating' are set, the date will be output with in UTC format (see date-time form #2 in section 3.3.5 of RFC 554).
repeating([Object repeating])
Appointment is a repeating event
event.repeating({
freq: 'MONTHLY',
count: 5,
interval: 2,
until: new Date('Jan 01 2014 00:00:00 UTC'),
byDay: ['su', 'mo'],
byMonth: [1, 2],
byMonthDay: [1, 15],
bySetPos: 3,
exclude: [new Date('Dec 25 2013 00:00:00 UTC')]
});
recurrenceId([moment|Date stamp])
Recurrence date as Date object.
summary([String summary])
Appointment summary, defaults to empty string.
description([String description])
Appointment description
htmlDescription([String htmlDescription])
Some calendar apps may support HTML descriptions. Like in emails, supported HTML tags and styling is limited.
location([String location])
Appointment location
geo([String|Object geo])
Appointment geo position (gps). See rfc for more details
cal.geo({
lat: 44.4987,
lon: -6.87667
});
cal.geo('44.4987;-6.87667');
organizer([String|Object organizer])
Appointment organizer
event.organizer({
name: 'Organizer\'s Name',
email: 'organizer@example.com'
});
event.organizer('Organizer\'s Name <organizer@example.com>');
You can also add an explicit mailto
email address.
event.organizer({
name: 'Organizer\'s Name',
email: 'organizer@example.com',
mailto: 'explicit@mailto.com'
})
createAttendee([Object options])
Creates a new Attendee (ICalAttendee
) and returns it. Use options to prefill the attendee's attributes.
Calling this method without options will create an empty attendee.
const ical = require('ical-generator');
const cal = ical();
const event = cal.createEvent();
const attendee = event.createAttendee({email: 'hui@example.com', name: 'Hui'});
attendee.email('hui@example.net');
event.createAttendee('Buh <buh@example.net>');
As with the organizer, you can also add an explicit mailto
address.
event.createAttendee({email: 'hui@example.com', name: 'Hui', mailto: 'another@mailto.com'});
attendee.mailto('another@mailto.net');
attendees([Object attendees])
Add Attendees to the event or return all attached attendees.
const event = ical().createEvent();
cal.attendees([
{email: 'a@example.com', name: 'Person A'},
{email: 'b@example.com', name: 'Person B'}
]);
cal.attendees();
createAlarm([Object options])
Creates a new Alarm (ICalAlarm
) and returns it. Use options to prefill the alarm's attributes.
Calling this method without options will create an empty alarm.
const ical = require('ical-generator');
const cal = ical();
const event = cal.createEvent();
const alarm = event.createAlarm({type: 'display', trigger: 300});
event.createAlarm({
type: 'audio',
trigger: 300,
});
alarms([Object alarms])
Add alarms to the event or return all attached alarms.
const event = ical().createEvent();
cal.alarms([
{type: 'display', trigger: 600},
{type: 'audio', trigger: 300}
]);
cal.attendees();
createCategory([Object options])
Creates a new Category (ICalCategory
) and returns it. Use options to prefill the categories' attributes.
Calling this method without options will create an empty category.
const ical = require('ical-generator');
const cal = ical();
const event = cal.createEvent();
const category = event.createCategory({name: 'APPOINTMENT'});
event.createCategory({
name: 'MEETING'
});
categories([Object categories])
Add categories to the event or return all selected categories.
const event = ical().createEvent();
cal.categories([
{name: 'APPOINTMENT'},
{name: 'MEETING'}
]);
cal.categories();
url([String url])
Appointment URL
status([String status])
Appointment status. May be any of the following: confirmed
, tentative
, cancelled
.
busystatus([String busystatus])
Appointment busystatus. May be any of the following: free
, tentative
, busy
, oof
.
created([moment|Date created])
Date object of the time the appointment was created.
lastModified([moment|Date lastModified])
Date object of the time the appointent was modified last.
Attendee
name([String name])
Use this method to set the attendee's name.
email([String email])
The attendee's email address. An email address is required for every attendee!
rsvp([String rsvp])
Set the attendee's RSVP expectation. May be one of the following: true
, false
role([String role])
Set the attendee's role, defaults to REQ-PARTICIPANT
. May be one of the following: chair
, req-participant
, opt-participant
, non-participant
status([String status])
Set the attendee's status. May be one of the following: accepted
, tentative
, declined
, delegated
, needs-action
(See Section 4.2.12)
type([String type])
Set the attendee's type. May be one of the following: individual
, group
, resource
, room
, unknown
(See Section 4.2.3)
delegatesTo(ICalAttendee|Object attendee)
Creates a new Attendee if the passed object is not already an attendee. Will set the delegatedTo and delegatedFrom attributes.
const cal = ical();
const event = cal.createEvent();
const attendee = cal.createAttendee();
attendee.delegatesTo({email: 'foo@bar.com', name: 'Foo'});
delegatesFrom(ICalAttendee|Object attendee)
Creates a new Attendee if the passed object is not already an attendee. Will set the delegatedTo and delegatedFrom attributes.
const cal = ical();
const event = cal.createEvent();
const attendee = cal.createAttendee();
attendee.delegatesFrom({email: 'foo@bar.com', name: 'Foo'});
Alarm
type([String type])
Use this method to set the alarm type. Right now, audio
and display
are supported.
trigger([Number|moment|Date trigger]) / triggerBefore([Number|moment|Date trigger])
Use this method to set the alarm time.
const cal = ical();
const event = cal.createEvent();
const alarm = cal.createAlarm();
alarm.trigger(600);
alarm.trigger(new Date());
triggerAfter([Number|moment|Date trigger])
Use this method to set the alarm time.
const cal = ical();
const event = cal.createEvent();
const alarm = cal.createAlarm();
alarm.triggerAfter(600);
alarm.triggerAfter(new Date());
repeat([Number repeat])
Use this method to repeat the alarm.
const cal = ical();
const event = cal.createEvent();
cal.createAlarm({
repeat: 4,
interval: 300
});
interval([Number interval])
Use this method to set the alarm's interval.
const cal = ical();
const event = cal.createEvent();
cal.createAlarm({
repeat: 4,
interval: 300
});
attach([String|Object attach])
Alarm attachment; used to set the alarm sound if type = audio. Defaults to "Basso".
const cal = ical();
const event = cal.createEvent();
event.createAlarm({
attach: 'https://example.com/notification.aud'
});
event.createAlarm({
attach: {
uri: 'https://example.com/notification.aud',
mime: 'audio/basic'
}
});
description([String| description])
Alarm description; used to set the alarm message if type = display. Defaults to the event's summary.
Category
name([String name])
Use this method to set the category name.
Tests
npm test
npm run coverage
npm run browser-test
FAQ
What's Error: Can't resolve 'fs'
?
ical-generator
uses the node.js fs
module to save your calendar on the filesystem. In browser environments, you usually don't need this, so if you pass null
for fs in your bundler. In webpack this looks like this:
{
"node": {
"fs": "empty"
}
}
Thanks @rally25rs for this tip.
Copyright and license
Copyright (c) Sebastian Pekarek under the MIT license.