Extension:Semantic Forms/Defining new inputs

From MediaWiki.org

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 "Integer", 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 an array of two elements: the first is the HTML text that will be displayed on the page for this input, and the second is whatever Javascript text should be added at the top of the page to enable both this input's running and its validation (this value can be null).

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 Integers), change that second line to:

$sfgFormPrinter->setSemanticTypeHook($smwgContLang->smwDatatypeLabels['smw_integer'], 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 code for the Semantic Google Maps extension; you can see this code in action here.