4.17 Calendar

Scoop's calendar feature permits multiple public and private calendars and events, as well as allowing users to maintain their own personal calendars in addition to the site-wide calendars.

Calendars are turned on using the Site Control use_calendars. See the sections below for details on configuring the specific behaviour you want. Global calendar configuration is handled by the site controls in the `Events' category; calendar display is handled by the blocks in the `Calendars and Events' category. Per-calendar configuration and global event configuration are managed in the Calendars Admin Tool (A.22).

Site-wide calendars can be managed by anyone with the edit_calendars perm (A.12.15). One site-wide calendar is included by default, but you may create as many as you like.

If the Site Control allow_user_calendars is on, users may create their own calendars, but only one calendar may be created per account. Users may set the access controls (4.17.1) on their calendar however they choose, but admins always have the ability to see all calendars.

If a user has the submit_event perm (A.12.49) and the calendar permissions allow it, they may submit events to a calendar for display to all other users. On submitting the event, they are marked as the `organizer' of that event and they (and the owner of the calender the event is submitted to) are able to invite site members to view the event and see the RSVP status, and, if they have the update_own_event perm (A.12.53) can change the event.

If there is more than one site-wide calendar, or if users can have their own calendars, you probably want to enable calendar subscriptions (4.17.2). Users are automatically subscribed to their own calendar when it is created.

The mini-calendar that can be displayed on the front page (the box mini_calendar) contains the same events as the full-sized calendar displayed on the /calendar URL, when no calendar ID is specified. If calendar subscriptions (4.17.2) are on, this is the current user's personal calendar view; otherwise it is the calendar named in the site control default_calendar_id.

4.17.1 Access control

Calendars and events each have a system of access control that can be as fine-grained as the calendar or event owner likes. Each calendar and event has a trio of permissions associated with it, two of which the calendar or event owner can change.

This determines who can view the calendar or event. The three options are: everybody (public), only people on the invitation list, and only me (private). Whenever a calendar or event is viewed, this permission is checked to make sure the current user has permission to see it. For calendars, somebody with the edit_calendars perm (A.12.15) can see the calendar regardless of permissions. For events, somebody with the edit_events perm (A.12.16) OR the owner of the calendar the event was submitted to can see the event regardless of permissions.
This determines who can submit events to the calendar, or stories to the event. The five options are: everybody (public); everybody, but I will review the events before they're visible; only people on the invitation list; only people on the invitation list, but I will review the events before they're visible; and only me (private). This is checked when building the menus attached to a calendar or event so only appropriate links are shown, and also when somebody attempts to submit. For calendars, somebody with the edit_calendars perm (A.12.15) can submit events to the calendar regardless of permissions. For events, somebody with the edit_events perm (A.12.16) OR the owner of the calendar the event was submitted to can submit to the event regardless of permissions.
This determines who can edit the calendar or event. For calendars, users with the edit_calendars perm (A.12.15) or the owner of the calendar can edit the calendar settings, moderate event submissions, and manage the calendar's invitation list. For events, users with the edit_events perm (A.12.16), the owner of the calendar the event was submitted to, or the user who submitted the event if that user has the update_own_event perm (A.12.53) can edit the event and its invitation lists.

Events submitted to a private or invitation-only calendar will only be visible to people who have permission to see that calendar, and may be restricted further. To have an event visible to all as well as visible in a private or invitation-only calendar, it must be submitted to a public calendar then included in the private calendar afterward.

4.17.2 Subscriptions

If the site control allow_personal_calendar_view is on (and the user has the edit_own_calendar perm (A.12.22) - wtf? FIXME: rusty added that), users can subscribe to multiple calendars and have their events displayed all at once in a `personal calendar view'. The personal calendar view is displayed when a user requests /my/calendar or otherwise doesn't specify a particular calendar ID. If the user is not subscribed to any calendars, the calendar named in the site control default_calendar_id is displayed.

When viewing a specified calendar, a subscribe/unsubscribe link is provided as appropriate. Clicking the link will subscribe or unsubscribe the user as required.

When viewing the personal calendar view, all calendars available for the user's subscription are listed beside checkboxes. Checked calendars are currently subscribed; unchecked calendars are not. Multiple calendars can be subscribed and unsubscribed simultaneously by adjusting the checkboxes as desired and clicking the `Update Calendar' button.

Users can also subscribe to events by clicking the `notify me of changes to this event' link on the event page. If you place the box event_notify on a page template, it will appear to let the user know that the event has changed since they last looked at it.

4.17.3 Event RSVP

Each event tracks RSVPs and volunteers (if volunteers are requested when the event is submitted). The event owner can see who has indicated via the RSVP form that they are coming, and whether or not they have volunteered. The event owner is emailed if somebody indicates that they would like to volunteer so they can get in touch and start planning duties. The volunteer form lets users know that their `realemail' will be emailed to the event owner for this purpose prior to them submitting it.

The RSVP list is sorted with volunteers at the top and everybody else below, to help the event organizer.

4.17.4 Event stories

Stories can be attached to particular events, to provide updates, more details, summaries, and a place to talk about the event both before and after the fact. They are displayed below the event details on the event's page, and are filed in the `events' section. Users must have the story_post perm (A.12.45) to post stories to events, and: the event must be set to allow anybody to post stories to it, the user is on the invitation list, or the user is the owner of the event.

The `events' section should be listed in the Site Control sections_excluded_from_all so event stories do not appear on the `Everything' page or in the site's RSS feed. The section's `story post' permissions should be set to `Hide' for all groups so it does not appear in the normal story submit form, only when posting a story specifically to a particular event.

By placing |BOX,event,|sid|| in the story_summary block, stories associated with events will have a link added to the relevant event's page. All other stories will have nothing added.