Extension:SemanticQueryFormTool

UPDATE
Please note that this extension is only compatible for SMW versions < 1.6 (see Compatibility section below for details). A new modified version of SQFT, named Extension:SemanticPropertyTools is being tested for SMW 1.8 (MW 1.19.1) and should be mostly backwards compatible for existing SQFT uses.

Purpose
The SemanticQueryFormTool (SQFT) extension is not meant to be a general purpose extension per-se but was rather written and is further developed to provide solutions for tasks (especially in terms of querying the semantic data) with a specific wiki in mind. Still most functions are general enough to be also useful for other semantic wikis. It is, however, recommended to have first a look at the Semantic Forms extension which is a very versatile general tool extension also for querying semantic wikis via forms with many options and to check if it can provide the required functionality. SQFT comes in two forms: SQFT itself which contains all files and SQFTlight which tries to include only the necessary code for the search functionality and comes without files needed only for more exotic tasks.

Instead of the full SQFT extension it is recommended to use SQFTlight which is much smaller as it contains only the core functions of SQFT! (for SMW 1.5.x+ only).

Compatibility
NOTE that SQFT is NOT compatible with SMW 1.6 (as SMW 1.6 doesn't store anymore the complete information about multi-value properties in the DB the data SQFT requires are simple not available in the DB)

'SMW 1.5.* is only compatible with SQFT >= 0.3.0 !'

SQFT 0.3.0 also still works with SMW >= 1.4.2, if no n-ary properties are used SQFT 0.2.9 should be working ok with SMW 1.5.*

Introduction
The SemanticQueryFormTool (SQFT) extension is an extension of the SMW extension rather than of MW itself. It implements the parser function (the leading 's' stands for 'Select' and 'Save' because generating 'select' form elements and saving query results are the two main usages of the function) which uses a similar syntax as the original SMW    parser function.

This extension was developed as a tool to support the generation of user friendly query forms for semantic data in our wiki. For many properties user neither know what data are already present nor what the syntax of the values is. Therefore it would be impossible to enter exact search terms into a text field of a query form. By providing select elements which contain the existing values of a property the user can simply select the desired value(s).

The extension has also more specific functions (which are not included in the SQFTlight version) like a Browse function for an enhanced and configurable display of properties and their values (for details see the description on help.malariapedia.info), a function to store query results and combine them at a later stage or display a large number of geo-referenced semantic property values via a map display.

Pre-requisite

 * Make sure the SMW extension is installed

Mandatory steps

 * 1) Download zip file from from here and unzip
 * 2) Create $IP/extensions/SemanticQueryFormTool/ folder
 * Note: $IP is your MediaWiki install dir.
 * 1) Copy files from the unziped SemanticQueryFormTool_version folder into the newly created folder
 * 2) Enable the extension by adding this line to your LocalSettings.php include_once('extensions/SemanticQueryFormTool/includes/SQFT_Settings.php');
 * Note: Make sure this appears LocalSettings below the include_once call that enables Semantic MediaWiki itself!
 * 1) For versions >= 0.2 of SQFT in conjuction with versions < 1.5.0 of SMW the following additional indexes SHOULD be created in your database (speed up in large wikis):
 * 2) create index p_s_val on $wgDBprefix_smw_atts2(p_id, s_id, value_xsd);
 * 3) create index p_o_id on $wgDBprefix_smw_rels2(p_id, o_id);
 * Note: $wgDBprefix_ is the name of the database prefix of your MediaWiki tables.

Optional steps

 * Optionally add lines to set values for variables in LocalSettings.php (see SQFT_Settings.php file)
 * $sqftgAdjustSMWQMaxVals
 * $sqftgDefaultParameter
 * $sqftgUseCache (requires creation of sqf_cache_time and sqft_cache_time database tables - see below !)
 * $sqftgUseCacheDefaults (requires creation of sqft_cache_time and sqft_cache_time database tables - see below !)
 * $sqftgAllowedNamespaces
 * $sqftgDefaultNamespaces
 * If in version >= 0.2 the custom indexes have been created (see point 5. above) the following line should be added to LocalSettings.php:
 * $sqftgCustomIndexes = true; (set it to 'false' if you are sure NOT to create the indexes)


 * Optionally create the following extra tables in your mediawiki db
 * Note $wgDBprefix stands for the database table prefix defined in your LocalSettings.php</tt>
 * Cache tables which may speed up execution
 * $wgDBprefix_sqft_cache_time "create table $wgDBprefix_sqft_cache_time (timestamp mediumtext, id varchar(480) primary key);"
 * $wgDBprefix_sqft_cache_value "create table $wgDBprefix_cache_values (id varchar(480), value mediumtext, index(id));"
 * If result-lists are saved in the in the type=article mode the following extra table needs to exist
 * $wgDBprefix_sqft_save_results "create table $wgDBprefix_sqft_save_results (user_id int(11), result_name varchar(255) not null, result_namespace int(11) not null,result_title varchar(255) not null, index(user_id), index(result_namespace));"
 * If several namespaces are used in the wiki and the default search namespace should be changed interactively the following extra table needs to exist
 * $wgDBprefix_sqft_namespaces "create table $wgDBprefix_sqft_namespaces (user_id int(11), namespaces mediumtext, index(user_id));"

Syntax

 * or


 * Property is the name of any SMW property used in the wiki.
 * Parameters are a number of optional parameters which direct the behaviour of the function and determine the result format (they usually have the format name=value)

Property type usage mode
The main purpose of the parser function is to generate a unique list of values existing for a specific property or a value-part of a multi-valued (nary) property in various formats. In its default form the function returns a complete 'select' element of an HTML form which can be incorporated directly in a form (in our case forms are build using the SimpleForms extension). This is the default type=property usage mode.

Article type usage mode
A second more specific functionality of the parser function is to store, combine and manage search results in form of article title lists (type=article usage mode). This was implemented to be able to use basic generic query forms but still allow to answer more complex questions by combining the results of the basic queries. This mode requires an extra table to be created in the database.

MW
Version 0.1 has fixed some problems with MW 1.13 and is now the recommended version. The Ajax function of the SimpleForms extension works also with MW 1.13 after applying the patch posted by Danbrice on the SF Talk page.

As our wiki uses the Ajax feature of the SimpleForms extension (which doesn't work on MW versions later than 1.11) with query forms, version 0.1RC has mainly been tested with MW 1.11. However, prelimary testing on a MW 1.13 installation show no incompatibilities so far and the expeted outputs (MW 1.12 has not yet been tested).

Version 0.2.0 has been tested against the last SVN update (12.2.2009): MW 1.13.4 (r47174)

SMW

 * SQFT version 0.3.0 is the first version compatible with SMW 1.5.0 (but still also works with SMW 1.4.2 and later)
 * SQFT version 0.2.0 is the first version compatible with SMW 1.4.2 and later (tested against the update: SMW 1.4.3 (Version 1.5g-SVN)
 * SQFT version 0.1.9a is the last version compatible with SMW 1.4 - 1.4.1
 * SQFT version 0.1.7 is the first version compatible with SMW 1.4 - 1.4.1
 * SQFT version 0.1.6 is the last version compatible with SMW 1.3

Versions 0.1+ works also with the new SMW storage engine. Version 0.1RC of the extension works with SMW 1.3 and 1.2 but only with the old data storage engine.