README.md update

834142eb · Sebastian Pekarek · d1ac6c5f · 834142eb · 834142eb · 834142eb
Commit 834142eb authored Mar 01, 2015 by Sebastian Pekarek
--- a/README.md
+++ b/README.md
@@ -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).
--- a/example/example_serve.js
+++ b/example/example_serve.js
@@ -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);

--- a/lib/calendar.js
+++ b/lib/calendar.js
@@ -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]);
 		}
 	}