Extension:LifeMarks

LifeMarks is an extension for MediaWiki that will allow you to add simple tags to articles consisting of a date and a description, with the goal of marking a date with an event; these dates could be collected into a timeline of events. This is my first extension written for MediaWiki, developed for version 1.6.8. I created it because the Events Extension, while very close to my needs, lacked some of the capability I needed. Also, I became somewhat enamored with the idea of filling out a wiki and (once a goodly number of events are recorded) using the events list to fill out a timeline.


 * Note: See discussion page for a fix for Fatal Errors caused by newer versions of MW.

Introduction
This extension started badly by borrowing code from the Events Extension and Tasks Extension, notably the database interface. I corrected the bug that resulted from a double-call of the parse function (this would clobber any other extensions on the page and render them into UNIQ tags).

This extension introduces two new tags for use in an article. The first,   is used to set an event marker on a date. The second,   will render a list of all lifemarkers across the wiki that matches given criteria.

In its most simple form:

1533-09-07: Queen Elizabeth I born

This would create an event marker on the date of September 7, 1533, described as "Queen Elizabeth I born".

LifeMarks can further be given category tags for easy lookup later, such as listing all categories tagged with the word "births":

1533-09-07: Queen Elizabeth I born

All lifemarks can be listed in either a table or straight list by calling the   tag. Following the above example, to display all LifeMarks tagged with the word "births":

List of Births

As you can see, the text in between the   tags is the title of the list returned. Also, all texts provided (desciptions and titles) can include wiki-markup.

Using &lt;LifeMarks&gt;
LifeMarks can be set anywhere in any article. By default, they produce no output, so they're safe to use in the middle of a paragraph or block of text where appropriate.

LifeMark Syntax
LifeMarks can be called simply in the form of (which by default produces no output): Or with optional display and organizational parameters: Finally, multiple lifemarks can be set within a single tag. In this form, all lifemarks will receive the same display styling and tagging text as defined in the :

Using &lt;LifeMarkList&gt;
In the course of demonstrating the above, we've created a goodly number of lifemarks. Setting dates and events would be useless if there was no way to collect them and display them, which is where the   comes in. LifeMarkLists, by default, are not returned in tables. They come out as straight text with a title, a hard line break, and then a list of lifemarkers that each use the events display keyword. (For tables, see below) The text in between the   tags will become the title of the list. Just as with the   tag, there are a number of display parameters and filtering parameters you can pass.

LifeMarkList Syntax
Generating a LifeMarkList of all LifeMarkers in the wiki is possible simply by using:

List of LifeMarks

You can even remove the title by simply calling:  for a streamlined, no-options-at-all list of LifeMarks. There are, however, a great number of parameters that can be passed to the list to control its display and behavior.

Title Goes here

Customizing LifeMarkList Display
To limit the number returned, simply specify the criteria in the tag. For example:

Events in 1993

would list all lifemarkers in 1993. You can limit by year, month, day, source page_id, or by tags. For the first three, you can even specify a range, such as 1990-1992. Thus, the following:

Happy Christmas dates in Vermont

would show all events that occurred on December 25, during the years 1992 to 2006 and tagged with the word "happy". Listing all lifemarks from one page in the Wiki requires knowledge of that article's page_id. Users will rarely know or care about an article's page ID, however, by using the word "current", you can list all LifeMarkers defined on the current page.

All events found on this page

Further ways to limit the display would be to set a limit on the number of events returned (limit="5"), or specifying the offset (offset=12).

You can change the order of events displayed as well. By default, the events are ordered chronologically starting with the earliest date. To list the events by month, you can use orderby="month", or by years in reverse order, "orderby=!year". The available sort methods are year, month, day, desccription, tags, page_id. Each method can be reversed by placing a ! in front, so !desc would list LifeMarkers by description in reverse alphabetical order.

Finally, you can set a display which is nearly identical to the display parameter on the   tag, with a few notable exceptions. Firstly, it supports a display variable %source% which is replaced with a link to the page that has the LifeMarker in question. To extend this even further, you can pass another parameter, sourcelinktext which will become the link text. By default, this is "(src)". If you want the link to be the title of the origin page, use sourcelinktext="title".

