Extension:Semantic Drilldown

MediaWiki extensions manual

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
Maintainer(s)	gesinn.it
Latest version	4.0.0-beta3 (November 2022)
MediaWiki	1.35+
PHP	7,4+
Database changes	No
License	GNU General Public License 2.0 or later
Download	GitHub: project page git repository URL [help ] commit history
Example	Narutopedia
Parameters $sdgShowCategoriesAsTabs $sdgNumRangesForNumberFilters $sdgDisableFilterCollapsible $sdgFiltersLargestFontSize $sdgHideCategoriesByDefault $sdgFiltersSmallestFontSize $sdgMinValuesForComboBox $sdgHideFiltersWithoutValues $sdgNumResultsPerPage $sdgResultFormatTypes
Hooks used AdminLinks MagicWordwgVariableIDs MakeGlobalVariablesScript ParserAfterTidy PageSchemasRegisterHandlers ParserFirstCallInit UnitTestsList

The Semantic Drilldown extension 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, which adds semantic annotations that allow a wiki to function as a collaborative database.

Installation

• You must have Semantic MediaWiki installed for this extension to work.
• Download and place the file(s) in a directory called SemanticDrilldown in your extensions/ folder.
• Add the following code at the bottom of your LocalSettings.php file:

  wfLoadExtension( 'SemanticDrilldown' );
  

• Run the update script which will automatically create the necessary database tables that this extension needs.
•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Authors

Semantic Drilldown was mostly written by Yaron Koren. 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. Much of the current code for handling date filters was written by Edward Chernenko. Helpful contributions have also been made by MWJames, Joel Natividad and others.

Version history

• 3.x+ version history
• < 3.x 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 Page Forms "Getting started" section for more on how to set these up.

Make sure that some pages exist, that these pages contain annotations, and that the pages belong to a category.

After all this is done, you should first go to the page "Special:BrowseData" and see what the category structure looks like on your site.

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.

Usage

Special:BrowseData

A Semantic Drilldown page

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 they have 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.

#drilldowninfo

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.

#drilldowninfo takes in the following parameters:

• filters - takes in 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.

Example

{{#drilldowninfo:filters=Author (property=Was written by),
Second author (property=Was written by),
Date (property=Was published on),
Source (property=Was published by,category=Sources),
Topic (property=Addresses topic,category=Topics),
For (property=Is for, category=Positions,requires=Topic),
Against (property=Is against,category=Positions,requires=Topic),
Mixed (property=Is mixed on,category=Positions,requires=Topic)}}

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).
• header - sets the name of a page (e.g. Template:SD Header) to be displayed before the filters.
• footer - sets the name of a page to be displayed after the drilldown output.
• 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.
• As of Semantic MediaWiki version 1.8 and later wiki markup and html in properties of type text is displayed as plain text in various table result formats (table, broadtable, datatables), a workaround would be using result format template to create tabular output

Display options

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

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.

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:

$sdgNumResultsPerPage=250;

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:

$sdgMinValuesForComboBox=50;

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

$sdgNumRangesForNumberFilters=4;

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.

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

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:

$sdgHideCategoriesByDefault = true;

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;

{{#drilldownlink:category=|subcategory=|single|link text=|tooltip=|filters=}}

The parameters are as follows:

• category - the category name
• subcategory - the subcategory, if any
• single - if this parameter is added, the list of categories is not displayed
• link text - the text of the link; by default, it's the category name
• tooltip - the text that appears when the cursor hovers over the link, if any
• filters - 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:

• Edge of Darkness Wiki
• Structural Wiki
• Verwaltungskooperation

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.

Contributing to the project

Bugs and feature requests

You can submit bug reports and requests for new features in GitHubs's bug tracker.

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

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.

See also

• Cargo - provides a similar drill-down interface, on top of a different storage system