README.md 7.62 KB
Newer Older
Sebastian Pekarek's avatar
Sebastian Pekarek committed
1
2
# ical-generator

Sebastian Pekarek's avatar
Sebastian Pekarek committed
3
4
[![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)
Sebastian Pekarek's avatar
Sebastian Pekarek committed
5

Sebastian Pekarek's avatar
Sebastian Pekarek committed
6
7
ical-generator is a small piece of code which generates ical calendar files. I use this to generate subscriptionable
calendar feeds.
Sebastian Pekarek's avatar
Sebastian Pekarek committed
8

9

Sebastian Pekarek's avatar
Sebastian Pekarek committed
10
11
12
13
## Installation

	npm install ical-generator

14

Sebastian Pekarek's avatar
Sebastian Pekarek committed
15
16
17
18
19
20
21
22
23
24
## 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
Sebastian Pekarek's avatar
Sebastian Pekarek committed
25
26
27
28

```javascript
var ical = require('ical-generator'),
	http = require('http'),
Sebastian Pekarek's avatar
Sebastian Pekarek committed
29
	cal = ical({domain: 'github.com', name: 'my first iCal'});
Sebastian Pekarek's avatar
Sebastian Pekarek committed
30

Sebastian Pekarek's avatar
Sebastian Pekarek committed
31
32
// overwrite domain
cal.domain('sebbo.net');
33

Sebastian Pekarek's avatar
Sebastian Pekarek committed
34
cal.createEvent({
Sebastian Pekarek's avatar
Sebastian Pekarek committed
35
36
37
38
	start: new Date(),
	end: new Date(new Date().getTime() + 3600000),
	summary: 'Example Event',
	description: 'It works ;)',
Sebastian Pekarek's avatar
Sebastian Pekarek committed
39
	location: 'my room',
Sebastian Pekarek's avatar
Sebastian Pekarek committed
40
41
42
43
44
	url: 'http://sebbo.net/'
});

http.createServer(function(req, res) {
	cal.serve(res);
Sebastian Pekarek's avatar
Sebastian Pekarek committed
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
}).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();
100
101
102
103
104
105
```



## API

Sebastian Pekarek's avatar
Sebastian Pekarek committed
106
### ical-generator
107

Sebastian Pekarek's avatar
Sebastian Pekarek committed
108
#### ical([Object options])
109

Sebastian Pekarek's avatar
Sebastian Pekarek committed
110
Creates a new [Calendar](#calendar) ([`ICalCalendar`](#calendar)).
111

Sebastian Pekarek's avatar
Sebastian Pekarek committed
112
113
114
115
116
117
118
119
120
121
```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'});
Sebastian Pekarek's avatar
Sebastian Pekarek committed
122

Sebastian Pekarek's avatar
Sebastian Pekarek committed
123
// is the same as
Sebastian Pekarek's avatar
Sebastian Pekarek committed
124

Sebastian Pekarek's avatar
Sebastian Pekarek committed
125
cal = ical().domain('sebbo.net');
Sebastian Pekarek's avatar
Sebastian Pekarek committed
126

Sebastian Pekarek's avatar
Sebastian Pekarek committed
127
// is the same as
lee's avatar
lee committed
128

Sebastian Pekarek's avatar
Sebastian Pekarek committed
129
130
131
132
133
134
135
136
cal = ical();
cal.domain('sebbo.net');
```


### Calendar

#### domain([String domain])
lee's avatar
lee committed
137

Sebastian Pekarek's avatar
Sebastian Pekarek committed
138
139
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()`).
lee's avatar
lee committed
140

141

Sebastian Pekarek's avatar
Sebastian Pekarek committed
142
143
144
145
#### 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:
146
147

```javascript
Sebastian Pekarek's avatar
Sebastian Pekarek committed
148
cal.prodId({
149
150
	company: 'My Company',
	product: 'My Product',
Sebastian Pekarek's avatar
Sebastian Pekarek committed
151
	language: 'EN' // optional, defaults to EN
152
});
Sebastian Pekarek's avatar
Sebastian Pekarek committed
153
154
155
156

// OR

cal.prodId('//My Company//My Product//EN');
157
158
159
```


Sebastian Pekarek's avatar
Sebastian Pekarek committed
160
#### name([String name])
161

Sebastian Pekarek's avatar
Sebastian Pekarek committed
162
Use this method to set your feed's name. Is used to fill `X-WR-CALNAME` in your iCal file.
163
164


Sebastian Pekarek's avatar
Sebastian Pekarek committed
165
#### timezone([String timezone])
166

Sebastian Pekarek's avatar
Sebastian Pekarek committed
167
Use this method to set your feed's timezone. Is used to fill `X-WR-TIMEZONE` in your iCal.
168
169

```javascript
Sebastian Pekarek's avatar
Sebastian Pekarek committed
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
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');
186
187
```

Sebastian Pekarek's avatar
Sebastian Pekarek committed
188

Sebastian Pekarek's avatar
Sebastian Pekarek committed
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
#### 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])
268
269
270
271
272
273
274
275
276
277
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
> 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.

278

Sebastian Pekarek's avatar
Sebastian Pekarek committed
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
#### 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])
298
299
300

Appointment description

Sebastian Pekarek's avatar
Sebastian Pekarek committed
301
302

#### location([String location])
Sebastian Pekarek's avatar
Sebastian Pekarek committed
303
304
Appointment location

Sebastian Pekarek's avatar
Sebastian Pekarek committed
305
#### organizer([String|Object organizer])
306
307
308
Appointment organizer

```javascript
Sebastian Pekarek's avatar
Sebastian Pekarek committed
309
310
311
cal.organizer({
    name: 'Organizer\'s Name',
    email: 'organizer@example.com'
312
313
});

Sebastian Pekarek's avatar
Sebastian Pekarek committed
314
// OR
Lisa Övermyr's avatar
Lisa Övermyr committed
315

Sebastian Pekarek's avatar
Sebastian Pekarek committed
316
317
cal.organizer('Organizer\'s Name <organizer@example.com>');
```
Lisa Övermyr's avatar
Lisa Övermyr committed
318

319

Sebastian Pekarek's avatar
Sebastian Pekarek committed
320
#### url([String url])
321

Sebastian Pekarek's avatar
Sebastian Pekarek committed
322
Appointment URL
323
324


Sebastian Pekarek's avatar
Sebastian Pekarek committed
325
#### method([String method])
326

Sebastian Pekarek's avatar
Sebastian Pekarek committed
327
Appointment method. May be any of the following: publish, request, reply, add, cancel, refresh, counter, declinecounter.
328
329


Sebastian Pekarek's avatar
Sebastian Pekarek committed
330
#### status([String status])
331

Sebastian Pekarek's avatar
Sebastian Pekarek committed
332
Appointment status. May be any of the following: confirmed, tenative, cancelled.
Sebastian Pekarek's avatar
Sebastian Pekarek committed
333

Sebastian Pekarek's avatar
Sebastian Pekarek committed
334
335
336
337


## Tests

Sebastian Pekarek's avatar
Sebastian Pekarek committed
338
```
Sebastian Pekarek's avatar
Sebastian Pekarek committed
339
npm test
340
341
342
343
344
```


## Copyright and license

Sebastian Pekarek's avatar
Sebastian Pekarek committed
345
Copyright (c) Sebastian Pekarek under the [MIT license](LICENSE).