Extension:Semantic Drilldown

Description
Semantic Drilldown is an extension to MediaWiki that provides a page for drilling down through a site's data, using categories and filters on semantic properties. It is heavily tied in with the Semantic MediaWiki extension, and is meant to be used for structured data that has semantic markup. Having Semantic MediaWiki installed is a precondition for the Semantic Drilldown extension; the code will not work without it.

The "Browse data" page is the heart of the extension. It shows, at the top, all the top-level categories in the wiki; i.e., the categories that are not subcategories of another category, and the number of pages within that category. Each category name is a link to a drilldown for the pages in that category. It lets the user select additional constraints to limit the number of results. These constraints come in two types:


 * Subcategories - if the category has any subcategories, those will show up in a "Subcategory" row. Each one will be a link that will let the user only view the pages that belong to that subcategory. The resulting drilldown page will include links for all the filters for the top-level category, and links for any subcategories of that subcategory. You can thus use the "Browse data" page to navigate through an entire category tree.


 * Filters - filters based on semantic properties can be manually added for any top-level category. Each such filter gets its own row within the constraints area, to let the user limit the results to only those pages that have that value for this semantic property. There are four ways to set the possible values for a filter:
 * Inherited from an enumeration - if the property for the filter is an enumeration, the filter can simply use that property's allowed values as its possible values.
 * Pages in a category - the filter's values can be all the pages that belong, either directly or through a subcategory, to a category.
 * By date range - results are grouped into date ranges, based on a specified time period.
 * Set manually - the filter's values can be set manually. For properties that are numbers, a numerical range can also be set for a filter value, instead of a single number.

In the display of the filter in the drilldown, values that do not have any results for them will not be displayed. The filter will also show two additional values: "Other" and "None". Pages that show up for "Other" are those that have a value for that filter's property other than one of the pre-specified values. Pages that show up for "None" are those that have no value for that property. "Other" and "None", like other filter values, will not show up if there are no results for them.

After any amount of clicking on different subcategories and filters, the user will be able to see, in the page header near the top of the page, the set of subcategories and filters he/she has clicked on, that currently set constraints on the result. The user can get rid of any constraint by clicking on the "x" next to its name in the header.

See below for instructions on how to define such filters, and how to add them to categories.

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


 * semantic_drilldown_0.3.tar.gz
 * semantic_drilldown_0.3.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/SemanticDrilldown/. 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 'SemanticDrilldown' 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):

You may also wish to change the number value for the new "Filter" namespace, defined in SD_Settings.php; by default it is set to 170.

Also, if you have any custom namespaces declared, you should add the following declaration before the 'include_once' call in the file 'LocalSettings.php':

(Or, instead of 170, whatever number you want the "Filter" namespace set to.)

NOTE: The definition of $sdgNamespaceIndex and the call to SD_Settings.php must be placed after the initialization of any custom namespace definitions in LocalSettings.php. Otherwise, the Filter namespace will not initialize.

Languages supported
Semantic Forms has full support for English, Taiwanese Chinese, Mainland Chinese, German and Persian, and partial support for Dutch.

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

Version
Semantic Drilldown is currently at version 0.3.

The version history is:
 * 0.1 - December 10, 2007 - Initial version
 * 0.2 - December 17, 2007 - 'CreateFilter' page added; improved property lookup for SMW 1.0; Persian-language support added; small bug fixes
 * 0.2.1 - December 20, 2007 - Added "Uses time period" and "Requires filter" properties; header includes link to category; German-language support added
 * 0.2.2 - December 26, 2007 - Filters with only a property set have their possible values retrieved dynamically, instead of from "Allows value" settings
 * 0.3 - January 8, 2007 - Language files changed to be updated by Betawiki, the MediaWiki translation wiki; look of main change updated, and name changed from "View data" to "Browse data"

Special pages
The extension defines three "special" MediaWiki pages:


 * Special:BrowseData - displays a drilldown interface for browsing all the data on the site. (See example of page)
 * Special:CreateFilter - lets a user create a new filter. (See example of page)
 * Special:Filters - lists all filter pages on the site. (See example of page)

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

