Help:Filtered format

From semantic-mediawiki.org
Jump to: navigation, search
Filtered format
Displays query results as switchable views, offers filtering
Further Information
Provided by: Semantic Result Formats
Added: 1.8.0
Removed: still supported
Requirements: none
Format name: filtered
Enabled by default: 
Indicates whether the result format is enabled by default upon installation of the respective extension.
No
Authors: Stephan Gambke
Categories: misc
Group:
Table of Contents

↓ INFO ↓


The result format filtered, part of the Semantic Result Formats extension, displays results in switchable views and offers client-side (JavaScript based) filtering.

This result printer replaced the "exhibit" format starting with Semantic MediaWiki 1.8.0. Currently a list view (SRF 1.8.0 and later), a calender 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.

NoteNote: Starting with Semantic Result Formats 2.5.0 this result format is no longer enabled be default. To enable it, see the instructions on Semantic Result Formats.

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 |+someFutureFilter filter option=someOptionValue
 |? SomeOtherPrintout |+filter=value, someOtherFutureFilter |+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

  • +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 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. If the number of values exceeds the specified height, you then get a scrollbar. This is especially useful for filters with large sets of values.

distance

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

  • +distance filter origin= e.g. start point or lat/long geographic coordinate
  • +distance filter unit= e.g. km or mi for miles
  • +distance filter initial value=x (does not need unit) sets initial value of the slider e.g. 100
  • +distance filter max distance=x limits the maximum value for the slider.

It should be noted that if Google geocoding is used, this funtionality will result in a lot of 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 set as filters. Job Title filter will start collapsed 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 set as filters. There will be a distance slider 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. → Live example

Calendar View

This view outputs the query results into a calendar. For the format to work you need to specify the printout that contains the start date of an event. 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 the start and end dates of each result.

'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 wikipage printout in the result is taken, which usually is 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 sortable table (available since SRF 2.3).

{{#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 am map (available since SRF 2.5). The Maps extension is not required for this to work.

{{#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
}}

$srfgMapProvider must be set in Localsettings.php to specify the used map.

$srfgMapProvider='OpenStreetMap.HOT';

A list of available providers is 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-filters,
.filtered-value { 
        overflow: visible;
        border: 1px solid #aaa;
        padding: 2px;
        margin: 0.5em;
        margin-bottom: 1em;
        width: 200px;
}

Here is 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;
}

Live Examples

An example of the filtered calendar can be seen here: http://www.wiltshireparentcarercouncil.co.uk/en/Children_Calendar
An example with switchable view can be seen here: http://www.wiltshireparentcarercouncil.co.uk/en/User:Stephan_Gambke (see also the respective query)

Sponsorship

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



This documentation page applies to all SMW versions from 1.8.0 to the most current version.
     

Help:Filtered format en 1.8.0