The list can easily be returned in the form of a table as well. If you specify a border, cellpadding, cellspacing, style or class, or if you specify format="table", a table will be returned. (To apply a CSS class or style to a list, use format="list" to force a list-based output, but it's not guaranteed that the style will be applied properly throughout.) The table returned will place the table in the top row (colspan=3) and have columns for the date, source link, and description. When table output is used, the display parameter applies only to the date field. Placing the variable %description% in the display paramter for a table output would display the description twice: once in the description column and once crammed into the date column.

Special Page
A SpecialPage called LifeMarks will allow for collecting all LifeMarks and displaying them in order. They can also be filtered by year, month, day, source pages, description or (most likely) tag texts. (Although not through a web interface. That's a feature for the next version or an intrepid hacker.)

The SpecialPage differs from the usage of a   tag in that it has links at the top of the table which can change the sort order immediately via up and down arrows next to the date, source, and description headers.

The source page definitions are included in the  file, so no extra files are needed to be installed in other directories.

Future plans (beyond the simple filtering form fields) include a rudementary duplicate search.

Global Settings
The following Global Settings can be set in your LocalSettings.php file to alter the basic options of the LifeMarkers Extension.
 * $wgLifeMarkDefaultDisplay : If you require a prefix before your MySQL table names, include it with this setting. This string will be prefixed before all SQL calls.
 * $wgLifeMarkDefaultDisplay : Defaults to "none". By default, the   tag produces no output.  If you would like to define a default display, place it here.
 * $wgLifeMarkDefaultListDisplay : Defaults to "events". Similarly, the   tag, when in list mode, display by default according to the events keyword.  Change its default here.
 * $wgLifeMarkDefaultOrderBy = : Defaults to: 'year ASC, month ASC, day ASC, description ASC'. If you would like to change the default order that LifeMarkLists are displayed in, place it here.  Please note that this is the SQL order which is appended directly to the end of the MySQL SELECT statement.  This does not support the OrderBy keywords above.

SQL Setup
This extension saves all of its information in a MySQL table, which means you must run the following SQL command to create the space for its data. Read the note below if you use table prefixes CREATE TABLE lifemarks (   lmid MEDIUMINT(9) AUTO_INCREMENT NOT NULL PRIMARY KEY,    page_id INT(8) UNSIGNED NOT NULL DEFAULT 0,    year INT(4) UNSIGNED NOT NULL DEFAULT 0,    month INT(2) UNSIGNED NOT NULL DEFAULT 0,    day INT(2) UNSIGNED NOT NULL DEFAULT 0,    description MEDIUMTEXT NOT NULL,    tags MEDIUMTEXT NOT NULL );

LocalSettings.php
Place the source code below into a file called LifeMarks.php in your extensions directory. Then add the following line to your LocalSettings.php file: require_once("extensions/LifeMarks.php"); If you require a SQL table prefix, alter the SQL code above to include it in the CREATE line. You must also set up the global setting $wgLifeMarkDBPrefix in your LocalSettings.php.

Source Code
See Extension:LifeMarks/LifeMarks.php for the source code for this extension.

Development

 * Fuzzy Dates : One possible further parament to the   tag, fuzziness, would be a number of days (or more likely weeks) with which the date is fuzzy. Namily, if you have an event that took place in the Summer of 1985, you could set the date as July-1-1975 with a fuzziness of 8 weeks.
 * Not too dynamic : One of the problems with the   tag is the fact that it's not dynamic. If you create a page that has, for example,   (clearly to list all birthday lifemarks), save the page and then later add more birthday tagged lifemarks, the new lifemarks will not appear on the calling page.  Essentially, the list is generated when the page is saved, not when the page is collected for view.  I'm pretty sure that I can change that with some modifications to the code (there are some hooks set up for when a page is generated, right?), but that will have to wait for the next version.
 * Duplicate Events : The   tag is secondary to the purpose of the extension which is to log important events for collection later. One shortfall, however, is that a lifemark can be noted too many times.  For example, if you had a page listing the U.S. Presidents, you might include lifemarks for the dates that they began and ended their terms.  Further, a set of lifemarks will likely be placed on each of the Presidents' articles, noting not only their birth and death, but also their terms dates.  These lifemarks have just been duplicated and will show up as two seperate events, even if they have the same text.  There needs to be a more intuitive method of determining duplicate lifemarks beyond convention. For example, I tend to list only birth and death dates on a biographical article and try to list lifemarks only on pages specifically dedicated to the event being marked, but duplicates still happen, especially in cases of ambiguity where it's uncertain which page the lifemark should be noted on.

Issues
First and foremost, LifeMarks has no code to support the deletion of a page containing a LifeMark. In other words, if you delete a page that has a LifeMark on it, the LifeMark is not removed as well.

The real nagging issues with the extension has to do with the way the LifeMarkLists are generated. Namely, they're not rendered on the fly when the page is viewed, but rather assembled when the page is edited and saved. This means that if you've add LifeMarks throughout the Wiki that would normally appear on a LifeMarkList, they won't show up until the page containing the LifeMarkList is edited. A null edit will, I believe, suffice, but it somewhat defeats the purpose of the LifeMarkLists.

Finally, the LifeMarks need a clear way to be organized. I established on my Wiki a rule of thumb of only declaring a LifeMark on the absolute page it references. For example, on a person's Bio page you can expect to see a LifeMark for their birthday or death date. If they got married and a page exists detailing the wedding, then the LifeMake goes on that page. Unfortunately, as will often be the case, a LifeMark belongs equally on two pages; for example, the wedding LifeMark would belong on both the groom's and bride's Bio pages. This results in two LifeMarks for the same event and no clear resolution to prevent this.

Personal Thoughts
I tried to stay organized with this, but the bigger it became, the harder it was to keep the bloat and sprawl away. I've probably written a lot of spaghetti here, so I ask for comment from anyone brave enough to dive in. I'm fairly satisfied with my first attempt at an extension, and I hope that some of you find it useful. Feel free to use the Talk page for comments or requests.

--Bakerq 19:57, 9 September 2006 (UTC)