User:Yury Katkov/FormInput creation

From semantic-mediawiki.org
Jump to: navigation, search

In this page I will descibe how to create your own form input element for Semantic Forms.

Introduction

The big picture

All the Semantic Form Inputs are derived from SFFormInput class. All you need to do is to override some methods of this class and register the new form input. The input consists of the piece of Html code and some javascript.

Some details

There are several important functions that need to be overloaded.

Constructor

Let's begin with a constuctor. Typically there is no need to create the constructor that is different from the one in SFInput. don't forget to call the parent constructor passing all the parameters to it:

  public function __construct($input_number, $cur_value, $input_name, $disabled, $other_args)
  {
          parent::__construct($input_number, $cur_value, $input_name, $disabled, $other_args);
  }

Making js-less Html code

First important function is getHtmlText(). You should override it so it would return the html code of your input. Such code should not include style or script tags, see below how to use CSS and Javascript in your input. The code generated by getHtmlText() function ideally should execute normally even in browsers where javascript is turned off.

The good way of creating the html tag is by using static methods of Xml class.

Typically we'll need the following functions:

  • Html::openElement, Xml::openElement for creating opening tags and adding parameters
  • Html::closeElement, Xml::closeElement for creating closing tags
  • Xml::element, Html::element, Html::rawElement for creating simple tags

There are a lot more useful functions in Xml and Html classes for creating checkboxes, radiobuttons, selects and other html elements.

It's crucially important to add the "id", "name" and "value" parameters to html tags you're creating. Typically you should do this:

  • set the name attribute to $this->mInputName
  • set the id of the element to 'input_' . $this->mInputNumber
  • set the value attribute to $this->mCurrentValue. However it's not so for checkboxes, radiobuttons and selects.

Registering the input

For making out input work we need to properly register it. In MediaWiki it's done by calling the $sfgFormPrinter->registerInputType('INPUT CLASS NAME') inside the ParserFirstCallInit hook.


Adding css and javascript

So, our plain html version of an input is ready! But it's usually not enough because you probably want to style up you html element and add some animation or even program more complex behavior with JavaScript.

In MediaWiki we use ResourceLoader mechanism for that.

An example

More examples

There are many examples of Form Inputs in SemanticForms/includes/forminputs directory, and there are some inputs in SemanticFormsInputs extension.