Form calculator/doc

This article is a direct transcription, copied *verbatim*, of documents released on *GameHive.com*. This content is copyrighted by GameHive.
***Form calculator** invokes Module:Form calculator using Lua.*
This template is for creating form calculators in a standardised way.

## About

***Form calculator** invokes Module:Main article using Lua.*
This template can be used to link to another relevant article or set of articles when there is no way to fluently link the article in prose.

Good example

```
==Equipment==
{{Main|/Weapons}}
The Swashbuckler is a Mythic All Damage weapon.

```

Bad example
Below, it makes more sense to simply link rarity in the paragraph:

```
==Rarity==
{{Main|Rarity}}
Rarity is an equipment power.

```

A brief rundown of how form calculators work:

1. The configuration is defined on the page by an editor; either using this template or using plain code
	* This code includes two unique identifiers, one for the form and one for the result
	* It also includes the name of a template
2. This template adds a usage of each of the IDs, to define where the form and result go (alternatively the editor can do this manually)
3. When the page loads, the javascript detects the config (specifically the `jcConfig` class) and reads it in
4. The javascript generates the form from the config and places it in the location defined by the form ID, replacing what is there already
5. The user inputs their data and presses submit
6. The javascript builds and sends a query to the MediaWiki API, which processes the template and returns the HTML
	* Think of this like editing a page with just the template on it, changing the values and pressing preview
7. The response to the query comes back and is placed into the result ID, replacing what is there already
8. Repeat from 5

## Usage

```
{{Form calculator
...
}}
```

### page

**Optional.** The name of the page the template is on. Don't use the `{{FULLPAGENAME}}` magic word, subsitute it in: `{{subst:FULLPAGENAME}}`. This makes the category only appear on the relevant page. If omitted, will appear on all pages transcluding the calculator.

### cat

**Optional.** Set to `no` to prevent the category being applied.

### template

**Required.** The template associated with the form. This is equivalent to what you would place inside `{{}}`.

If the template is in the *Template:* namespace, the Template: prefix can be omitted. Other namespaces are required - mainspace is used by a preceding colon only (i.e. `|template = :Test/template`).

### form

**Required.** A unique identifier for the form. Make sure this is sufficiently descriptive so it cannot clash with general IDs on the page.

For example, `|form = jsCalc-effigies-form`.

### result

**Required.** A unique identifier for the result. Like `form`, make sure it is sufficiently unique.

For example, `|result = jsCalc-effigies-result`.

### suggestns

**Optional.** A comma-separated list of namespace IDs to use in autocomplete fields.

### outputtype

**Optional.** This defines the type of automatically created form/result location is used. The relevant values are:

* `none` - **Default.** No form/result location is created, so user can define their own.
* `basic` - A simple output which has the form directly above the result (separated by two line breaks) with no additional formatting. Most form calculators where the result is a table will use this. Equivalent to:

```
<div id="formid">[standard form message]</div>

<div id="resultid">[standarad result message]</div>
```

* `verticaltable` - A wikitable with the form placed directly above the result, with some generic headers. This is best for small forms and results. Example: []
* `horizontaltable` - An unstyled table with the result to the right of the form. This is a good way of having the form and result horizontally adjacent to each other.

### forminit

**Optional.** Override the message that appears before the calculator loads. By default this is (borders for clarity):

The calculator form will appear here soon. You will need Javascript enabled and cannot be using the mobile version of the Wiki.
If you are on a mobile device, you can load the full version of the site by clicking here.
### resultinit

**Optional.** Override the message that appears before the calculator is submitted. By default this is (borders for clarity):

The result will appear here when you submit the form.
### Parameter definition

Any number of parameters can be defined. Each parameter defines a row in the form, and has 5 components:

* param
* label
* type
* range
* default

These are followed by a number - param1, label1, etc. Things with the same number refer to the same row of the form.

No parameters are required - though a no-parameter form calculator is weird. However, if a parameter is defined, only `param#` is required (though some combinations of `type#`, `range#`, and `default#` are invalid).

Parameters are processed in numerical order starting at 1, and ending when one cannot be found. If you only define a `param1` and a `param5`, it won't process `param5` - you'll need to define 1, 2, 3, 4, and 5.

#### param

The parameter of the template. This is the name of the parameter which will be passed to the template when submitted.

#### label

The [user-friendly] label to display in the form. The default value is the corresponding `param#`. The label can contain most normal wikitext: links, images, spans with styles and titles (hover-overs), etc.

#### type

The type of input for this param. This can be used to restrict user input, or change the input field to a different type. It can be one of:

* `string` - **Default.** Text input field, no restriction.
* `article` - Text input field, no restrictions. Enables autocomplete for this field, based on the `suggestns` parameter.
* `number` - Numbers. Text input field, set to number. Will prevent non-numbers being submitted.
* `int` - Integers. Text input field, set to number. Will prevent non-integers being submitted.
* `select` - Drop-down menu generated from the corresponding `range#`.
* `check` - Checkbox for submitting a boolean choice.
* `hs` - Text input field, no restriction. Generates a lookup button to get data from hiscores, and updates the other fields as defined by `range#`.
* `fixed` - The default value provided is shown but cannot be changed. Can be used as a separator or for in-form notes.
* `hidden` - The default value provided is hidden from the form entirely. Used to pass things to the template that shouldn't be seen or changed by the user.
* `semihidden` - The default value provided is hidden in the form, but still present in the HTML. This is for inter-script usage.

If anything other than those values are entered (or the parameter is omitted), `string` is used.

#### range

The range for the parameter, or any other configuration.

* `string`, `article`, `fixed`, `hidden`, `semihidden` - Unused.
* `number`, `int` - Format *min-max*. If either max or min is omitted, infinity/negative infinity is assumed. For example, `|range1=1-99`.
* `select` - A comma-separated list of the options for the drop-down.
* `check` - By default, the form will pass *true* if ticked, or *false* if unticked, to the template. This can be overriden by setting the range in the format *true value,false value*. (If you set your template to check for Yes/No instead of true/false, use this.)
* `hs` - A list of lists defining which other fields to change and what to change them to:
	+ The small lists are defined in format *param,skill,value*:
		- param: the parameter to change
		- skill:the skill ID to find - skill IDs range from 0 to 50, per here
		- value: value to change it to - values are 0 for rank, 1 for level and 2 for experience
	+ Each small list is separated from the next by a semicolon
	+ For example, `|range2=craft,13,1;agil,17,2` will change the `craft` field to the looked-up Crafting level, and the `agil` field to the looked-up Agility experience.

#### default

The default value for the parameter in the form. This is pre-filled into the form when loaded.

* `string`, `article` - Defaults to empty.
* `number`, `int` - Defaults to empty. Should respect the range given.
* `select` - One of the options given in the range.
* `check` - Unticked by default. Will be ticked by default if defined as `true` or the same as `value if true` in the range/
* `hs` - Unused, does nothing.
* `fixed`, `hidden`, `semihidden` - Can't be changed away from.