/includes


 * SD_AppliedFilter.php - defines the class SDAppliedFilter, which represents a filter in conjunction with a value.
 * SD_Filter.inc - defines the class SDFilter, which represents a filter on a single property.
 * SD_GlobalFunctions.php - functions and constants used by the rest of the Semantic Drilldown code.
 * SD_Settings.php - various settings for Semantic Drilldown.

/languages


 * SD_Language.php - parent class for all language files
 * SD_LanguageDe.php - German-language text
 * SD_LanguageEn.php - English-language text
 * SD_LanguageFa.php - Persian-language text
 * SD_LanguageZh_cn.php - Mainland-Chinese-language text
 * SD_LanguageZh_tw.php - Taiwanese-Chinese-language text

/skins


 * SD_main.css - main CSS file for Semantic Drilldown

/specials


 * SD_CreateFilter.php - defines the 'CreateFilter' special page
 * SD_Filters.php - defines the 'Filters' special page
 * SD_ViewData.php - defines the 'ViewData' special page

Getting started
Before you set up Semantic Drilldown, you should have all the data structures on your site set up - properties/attributes/relations, categories, templates, and, if you're using them, forms. See the Semantic Forms "Getting started" section for more on how to set these up.

After all this is done, and you've added some actual data, you should take the following steps:


 * Drill down through the data. As soon as you've installed Semantic Drilldown, you can go to the "ViewData" special page and see what the category structure looks like on your site. There you can see what filters are needed or would be helpful for each category.


 * Create filters. Every filter you want to be able to drill down with has to be defined separately, on a page in the "Filter:" namespace. The easiest way to create filters is using the 'CreateFilter' special page (see above).


 * Add filters to categories. To add a filter to a category, simply add the tag Has filter::Filter :filter-name to the category's page. Filters should only be added to top-level categories.

Filter settings
Within the page for each filter, you should place semantic tags that define the filter. The allowed tags are:


 * - The only mandatory tag. Specifies which relation, attribute or property this filter applies to.
 * - States that the possible values for this filter are all the pages that are members of a certain category.
 * - Adds a specific value allowed for this category. You can add as many such tags as you want to a filter.
 * - Used for date filters; indicates the period of time that values are divided into (options are "Month" and "Year").
 * - Specifies the name of the filter which will be displayed on the screen.
 * - States that a filter should only be displayed for users if they have already selected a value from the specified filter.

If neither "Gets values from category", "Has value" or "Uses time period" are defined for a filter, the extension will simply list all current values of the property for the given set of pages.

Example
Here is the relevant part of the source code for the 'Sources' category page at Discourse DB:

This category uses the filters Has filter::Filter:Type, Has filter::Filter:Circulation and Has filter::Filter:Country.

And here are the source codes for the three relevant filters - Type:

This filter covers the property Covers property::Attribute:Publication type.

Circulation:

This filter covers the property Covers property::Attribute:Has circulation. It has the values Has value:=< 100,000, Has value:=100,001 - 250,000, Has value:=250,001 - 500,000, Has value:=500,001 - 1,000,000 and Has value:=> 1,000,000.

and Country:

This filter covers the property Covers property::Attribute:Is published in country. It has the values Has value:=Australia, Has value:=Great Britain and Has value:=United States.

Excluding categories from the drilldown
You may want certain categories to not show up in the main top-level list of categories. There is no way to completely exclude such a category. However, you can create a new category, called "Other" or anything else, and make each such category a member of that new category. That way, all such categories will only be viewable as subcategories of that "Other" category, instead of cluttering up the list of categories at the top.

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


 * Discourse DB
 * Placeography - Histories and stories about buildings and places
 * Verwaltungskooperation - Cooperation in Public Administration

Bugs and feature requests
You can submit bug reports and requests for new features at MediaWiki's Bugzilla, here.

The current list of known bugs and requested features for Semantic Drilldown can be found here.

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 "SemanticDrilldown" directory, and typing:

svn diff >descriptivename.patch

Then go to the relevant bug report in Bugzilla, or create one if one doesn't exist (note, again, that Bugzilla is used for both bugs and feature requests), and attach this patch file to it.

If, for any reason, you don't wish to use Bugzilla, feel free to simply send this patch, with a description, to Yaron Koren.

Translating
Translation of Semantic Drilldown 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.

Donate
Semantic Drilldown was created and is developed on a strictly volunteer basis, with no funding whatsoever; all donations are welcome. You can donate to the project here.