Extension:Calendar (Kenyu73)/Readme

Setup (v3.7 Release) 1/27/2009

 * It's recommended to create a custom calendar type Namespace, like Calendars, but can be whatever Namespaces defined in LocalSettings.php or standard MediaWiki namespaces (like user namespaces) however, it's not required. It is recommended though so seaches in the main wiki do not included calendar events.
 * The easist way is to enter "Calendars:PageName" in the search box to create the main base calendar page.
 * Add a extension tag to the newly create page (or existing page)
 * Add parameters as required (see below listing)

Note: You can have more then one calendar per page. It's fun to find unique combinations of how to use "full" calendar view and "day" only view. Don't forget, since this is a tagged extension, you could always wrap the calendar in a table to shrink it down or justify it...

The calendar has many advanced features; below is a simple basic way to setup the calendar. This calendar will create a standard calendar named "Public" if no name parameter is given, but it's recommended that, at minimun, you create a 'name' parameter. This will give you a good all around full featured calendar. Read and use the advanced parameters at you own risk! :) 

Important: To gain the ability of Parent/Subpage linking, place the calender in an existing namespace (Help:Namespaces) or create a new one. Create a wiki page as shown above and then add your calendar extension tag to that page. This will populate a "quick" shortcut link back to the calendar after the event is entered and saved. The calendar will still work fine if not added to a namespace, but you will not get a "quick link" back to the main calender page.

The following are examples of how an (Namespace:Page/Name/EventDate) event will look:

 Calendars:Acme Company/Sales/12-1-2008 -Event 1

 Calendars:Acme Company/Support/12-1-2008 -Event 1

Sharing Calendars
You can also "share" or subscribe to other calendars by using the "subscribe" or "fullsubscribe" parameter. This will create a calendar of your own, but you'll also have all the events listed from "Sales". Remember to use the full "wiki page/calendar name" format. Be sure to include usetemplates or other special parameters in your calendar if the subscibed calendar uses them. Namespace not used: 

Namespace is used: 

Parameters
Please use quotes for any parameter that may contain a space

Events
Events can be entered either by the "add event" link or via the "template load" button (if enabled). Both work together seemlessly, but clicking each of them will bring you back to the respective method of creation. Once you save the event, you can easily go back to the calendar via the Subpage/Parent link right above the page body.

Events are listed on the calendar with the information on the first line of the page if created via "add event".

In this example, Summer Picnic will appear on the calendar. Summer Picnic Our department will be holding a summer picnic at the park. Bring your families and your appetites!

Multiple Events
In this example, two calendar events are created using the same page. The == event == can be used to create these mulitple events per page. However, you can still create new page events by clicking Add Event. You can force all new events into one page by using the usemultievent parameter.

In this example, Picnic and Party will show up on the same day.

Picnic
Bring food!

Party
Bring drinks

Repeating Events
Repeating events are not an easy task to handle via "wiki" page structure. However, I did come up with a way... The below example will create 5 repeating Vacation events in the caledar. You MUST enable the functionality by adding enablerepeatevents to your parameter tag or config page. Enabling repeating events causes the calendar to look back 15 days into the previous month for any carry over events. If by chance you have a repeating event prior to the 15th, it will not carry over to the next month. 5# Vacation

Recurrence Event
Recurrence type events are traditional repeating yearly events like holidays, birthdays, etc. To create a recurrence event, choose 'add event' and add the following trigger syntax:
 * 1) My Birthday

This will convert the event into an vCalendar RRULE event and store it into the 'page/name/recurrence' wiki page. This is also where any ical recurrence events are stored.

Template Events
The template button (if enabled) allows users to add a bunch of events into one page. Only one template is created per month/year. This can be used along with all other event types.

The day and the event must be seperated by an '#' as shown in the example. You can also create duplicated days. The days do not have to be in order

1# Vacation 2# Holiday 7# Election Day 7# Office Closed 31# Half Day 19# Appointment 20-25# Hiking Trip <-- multiple day event

