User:Badon/Extension:Semantic MediaWiki/Manual

Semantic MediaWiki is a system. An integrated approach is needed to make sense of how to use SMW, which itself aims to make the data in a wiki more useful. SMW documentation is scattered across several extension pages as well as many different websites, some of which are occasionally down for maintenance [1]. This page is intended to provide supplemental information, and link all available information in one easily-accessible place.

Semantic MediaWiki

Stay in the loop

TODO

If you want to do any of these things, contact badon. It might be possible to arrange [2] some donated funding for you [3].

Add jqPlot and PHPlot to Semantic Result Formats for enhanced data visualization.
Create Extension:ImageAnnotator to ease installation of ImageAnnotator. Currently installation must be done manually, and all scripts, templates, messages, etc are tuned for only WikiMedia Foundation wikis. An extension can make it simple to install on any wiki. You may view changes done to make it work on a private MediaWiki installation here: [4]
Create Extension:Semantic_ImageAnnotator to enable Semantic Forms in ImageAnnotator, so image annotations can be part of SMW's semantics.
Extension:Collection needs to support parser functions and work with SMW's property syntax [5]

Shortcomings and limitations

Cannot traverse property "chains" easily with ordinary queries.
"Lite" version for Wikipedia will not be able to do queries at all.
Semantic forms cannot create file pages [6]
SMW persistently shows deleted pages

Common problems

If you use a query with the sort parameter for a property, if there are any pages that do not have that property, they will not be returned in the query. You might normally expect them to be returned unsorted.

Needed special properties

Page name
Page categories
Page templates
Page forms
Page number of edits
Page number of links outbound
Page number of links inbound
Page size
Page number of views
Page modification date - already implemented
Page creation date - in progress
Page creator Bugzilla:30610
Page editors Bugzilla:30610
Page last editor
User registration date
User number of edits

Of those in the above list, these are currently doable, mostly with workarounds, and should have lower priority:

Page name - store manually with {{CURRENTPAGE}} magic word
Page categories - store manually, also queriable as ?Category
Page templates - store manually
Page forms - store manually
Page modification date - already implemented

These are available in Extension:SemanticExtraSpecialProperties Bugzilla:30610:

Page creator
Page editor
Revision ID
Number of page views

This list of needed special properties is taken from these three sources:

http://smw.referata.com/wiki/Add_page_metadata_properties_to_a_page_(using_DPL)
Bugzilla:13151
Bugzilla:29988 (mentions they need need to show in SMW factbox)

And consolidated here:

Bugzilla:30610

Page creation date has turned out to be critical:

Bugzilla:30784

Additionally, special properties do not show up in the SMW factbox:

Bugzilla:30628

Future goals

How to

Semantic MediaWiki 1.7 undocumented breaking changes

The official Semantic MediaWiki documentation is obsolete. In fact, the official SMW site is still running an obsolete version of SMW. Documented below are some crucial differences that upgraders will need in moving from SMW 1.6.x to SMW 1.7.x.

#ask query for page names

If you upgraded to Semantic MediaWiki 1.7 and suddenly nothing works on your site, it is because there were undocumented breaking changes made to the #ask query syntax [9]. In earlier versions, this used to produce page names:

{{#ask: [[Category:Some category]]
        | ? 
        | link=none 
}}

Now it produces a table with the page names repeated such that there are two columns containing the same page name data, that looks like this:


Some page	Some page

These queries now produce the same output, identical to the older behavior of SMW prior to 1.7 that would be expected from the first example where only the page names were output:

{{#ask: [[Category:Some category]]
        | link=none 
}} 

{{#ask: [[Category:Some category]]
        | ?= 
        | mainlabel=- 
        | link=none 
}}

I'm still not sure if that intentional, or is a bug, but I think it is intentional. The new behavior seems reasonable, and simpler, even though it's a frustrating breaking change that is undocumented, not backwards compatible, and requires site-wide changes to fix broken queries. If this was intentional, it should definitely be documented very prominently so users will know in advance that upgrading will break older queries, and explain what they need to change to fix the broken queries so they will display as intended with SMW 1.7.

count format

This used to produce 0 if there were no results:

{{#ask: [[Category:Some category]]
        | format=count
}}

Now, it produces nothing instead of zero. You can get a zero this way (using Extension:Variables for #vardefine):

{{#vardefine: count |
        {{#ask: [[Category:Some category]]
                | format=count
        }} 
}}<nowiki />
{{#if: {{#var: count }}
        |
        | {{#vardefine: count | 0 }}
}}<nowiki />

Then, you have a variable that contains the number 0 if your query has no results. The reason you use #vardefine is so you only need to run the query once. Without it, you may need to run it multiple times, every time you want to use the number of results.

However, when your query is on a property, it will still give you 0 like it always has, even if the property does not exist on your wiki:

{{#ask: [[Some property name::Some property]]
        | format=count
}}

This is inconsistent behavior, and is probably a bug, described here: count format not producing 0 on non-existing category queries.

#ask multiple property comma delimited list format

This used to produce a comma delimited list of values if a property was specified more than once, so that it has more than one value:

[[Some property::value 1]]
[[Some property::value 2]]

{{#ask: [[Some page]] | ?Some property= | link=none }}

The output would look like this:

value 1, value 2

Now it produces a table with the multiple properties listed in a column, like this:


Some page	value 1 value 2

These queries now produce the same output as they did with the older versions of SMW:

{{#ask: [[Some page]] | ?Some property= | mainlabel=- | link=none }}

{{#show: Some page | ?Some property | link=none }}

The output will look like this:

value 1, value 2

Note that there is a serious bug that inserts 2 invisible spaces after the comma, instead of just one that you will see in your web browser when you run the queries above on a wiki that has SMW installed. The extra space is invisible because web browsers do not display more than one space at a time - all other spaces are hidden. If you try to do comparison operations, you will get incorrect results. The bug is described in detail here:

Bugzilla:33478

Semantic Forms

How to

Shortcomings and limitations

#formlink parses query strings incorrectly if there is an & character in parameters

Semantic Maps

Shortcomings and limitations

Display_points fails in templatized queries with unnamed parameters because points are delimited by semicolons, but Semantic Maps cannot handle a semicolon on the last point. This can be worked-around with more complex conditional code to find the last point, and ensure it does not have a semicolon. See Bugzilla:30534
Maps do not work in most situations when a map is generated within a template. A workaround is available for 1.0.1. Version 1.0.4 of the Semantic Maps bundle cause a wiki to completely cease functioning, and 1.0.3 causes the workaround used in 1.0.1 to fail. 1.0.2 has not been tested. Bugzilla:32416#c10