Extension:Semantic Drilldown

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.6 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 set 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 certain values for a semantic property. There is special handling for filters that correspond to properties of type Date or Number - for Date filters, the time range by which values are grouped (years, months or days) depends on the distribution of the current set of values, and for Number filters, the number values are grouped into a set of ranges of approximately equal size, again depending on the current set of values.



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.

Code and download
You can download the Semantic Drilldown code, in .zip format, here.

You can also download the code directly via Git from the MediaWiki source code repository. From a command line, you can call the following:

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

Installation
After you've obtained a 'SemanticDrilldown' directory (either by extracting a compressed file or downloading via Git), 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):

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.

Authors
Semantic Drilldown was mostly written, and is maintained, by Yaron Koren, reachable at yaron57 -at- gmail.com. The code to display drilldown results was written by David Loomer. The 'combo box' jQuery input was created by Sanyam Goyal as part of the 2010 Google Summer of Code. The code for interfacing with the Page Schemas extension was created by Ankit Garg as part of the 2011 Google Summer of Code. Helpful contributions have also been made by MWJames, Joel Natividad and others.

Version history
Semantic Drilldown is currently at version 2.0. See the entire version history.

Getting started
Before you set up Semantic Drilldown, you should have all the data structures on your site set up - properties, 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 first go to the page "Special:BrowseData" 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.

At this point, you have two options, depending on whether or not you have the Page Schemas extension installed. (In brief, it presents a single interface for generating templates, forms and filters.) If you are using Page Schemas, then you can go back into the page schema(s) you have already created (or, if you haven't, create new ones), and add filters onto each relevant property via the interface.

If you don't have it, you should make use of the #drilldowninfo parser function.

#drilldowninfo

 * 1) drilldowninfo takes in the following parameters:


 * filters - takes in a the set of filters for this category. In most cases, this will be the only parameter set. Filters should be separated by commas, and after each filter's name, in parentheses, should be a clause listing any of the following:
 * property - the Semantic MediaWiki property that this filter applies to (mandatory)
 * category - a MediaWiki category from which to get values
 * requires - any number of previously-listed filters, that the user must select a value for before they can see this filter.


 * For example, here is is the relevant part of the source code for the 'Items' category page at Discourse DB:


 * Filters are displayed in Special:BrowseData in the order in which they are listed in #drilldowninfo.


 * title - sets the title for the drilldown page for this category (optional).


 * display parameters - this parameter lets you 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, and the format (such as a map or calendar) in which results will be displayed. "display parameters=" 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 have the following in the call: "|display parameters=? Has coordinates;format=googlemaps3".


 * You can see an example of a simple use of this functionality here; every event gets its city shown as well. The relevant #drilldowninfo call is here.


 * There are several issues relating to the use of "display parameters=":
 * Unfortunately, currently one format is allowed for any one category.
 * The "sort=" and "order=" parameters for inline queries will not work - pages will always be sorted by their name.

The #drilldowninfo parser function should only be added to either top-level categories, or categories whose page contains "__SHOWINDRILLDOWN__" - see Excluding and including categories from the list.

Note: this process of using #drilldowninfo is new as of SD 2.0; before then, setting up the drilldown involved creating pages in the "Filter:" namespace, and using SMW "special properties". These are still supported for the foreseeable future, although deprecated. For documentation on how to set up filters for earlier versions of Semantic Drilldown, see this earlier version of the documentation.

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:

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

Setting the number of results per page
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:

Setting the display of filter values
For filters that have above a certain number of values, values are shown in a combo box, instead of individually. By default, that number is 40. To change the number, add something like this to LocalSettings.php: ...or you can set it to 0 or 1 if you want filter values to always show up within a combo box, in order to boost performance; values shown individually require an additional database query in order to get the number of instances of that value.

For filters that correspond to Number properties, the values are automatically grouped into ranges, with an attempt to create ranges of roughly equal size while still having "nice" numbers for the boundaries (e.g., 1200 instead of 1234). By default, values are grouped into 6 ranges. To change this number, add something like this to LocalSettings.php:

Display of categories
By default, a list of all top-level categories on the wiki shows up on one side of the "Browse data" page, to let users navigate to the drilldown interface for each such category. However, this display can be modified in a number of ways.

Removing the list of categories
You may want to have the drilldown page show the data only for one category, and not display the list of other categories. To do 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" - see here for one example.

Showing category names as tabs
If you add the following line to LocalSettings.php:

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

Excluding and including categories from the list
You may want certain categories to not show up in the 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__

Conversely, you can also set for categories to only show up in the list if you specifically include them, i.e. have an "opt-in" instead of an "opt-out" approach. You can do that by adding the following to LocalSettings.php:

If you do that, only categories marked with " __SHOWINDRILLDOWN__ " will appear. (The " __HIDEFROMDRILLDOWN__ " marking, on the other hand, will become irrelevant.)

Linking to a drilldown page
The best way to link to Special:BrowseData is with the #drilldownlink parser function. It has the following syntax;

The parameters are as follows:
 * category - the category name
 * subcategory - the subcategory, if any
 * single</tt> - if this parameter is added, the list of categories is not displayed
 * link text</tt> - the text of the link; by default, it's the category name
 * tooltip</tt> - the text that appears when the cursor hovers over the link, if any
 * filters</tt> - the set of filters to apply, in the format "a=b&c=d&..."

Sites that use Semantic Drilldown
Here is a small sampling of sites that use Semantic Drilldown:

For a much more comprehensive listing, see the Semantic MediaWiki Community Wiki (which itself uses Semantic Drilldown to show the list).
 * Discourse DB
 * Domotiki - A French wiki about home automation including a collaborative prices comparator
 * EPSA - European Public Sector Award winners and nominees
 * Food Finds
 * Politique.sémantique.com a wiki about statements of french policy makers (in french)
 * SKYbrary - wiki for Aviation Safety, browser for Accidents and Incidents in Civil Aviation
 * Solutions-web.eu, lists and compares commercial offers about web sites benefits : hosting, conception...
 * Structural Wiki - wiki for structural engineers
 * Technical Presentations
 * UNDP Inter-Municipal Cooperation
 * Verwaltungskooperation - Cooperation in Public Administration
 * WeCoWi

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.

Hosting
Currently two 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 - some wikis on Wikia have Semantic MediaWiki, Semantic Drilldown and Semantic Forms installed.

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 either create a Git commit with that change, create a patch by going to the main "SemanticDrilldown" directory, and typing:

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 either link to the Git commit or attach this patch file to it.

If, for any reason, you don't wish to use Bugzilla, feel free to simply send an email to Yaron Koren.

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.