Colors and Formatting

 * 1) The calendar supports most of the basic MediaWiki text/font properties including the 'ticks' for italic and bold.
 * 2) *  vacation 
 * 3) * Vacation time!! --> Vacation time!!
 * 4) Setup the event style' page by adding as many 'styles' as you wish. These styles are based on keyword matches, so be wary of what words you choose... The styles follow standard html/css style properties.
 * 5) * syntax: keyword:: style1; style2; etc
 * 6) ** myStyle:: color:green; text-decoration:line-through; --> Whatever
 * 7) ** birthday:: color:red; font-style: bold; -->  My Birthday 
 * 8) ** sick:: color: green;background-color: yellow --> Out Sick today
 * 9) ** vacation:: color: red; font-style: italic -->  Vacation to Florida! 

I'm not sure how far and how many variation of the css and/or Wiki formatting will go, but I've tested a good portion of the standard text properties. (  is giving me an issue at this time though... but   works just fine!)

Time Tracker
You can keep simple time tracking of events by formatting the event as below. This will track any dynamically created event in a simple table below the calendar in full mode only. ::Vacation: 8 or ::Vacation -8 ::Team Project 1 - 3 ::Sick : 4

Note that events created using the 'add event' link only track time for that month. If you want to track a years total, you need to enable and use month templates (usetemplates)

vCalendar (iCal) Support
The calendar supports the basic importing of vCalendar formatted files. The import utility is enabled by adding ical or ical=overwrite to your parameter string or config file settings. The calendar excepts the following vCalendar formats
 * DTSTART
 * DTEND
 * SUMMARY
 * DESCRIPTION (not with RRULEs though)
 * RRULE

The RRULE evaluates basic calendar event logic only... nothing complex like "every 3rd Monday of every-other month". It does handle typical repeats like Thanksgiving, Mothers Day, etc that required logic like "the 4th Thursday of November" or "the last Monday of March" kinda logic. Basically, it should capture most repeating events like birthdays and holidays.

The RRULE (repeating) events are stored in a subpage called recurrence. Basically, in the following format page/calendarname/recurrence. You can manually edit or delete these as needed. If you use the ical=overwrite option, it deleted the data before writing in the new ical data.

Imported events without the RRULE are created in the calendar as normal pages in the -Event 0 page for the respective day.

Internationalization (i18n)
The calendar months and weekday names will display in any MediaWiki language selected in the user preferences. However, the custom buttons and other calendar specific information has only been converted to French (fr) and Spanish (es).

If any other languages are required, new messages structures will have to be created in the calendar.i18n.php file as needed by the user. It's not hard really, just copy an existing message structure in that file and update the required translations. It would take all of 15 minutes to add additional languages. The calendar logic is coded as such that any new message structures added will auto-load and be available right away! If you post the newly created language to the google issue tracker, I'll add it into the next code release....

I only used Google's language translator, so the custom translations I've added may be "syntaxually?" incorrect. Please feel free to make a bug report if I need to update a bad translation!

Installation
The following are details of the administrator installation of this calendar extension. If you dont have any custom Namespaces, then 100 and 101 are fine, if you do have existing custom Namespaces, just bump the numbers up accordingly. See Help:Namespaces for more information. The $wgNamespacesWithSubpages values must match the values assigned to the $wgExtraNamespaces. Recommended Folder Path: /extensions/Calendar Localsettings.php: Simple: require_once("$IP/extensions/Calendar/Calendar.php"); Recommended: require_once("$IP/extensions/Calendar/Calendar.php"); // Puts events into their own namesspace/group (not included in 'main' searches... etc) $wgExtraNamespaces[100] = "Calendars"; $wgExtraNamespaces[101] = "Calendars_talk"; //Note: 'Calendars' is an example, please feel free to use whatever name you wish // Puts the events into Subpages (allows a quick link back to primary calendar) $wgNamespacesWithSubpages[100] = true; $wgNamespacesWithSubpages[101] = true; The additional namespaces move all the events outside the "main" group... should clean the mess up some. If you have custom namespaces installed already, make sure you bump up the [100][101] values up accordingly.

Beta Readme