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.

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


 * semantic_drilldown_0.1.tar.gz
 * semantic_drilldown_0.1.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.

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

Version
Semantic Drilldown is currently at version 0.1.

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


 * Special:ViewData - displays a drilldown interface for viewing all the data on the site. (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_LanguageEn.php - English-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_ViewData.php - defines the 'ViewData' special page
 * SD_Filters.php - defines the 'Filters' 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. There is currently no form to let you create a filter; it has to be done manually. See the "Filter settings" section for the tags you can place in each filter page.


 * 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.
 * - Specifies the name of the filter which will be displayed on the screen.

If neither "Gets values from category" nor "Has value" are defined for a filter, the extension will assume that the property for this filter is an enumeration, and get its values from that property's "allowed values".

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.

Note that the "Type" filter doesn't need to specify its own values, because the property it covers, "Publication type", is an enumeration.

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


 * Discourse DB

Viewing the data
At the top of the "ViewData" page, you should see a list of top-level categories. Clicking on any one of these will show you the list of subcategories and filters you can use for this category, along with all their possible values, and the number of pages that match each option; below that will be the list of all pages that match this category. Clicking on any option, whether it's for a subcategory or a filter, will filter the page to only show results that match the option you selected. Clicking further on subcategories or filter values will further to the list of conditions applied to the results that you are viewing. You can get rid of a condition by clicking on the "x" next to its name in the page header.

Bugs and feature requests
For now, any bug reports and requests for new features should simply be sent to Yaron, at yaron57@gmail.com

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

For now, you should send this patch, with a description, to Yaron.

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.