Template:Form calculator

From the RuneScape Wiki, the wiki for all things RuneScape
Jump to: navigation, search
Template documentation
This documentation is transcluded from Template:Form calculator/doc. [edit] [purge]
Template:Form calculator invokes function main in 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.

x-css

Optional. The tablecss, tableformcss, tableresultcss parameters can be used to apply inline CSS to the entire table, the cell containing the form, and the cell containing the result, when using the verticaltable or horizontaltable output types.

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.

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
  • default
  • type
  • range
  • toggles
  • help

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.

For more information on setting up parameters see RuneScape:Calculators/Form_calculators

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.
  • group - Used to group other inputs together.
  • 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#.
  • buttonselect - A series of buttons for selecting an option (only 1 selected at a time).
  • combobox - Text input with a drop-down menu that automatically filters; dropdown list generated from the corresponding range#.
  • check - Checkbox for submitting a boolean choice.
  • toggleswitch - Same function as checkbox but is a toggle instead.
  • togglebutton - Same function as checkbox but is a button (toggles on/off).
  • hs - Text input field, no restriction. Generates a lookup button to get data from hiscores, and updates the other fields as defined by range#.
  • rsn - A special field for player names (when used by the calculator and not to populate another field).
  • 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.


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, buttonselect, combobox - 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, rsn - If left blank, tries to use the RuneScape name entered elsewhere on the wiki.
  • fixed, hidden, semihidden - Can't be changed away from.

range

The range for the parameter, or any other configuration.

  • string, article, fixed, hidden, semihidden - Unused.
  • group - A comma separated list of the inputs to include in the group
  • number, int - Format min-max,step. If either max or min is omitted, infinity/negative infinity is assumed. For example, |range1=1-99.
  • select, buttonselect, combobox - A comma-separated list of the options for the drop-down.
  • check, toggleswitch, togglebutton - 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.

toggles

The inputs or groups of inputs toggled by this widget. Applies to select, buttonselect, combobox, check, toggleswitch, togglebutton, int and number param types. Toggles are given in the format value=toggles. Note that when an option is chosen, all the groups/fields listed for other options (that aren't listed on the selected option) will be hidden.

  • Default toggles: For checkboxes, toggleswitches and togglebutton the keys are "true" and "false" (values specified in Param range cannot be used), if no key is given key is assumed to be "true". For number and int inputs available keys are any numbers or "not0" which is also used for any nonzero input (if no key is specified key is assumed to be "non0").
  • Value is the name of the option (listed in param range for the input). Multiple options can be assigned them same toggles by separating them with a comma ,.
  • Toggles are the groups or fields toggled by that option, multiple groups should be separated by a comma ,. The group or field names should be those specified in their respecitve param name.
  • Multiple toggle sets are separated by semicolons ;.
  • Examples:
    • If a select has Option 1,Option 2 for the range and Option 1=Group1,Group2;Option 2=Group2,Group3 for the toggles then when "Option 1" is selected all inputs that belong to "Group1" and "Group2" will be shown while those belonging to "Group3" will be hidden. when "Option 2" is selected all inputs that belong to "Group2" and "Group3" will be shown while those belonging to "Group1" will be hidden.
    • If a button select has Button 1,Button 2,Button 3 for the range and Button 1,Button 2=Input1 for the toggles then when "Button 1" or "Button 2" is selected the other input "Input1" will be displayed while if "Button 3" is selected it will not be.


help

Help text for the form field. If text is Defaults to displaying an (i) icon that can be clicked to display the help.

  • Default display for help (if given) displays an (i) icon that when clicked shows the help text in a tooltip. To display the help inline (below the input) start the help with inline= followed by the help text. Inline is not currently available.
  • Help supports using HTML to format the help (both tooltip and inline) - including simple formats like <em>, <span> and even <img />. As this is formated as wikitext use [[Link location]] for links.