Commit 5ea02554 authored by Sebastian Pekarek's avatar Sebastian Pekarek
Browse files

Merge branch 'develop'

parents c7d62ce5 53ad52bd
coverage/**
node_modules/**
\ No newline at end of file
{
"maxerr": 50,
"smarttabs": true,
"nonbsp": false,
"quotmark": "single",
"node": true,
"mocha": true
}
\ No newline at end of file
# ical-generator
[![License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
[![CI Status](https://sebbo.helium.uberspace.de/teamcity-badges/iCalGenerator_Develop/status)](https://ci.sebbo.net/viewType.html?buildTypeId=iCalGenerator_Develop&guest=1)
[![Code Coverage](https://sebbo.helium.uberspace.de/teamcity-badges/iCalGenerator_Develop/coverage-istanbul)](https://ci.sebbo.net/viewType.html?buildTypeId=iCalGenerator_Develop&guest=1)
[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
[![CI Status](https://sebbo.helium.uberspace.de/teamcity-badges/ICalGenerator_Develop/status)](https://ci.sebbo.net/viewType.html?buildTypeId=ICalGenerator_Develop&guest=1)
[![Test Coverage](https://sebbo.helium.uberspace.de/teamcity-badges/ICalGenerator_Develop/coverage-istanbul)](https://ci.sebbo.net/viewType.html?buildTypeId=ICalGenerator_Develop&guest=1)
ical-generator is a small piece of code which generates ical calendar files. I use this to generate subscriptionable calendar feeds.
ical-generator is a small piece of code which generates ical calendar files. I use this to generate subscriptionable
calendar feeds.
## Installation
......@@ -12,16 +13,26 @@ ical-generator is a small piece of code which generates ical calendar files. I u
npm install ical-generator
## Example
## Upgrade from 0.1.x
ical-generator 0.2.0 introduces a completely new API, but because you guys used 0.1.x a lot, the old API still works. So
you should be able to upgrade from ical-generator 0.1.x to 0.2.0 without any code changes. In case you need the old API
docs, you can find the deprecated documentation [here](https://github.com/sebbo2002/ical-generator/blob/0.1.10/README.md).
In case you have any issues with the new API, feel free to [create an issue](https://github.com/sebbo2002/ical-generator/issues/new).
## Quick Start
```javascript
var ical = require('ical-generator'),
http = require('http'),
cal = ical();
cal = ical({domain: 'github.com', name: 'my first iCal'});
cal.setDomain('sebbo.net').setName('my first iCal');
// overwrite domain
cal.domain('sebbo.net');
cal.addEvent({
cal.createEvent({
start: new Date(),
end: new Date(new Date().getTime() + 3600000),
summary: 'Example Event',
......@@ -32,73 +43,229 @@ cal.addEvent({
http.createServer(function(req, res) {
cal.serve(res);
}).listen(3000, '127.0.0.1');
console.log('Server running at http://127.0.0.1:3000/');
}).listen(3000, '127.0.0.1', function() {
console.log('Server running at http://127.0.0.1:3000/');
});
```
## Just another example
```javascript
var ical = require('ical-generator'),
// Create new Calendar and set optional fields
cal = ical({
domain: 'sebbo.net',
prodId: {company: 'superman-industries.com', product: 'ical-generator'},
name: 'My Testfeed',
timezone: 'Europe/Berlin'
});
// You can also set values like this…
cal.domain('sebbo.net');
// … or get values
cal.domain(); // --> "sebbo.net"
// create a new event
var event = cal.createEvent({
start: new Date(),
end: new Date(new Date().getTime() + 3600000),
timestamp: new Date(),
summary: 'My Event',
organizer: 'Sebastian Pekarek <mail@example.com>'
});
// like above, you can also set/change values like this…
event.summary('My Super Mega Awesome Event');
// get the iCal string
cal.toString(); // --> "BEGIN:VCALENDAR…"
// You can also create events directly with ical()
cal = ical({
domain: 'sebbo.net',
prodId: '//superman-industries.com//ical-generator//EN',
events: [
{
start: new Date(),
end: new Date(new Date().getTime() + 3600000),
timestamp: new Date(),
summary: 'My Event',
organizer: 'Sebastian Pekarek <mail@example.com>'
}
]
}).toString();
```
## API
### setDomain(domain)
### ical-generator
Use this method to set your server's hostname. It will be used to generate the feed's UID. Default hostname is localhost.
#### ical([_Object_ options])
Creates a new [Calendar](#calendar) ([`ICalCalendar`](#calendar)).
### setName(name)
```javascript
var ical = require('ical-generator'),
cal = ical();
```
Use this method to set your feed's name.
You can pass options to setup your calendar or use setters to do this.
```javascript
var ical = require('ical-generator'),
cal = ical({domain: 'sebbo.net'});
### setTZ(timezone)
// is the same as
Use this method to set your feed's timezone.
cal = ical().domain('sebbo.net');
// is the same as
### setProdID(prodID)
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()`).
This method is used to overwrite the default ProdID:
#### prodId([_String_|_Object_ prodId])
Use this method to overwrite the default Product Identifier (`//sebbo.net//ical-generator//EN`). `prodId` can be ether
a valid Product Identifier or an object:
```javascript
cal.setProdID({
cal.prodId({
company: 'My Company',
product: 'My Product',
language: 'EN'
language: 'EN' // optional, defaults to EN
});
// OR
cal.prodId('//My Company//My Product//EN');
```
### addEvent(options)
Add an event. Options is an plain object, that configure the event.
#### name([_String_ name])
#### options.uid (String)
Event UID. If not set, an UID will be generated randomly.
Use this method to set your feed's name. Is used to fill `X-WR-CALNAME` in your iCal file.
#### options.start (Date Object, required)
Appointment date of beginning
#### options.end (Date Object, required)
Appointment date of end
#### timezone([_String_ timezone])
#### options.repeating (Plain Object)
Appointment is a repeating event
Use this method to set your feed's timezone. Is used to fill `X-WR-TIMEZONE` in your iCal.
```javascript
cal.addEvent({
/* Other options */
repeating: {
freq: 'MONTHLY', // required
count: 5,
interval: 2,
until: new Date("Jan 01 2014 00:00:00 UTC")
}
});
var cal = ical().timezone('Europe/Berlin');
```
#### options.allDay (Bool)
Appointment is for the whole day
#### options.floating (Bool)
#### createEvent([_Object_ options])
Creates a new [Event](#event) ([`ICalEvent`](#event)) and returns it. Use options to prefill the event's attributes.
Calling this method without options will create an empty event.
```javascript
var ical = require('ical-generator'),
cal = ical(),
event = cal.createEvent({summary: 'My Event'});
// overwrite event summary
event.summary('Your Event');
```
#### events([_Object_ events])
Add Events to calendar or return all attached events.
```javascript
var 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(); // --> [ICalEvent]
```
#### save(**_String_ file**[, _Function_ cb])
Save Calendar to disk asynchronously using [fs.writeFile](http://nodejs.org/api/fs.html#fs_fs_writefile_filename_data_options_callback).
#### saveSync(**_String_ file**)
Save Calendar to disk synchronously using [fs.writeFileSync](http://nodejs.org/api/fs.html#fs_fs_writefilesync_filename_data_options).
#### serve(**_http.ServerResponse_ response**)
Send Calendar to the User when using HTTP. See Quick Start above.
#### toString()
Return Calendar as a String.
#### length()
Returns the ammount 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.
#### start([_Date_ start])
Appointment date of beginning as Date object. This is required for all events!
#### end([_Date_ end])
Appointment date of end as Date object. This is also required for all events!
#### timestamp([_Date_ stamp]) or stamp([_Date_ stamp])
Appointment date of creation as Date object. Default 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](https://tools.ietf.org/html/rfc5545#section-3.3.12):
> Time values of this type are said to be "floating" and are not
......@@ -109,78 +276,157 @@ Appointment is a "floating" time. From [section 3.3.12 of RFC 554](https://tools
> 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.
#### options.stamp (Date Object)
Appointment date of creation
#### options.summary (String, required)
Appointment summary
#### repeating([_Object_ repeating])
Appointment is a repeating event
```javascript
cal.repeating({
freq: 'MONTHLY', // required
count: 5,
interval: 2,
until: new Date('Jan 01 2014 00:00:00 UTC')
});
```
#### summary([_String_ summary])
Appointment summary, default to empty string.
#### description([_String_ description])
#### options.description (String)
Appointment description
#### options.location (String)
#### location([_String_ location])
Appointment location
#### options.organizer (Plain Object)
#### organizer([_String_|Object organizer])
Appointment organizer
```javascript
cal.addEvent({
start: new Date(),
end: new Date(new Date().getTime() + 3600000),
summary: 'Example Event',
description: 'Appointment with Organizer',
location: 'Room 123',
organizer: {
name: 'Organizer\'s Name',
email: 'organizer@example.com'
}
cal.organizer({
name: 'Organizer\'s Name',
email: 'organizer@example.com'
});
// OR
cal.organizer('Organizer\'s Name <organizer@example.com>');
```
#### createAttendee([_Object_ options])
Creates a new [Attendee](#attendee) ([`ICalAttendee`](#attendee)) and returns it. Use options to prefill the attendee's attributes.
Calling this method without options will create an empty attendee.
```javascript
var ical = require('ical-generator'),
cal = ical(),
event = cal.createEvent(),
attendee = event.createAttendee({email: 'hui@example.com', 'name': 'Hui'});
// overwrite attendee's email address
attendee.email('hui@example.net');
// add another attendee
event.createAttendee('Buh <buh@example.net>');
```
#### options.url (String)
Appointment Website
#### options.method (String)
#### attendees([_Object_ attendees])
Add Attendees to the event or return all attached attendees.
```javascript
var event = ical().createEvent();
cal.attendees([
{email: 'a@example.com', name: 'Person A'},
{email: 'b@example.com', name: 'Person B'}
]);
cal.attendees(); // --> [ICalAttendee, ICalAttendee]
```
#### url([_String_ url])
Appointment URL
#### method([_String_ method])
Appointment method. May be any of the following: publish, request, reply, add, cancel, refresh, counter, declinecounter.
#### options.status (String)
#### status([_String_ status])
Appointment status. May be any of the following: confirmed, tenative, cancelled.
### save(file[, cb])
Save Calendar to disk asynchronously using [fs.writeFile](http://nodejs.org/api/fs.html#fs_fs_writefile_filename_data_options_callback)
### Attendee
### saveSync(file)
Save Calendar to disk synchronously using [fs.writeFileSync](http://nodejs.org/api/fs.html#fs_fs_writefilesync_filename_data_options)
#### name([_String_ name])
Use this method to set the attendee's name.
### serve(response)
Send Calendar to the User when using HTTP. See example above.
#### email([_String_ email])
### toString()
Return Calendar as a String.
The attendee's email address. An email address is required for every attendee!
### length()
Returns the ammount of events in the calendar.
### clear()
Empty the Calender.
#### role([_String_ role])
Set the attendee's role, defaults to `REQ-PARTICIPANT`. May be one of the following: req-participant, non-participant
## Tests
#### status([_String_ status])
Set the attendee's status. May be one of the following: accepted, tentative, declined
#### delegatesTo(**_ICalAttendee_|_Object_ attendee**)
Creates a new Attendee if passed object is not already an attendee. Will set the delegatedTo and delegatedFrom attributes.
```javascript
var cal = ical(),
event = cal.createEvent(),
attendee = cal.createAttendee();
attendee.delegatesTo({email: 'foo@bar.com', name: 'Foo'});
```
#### delegatesFrom(**_ICalAttendee_|_Object_ attendee**)
Creates a new Attendee if passed object is not already an attendee. Will set the delegatedTo and delegatedFrom attributes.
```javascript
// simple unit tests
mocha -R spec
var cal = ical(),
event = cal.createEvent(),
attendee = cal.createAttendee();
attendee.delegatesFrom({email: 'foo@bar.com', name: 'Foo'});
```
// coverage test
istanbul cover _mocha -- -R spec
## Tests
```
npm test
```
## Copyright and license
Copyright (c) Sebastian Pekarek under the [MIT license](LICENSE).
\ No newline at end of file
Copyright (c) Sebastian Pekarek under the [MIT license](LICENSE).
var ical = require('../lib/ical-generator.js'),
http = require('http'),
cal = ical();
'use strict';
cal.addEvent({
start: new Date(),
end: new Date(new Date().getTime() + 3600000),
summary: 'Example Event',
description: 'It works ;)',
url: 'http://sebbo.net/'
});
var ical = require('../lib/'),
http = require('http'),
cal = ical({
domain: 'sebbo.net',
prodId: '//superman-industries.com//ical-generator//EN',
events: [
{
start: new Date(),
end: new Date(new Date().getTime() + 3600000),
summary: 'Example Event',
description: 'It works ;)',
url: 'http://sebbo.net/'
}
]
});
http.createServer(function(req, res) {
cal.serve(res);
}).listen(3000, '127.0.0.1');
console.log('Server running at http://127.0.0.1:3000/');
\ No newline at end of file
}).listen(3000, '127.0.0.1', function() {
console.log('Server running at http://127.0.0.1:3000/');
});
\ No newline at end of file
var ical = require('../lib/ical-generator.js'),
cal = ical();
var ical = require('../lib/'),
cal = ical({domain: 'localhost'}),
event;
cal.setDomain('example.com');
// overwrite domain
cal.domain('example.com');
cal.addEvent({
event = cal.createEvent({
start: new Date(new Date().getTime() + 3600000),
end: new Date(new Date().getTime() + 7200000),
summary: 'Example Event',
description: 'It works ;)',
organizer: {
name: 'Organizer\'s Name',
email: 'organizer@example.com'
},
organizer: 'Organizer\'s Name <organizer@example.com>',
url: 'http://sebbo.net/'
});
// update event's description
event.description('It still works ;)');
console.log(cal.toString());
\ No newline at end of file
module.exports = function(grunt) {
'use strict';
grunt.loadNpmTasks('grunt-contrib-clean');
grunt.loadNpmTasks('grunt-contrib-watch');
grunt.loadNpmTasks('grunt-contrib-jshint');
grunt.initConfig({
clean: {
coverage: ['coverage/**']
},
jshint: {
options: {
jshintrc: true
},
lib: [
'lib/*.js',
'test/*.js'
]
},
watch: {
lib: {
files: ['lib/*.js', 'test/*.js'],
tasks: ['jshint:lib']
}
}
});
grunt.registerTask('default', ['jshint:lib']);
grunt.registerTask('dev', ['jshint:lib', 'watch']);
};
\ No newline at end of file
'use strict';
/**
* @author Sebastian Pekarek
* @module attendee
* @constructor ICalAttendee Attendee
*/
var ICalAttendee = function(_data, event) {
var vars,
i,
data;
if(!event) {
throw '`event` option required!';
}
vars = {
allowedRoles: ['REQ-PARTICIPANT', 'NON-PARTICIPANT'],
allowedStatuses: ['ACCEPTED', 'TENTATIVE', 'DECLINED', 'DELEGATED']
};