Extension:Semantic Calendar
From MediaWiki.org
 Release status: beta |
|
|---|---|
| Implementation | Parser function |
| Description | An extension, based around Semantic MediaWiki, that displays calendars that hold event data using semantic date properties. |
| Author(s) | Yaron Koren <yaron57@gmail.com> |
| Version | 0.2.4 (April 2008) |
| MediaWiki | 1.8.* or greater |
| Download | See here |
| Example | A calendar showing opinion items by publication date on Discourse DB |
| Hooks used | |
Contents |
[edit] Description
Semantic Calendar is an extension to MediaWiki that displays a monthly calendar displaying 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, and preferably SMW version 1.0 or later. It will work with previous versions of SMW, but not as well.
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.
[edit] Code and download
You can download the Semantic Calendar code in either one of these two compressed files:
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:
svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticCalendar/
To view the code online, including version history for each file, you can go here.
[edit] 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):
include_once('extensions/SemanticCalendar/includes/SC_Settings.php');
[edit] Languages supported
Semantic Calendar supports Afrikaans, Arabic, Breton, Bulgarian, Taiwanese Chinese, Dutch, English, Esperanto, French, Galician, German, Greek, Hindi, Hungarian, Japanese, Khmer, Lithuanian, Luxembourgish, Marathi, Norwegian Bokmål, Norwegian Nynorsk, Occitan, Pashto, Persian, Polish, Portuguese, Russian, Slovak, Swedish, Tajik, Telugu, Vietnamese, Volapük and Upper Sorbian.
[edit] Authors
Semantic Calendar was written by Yaron Koren, reachable at yaron57 -at- gmail.com.
[edit] Version
Semantic Calendar is currently at version 0.2.4.
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
[edit] 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
[edit] 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:
{{#semantic_calendar:Has date}}
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:
{{#semantic_calendar:Has start date|[[Category:Corporate events]][[Has priority::High]]}}
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:
{{#semantic_calendar:Has start date;Has deadline|[[Category:Corporate events]][[Has priority::High]];[[Category:Projects]]}}
[edit] 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.)
For now, the easiest way to get Semantic Calendar to work is to 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:
$wgEnableParserCache = false; $wgCachePages = false;
However, depending on how much data you have, this could drastically slow down the speed of your wiki. You can instead 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:
if (strpos($_SERVER['REQUEST_URI'], 'Calendar_1') || strpos($_SERVER['REQUEST_URI'], 'Calendar_2')) { $wgEnableParserCache = false; $wgCachePages = false; }
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. However, it will allow you to run Semantic Calendar without affecting the performance of the rest of the site.
[edit] 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)
[edit] Contributing to the project
[edit] Bugs and feature requests
Send any bug reports and requests to Yaron Koren, at yaron57 -at- gmail.com.
[edit] 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.
[edit] 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.
