Extension:SemanticFormsSelect

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
Semantic Forms Select

Release status: stable

Implementation User interface, Ajax
Description Generate a select form element inside Semantic Forms. The values for the select element are generated before form loading or retrieved through ajax call after form loading. The values are ultimately from a Semantic Query or a parser function.
Author(s) Jason Zhang (Jasonzhangtalk)
Latest version 1.1 (2013-02-23)
MediaWiki 1.15+
License GPL
Download binary

Translate the SemanticFormsSelect extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

What can this extension do?[edit | edit source]

This extension generates a select form element which option values are from semantic query or parser function. Semantic Forms provides useful input type for select elements such as dropdown, combobox, and listbox. Their option values can be derived from a static list, pages in a category, concept, property's allowed values, etc. However, it is still limited. This extension provides these features

  • The option values for select element is from an SMW query or parser function.
  • If the SMW query or parser function is not parametrized, its optioned values are loaded at form generation time.
  • If the SMW query or parser function is parametrized, in another word, its values depend on another form field. Its values are loaded through ajax call when trigger field changes.

Usage[edit | edit source]

Two form fields are involved. The first one is the form field we are trying to define. It is termed as Select field. The second one is the field the Select field depends on. It is termed as Value field. A change of Value field will trigger the loading of Select field.

The input type from this extension is SF_Select. Field parameters are shown in the table below.

Name Required Description Note
query=x Yes Semantic Query Either query or function must be present. More information.
function=x Yes Parser Function Either query or function must be present. More information.
template=x No The template the Value field in Use either template or sametemplate
sametemplate No The Value field is in the same template as the Select field use either template or sametenmplate
field=x No the Value field name Value field has to be pure text field or html select field. Fields with Autocomplete feature are not supported
rmdiv No remove current instance when Select field's value is not valid anymore More information.
list No As it is defined in Semantic Forms
size=x No As it is defined in Semantic Forms

Query And Function format[edit | edit source]

 {{{field|AllProtocols|input type=SF_Select|query=((Category:Protocol));format~list;sep~,;link~none;headers~hide;limit~500}}}

In the above example, the query is [[Category:Protocol]]|format=list|sep=,|link=none|headers=hide|limit=5000. To avoid parsing and text transform, we have to convert [ to (, = to ~ and | to ; in the query.

 {{{field|AllProtocols1|input type=SF_Select|function=ask:((Category:Protocol));format~list;sep~,;link~none;headers~hide;limit~500}}}

Parser function follows the same rule. The parser function is ask in example above. We can of course use other valid parser function. To fit a parser function into field definition, Strip the {{# and }} at the beginning and the end of normal parser function format.

The result from query or parser function should be a list of string separated by comma.

Examples[edit | edit source]

  • Example 1: Static query. The values are retrieved when form is loaded.
 {{{field|AllProtocols|input type=SF_Select|query=((Category:Protocol));format~list;sep~,;link~none;headers~hide;limit~500}}} 
  • Example 2: Static function. The values are retrieved when form is loaded.
 {{{field|Users|input type=SF_Select|function=getallusers}}}

Here the getallusers is a custom parser function which gives all users in current installation.

  • Example 3: Parametrized query/function.
 {{{field|P2Protocols3|input type=SF_Select|query=((Category:Protocol))((Protocol Belongs to Project::@@@@));format~list;sep~,;link~none;headers~hide;limit~
200|sametemplate|field=Project1}}}

The parameter is the special character string @@@@. In this example, the Select field is P2Protocols3. The Value field is Project1. Both Select field and Value field are in the same template since we have sametemplate in field definition. If Value field is from another template, the template parameter should be used. When Project1 field changes, the @@@@ will be replaced by the value of Project1's value. The query is then sent to server through ajax call. The results will be the option values for P2Protocols3 field. if the current template is multiple, the P2Protocols3 only depends on the Project1 in the same instance.

Parser functions can be parametrized in the same way.

 {{{field|UserInGroup|input type=SF_Select|function=getallusersInGroup:@@@@|sametemplate|field=Group}}}

In this example, we list all users in the selected group of Group field.

  • Example 4: rmdiv.
 
{{{for template|StudyProtocolMultiple3|label=Demostrate External Dependency multiple, rmove|multiple}}}
{|
!Depends on Protocols 5 on Study template
|{{{field|Endpoint|input type=SF_Select|list|size=2|query=((Is a Protocol Endpoint::@@@@));mainlabel~-;?Endpoint Name;format~list;sep~,;headers~hide;limit~5
0|list|size=5|template=Study|field=P2Protocols4|rmdiv}}}
|}
{{{end template}}}
 

In this example, the Endpoint field depends on P2Protocols4 field in study template. The current template is also a multiple template. Endpoint's value is reloaded after P2Protocols4 changes. After reloading, Endpoint may not have any selected values and it is left in an invalid state. In this case, we may want to automatically remove the current instance. This is what rmdir parameter is for.

Download instructions[edit | edit source]

binary release

Installation[edit | edit source]

Requirement[edit | edit source]

  • Semantic Forms

To install this extension, add the following to LocalSettings.php:

#add configuration parameters here
#setup user rights here
require_once("$IP/extensions/SemanticFormsSelect/SemanticFormsSelect.php");

Demonstration[edit | edit source]

Live Demo: Online SemanticFormsSelect Demo

Install Demo in your site:

  1. Download the file sfs_demo.xml from download link.
  2. Import the pages in this file using Special:Import.
  3. Then follow instruction in SFDemo Page.

That demo contains 5 Projects. Each Project has a set of Protocols. Each Protocol has two Endpoints as internal object.

Form Feature to Demonstrate
Form:DemoStatic Demonstate static loading using query function and parser function.
Form:DemoAjax1 Demonstrate field dependency within a template and dynamically loading using query or parser function.
Form:DemoAjax2 Demonstrate field dependency cross templates. The 2nd template is a multiple template
Form:DemoAjax3 Demonstrate cascading dependency feature
Form:DemoAjax4 Demonstrate the rmdiv parameter

See also[edit | edit source]

Acknowledge And Support[edit | edit source]

This project was sponsored by BioTeam

This project is sponsored by flexdms. Check out professional data management software from flexdms.

For support, please send email to user mail list in SemanticMediawiki.