 |
This project page is currently under construction. The information contained within should not be considered fully accurate and/or complete.
|
- To suggest a calculator, see RuneScape:Calculators/Ideas.
Calculators are tools for determine quantities of ingame items, actions, or money. They can be found here.
Guidelines[]
This set of guidelines aims to organise all calculators, mostly located in the calculator namespace.
Basics[]
There are many types of calculators:
- Static calculators are calculators that don't take user input to give their result. There are many variants of this, but many have a common theme of cost-analysis. Many calculate the profit/cost of making one of a given item, and the profit per experience point of making that item. They're commonly one or more tables.
- Dynamic calculators are calculators that take user input to calculate their result. They almost always use Javascript to do this (be that via one of the wiki's two available general-purpose calculator scripts, or with a custom-made script).
- One common subset of these are skill calculators (sometimes called skillcalcs) which work out how many of each item a user needs to train from X experience to Y experience.
- The first general script available is the form calculator script, which creates a form which a user can input into and submit for the result. It essentially is an easy way to use templates - and as such, requires a template backend.
- The second general script available is the dynamic calculator script. It is more complex than the form script but does not necessarily require a template backend, though it can use them.
Calculators of all types may utilise (and if they use the form script, require) helper templates. These calculator templates have one primary purpose: to be used for the calculator. This is distinct from standard templates used by calculators like {{Coins}}, which is a general-purpose template. Some calculators use lua modules instead (calculator modules); there isn't a requirement to use these, but lua modules are generally more efficient than wikiscript so help offset loading issues that come with particularly large calculators with many template transclusions.
Organisation[]
- Namespace
All calculators should be located in the calculator namespace. This includes very small calculators designed for one page - they can be transcluded directly onto the page if required.
- Name
Calculators should have a logical name directly related to their subject. If it is a calculator directly related to a skill, it should be a subpage of the skill name (within the namespace), for example Calculator:Construction/Flatpacks1.
- Templates
Templates associated with calculators should be a subpage of the calculator, named /template. For example, the template for Calculator:Construction should be at Calculator:Construction/template
Lua modules should be invoked via a template (as is the case with normal modules), named something logical with respect to the template. They should not be subpages.
- Headers
All calculators should have a messagebox header. This is either {{StaticCalculator}} for static calculators or {{JSCalculator}} for dynamic calculators. All calculators that use a template backend should also use the {{Calc use}} template, either positioned at the bottom of the page underneath the calculator itself, or near the form - it should be positioned in a way that doesn't confuse it with the calculator itself.
Calculator templates should have {{Calculator template}} placed on their documentation, and {{invokes}} if that template is a wrapper for a calculator module.
Code[]
Calculators should aim to use code efficiently and try not to be wasteful, or use overcomplicated code when simpler alternatives exist.
An example of poor code:
{{Coins|Amount={{#expr:{{GEPrice|Bones|n}}*5}}}}- The first unnamed parameter is preferred to Amount
{{GEP|item}}returns the price without the commas, so that is preferred to{{GEPrice|item|n}}{{GEP}}can also accept a number to do the multiplication more efficiently via lua:{{GEP|Bones|5}}{{Coins}}already has an #expr: built into it, so the the #expr: is doubly unnecessary.- Thus the better code is
{{Coins|{{GEP|Bones|5}}}}
[[File:Bones.png|link=Bones|Bones]] [[Bones]]
You should try to prefer doing calculations via lua. This doesn't mean the calculator needs to be in lua - it just means using templates that already make good use of lua effectively (though you can make the entire thing in lua if you like). For example, if calculating the sum of a number of items from the Grand Exchange, one should use {{GETotal}} or {{GETotalqty}}, as these modules remove the 'middlemen' in the code (one template expansion for all the items rather than one template expansion each). One should also be aware of templates that might already exist to significantly reduce the complexity of something: for example, if working with the cost of overloads, one can use the {{ovlcost}} template rather than reinventing the wheel.
Categories[]
All calculators should be in Category:Calculators. They should be sorted by their pagename within this category, i.e. [[Category:Calculators|{{PAGENAME}}]]. Calculators should also be in categories related to their subject, sorted to *.
All calculator templates should be in Category:Calculator templates with PAGENAME sorting, like above.
Documentation[]
Both calculators and their templates should be documented. Having sufficient documentation makes maintenance of the calculator significantly easier, both for the original creator and any future editors.
- Calculators
All calculators should have some basic documentation, describing what the calculator does, any assumptions it makes and what any non-obvious fields or columns mean.
This is the user-facing page, and as such it should make sure the user understands what the calculator is doing and how to use it properly.
- Calculator templates
All calculator templates should have documentation. This is more the editor-facing area, so the template can be more technical than the calculator documentation - but remember that your fellow editors still need to be able to understand it and might not be as technically minded as you.
Documentation should at the very least be a list of the parameters and what those parameters do.
Ideally the documentation should be transcluded from a subpage of the template (templatename/doc), utilising the {{documentation}} template. It should sufficiently detailed in order to cover accepted values for each parameter, error conditions, a general overview and possibly an example. Like normal templates, the documentation subpage should contain the calculator template's categories (sorted to PAGENAME).
Documentation should also include {{Calculator template}} to link it to the calculator. If the template is a module invocation wrapper, it should also use {{invokes}}.
Linking[]
Calculators should all be linked with a short description on Calculators.
Calculators should be linked from their relevant page(s) - depending on the page(s) and the calculator, this can use {{HasCalculator}}. If the subject has a number of calculators associated with it (e.g. skill articles), a calculator section on the page with a description of each calculator may be a better choice.
Resources[]
- Form calculator script documentation
- Dynamic calculator script documentation