Help:Filtered format

From semantic-mediawiki.org
Help:Filtered formatFiltered format/zh-hans
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

Sponsorship

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


References

  1. ^  Semantic Result Formats: GitHub issue gh:srf:272
  2. ^  Semantic Result Formats: GitHub issue gh:srf:239