Extension:Semantic Forms/Developers' documentation

This page holds information about the Semantic Forms code, for developers who want to better understand it, modify it, or create code that ties into it.

Code structure

For the complete listing of files in Semantic Forms and a short description of each one, see the Code structure page.

To view the code online, including version history for each file, you can go here.

Modifying or improving Semantic Forms

There's certainly no shortage of ways to improve Semantic Forms, including bugs that can be fixed, interface elements that can be improved, or new features that can be added. If you are a developer, or simply a user with some technical skill, any help you can provide in improving the software is welcome: Semantic Forms would not be at its current state without the contributions of many people.

If you encounter some issue or limitation in Semantic Forms, and have an interest in fixing it, you should consider first writing the semediawiki-devel mailing list about it - others may have relevant opinions about your proposed change.

You can also see the current list of Known bugs and planned features.

Defining new inputs

There are two kinds of hooks one can use to define new inputs: input-type hooks and semantic-type hooks. The first let you register a function that creates an input based on an input-type name in the form definition, and the second let you register a function for a specific semantic type (like "Number", etc.); which is especially useful if you want to override Semantic Forms' own handling. To create a new input type, you just need to create a function with the following structure:

function my_input_html($cur_value, $input_name, $is_mandatory, $is_disabled, $field_args) {
   ...
}

This function needs to return the HTML text that will be displayed on the page for this input. In addition, the function also has to be registered, with code that looks like this:

global $sfgFormPrinter;
$sfgFormPrinter->setInputTypeHook('myinput', 'my_input_html', array());

Where 'myinput' is the name of the input that users are meant to insert in the form. To register it as a semantic-type input instead (in this case, for Numbers), replace that second line with:

global $smwgContLang;
$datatype_labels =  $smwgContLang->getDatatypeLabels();
$sfgFormPrinter->setSemanticTypeHook($datatype_labels['_num'], false, 'my_input_html', array());

The second argument to setSemanticTypeHook() specifies whether this is a hook for a single integer, or for a delimited list of integers (false means it's a single value).

In the declaration of my_input_html(), the first parameter is the current value of this field (which is sometimes null); the second parameter is the HTML name that this input should have, so that the system knows where among the POST variables to find the value for this input; the third parameter indicates whether this field is mandatory for the user; the fourth indicates whether it's disabled (meaning, the user can't edit); and, finally, the fifth parameter, $field_args, is a hash representing all the other properties defined for this input in the form definition: you can specify special properties that can be set in the form for this input. So, for instance, if the form contains a line reading:

{{{field|some-field|input type=myinput|color=orange|height=200}}}

....then, when my_input_html() is called, $field_args will contain the "color=orange" and "height=200" key-value pairs, which the function can do whatever it wants to with.

For an example of the use of Semantic Forms hooks, see the the definition of formInputHTML() in the code here for the Semantic Maps extension; you can see the code in action here.