Extension:Semantic Drilldown

From MediaWiki.org
Jump to: navigation, search
Manual on MediaWiki Extensions
List of MediaWiki Extensions
Crystal Clear action run.png
Semantic Drilldown

Release status: stable
Implementation Special page
Description An extension, based around Semantic MediaWiki, that provides a page for drilling down into the category-based and semantic data of a site, using easily-created filters.
Author(s) Yaron Koren <yaron57@gmail.com>, David Loomer
Last Version 0.8 (August 2010)
MediaWiki 1.13.* or greater
License GPL
Download See here
Example The "browse data" interface for Discourse DB

check usage (experimental)

Contents

[edit] Description

A Semantic Drilldown page

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. You must have version 1.4.3 or later of Semantic MediaWiki installed for the Semantic Drilldown extension to work. The code will not work without it, or with an earlier version.

The "Browse data" page is the heart of the extension. It lists 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:

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.

The drilldown 'results', i.e. the set of pages displayed at any given time during the drilling-down, are by default displayed in the same manner as in MediaWiki's category page; this display, however, can be customized, to show additional values for each page, or to show results in other formats such as tables, maps and timelines.

[edit] Code and download

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

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:

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticDrilldown/

To view the code online, including version history for each file, you can go here.

 You can also download this extension as part of Semantic Bundle, which includes Semantic Drilldown version 0.7.2, as well as some other very interesting extensions.

Finally, you can download a snapshot of the latest version of Semantic Drilldown, using the Extension Distributor:

Download snapshot
Subversion [Help]
Browse source code

[edit] 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):

include_once("$IP/extensions/SemanticDrilldown/SemanticDrilldown.php");

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

$sdgNamespaceIndex = 170;

(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.

NOTE: This extension requires the database account used by MediaWiki to be able to create and drop temporary tables, as well as to create table indexes.

[edit] Languages supported

Semantic Drilldown has support for over 100 other languages.

[edit] Authors

Semantic Drilldown was written by Yaron Koren, reachable at yaron57 -at- gmail.com, and David Loomer.

The 'combo box' jQuery input was created by Sanyam Goyal, reachable at goyalsanyam --[at]--gmail--[dot] com as part of the 2010 Google Summer of Code.

[edit] Version

Semantic Drilldown is currently at version 0.8. See the entire version history.

[edit] Special pages

The extension defines three "special" MediaWiki pages:

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

[edit] Filter settings

Within the page for each filter, semantic tags need to be placed that define the filter. The allowed tags are:

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.

The easiest way to add such properties to a filter is using the 'CreateFilter' special page; see above.

[edit] 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::Publication type]].

Circulation:

This filter covers the property [[Covers property::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::Is published in country]]. It has the values
 [[Has value::Australia]], [[Has value::Great Britain]] and [[Has value::United States]].

[edit] Display options

A Semantic Drilldown page with map. (see the result of drilling down)

[edit] Setting drilldown page title

You can manually set the title of the drilldown page for any specific category, by adding the special property "Has drilldown title" to the category's page. An example would be, in a page called "Category:Cities", the property:

This category has the drilldown title [[Has drilldown title::Browse all cities]].

[edit] Tag-cloud-style display of filter values

You can set the drilldown page to show the values for each filter and each subcategory in "tag-cloud" style, where the size of each value's name is dependent on the number of results it has. To do this, you need to add two values to your LocalSettings.php file, "$sdgFiltersSmallestFontSize" and "$sdgFiltersLargestFontSize"; these represent the font size of the names of the least-popular and most-popular filter values, respectively, in pixels. Here is an example:

$sdgFiltersSmallestFontSize=9;
$sdgFiltersLargestFontSize=25;

Make sure to add these below the inclusion of Semantic Drilldown itself.

[edit] Setting the display of drilldown results

By default, the list of results, or pages that match the current set of filters, is displayed in the style of a category page, with a maximum of 100 results per page. You can change the number of results per page in your LocalSettings.php file, by setting the variable "$sdgNumResultsPerPage". To set the page to show 250 results per page, add the following:

$sdgNumResultsPerPage=250;

More importantly, you can set the display of results as you would the display of Semantic MediaWiki's inline queries: that includes both additional properties that you would want to see displayed, the format (such as a map or calendar) in which results will be displayed. To do this, use the "Has display parameters" special property on the category page. It takes in a set of parameters like that of an inline query, although separated by semicolons instead of pipes. So, for instance, to display the drilldown results of a category on a Google Maps map, you could add the following to the category page:

[[Has display parameters::? Has coordinates;format=googlemaps| ]]

(Note: the final '|' simply hides the ugly-looking value from appearing on the the category page; see "To hide the property" here.) You can see an example of a simple use of this functionality here; every event gets its city shown as well. This is done through a "Has display parameters" call found here.

There are several issues relating to the use of "Has display parameters":

[edit] Removing the list of categories

You may want to have the drilldown page show the data only for one category, and not include the list of categories for the user to click away from the current one. To enable that, just add the string "_single" to anywhere in the URL query string; this will remove the list of categories. An example of such a URL is "Special:BrowseData/Cars?_single".

[edit] Showing category names as tabs

If you add the following line to LocalSettings.php:

$sdgShowCategoriesAsTabs = true;

...it will display categories as tabs at the top of the page, instead of in a vertical list on the side of the page. This option makes more sense for sites with a smaller number of categories (less than seven or so).

[edit] Changing the order of filters

By changing the order in which the "Has filter" tags appear on the category page, the order of the filters on the drilldown page can be changed.

[edit] Excluding and including categories in the drilldown

You may want certain categories to not show up in the main top-level list of categories. You can easily remove a category by adding the following anywhere within the category's page:

__HIDEFROMDRILLDOWN__

Conversely, there are some categories that you may want to show up in the main BrowseData list, even though they are not top-level categories. You can accomplish this as well, by adding the following to the category's page:

__SHOWINDRILLDOWN__

[edit] Sites that use Semantic Drilldown

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

You can see an alternate listing of sites that use Semantic Drilldown on the Semantic MediaWiki Community Wiki, an SMW-based wiki that contains additional information on each wiki.

[edit] Mailing list

You should use the Semantic MediaWiki mailing list, semediawiki-user, for any questions, suggestions or bug reports about Semantic Drilldown. If possible, please add "[SD]" at the beginning of the subject line, to clarify the subject matter.

[edit] Hosting

Currently three wiki hosting sites offer support for Semantic Drilldown:

[edit] Contributing to the project

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

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

[edit] Translating

Translation of Semantic Drilldown is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, 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.

Language: English  • 中文 • ‪中文(繁體)‬
Retrieved from "http://www.mediawiki.org/wiki/Extension:Semantic_Drilldown"
Personal tools
Namespaces
Variants
Actions
Site
Support
Download
Development
Communication
Toolbox