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: beta
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.6.2 (November 2009)
MediaWiki  1.8.* or greater
License GPL
Download See here
Example  The "browse data" interface for Discourse DB

check usage (experimental)

Contents

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

  • 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 view only the pages that belong to that subcategory. The resulting drilldown page will include links for all the filters for the top-level category, and any subcategories of the selected subcategory. You can thus use the "Browse data" page to navigate through the entire category tree.
  • Filters - filters based on semantic properties can be manually created and added to 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 certain values for a semantic property. There are four ways to set the possible values for a filter (described in detail below):
    • From property values - the default method; the filter simply shows all current values for this property.
    • 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.

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.5.8, as well as some other very interesting extensions.

[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/includes/SD_Settings.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: The CreateFilter special page requires that the MySQL user has the 'Create_tmp_table_priv' privilege.

[edit] Languages supported

Semantic Drilldown has full support for English, Taiwanese Chinese, Mainland Chinese, German and Persian, and partial support for Afrikaans, Arabic, Belarusian, Bulgarian, Danish, Dutch, Finnish, French, Greek, Hebrew, Hindi, Hungarian, Indonesian, Japanese, Khmer, Korean, Marathi, Pashto, Polish, Portuguese, Brazilian Portuguese, Romanian, Russian, Spanish, Swedish, Tagalog, Tajik, Thai, Turkish, Vietnamese and many other languages.

[edit] Author

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

[edit] Version

Semantic Drilldown is currently at version 0.6.2. 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:

  • Drill down through the data. As soon as you've installed Semantic Drilldown, you can go to the "BrowseData" 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.

[edit] Filter settings

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

  • Covers property - The only mandatory tag. Specifies which relation, attribute or property this filter applies to.
  • Gets values from category - States that the possible values for this filter are all the pages that are members of a certain category.
  • Has value - Adds a specific value allowed for this category. You can add as many such tags as you want to a filter.
  • Uses time period - Used for date filters; indicates the period of time that values are divided into (options are "Month" and "Year").
  • Has input type - Sets an input type for the user to enter a filter value, instead of clicking on pre-specified values (options are "combo box" and "date range").
  • Has label - Specifies the name of the filter which will be displayed on the screen.
  • Requires filter - 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.

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

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

Unfortunately, currently one format is allowed for any one category.

Note that, due to a Javascript conflict, the 'combobox' input won't work on a drilldown results page if a map format is being used.

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

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

  • Referata - a site created and run by Yaron Koren. Wikis on Referata can use Semantic MediaWiki, Semantic Drilldown and a variety of related extensions; basic usage is free.
  • Wikia - wikis on Wikia can request Semantic MediaWiki, Semantic Drilldown and Semantic Forms to be turned on (they are not enabled by default). Be aware that these extensions can be several versions behind on Wikia; see here, for example, for the current version numbers. Additional SMW-based extensions are currently not available on Wikia.
  • YourWiki - similarly to Wikia, Semantic Drilldown and related extensions can be turned on by request.

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

Languages Language: 

English  • 中文  • ‪中文(繁體)‬
Retrieved from "http://www.mediawiki.org/wiki/Extension:Semantic_Drilldown"