Help:Filtered format

Filtered format
Displays query results as switchable views, offers to filter
Further Information
Provided by:	Extension "Semantic Result Formats"
Added:	1.8.0
Removed:	still supported
Requirements:	none
Format name:	filtered
Enabled? Indicates whether the result format is enabled by default upon installation of the respective extension.	Yes
Authors:	Stephan Gambke
Categories:	misc
Table of Contents

The result format filtered, part of extension "Semantic Result Formats"Provides additional formats for semantic queries, displays results in switchable views and offers client-side (JavaScript-based) filtering.

This result printer replaced result format "Exhibit"Displays query results in interactive charts, tables and maps starting with Semantic MediaWiki 1.8.0Released on 2 December 2012 and compatible with MW 1.17.0 - 1.22.x
(except 1.22.1).. Currently, a list view (SRF 1.8.0 and later), a calendar view (SRF 1.8.0 and later), a table view (SRF 2.3.0 and later), a map view (SRF 2.5.0 and later) and a number view (SRF 2.5.0 and later) are available. It is possible to switch between views. There are the value and distance filters available. The output may be templated. You can specify a different template for each view. See also the format specific README.

From Semantic Result Formats 2.5.0 to 2.5.2, this result format was not enabled by default.1 To enable it for these versions, see the instructions on extension "Semantic Result Formats"Provides additional formats for semantic queries.

Usage

Syntax of the #ask call: (This is only a syntax example. For currently available features, see the documentation of the various views and filters.)

{{#ask:
 
 [[SomeCondition]]

 |? SomePrintout |+filter=value, someFutureFilter |+value filter switches=and or, disable, select all, select none |+hide=no |+someFutureFilter filter option=someOptionValue
 |? SomeOtherPrintout |+filter=value, someOtherFutureFilter |+hide=no |+someOtherFutureFilter filter option=someOptionValue

 |format=filtered
 |views=list, calendar, someFutureView, someOtherFutureView

 |list view type=list
 |list view template=ListItem

 |calendar view title template=CalendarItem

 |someFutureView view option=someOptionValue

 |someOtherFutureView view option=someOptionValue

}}

Parameters

General

Parameter	Type	Default	Description
source	text	empty	Alternative query source
limit	whole number	50	The maximum number of results to return
offset	whole number	0	The offset of the first result
link	text	all	Show values as links
sort	list of texts	empty	Property to sort the query by
order	list of texts	empty	Order of the query sort
headers	text	show	Display the headers/property names
mainlabel	text	no	The label to give to the main page name
intro	text	empty	The text to display before the query results, if there are any
outro	text	empty	The text to display after the query results, if there are any
searchlabel	text	... further results	Text for continuing the search
default	text	empty	The text to display if there are no query results

Format specific

Parameter	Type	Default	Description
views	text	empty	The views that shall be available in the result display.
filter position	text	top	The position of the filters in relation to the views. Allowed values: "top", "bottom". Default: "top".
list view type	text	list	The type of the list. Allowed values: "list", "ul", "ol". Default: "list".
list view template	text	empty	The template that is to be used to format the list entries.
list view named args	yes/no	no	Name the arguments passed to the template.
list view introtemplate	text	empty	The name of a template to display before the query results, if there are any.
list view outrotemplate	text	empty	The name of a template to display after the query results, if there are any.
calendar view start	text	empty	The printout containing the start date of an event
calendar view end	text	empty	The printout containing the end date of an event
calendar view title	text	empty	The printout containing the title of an event. Can not be used together with a title template.
calendar view title template	text	empty	A template used to format the event's title in the calendar
table view class	text	wikitable sortable	An additional CSS class to set for the table
map view marker position property	text	empty	The printout containing the geographical position.
map view marker icon property	text	empty	The printout which decides the map icon to be used.
map view marker icons	list of texts	empty	A map of values to icons to be used for these values on the map.
map view height	number and dimensional unit	auto	The height of the map.
map view zoom	whole number	empty	The zoom level when the map is loaded. This may be changed by the user. See: map view min zoom and map view max zoom
map view min zoom	whole number	empty	The minimum selectable zoom level of the map
map view max zoom	whole number	empty	The maximum selectable zoom level of the map
map view marker cluster	yes/no	yes	Turn marker clustering on or off.
map view marker cluster max zoom	whole number	empty	Maximum zoom level at which map markers are still clustered. Above this level markers will always be unclustered.
map view marker cluster radius	whole number	empty	The maximum radius that a cluster will cover from the central marker (in pixels). Default 80.
map view marker cluster zoom on click	yes/no	yes	When enabled clicking cluster will zoom to its bounds.

