FANDOM


Documentation icon Template documentation[edit] [purge]
This documentation is transcluded from Template:Form calculator/doc.
Template:Form calculator invokes Module:Form calculator using Lua.

This template is for creating form calculators in a standardised way. This implements the syntax of RuneScape:Calculators/Form calculators as a template.

About

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 = name of the page the calculator is on: use {{subst:FULLPAGENAME}}
|cat = set to no to remove category
|template = the form's template to call
|form = unique id for the form
|result = unique id for the result
|outputtype = type of output
|forminit = intial text in the form area
|resultinit = initial text in the result area
|param1 = name of the first parameter
|label1 = label for parameter 1
|default1 = default value for parameter 1
|type1 = type of parameter 1
|range1 = range of parameter 1
...
|paramX = name of the Xth parameter
|labelX = label for parameter X
|defaultX = default value for parameter X
|typeX = type of parameter X
|rangeX = range of parameter X
}}

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. See RuneScape:Calculators/Form calculators#Namespaces for a list of IDs. Should be omitted if no parameters use the article type.

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.
Community content is available under CC-BY-SA unless otherwise noted.