Extension:Semantic Calendar

'''

Description
Semantic Calendar is an extension to MediaWiki that shows a monthly calendar that displays pages by their semantic date information. The heart of the extension is a parser function, #semantic_calendar, that displays a calendar on a page, with links to navigate backwards and forwards through time. The parser function takes as an input the name of the semantic property used for the date, as well as an optional set of semantic queries that can be used to filter the set of events. By default, the calendar displays the current month initially.

This extension requires the Semantic MediaWiki extension, in version 1.0 or later.

Also, it is important to note that this extension currently does not work unless caching is disabled on calendar pages.. To get Semantic Calendar to work, you either have to disable all caching on your wiki, or add in a special hack in your LocalSettings.php file; see "The caching issue", below.

Code and download
You can download the Semantic Calendar code in either one of these two compressed files:


 * semantic_calendar_0.2.9.tar.gz
 * semantic_calendar_0.2.9.zip

You can also download the code directly via SVN from the MediaWiki source code repository, at http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticCalendar/. From a command line, you can call the following:

To view the code online, including version history for each file, you can go here.

Installation
After you've obtained a 'SemanticCalendar' directory (either by extracting a compressed file or downloading via SVN), place this directory within the main MediaWiki 'extensions' directory. Then, in the file ' LocalSettings.php' in the main MediaWiki directory, add the following line somewhere below the calls for the Semantic MediaWiki extension (both the main 'include_once' line and the 'enableSemantics' line):

Languages supported
Semantic Calendar supports Afrikaans, Arabic, Breton, Bulgarian, Taiwanese Chinese, Dutch, English, Esperanto, French, Galician, German, Greek, Hebrew, Hindi, Hungarian, Italian, Japanese, Javanese, Khmer, Lithuanian, Luxembourgish, Malayalam, Manx, Marathi, Norwegian Bokmål, Norwegian Nynorsk, Occitan, Pashto, Persian, Polish, Portuguese, Russian, Slovak, Swedish, Tajik, Telugu, Venetian, Vietnamese, Volapük and Upper Sorbian.

Authors
Semantic Calendar was written by Yaron Koren, reachable at yaron57 -at- gmail.com.

Version
Semantic Calendar is currently at version 0.2.9.

The version history is:
 * 0.1 - February 6, 2008 - Initial version
 * 0.1.1 - February 8, 2008 - Language support added for Arabic, Bulgarian, French, Galician, German, Hungarian, Japanese, Luxembourgish, Persian, Portuguese, Slovak, Vietnamese, Volapük and Upper Sorbian
 * 0.1.2 - February 13, 2006 - Fix for multiple dates for an event for SMW 1.0; language support added for Afrikaans, Taiwanese Chinese and Norwegian Nynorsk
 * 0.2 - February 26, 2008 - Date handling no longer uses PHP date functions, and thus is no longer constrained by limitations of the operating system; language support added for Lithuanian, Norwegian Bokmål, Occitan, Swedish and Telugu
 * 0.2.1 - March 14, 2008 - Language support added for Esperanto, Khmer, Marathi, Pashto, Polish and Tajik
 * 0.2.2 - March 25, 2008 - Fix to always display calendar as HTML; language support added for Greek
 * 0.2.3 - April 9, 2008 - Fixes for non-main namespace in both event and calendar pages; language support added for Breton and Russian
 * 0.2.4 - April 16, 2008 - Fix of language-value setting for MediaWiki versions before 1.11; small image fix; language support added for Hindi
 * 0.2.5 - June 16, 2008 - Security hole fixed; limit removed on event retrieval; language support added for Javanese, Malayalam, Manx and Venetian
 * 0.2.6 - July 10, 2008 - Handling added for SMW 1.2, and dropped for SMW 0.7; loading of language values simplified and improved (SMW 1.11 now required); language support added for Hebrew
 * 0.2.7 - July 22, 2008 - Support added for printing calendars to PDF
 * 0.2.8 - August 29, 2008 - Autoloading added for classes and parser; language support added for Italian
 * 0.2.9 - November 24, 2008 - Handling added for SMW 1.4; language support added for Egyptian Arabic, Ancient Greek, Erzya, Interlingua and Ripuarian

Code structure
The following are the directories and files in the Semantic Calendar extension:

/includes


 * SC_ParserFunctions.php - defines the parser function, '#semantic_calendar', used for the extension
 * SC_GlobalFunctions.php - functions and constants used by the rest of the Semantic Calendar code
 * SC_HistoricalDate.php - a class used for date functions, to avoid the constraints of UNIX-based systems
 * SC_Settings.php - various settings for Semantic Calendar

/languages


 * SC_Language.php - parent class for all language files
 * SC_LanguageEn.php - English-language text
 * SC_Messages.php - Display messages for all languages

/skins


 * SC_main.css - main CSS file for Semantic Calendar

Creating calendars
To display a calendar on a page, showing all events that have a date represented by the property "Has date", add the following to the page:

Note that you can replace "Has date" with whatever property name you use.

You can also add a set of queries to filter the events being displayed; the query format used is the same as that used for Semantic MediaWiki's "ask" inline queries. For example, to display the start date of only those events that also belong to a category called "Corporate events" and have a value of "High" for a property called "Has priority", you can use the following call:

You can also display multiple sets of data on the same calendar, by separating the different date properties, and their corresponding sets of filter queries, with semicolons. There should be the same number of date properties and filter-query sets. For instance, here is how to get a calendar to display both the data from above, and the set of events of category "Projects", by their deadline:

The caching issue
Currently, the #semantic_calendar function cannot work if there is caching enabled for the page in which it sits. This is for two reasons: it will not be able to read the special CSS file for Semantic Calendar, and it will not be able to get the values for the month and year from the URL query string. (If you know of any way to change the Semantic Calendar code to get around this problem, please let me (Yaron) know, either by email or via the Talk page.)

Currently, there are three ways to get around this issue:

1) Simply disable all caching for your wiki, by following the instructions here; in short, add the following two lines to anywhere in your "LocalSettings.php" file:

Depending on how much data you have, this could noticeably slow down the speed of your wiki.

2) Install the MagicNoCache extension, and add the string "__NOCACHE__" to any page that contains a calendar.

3) Disable caching only for those pages that have calendars on them. If, for instance, you have two calendar pages, located at "mywiki.com/wiki/Calendar_1" and "mywiki.com/wiki/Calendar_2", you could have the following in your "LocalSettings.php" file: This code will ideally disable caching only for those two pages (though, if you have any other pages whose title contains 'Calendar_1' or 'Calendar_2', those too will get caching disabled). There are two downsides to this approach: first, it's a complete hack, and second, any time you want to add or rename calendar pages, you or another administrator will have to change this file again.

Adding events
You may wonder how to create events that are displayed with Semantic Calendar. An "event" in this case is nothing more than a page that contains a semantic property of type Date. If that does not make sense, chances are that you should gain more familiarity with the Semantic MediaWiki extension before setting up Semantic Calendar. If you do understand Semantic MediaWiki and want to make a way for users to easily create and edit event pages, consider using the Semantic Forms extension.

Sites that use Semantic Calendar
Here are some sites that use Semantic Calendar in conjunction with Semantic MediaWiki:


 * Cultureel erfgoed
 * Discourse DB (view calendar)
 * Region 3 Levees Wiki (view calendar)
 * The Music Snob (view calendar)
 * The Seventh Sun Wiki (view calendar)
 * Web Community Wiki (view calendar)

Bugs and feature requests
Send any bug reports and requests to Yaron Koren, at yaron57 -at- gmail.com.

Contributing patches to the project
If you found some bug and fixed it, or if you wrote code for a new feature, please create a patch by going to the main "SemanticCalendar" directory, and typing:

svn diff >descriptivename.patch

Then send this patch, with a description, to Yaron Koren.

Translating
Translation of Semantic Calendar is done through Betawiki. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on Betawiki, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.