Extension:LifeMarks

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
LifeMarks

Release status: unknown

Implementation Tag, Database
Description Mark notable dates and events for collection and display
Author(s) User:Bakerq
Latest version 0.2.0 (2006-09-11)
MediaWiki developed on 1.6.8
License No license specified
Download Posted on LifeMarks.php

Translate the LifeMarks extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

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[edit | edit source]

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, <lifemark> is used to set an event marker on a date. The second, <lifemarklist> will render a list of all lifemarkers across the wiki that matches given criteria.

In its most simple form:

<lifemark>1533-09-07: Queen Elizabeth I born</lifemark>

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":

<lifemark tags="births">1533-09-07: [[w:Elizabeth I of England|Queen Elizabeth I]] born</lifemark>

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

<lifemarklist tags="births">List of Births</lifemarklist>

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

Using <LifeMarks>[edit | edit source]

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[edit | edit source]

LifeMarks can be called simply in the form of (which by default produces no output):

<lifemark>yyyy-mm-dd: Description or Title</lifemark>

Or with optional display and organizational parameters:

<lifemark display="display_def" tags="tagging_text">yyyy-mm-dd: Description or Title</lifemark>

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 <lifemark>:

<lifemark display="display_def" tags="tagging_text">
yyyy-mm-dd: Description
yyyy-mm-dd: Description
yyyy-mm-dd: Description
yyyy-mm-dd: Description
</lifemark>

Customizing LifeMarks Display[edit | edit source]

What it looks like What you type

The default display keyword is "none". This produces no output as shown in a simple lifemark:

The following keywords are also available:

The default display keyword is "none".  This produces
no output as shown in a simple lifemark:

<lifemark>1999-9-9: Simple Lifemark</lifemark>

The following keywords are also available:
date 

September 9th, 1990

; date : 
<lifemark display="date">
1990-9-9: Lifemark with display keyword: "date"
</lifemark>
slashdate 

09/09/91

; slashdate : 
<lifemark display="slashdate">
1991-9-9: Lifemark with "slashdatedate" display keyword: "slashdate"
</lifemark>
meddate 

Sep 9, 1993

; meddate : 
<lifemark display="meddate">
1993-9-9: Lifemark with "meddate" display keyword: "meddate"
</lifemark>
longdate 

September 9th, 1992

; longdate : 
<lifemark display="longdate">
1992-9-9: Lifemark with "longdate" display keyword: "longdate"
</lifemark>

Notice that the date-based keywords do not contain line-breaks. This allows them to be used inside a paragraph and contribute to its composition. In the following line of text, the date is generated by a lifemark tag with the display set to "longdate":

The Y2K bug came and went on January 1st, 2000 with little tragedy.

Notice that the date-based keywords 
do '''not''' contain line-breaks.  
This allows them to be used inside 
a paragraph and contribute to its 
composition.  In the following line 
of text, the date is generated by a 
lifemark tag with the display set 
to "longdate":

The Y2K bug came and went on 
<lifemark display="longdate">2000-01-01: Y2K non-event</lifemark>
with little tragedy.

Event-based dispay keywords contain the desciption or title text given with the tag:

event 

09-09-1994: Lifemark with display keyword: "event"

Event-based dispay keywords contain the desciption or
title text given with the tag:
; event :
<lifemark display="event">
1994-9-9: Lifemark with display keyword: "event"
</lifemark>
longevent 

September 9th, 1996: Lifemark with display keyword: "longevent"

; longevent :
<lifemark display="longevent">
1996-9-9: Lifemark with display keyword: "longevent"
</lifemark>
medevent 

Sep 9, 1998: Lifemark with display keyword: "medevent"

; medevent :
<lifemark display="medevent">
1998-9-9: Lifemark with display keyword: "medevent"
</lifemark>
slashevent 

09/09/00: Lifemark with display keyword: "slashevent"

; slashevent :
<lifemark display="slashevent">
2000-9-9: Lifemark with display keyword: "slashevent"
</lifemark>

For convenience, each of the event-type display keywords also contain a plural form: events, longevents, medevents, and slashevents. Each of these display keywords end with a line-break, allowing lists to be formatted easily for multiple lifemarks.

events 

January 20th, 1989: George H. W. Bush inaugurated
January 20th, 1993: Bill Clinton inaugurated
January 20th, 2001: George W. Bush inaugurated

For convenience, each of the event-type display keywords
also contain a plural form: '''events''', '''longevents''',
'''medevents''', and '''slashevents'''.  Each of these
display keywords end with a line-break, allowing lists
to be formatted easily for multiple lifemarks.

; events :
<lifemark display="longevents">
1989-1-20: George H. W. Bush inaugurated
1993-1-20: Bill Clinton inaugurated
2001-1-20: George W. Bush inaugurated
</lifemark>

Finally, if none of these keywords fit, you can define your own. You can construct a display tag with the variables %year%, %month%, %day% and %description%.

New Years Day (01-01-2006)

Finally, if none of these keywords fit, you can
define your own. You can construct a display tag with
the variables '''%year%''', '''%month%''', '''%day%'''
and '''%description%'''.

<lifemark display="%description% (%month%-%day%-%year%)">
2006-01-01: New Years Day
</lifemark>

If you're familiar with the PHP function date() then you may recognize a few of these display variables.

  • %year% is the same as %Y%, a 4-digit year.
  • %month% is the same as %m%, a 2-digit month.
  • %day% is the same as %d%, a 2-digit day.

1990-05-05

If you're familiar with the PHP function <code>date()</code>
then you may recognize a few of these display variables,
wrapped with '''%''' marks.

*'''%year%''' is the same as '''%Y%''', a 4-digit year.
*'''%month%''' is the same as '''%m%''', a 2-digit month.
*'''%day%''' is the same as '''%d%''', a 2-digit day.

<lifemark display="%Y%-%m%-%d%">1990-05-05: Cinco de Mayo!</lifemark>

Other date() variables that can be used are:

  • %y% is a 2-digit year.
  • %j% is the day with no leading zeros.
  • %n% is the month with no leading zeros.

7/4/76 Declaration of Independence

Lastly there are the names of the month in both long and short form, and a suffix for the day.

  • %F% is the full month name, like "January".
  • %M% is the abbreviated month name, "Jan"
  • %S% is the "st" in "1st", the "nd" in "2nd"
    the "rd" in "3rd" and the "th" in every other day.

Valentines Day fell on Feb 14th of 2004

Other <code>date()</code> variables that can be used are:
*'''%y%''' is a 2-digit year.
*'''%j%''' is the day with no leading zeros.
*'''%n%''' is the month with no leading zeros.

<lifemark display="%n%/%j%/%y% %description%">
1776-07-04: Declaration of Independence
</lifemark>

Lastly there are the names of the month in both
long and short form, and a suffix for the day.
*'''%F%''' is the full month name, like "January".
*'''%M%''' is the abbreviated month name, "Jan"
*'''%S%''' is the "st" in "1st", the "nd" in "2nd"
*:the "rd" in "3rd" and the "th" in every other day.

<lifemark display="%description% fell on %M% %j%%S% of %Y%">
2004-02-14: Valentines Day
</lifemark>

Using <LifeMarkList>[edit | edit source]

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 <lifemarklist> 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 <lifemarklist> tags will become the title of the list. Just as with the <lifemark> tag, there are a number of display parameters and filtering parameters you can pass.

LifeMarkList Syntax[edit | edit source]

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

<lifemarklist>List of LifeMarks</lifemarklist>

You can even remove the title by simply calling: <lifemarklist/> 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.

<lifemaklist year="year_filter" month="month_filter" day="day_filter"
page="source_page_filter" limit="number_of_markers" offset="skipped_markers"
display="display_template" format="list|table" orderby="sort_order" sourcelinktext="link_word"
border="table_border_size" cellpadding="padding_size" cellspacing="spacing_size" style="css_style" 
class="css_class">Title Goes here</lifemarklist>

Customizing LifeMarkList Display[edit | edit source]

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

<lifemarklist year="1993">Events in 1993</lifemarklist>

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:

<lifemarklist year="1992-2006" month="12" day="25" tags="happy">Happy Christmas dates in Vermont</lifemarklist>

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.

<lifemarklist page="current">All events found on this page</lifemarklist>

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 <lifemarklist> 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[edit | edit source]

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 <lifemarklist> 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 LifeMarks.php 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[edit | edit source]

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 <lifemark> tag produces no output. If you would like to define a default display, place it here.
$wgLifeMarkDefaultListDisplay 
Defaults to "events". Similarly, the <lifemarklist> 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.

Installation[edit | edit source]

SQL Setup[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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

Ideas and Development, Wishlist, Bugs[edit | edit source]

Development[edit | edit source]

Fuzzy Dates 
One possible further parament to the <lifemark> 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 <lifemarklist> tag is the fact that it's not dynamic. If you create a page that has, for example, <lifemarklist tags="birthday"> (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 <lifemarklist> 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[edit | edit source]

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[edit | edit source]

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)