@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Document Calendar imports
Summary:
Ref T10747.
- Adds import documentation.
- Adds import/export docs to the help menu.
- Removes some weird/old/out-of-date information from the general user guide, which I'll rewrite later.
Test Plan: Read documentation somewhat thoroughly.
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T10747
Differential Revision: https://secure.phabricator.com/D16766
+147
-69
+10
src/applications/calendar/application/PhabricatorCalendarApplication.php
+10
src/applications/calendar/application/PhabricatorCalendarApplication.php
···
104
104
'name' => pht('Calendar User Guide'),
105
105
'href' => PhabricatorEnv::getDoclink('Calendar User Guide'),
106
106
),
107
+
array(
108
+
'name' => pht('Importing Events'),
109
+
'href' => PhabricatorEnv::getDoclink(
110
+
'Calendar User Guide: Importing Events'),
111
+
),
112
+
array(
113
+
'name' => pht('Exporting Events'),
114
+
'href' => PhabricatorEnv::getDoclink(
115
+
'Calendar User Guide: Exporting Events'),
116
+
),
107
117
);
108
118
}
109
119
+5
-69
src/docs/user/userguide/calendar.diviner
+5
-69
src/docs/user/userguide/calendar.diviner
···
9
9
IMPORTANT: Calendar is a prototype application. See
10
10
@{article:User Guide: Prototype Applications}.
11
11
12
-
The Calendar application is a tool that allows users to schedule group events
13
-
and share personal plans.
14
-
15
-
There are several kinds of events you can create:
16
-
17
-
- Regular events such as a one-time meeting or a personal appointment.
18
-
- All day events such as a company-wide holiday or a vacation.
19
-
- Recurring events, which can be regular or all day, such as a weekly 1-1 or
20
-
a birthday.
21
-
22
-
23
-
Editing Events
24
-
==============
25
-
26
-
All fields of basic and all day events can be edited after the event has been
27
-
created.
28
-
29
-
Every instance of a recurring event has an index that maintains its place in
30
-
the sequence order. Before an instance of a recurring event is edited, it is
31
-
considered a ghost event, or a placeholder. This means that there is no
32
-
database entry for that instance. Rather, when querying for events, if a
33
-
recurring series of events overlaps with the query range, instance
34
-
placeholders of that recurring event are generated and are displayed for
35
-
that range. If a placeholder instance of a recurring event is edited, a real
36
-
entry in the database is created and all changes are saved. When that
37
-
instance falls within a query range, the real instance event replaces the
38
-
old placeholder instance.
39
-
40
-
To prevent disordering of the recurring sequence of events, parent recurring
41
-
events do not allow editing of date-related fields like recurrence frequency
42
-
and recurrence start and end dates. If all instances of the recurring event
43
-
need to be rescheduled, users are encouraged to cancel a recurring event and
44
-
create a new recurring event with the revised date and time.
45
-
46
-
47
-
Cancelling Events
48
-
=================
49
12
50
-
Cancelling basic events will hide that event from most of the builtin Calendar
51
-
queries, unless the query specifies to display cancelled events.
13
+
Next Steps
14
+
==========
52
15
53
-
There are two ways to cancel an instance of a recurring event.
16
+
Continue by:
54
17
55
-
- Cancel an instance of a recurring event.
56
-
- Cancel the entire series of a recurring event.
57
-
58
-
Cancelling a placeholder instance of a recurring event will create a real
59
-
cancelled event that will replace the placeholder instance. Consequently,
60
-
the cancellation status of that instance of the recurring event will
61
-
persist if the parent event is cancelled and subsequently reinstated.
62
-
63
-
When an entire series of a recurring event is cancelled, all the placeholder
64
-
and real instances are also cancelled. An entire series can similarly be
65
-
reinstated, but it is currently not possible to reinstate an instance of a
66
-
cancelled recurring event series. To reinstate that instance, the entire
67
-
series must be reinstated. If an instance of a recurring event has been
68
-
cancelled, then the entire recurring event series is also cancelled,
69
-
reinstating the series will not reinstate the previously cancelled instances
70
-
of that event.
71
-
72
-
73
-
Commenting On Recurring Events
74
-
==============================
75
-
76
-
If a placeholder instance of a recurring event has not been converted to a
77
-
real instance of the series as a result of editing or cancelling, commenting on
78
-
that placeholder instance does not currently save a draft for that instance
79
-
only. The draft is saved for the recurring event parent, so the parent
80
-
recurring event and all placeholder instances will show that draft. When a
81
-
comment is actually added to a placeholder instance, the instance is converted
82
-
to a recurrence exception, and the comment will only appear on that instance
83
-
of the recurring event.
18
+
- importing events with @{article:Calendar User Guide: Importing Events}; or
19
+
- exporting events with @{article:Calendar User Guide: Exporting Events}.
+132
src/docs/user/userguide/calendar_imports.diviner
+132
src/docs/user/userguide/calendar_imports.diviner
···
1
+
@title Calendar User Guide: Importing Events
2
+
@group userguide
3
+
4
+
Importing events from other calendars.
5
+
6
+
Overview
7
+
========
8
+
9
+
IMPORTANT: Calendar is a prototype application. See
10
+
@{article:User Guide: Prototype Applications}.
11
+
12
+
You can import events into Phabricator to other calendar applications or from
13
+
`.ics` files. This document will guide you through how to importe event data
14
+
into Phabricator.
15
+
16
+
When you import events from another application, they can not be edited in
17
+
Phabricator. Importing events allows you to share events or keep track of
18
+
events from different sources, but does not let you edit events from other
19
+
applications in Phabricator.
20
+
21
+
22
+
Import Policies
23
+
===============
24
+
25
+
When you import events, you select a visibility policy for the import. By
26
+
default, imported events are only visible to you (the user importing them).
27
+
28
+
To share imported events with other users, make the import **Visible To**
29
+
a wider set of users, like "All Users".
30
+
31
+
32
+
Importing `.ics` Files
33
+
======================
34
+
35
+
`.ics` files contain information about events, usually either about a single
36
+
event or an entire event calendar.
37
+
38
+
If you have an event or calendar in `.ics` format, you can import it into
39
+
Phabricator in two ways:
40
+
41
+
- Navigate to {nav Calendar > Imports > Import Events > Import .ics File}.
42
+
- Drag and drop the file onto a Calendar.
43
+
44
+
This will create a copy of the event in Phabricator.
45
+
46
+
If you want to update an imported event later, just repeat this process. The
47
+
event will be updated with the latest information.
48
+
49
+
Many applications send `.ics` files as email attachments. You can import these
50
+
into Phabricator.
51
+
52
+
53
+
.ics Files: Google Calendar
54
+
===========================
55
+
56
+
In **Google Calendar**, you can generate a `.ics` file for a calendar by
57
+
clicking the dropdown menu next to the calendar and selecting
58
+
{nav Calendar Settings > Export Calendar > Export this calendar}.
59
+
60
+
61
+
.ics Files: Calendar.app
62
+
========================
63
+
64
+
In **Calendar.app**, you can generate an `.ics` file for a calendar by
65
+
selecting the calendar, then selecting {nav File > Export > Export...} and
66
+
saving the calendar as a `.ics` file.
67
+
68
+
You can also convert an individual event into an `.ics` file by dragging it
69
+
from the calendar to your desktop (or any other folder).
70
+
71
+
When you import an event using an `.ics` file, Phabricator can not
72
+
automatically keep the event up to date. You'll need to repeat the process if
73
+
there are changes to the event or calendar later, so Phabricator can learn
74
+
about the updates.
75
+
76
+
77
+
Importing .ics URIs
78
+
=====================
79
+
80
+
If you have a calendar in another application that supports publishing a
81
+
`.ics` URI, you can subscribe to it in Phabricator. This will import the entire
82
+
calendar, and can be configured to automatically keep it up to date and in sync
83
+
with the external calendar.
84
+
85
+
First, find the subscription URI for the calendar you want to import (see
86
+
below for some guidance on popular calendar applications). Then, browse to
87
+
{nav Calendar > Imports > Import Events > Import .ics URI}.
88
+
89
+
When you import a URI, you can choose to enable automatic updates. If you do,
90
+
Phabricator will periodically update the events it imports from this source.
91
+
You can stop this later by turning off the automatic updates or disabling
92
+
the import.
93
+
94
+
{icon lock} **Privacy Note**: When you import via URI, the URI often contains
95
+
sensitive information (like a username, password, or secret key) which allows
96
+
anyone who knows it to access private details about events. Anyone who can edit
97
+
the import will also be able to view and edit the URI, so make sure you don't
98
+
grant edit access to users who should not have access to the event details.
99
+
100
+
101
+
.ics URIs: Google Calendar
102
+
==========================
103
+
104
+
In **Google Calendar**, you can get the subscription URI for a calendar
105
+
by selecting {nav Calendar Settings} from the dropdown next to the calendar,
106
+
then copying the URL from the {nav ICAL} link under **Private Address**. This
107
+
URI provides access to all event details, including private information.
108
+
109
+
You may need to adjust the sharing and visibility settings for the calendar
110
+
before this option is available.
111
+
112
+
Alternatively, you can use the URI from the {nav ICAL} link under
113
+
**Calendar Address** to access a more limited set of event details. You can
114
+
configure which details are available by configuring how the calendar is
115
+
shared.
116
+
117
+
118
+
.ics URIs: Calendar.app
119
+
=======================
120
+
121
+
**Calendar.app** does not support subscriptions via `.ics` URIs.
122
+
123
+
You can export a calendar as an `.ics` file by following the steps above, but
124
+
Phabricator can not automatically keep events imported in this way up to date.
125
+
126
+
127
+
Next Steps
128
+
==========
129
+
130
+
Continue by:
131
+
132
+
- returning to the @{article:Calendar User Guide}.