Commit 834142eb authored by Sebastian Pekarek's avatar Sebastian Pekarek
Browse files

README.md update

parent d1ac6c5f
......@@ -3,7 +3,8 @@
[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
[![CI Status](https://sebbo.helium.uberspace.de/ci-badges/2)](https://ci.sebbo.net/projects/2)
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
......@@ -11,16 +12,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',
......@@ -31,73 +42,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();
```
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'});
Use this method to set your feed's name.
// is the same as
cal = ical().domain('sebbo.net');
### setTZ(timezone)
// is the same as
Use this method to set your feed's timezone.
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()`).
### setProdID(prodID)
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');
```
#### 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');
```
#### options.allDay (Bool)
Appointment is for the whole day
#### options.floating (Bool)
#### 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
......@@ -108,78 +275,71 @@ 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'
});
```
#### options.url (String)
Appointment Website
#### options.method (String)
Appointment method. May be any of the following: publish, request, reply, add, cancel, refresh, counter, declinecounter.
// OR
#### options.status (String)
Appointment status. May be any of the following: confirmed, tenative, cancelled.
cal.organizer('Organizer\'s Name <organizer@example.com>');
```
### save(file[, cb])
Save Calendar to disk asynchronously using [fs.writeFile](http://nodejs.org/api/fs.html#fs_fs_writefile_filename_data_options_callback)
#### url([String url])
Appointment URL
### saveSync(file)
Save Calendar to disk synchronously using [fs.writeFileSync](http://nodejs.org/api/fs.html#fs_fs_writefilesync_filename_data_options)
#### method([String method])
### serve(response)
Send Calendar to the User when using HTTP. See example above.
Appointment method. May be any of the following: publish, request, reply, add, cancel, refresh, counter, declinecounter.
### toString()
Return Calendar as a String.
#### status([String status])
### length()
Returns the ammount of events in the calendar.
Appointment status. May be any of the following: confirmed, tenative, cancelled.
### clear()
Empty the Calender.
## Tests
```javascript
// simple unit tests
mocha -R spec
// coverage test
```
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).
......@@ -2,15 +2,19 @@
var ical = require('../lib/'),
http = require('http'),
cal = ical();
cal.createEvent({
start: new Date(),
end: new Date(new Date().getTime() + 3600000),
summary: 'Example Event',
description: 'It works ;)',
url: 'http://sebbo.net/'
});
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);
......
......@@ -393,7 +393,7 @@ var ICalCalendar = function(_data) {
this.clear();
for(i in _data) {
if(_data.hasOwnProperty(i) && ['domain', 'prodId', 'name', 'timezone'].indexOf(i) > -1) {
if(_data.hasOwnProperty(i) && ['domain', 'prodId', 'name', 'timezone', 'events'].indexOf(i) > -1) {
this[i](_data[i]);
}
}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment