Announcing This Day in History

I'm pleased to announce my first Drupal module contribution: This Day in History. It provides an "on this day in history" feature block for your website. For example, if today was January 6th the birth of Joan of Arc (born January 6, 1412) might be displayed in the This Day in History block.

The module adds node type: Historical event, and supports the Node import module for importing historical events. Any number of display blocks can be created, and the events displayed can be selected by a number of different criteria, including randomly. If no event exists for the current day, no block is displayed.

Module Install & Setup

This Day in History installs the standard way. Download the module and extract the files into your module directory. After enabling the module at:

Administer > Site building > Modules

you should proceed to:

Administer > User management > Access Control

and enable the roles as appropriate for your site. The following screen shot fragment shows the four roles as they appear on that page.

Creating Events

Events are created on the Create content > Submit Historical event page. The relevant portion of this page is shown on the right. A Historical event consists of:

• Title - Drupal node title
• Date - Composed of Year, Month and Day fields
• Event - Drupal node body. The teaser is output to the block.
• Display in TDiH Blocks - check box for selecting whether or not the event should be displayed in a block.

Events can also be imported using the Node import module. The events should be placed in a comma or tab delimited file.

Four date formats are understood:

• yyyy-mm-dd (e.g.: 2007-10-31 )
• d/mm/yyyy (e.g.: 31/10/2007 )
• mm/d/yyyy (e.g.: 10/31/2007 )
• mmm d, yyyy (e.g.: Oct 31, 2007 )

For information on using the Node import module please refer to the Node import module documentation. Please be aware that the import_node module does not individually validate nodes, so it is possible to import content with an invalid date.

Using Taxonomy

This Day in History uses taxonomy in the standard Drupal fashion. If you want to tag your Historical events with taxonomy terms, go to

Administer > Content management > Categories

and assign a vocabulary to the Historical event type or create a vocabulary specifically for the Historical event type.

Creating Blocks

Blocks are created on the page:

Administer > Site configuration > This Day in History > Configure Blocks

The following screen shot fragment shows this page, with a block named "Example Block" already created.

By default, a block will display all events. Events can also be selected (i.e., filtered) based on the following criteria:

• Category (i.e., taxonomy term)
• User
• User role

Additionally, you can specify whether to display all events or randomly select a single event.

Blocks can be configured from either:

Administer > Site configuration > This Day in History > Configure Blocks
Administer > Site building > Blocks page.

The ability to add block header text is also provided. The Drupal filter mechanism is used, so PHP code is allowed to a sufficiently privileged block administrator. This allows dynamic block text. For example, the string "On March 27th in the world of sports:" can be created using the string:

<div>On <?php print date('F jS') ?> in the world of sports:</div>

Theming

Given all the possible ways a site might want to display the event information, a content theming mechanism is provided. It exposes all of the node and block content as raw data allowing total control over content. The results of this function are passed in the standard way to the block.tpl.php theming mechanism.

To customize This Day in History blocks, create a template.php function named {theme_name}_thisdayinhistory_block. For example, for the Garland theme the function name is: garland_thisdayinhistory_block

The following parameters are provided to the function call:

  P1: an array containing the block information
  P2: an array of Historical event nodes

The function definition would therefore look something like:

Blocks are individually themable by appending the block number to the function name. The block number is displayed on the menu:

Administer > Site configuration > This Day in History > Configure blocks

For example, if you were using the Garland theme and wanted to theme the "Example Block" shown in the previous screen shot as block id 14, you'd create a function named: garland_thisdayinhistory_block_14

To easily see the available values use the following code (you'll need to change the name to match your theme name):

If you are unsure how to write the theming function you can use the code in the module's theming function: theme_thisdayinhistory_block as a starting point. Simply copy the code into your theming function.

Coming Soon: Views Support & Pages

Views support is planned for displaying This Day in History historical events on a page. Although Views can be built using This Day in History nodes, there is currently no way to select by date.

The On This Day Module

There's a Drupal module named On This Day. Does This Day in History duplicate functionality?

Although similar in intent (displaying things from the past), these modules do not duplicate functionality. The On This Day module uses the site's existing content nodes, such as blog nodes, for its content. It uses the node creation date for selection. It would display something like: On this day in previous years Fred blogged this, this and this. The This Day in History module has it's own Historical event node type, allowing the entry of specific historical events. If today were January 22nd it would display something like: 1992 - Dr. Roberta Bondar becomes the first Canadian woman in space on Space Shuttle mission STS-42.

Feedback?

All feedback is welcome at http://drupal.org/project/issues/thisdayinhistory.

Acknowledgments

The Quotes module provided much of starting point for this module. My thanks go to authors and maintainers of that module.