Refactored template skeleton

ical4j · Dec 17, 2023 · 6cb920c · 6cb920c
1 parent 632f720
commit 6cb920c
Show file tree

Hide file tree

Showing 15 changed files with 156 additions and 170 deletions.
diff --git a/docs/template/agile.md → docs/template/agile/index.md b/docs/template/agile.md → docs/template/agile/index.md
diff --git a/docs/template/budget.md → docs/template/budget/index.md b/docs/template/budget.md → docs/template/budget/index.md
@@ -17,3 +17,7 @@ Funding agreement is tracked via the completion status.
 An Expense instance outlines the realised funding spend that is ultimately offset by Funding instances. Ideally the
 total of all Expenses will not exceed the total Funding available. This can be mitigated by establishing an Approval
 workflow that ensures agreed Funding is available prior to Expense fulfilment. 
+
+## Reimbursement
+
+A request for reimbursement of funds used from an external budget (e.g. a personal account, etc.).
diff --git a/docs/template/catalog.md → docs/template/catalog/index.md b/docs/template/catalog.md → docs/template/catalog/index.md
diff --git a/docs/template/groupware.md b/docs/template/groupware.md
diff --git a/docs/template/groupware/action.md b/docs/template/groupware/action.md
@@ -0,0 +1,4 @@
+# iCal4j Template - Groupware: Action
+
+Follow-up actions are a common output of meetings. Action instances may be associated with individual meetings or
+where available, the associated Agenda.
diff --git a/docs/template/groupware/agenda.md b/docs/template/groupware/agenda.md
@@ -0,0 +1,47 @@
+# iCal4j Template - Groupware: Agenda
+
+An Agenda represents one or more objectives for a meeting, or series of meetings. Sometimes a meeting may not
+address all the items on an agenda due to lack of time, etc., so it is useful to maintain the Agenda separately
+such that it may be shared across multiple meetings if required.
+
+### Examples
+
+Multiple Agenda may be linked in sequence to track items individually. This can be useful where time constraints
+require additional meetings to address outstanding Agenda items:
+
+    VToDo item4 = new Agenda().summary("Further business and close").uid(...).apply();
+    VToDo item3 = new Agenda().summary("Standing items").uid(...).nextItem(item4).apply();
+    VToDo item2 = new Agenda().summary("Business arising").uid(...).nextItem(item3).apply();
+    VToDo item1 = new Agenda().summary("ACME Monthly Board Meeting").uid(...).nextItem(item2).apply();
+
+    ComponentList agenda = new ComponentList(Arrays.asList(item1, item2, item3, item4);
+
+The resulting component list looks like this:
+
+    BEGIN:VTODO
+    DTSTAMP:20231113T000000Z
+    CONCEPT:https://ical4j.org/action-types/ACTION
+    SUMMARY:ACME Monthly Board Meeting
+    UID:1
+    LINK;VALUE=UID;LINKREL=next:2
+    END:VTODO
+    BEGIN:VTODO
+    DTSTAMP:20231113T000000Z
+    CONCEPT:https://ical4j.org/action-types/ACTION
+    SUMMARY:Business arising
+    UID:2
+    LINK;VALUE=UID;LINKREL=next:3
+    END:VTODO
+    BEGIN:VTODO
+    DTSTAMP:20231113T000000Z
+    CONCEPT:https://ical4j.org/action-types/ACTION
+    SUMMARY:Standing items
+    UID:3
+    LINK;VALUE=UID;LINKREL=next:4
+    END:VTODO
+    BEGIN:VTODO
+    DTSTAMP:20231113T000000Z
+    CONCEPT:https://ical4j.org/action-types/ACTION
+    SUMMARY:Further business and close
+    UID:4
+    END:VTODO
diff --git a/docs/template/groupware/appointment.md b/docs/template/groupware/appointment.md
@@ -0,0 +1,5 @@
+# iCal4j Template - Groupware: Appointment
+
+An Appointment is similar to a Meeting but is more of an open invitation to recipients. It is used to publish
+events to either a broad or narrow audience, and specifically doesn't cater for RSVPs or Attendance tracking.
+An Appointment may still have an associated Agenda for planning, but typically wouldn't include follow-up Actions.
diff --git a/docs/template/groupware/attendance.md b/docs/template/groupware/attendance.md
@@ -0,0 +1,31 @@
+# iCal4j Template - Groupware: Attendance
+
+A useful metric to track for meetings and other events is actual attendance. Whilst opaque events provide an
+intention to attend, Attendance can provide a record of actual participation after the event.
+
+### Examples
+
+For each participant in a meeting attendance may be recorded as follows:
+
+    VEvent meeting = ...
+    VCard attendee = ...
+    VJournal attendance = new Attendance().participant(new Contact(attendee))
+                .start(LocalDateTime.of(2023, 11, 15, 9, 0))
+                .end(LocalDateTime.of(2023, 11, 15, 9, 30))
+                .context(meeting)
+                .apply();
+
+The attendance record looks something like this:
+
+    BEGIN:VJOURNAL
+    DTSTAMP:20231115T000000Z
+    DTSTART:20231115T090000
+    DTEND:20231115T093000
+    RELATED-TO:9000
+    BEGIN:PARTICIPANT
+    PARTICIPANT-TYPE:CONTACT
+    UID:1234
+    CALENDAR-ADDRESS:mailto:[email protected]
+    STRUCTURED-DATA;VALUE=BINARY;ENCODING=BASE64;FMTTYPE=text/vcard:QkVHSU46VkNBUkQNClVJRDoxMjM0DQpGTjpBdHRlbmRlZQ0KQ0FMQURSVVJJOm1haWx0bzphdHRlbmRlZUBleGFtcGxlLmNvbQ0KRU5EOlZDQVJEDQo=
+    END:PARTICIPANT
+    END:VJOURNAL
diff --git a/docs/template/groupware/index.md b/docs/template/groupware/index.md
@@ -0,0 +1,5 @@
+# iCal4j Template - Groupware
+
+Groupware is a term used to describe software tools used for communication and collaboration within and across teams.
+The most widely adopted use of the iCalendar and vCard standards are in Groupware applications, where almost every
+calendar implementation supports the iCalendar format.
diff --git a/docs/template/groupware/meeting.md b/docs/template/groupware/meeting.md
@@ -0,0 +1,34 @@
+# iCal4j Template - Groupware: Meeting
+
+Perhaps the most common use of iCalendar is to define and share meeting invites. A Meeting is a closed invitation to
+select recipients in order for collaborative discussion or other activities. This template may be used to create
+or modify `VEVENT` objects to conform with conventional approaches to defining meeting invites.
+
+### Examples
+
+Assuming we use vCard to represent meeting participants, we can construct a new meeting:
+
+    VCard organizer = ...
+    VCard chair = ...
+
+    VEvent meeting = new Meeting().organizer(organizer)
+                .chair(new Contact(chair))
+                .start(LocalDate.of(2023, 11, 13).atStartOfDay())
+                .duration(Duration.ofMinutes(30)).apply();
+
+The result is something like this:
+
+    BEGIN:VEVENT
+    DTSTAMP:20231113T000000Z
+    ORGANIZER;CN=Big Boss:mailto:[email protected]
+    DTSTART:20231113T000000
+    DURATION:PT30M
+    CONCEPT:https://ical4j.org/event-types/MEETING
+    ATTENDEE;CUTYPE=INDIVIDUAL;ROLE=CHAIR:mailto:[email protected]
+    BEGIN:PARTICIPANT
+    PARTICIPANT-TYPE:CONTACT
+    UID:1234
+    CALENDAR-ADDRESS:mailto:[email protected]
+    STRUCTURED-DATA;VALUE=BINARY;ENCODING=BASE64;FMTTYPE=text/vcard:QkVHSU46VkNBUkQNClVJRDoxMjM0DQpGTjpUZWFtIExlYWQNCkNBTEFEUlVSSTptYWlsdG86bGVhZC1ieUBleGFtcGxlLmNvbQ0KRU5EOlZDQVJEDQo=
+    END:PARTICIPANT
+    END:VEVENT    
diff --git a/docs/template/groupware/note.md b/docs/template/groupware/note.md
@@ -0,0 +1,4 @@
+# iCal4j Template - Groupware: Note
+
+A Note is used to capture useful information such as outcomes of discussions, talking points and anything else
+not specifically actionable. Notes may be associated with Meetings or Agenda, and can also exist independently.
diff --git a/docs/template/project.md → docs/template/project/index.md b/docs/template/project.md → docs/template/project/index.md
diff --git a/docs/template/wiki.md → docs/template/wiki/index.md b/docs/template/wiki.md → docs/template/wiki/index.md
diff --git a/docs/template/workflow.md → docs/template/workflow/index.md b/docs/template/workflow.md → docs/template/workflow/index.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -76,21 +76,34 @@ nav:
       - Outlook: extensions/outlook.md
   - Template:
       - Overview: template/index.md
-      - Groupware: template/groupware.md
-      - Project: template/project.md
-      - Agile: template/agile.md
-      - Workflow: template/workflow.md
-      - Catalog: template/catalog.md
-      - Wiki: template/wiki.md
-      - Budget: template/budget.md
+      - Groupware:
+        - Overview: template/groupware/index.md
+        - Meeting: template/groupware/meeting.md
+        - Agenda: template/groupware/agenda.md
+        - Action: template/groupware/action.md
+        - Note: template/groupware/note.md
+        - Attendance: template/groupware/attendance.md
+        - Appointment: template/groupware/appointment.md
+      - Project:
+        - Overview: template/project/index.md
+      - Agile:
+        - Overview: template/agile/index.md
+      - Workflow:
+        - Overview: template/workflow/index.md
+      - Catalog:
+        - Overview: template/catalog/index.md
+      - Wiki:
+        - Overview: template/wiki/index.md
+      - Budget:
+        - Overview: template/budget/index.md
   - Serializer:
     - Overview: serializer/index.md
-    - JSON-lD: serializer/jsonld.md
+    - JSON-LD: serializer/jsonld.md
     - JMAP: serializer/jmap.md
   - Connector:
     - Overview: connector/index.md
     - Local: connector/local.md
-    - CalDAV/CardDAV: connector/dav.md
+    - WebDAV: connector/dav.md
   - Integration:
     - Overview: integration/index.md
     - Email: integration/email.md