Filters

value

Filter option	Comment
+value filter switches=and or	Display an AND/OR switch. When OR is checked, clicking >1 filter value will show results containing value1 OR value2, etc. If AND is selected, clicking >1 filter value will show results containing value1 AND value2, etc.
+value filter switches=on off	Display on ON/OFF switch. This way, users can switch off a filter completely.
+value filter collapsible=collapsed,uncollapsed	Allows the filter to be collapsed. You can specify whether to default to collapsed or uncollapsed.
+value filter height=xxxpx	Allows you to specify the height of each filter. You get a scrollbar if the number of values exceeds the specified height. This is especially useful for filters with large sets of values.
+hide=yes,no	+hide=yes, you can use the property for filtering but hide it from the printout in the view (e.g., if you don't want to repeat the filter value in the table view)
+value filter max checkboxes	Sets a maximum number of checkboxes to be displayed. (Default=5). If the different values of the property are more than this value, the checkboxes will be turned into a tokens field (multi-select dropdown).
+show if undefined	Makes filters show a result item even if the printout does not contain a value.

number

Provides a numerical slider for the result set based upon a number type property.

Filter option	Comment
+number filter switches=on off	Display on ON/OFF switch. This way, users can switch off a filter completely.
+number filter collapsible=collapsed,uncollapsed	Allows the filter to be collapsed. You can specify whether to default to collapsed or uncollapsed.
+number filter sliders (min|max|range|select)	Defines the numerical filter slider. min=Minimum value (1 slider on the left), max=maximum value (1 slider on the right, range=min and maximum (1 slider left, one slider right), select (1 slider that selects an exact value)
+number filter min value=(number)	Sets a minimum value for the filter.
+number filter max value=(number)	Sets a maximum value for the filter.
+number filter step=(number)	Sets a value for the steps of the slider.
+number filter values (auto|comma-separated list of values)	If this parameter is specified, min, max, and step will be ignored.
+number filter label (string)	Specifies a label for the filter

distance

Provides a distance slider based on a geographic coordinate type property for the result set. Additional parameters:

Filter option	Comment
+distance filter switches=on off	Display on ON/OFF switch. This way, users can switch off a filter completely.
+distance filter collapsible=collapsed,uncollapsed	Allows the filter to be collapsed. You can specify whether to default to collapsed or uncollapsed.
+distance filter origin=(coordinate)	e.g., start point or lat/long geographic coordinate
+distance filter unit=km,mi	e.g., km or mi for miles
+distance filter initial value=(number)	sets the initial value of the slider e. g., 100. It does not need a unit.
+distance filter max distance=(number)	limits the maximum value for the slider.

It should be noted that if Google geocoding is used, this functionality will result in many API calls. Google has set a limit for the number of free geocodes per day of 2500. It is best to work using lat/long as this currently has no limit.

Views

List View

• list view template=<template>

Allows you to specify a template to format the results. This is the same as format=template in standard SMW queries See here for details.

Example Queries

{{#ask:

 [[Category:People]]
 [[Name::+]]

 |?Job Title |+filter=value |+value filter height=150px |+value filter collapsible=collapsed
 |?Biog
 |?City |+filter=value |+value filter height=200px |+value filter collapsible=uncollapsed
 |?Country |+filter=value |+value filter switches=and or |+value filter collapsible=uncollapsed

 |format=filtered
 |views=list
 |list view type=list
}}

This will show a result set with Job Title, City, and Country properties as filters. The job Title filter will start collapsing and will have a scrollbar. City will start uncollapsed and will have a scrollbar. Country will have the AND/OR selector switched on and no scrollbar.

Example distance query

{{#ask:

 [[Category:People]]
 [[Name::+]]

 |?Job Title |+filter=value |+value filter height=150px |+value filter collapsible=collapsed
 |?Biog
 |?City |+filter=value |+value filter height=200px |+value filter collapsible=uncollapsed
 |?Coordinates=Distance |+filter=distance |+distance filter origin=London, UK

 |+distance filter unit=miles
 |+distance filter initial value=5

 |format=filtered
 |views=list
 |list view type=list
}}

This will show a result set with Job Title, City, and Country properties as filters. A distance slider will be visible that allows you to filter the results based on the distance from London, UK. This assumes each page has a geographic coordinate property set for each person.

Calendar View

This view outputs the query results into a calendar. For the format to work, you need to specify the printout containing an event's start date. You can also specify the printout for the end label. It should look like that:

{{#ask:

 [[Category:Event]]

 |?Start |+filter=value
 |?End

 |format=filtered
 |views=calendar

 |calendar view start=Start
 |calendar view end=End
}}

The 'calendar view start' parameter: If you do not specify the printout, the first date printout is used.

The 'calendar view end' parameter (optional): If the individual results span multiple days, you can specify the end date. The output will then be drawn as a bar between each result's start and end dates.

'calendar view title' parameter (optional). This names the printout to be used as a title of an event in the calendar. If you do not specify this, the first wiki page printout in the result is taken, usually the result object itself.

'calendar view title template' parameter (optional): Allows you to specify a template to format the results.

Table View

This view outputs the query result as a sortable table (available since SRF 2.3.0).

{{#ask:

 [[Category:People]]
 [[Name::+]]

 |?Job Title |+filter=value |+value filter height=150px |+value filter collapsible=collapsed
 |?Biog
 |?City |+filter=value |+value filter height=200px |+value filter collapsible=uncollapsed
 |?Country |+filter=value |+value filter switches=and or |+value filter collapsible=uncollapsed

 |format=filtered
 |views=table
}}

Map View

This view outputs the query result on a map (available since SRF 2.5.0). The Maps extension is not required for this to work.2

{{#ask:

 [[Category:People]]
 [[Name::+]]

 |?Job Title |+filter=value |+value filter height=150px |+value filter collapsible=collapsed
 |?Biog
 |?City |+filter=value |+value filter height=200px |+value filter collapsible=uncollapsed
 |?Country |+filter=value |+value filter switches=and or |+value filter collapsible=uncollapsed
 |?Coordinates

 |format=filtered
 |views=map

 |map view marker position property=Coordinates
 |map view height=800
 |map view marker cluster=true
 |map view marker cluster max zoom=11
 |map view marker icon property=Has icon
 |map view marker icons=building=house.png, bridge=bridge.png, default.png
}}

Configuration parameter $srfgMapProvider must be set in the "Localsettings.php" file to specify the used map:

$srfgMapProvider='OpenStreetMap.HOT';

A list of available providers can be found here [1].

Switching Views

You can specify several views and will be able to switch between them. The call looks something like this:

{{#ask:

 [[Category:Event]]

 |?Start |+filter=value
 |?End
 |?Location

 |format=filtered
 |views=calendar=Calendar View,list=List View

 |calendar view start=Start
 |calendar view end=End
 |calendar view title template=Calendar Format Template
 |list view template=List Format Template
}}

In the 'views' parameter, you can specify the label that should be put on the selector tab for the respective view.

Skinning

The filters can be skinned. The default CSS is contained in the skins folder of the extension. The default CSS presents the filters horizontally across the page with the result set below.

The following example CSS presents the filters appearing stacked on the left with the result set on the right:

.filtered {
    display: flex;
    flex-direction: row-reverse;
}

.filtered .filtered-views {
     flex: auto;
}

.filtered .filtered-filters {
    width: 300px;
    margin: 1em 0 0 1em;
}

Here is an example CSS for the collapse controls:

.filtered-filters,
.filtered-value,
.filtered-value-show {
	position: relative;
	top: -1em;
	right: 0;
	float: left;
	width: 1.5em;
	padding: 0 0.1em;
	margin: 0;
	cursor: pointer;
	text-align: center;
	font-size: 90%;
}
.filtered-filters,
.filtered-value,
.filtered-value-hide {
	position: relative;
	top: -1em;
	right: 0;
	float: left;
	width: 1.5em;
	padding: 0 0.1em;
	margin: 0;
	background-color: #EAF5E9;
	cursor: pointer;
	text-align: center;
	font-size: 90%;
}

Example CSS required for the scrollbars:

.filtered-filters,
.filtered-value,
.filtered-value-scrollable {
	overflow: auto;
}

Examples

• www.geschichtewiki.wien.gv.at – cinemas in vienna
• www.wissensmanagement.gv.at – toolbox of knowledge management tools
• fina.oeaw.ac.at – annotated printed books
• www.caf-network.eu – CAF practices

Sponsorship

This extension is sponsored by Prescient Software and KDZ - Centre for Public Administration Research.