Extension:SemanticQueryFormTool

= Feature description for SQFT version 0.2.3 =

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 now also a Browse function for an enhanced and configurable display of properties and their values (for details see the description on help.malariapedia.info).

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 the following additional indexes SHOULD be created (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);

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
 * 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

 * Version 0.2.0 is the first version compatible with SMW 1.4.2 and later (tested against the last SVN update (12.2.2009): SMW 1.4.2 (Version 1.5e-SVN)
 * Version 0.1.9a is the last version compatible with SMW 1.4 - 1.4.1
 * Version 0.1.7 is the first version compatible with SMW 1.4 - 1.4.1
 * 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.