Extension:Page Forms/Developers' documentation

From MediaWiki.org
Jump to: navigation, search
Page Forms - navigation (viewTemplate:Page Forms navigation)
Basics Main pageExtension:Page Forms (talk) · Download and installationExtension:Page Forms/Download and installation · Quick start guideExtension:Page Forms/Quick start guide · HostingExtension:Page Forms/Hosting · Special pagesExtension:Page Forms/Special pages
Using Page Forms PF and templatesExtension:Page Forms/Page Forms and templates · Defining formsExtension:Page Forms/Defining forms   (Input typesExtension:Page Forms/Input types) · The "Edit with form" tabExtension:Page Forms/The "edit with form" tab · Linking to formsExtension:Page Forms/Linking to forms · Creating query formsExtension:Page Forms/Creating query forms
Resources for help Common problemsExtension:Page Forms/Common problems · Known bugs and planned featuresExtension:Page Forms/Known bugs and planned features · Getting supportExtension:Page Forms/Getting support · Developers' documentationExtension:Page Forms/Developers' documentation · TestingExtension:Page Forms/Testing
About Page Forms Authors and creditsExtension:Page Forms/Authors and credits · Version historyExtension:Page Forms/Version history · Sites that use Page FormsExtension:Page Forms/Sites that use Page Forms · Related extensionsExtension:Page Forms/Related extensions

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

Code structure[edit]

For the complete listing of files in Page 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 Page Forms[edit]

There's certainly no shortage of ways to improve Page 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: Page Forms would not be at its current state without the contributions of many people.

If you encounter some issue or limitation in Page 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[edit]

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 data type (like "Number", etc.); which is especially useful if you want to override Page 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 $wgPageFormsFormPrinter;
$wgPageFormsFormPrinter->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();
$wgPageFormsFormPrinter->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.

Testing[edit]

You can find information on testing the code at the page Extension:Page Forms/Testing.