View source for Template:Key Start/doc

{{Documentation/subpage}}
'''Current version: 3.0''' This set of templates enables wiki authors to create single-access identification keys (also known as dichotomous or polytomous keys) like they are used in biology, in a manner that is well readable, printable, but also re-usable by other software.

NEWS:
* new combination result (page name if formatting stripped), or result+resulttext (pagename+display-text) combinations in Lead. 
** should this ber result text? result qualifier?
* if resulttext is supplied, result may be unformatted and contain a "#(id-code)" at the end (for internal links!)
* using resultlink+result, still works, but is deprecated - delete this later!
* new parent key (page name if formatting stripped), or parent key + parent key text (pagename+display-text) combinations in Key Start. 
* where parent key is missing, an internal category is created: [[Category:Management - Keys without Parent Key|en]] / [[Category:Intern - Übergeordneter Schlüssel fehlt|de]] 
* "common names" and "commonnames" are both supported (in Lead and Key start)
* New always-visible images j/k below statement are tested and documented
* A new separate template [[Template:Lead_Link]] enables authors to add hyperlinked cross-references to couplets inside the statement text (in addition to the normal next-couplet links of the key itself).

=== Highlights===

* The identification key is displayed using standard mediawiki "template syntax", not a purpose-built software extension. This means it is stable over a long time, and will not stop working when the mediawiki software is upgraded to new version. It is therefore suitable as an archive format over a long period.
* It uses a layout well known from printed works and is printable itself. The implementation of leader-dots leading up to the right-hand lead pointers makes it usable on different screen resolutions as well as on paper.
* The key is a data structure that can be read by software. This enables the use of specialized players that allow more interactive usage, such as displaying only one couplet at a time. Furthermore, editors that simplify creating a key are planned.
* In addition to the standard structure of lead-number, lead-statement, lead-pointer-or-result, the author can supply supporting text and image information.
* Text information can be structured into synonyms, (additional) description, occurrence and remarks. It is possible to supply further fields here. The purpose of the description field is to provide space for supplementary descriptive information, that did not occur in the statements, but is relevant in the case of incomplete specimens or as check characters.
* A wrappable image gallery:
** This supports up to 6 images, each with a label (letter or number) and caption (free form text) below it. The images will automatically wrap into the available space, using one, or multiple rows depending on the width of the screen. As a drawback for long caption text requiring more than 2 line, this requires specifying the number of "captionlines"; otherwise scrollbars will appear.
** The size of the images can be specified for all images together (secondary images width), or for each image individually. Normally, images will be automatically resized to this size. This creates undesirably fuzzy images if the image is originally smaller than the target size; in this case one has to add the size of the image to each image that is smaller.
** The images below the key offer an "imagesfooter" parameter, which puts a a note below all images together. This is useful of joint captions or attribution sources for all images together.
* Minor features: 
** The right-hand-side lead numbers are hyperlinked: in a long key you can click on them and jump directly to the right couplet.
** If a key author uses backlinks (example: "12 (4)" to express "couplet/question number 12, coming from couplet/question number 4"), the backlink will also be hyperlinked. However, currently this precludes the use of a single bracket after the lead ("10 a" is ok , "10 a)" currently creates an error, which will hopefully some day be fixed...)
** A key may contain subheadings to simplify orientation (use "<nowiki>{{Lead | subheading = The heading title | 1 a | statement text... }}</nowiki>")

==Using the single access key templates==

The basic structure is a '''Key Start''' template, containing metadata such as title, description, and author for the entire key, a sequence of '''Lead''' (or '''Lead Question''' plus Lead) templates containing the key itself, and a final '''Key End''' template. The sequence of lead statements can be further structured by adding a '''subheading''' parameter to the first lead in the first couplet of larger key sections to help humans to jump to specific portions of a key.

Each '''Lead''' template contains three unnamed parameters: (1) The lead number, optionally with a backlink; (2) the lead statement, and (3) the result as lead number or a taxon name. In the case of taxon names, it is possible to replace the unnamed 3rd parameter with an explicit parameter called "taxon=". In addition, the named parameters "images" and "description" allow additional information to be given. In edit view, keys looks like:

 <nowiki>{{Key Start| id = Example | title = Example key | description = Only a demo }}</nowiki>
 <nowiki>{{Lead | 1 | Blätter gegenständig    |  2 }}</nowiki>
 <nowiki>{{Lead | 1 | Blätter wechselständig  | 18   </nowiki>
 <nowiki>  | image a =Image:xyz.jpg </nowiki>
 <nowiki>  | caption a=A caption for the first image }}</nowiki>
 <nowiki> ... any number of leads ...</nowiki>
 <nowiki>{{Key End}}</nowiki>

: (Switch this documentation page into edit view to see the text behind the rendered examples on this page.)

* Users can duplicate any existing key and modify, translate, or shorten it, with requiring an expert or administrator to allow it to them.
* It is possible to rearrange the key or add new couplets or leads with new taxa.
** In both cases, renumbering the leads is a problem, but while building a key up, non-consecutive lead numbers can be an interim solution.
* Both lead statements and taxon links can contain links to internal Wiki pages or external web pages, defining or explaining characters, states, or taxa.
* '''Taxon or character images with captions and automatic resizing may be added to any lead (whether a taxon lead or not).'''


=== Key metadata (creators, audience, status, etc.) ===

The following parameters are available directly in the '''Key Start''' template. They serve as metadata for the entire key (small text at the end indicates the mapping to [[http://www.keytonature.eu/wiki/Resource_Metadata_Exchange_Agreement Key to Nature metadata fields]] or MRTG fields):
* '''id:''' 1-10 characters, no blank. Highly recommended; necessary if multiple keys exist on a single page. <small>(K2N/MRTG: Resource ID)</small>
* '''title:''' The title of the key, presented as a heading above the key <small>(K2N/MRTG: Title)</small>
* '''language:''' The language of the key. By default, a key is assumed to be in the default language of the wiki it is on. Note: Language is presently not shown in the header area, but may be important when indexing and searching keys form multiple sources. <small>(K2N/MRTG: Language)</small>
* '''geoscope:''' geographic scope <small>(K2N/MRTG: Locality (not fully matching, any better?)</small>
* '''audience:''' the intended audience: 12 yr old school children, 6th grade, university students, general public, experts, etc. <small>(K2N/MRTG: Audience)</small>
* '''description:''' optional, full text description, elaborating information not yet captured in title, geoscope, audience etc. <small>(K2N/MRTG: Description)</small>
* '''source:''' published source citation, if key itself was previously published. If key was newly developed, based on multiple publications, these should normally not be cited here. <small>(K2N/MRTG: Published Source)</small>
* '''collaboration limited to:''' a list of names, to which the collaboration shall be limited. Else "collaboration: open" is shown.  <small>(K2N/MRTG:  NOT APPLICABLE?)</small>
* '''status:''' Progress and status, e.g. "incomplete", "finished" <small>(K2N/MRTG: NOT APPLICABLE?)</small>
* '''creators:''' The main creator(s) of a key, i.e. the ones to be cited as primary authors in the title line. <small>(K2N/MRTG: Creators)</small>
* '''initiated by:''' Initiator(s) of a key project, who does not wish to be cited as primary author <small>(K2N/MRTG: Contributors (pro parte))</small>
* '''edited by:''' A list of editors desiring editor-authorship <small>(K2N/MRTG: Contributors (pro parte))</small>
* '''general review by:''' Persons that have acted as reviewers and quality control editors <small>(K2N/MRTG: Reviewer Names (pro parte))</small>
* '''nomreview by:''' Nomenclatural review <small>(K2N/MRTG: Reviewer Names (pro parte)</small>
* '''expert review by:''' Review by a taxonomic expert of the group. <small>(K2N/MRTG: Reviewer Names (pro parte))</small>

----
: TECHNICAL: To map the content to Key to Nature metadata, the following fields should be filled automatically:
:* Type = Identification Tool
:* Host Application = Web Browser
:* Interactivity = Dynamic
:* ID Tool Structure = polytomous
:* Copyright Statement = Copyright reserved by the contributing authors
:* License Statement = licensed under Creative Commons cc-by-sa 3.0
:* License URL = http://creativecommons.org/licenses/by-sa/3.0/
:* Best Quality Availability = online (free)
:* Best Quality URI = (the URL of the current wiki page, if id-field is present, add "#" and the id.
:In addition, if language was not given expressedly, it should default to the wikis language. Problem: it is unclear how to get this for an ingestion tool without making a specific mediawiki API call...
----
UNCERTAIN WHETHER TO USE (NOT YET IMPLEMENTED):
* taxgroup_bmpz = b for botany, m for mycology, p = prokaryotes, z for zoology -- this could be useful for automatic categorization!

Note: The '''Key End''' template has no parameters. It must, however, always be present at the end of a key (it closes the table opened by Key Start).

=== Lead parameters ===

The following parameters are available in the Lead templates and are listed here for reference. To learn creating keys it will generally, however, be easier to pick a suitably similar example key, switch the wiki into edit mode, and look how it is been done there.
* subheading: A heading that can be interspersed into a key; it will be displayed in in front of the couplet (it should always be used in the first lead of a couplet) for which it is designed.
* subheadingstyle: either a set of css definitions, or one of the following symbolic styles: orange, green, bigorange, biggreen, simple.
* 3 unnamed parameters (those not starting with a "fieldname=" construction). These are, in order:
** The couplet and lead number
** The full statement of the lead (or answer to previous Lead question)
** The next couplet number (without a lead-differentiator, i.e. "34", not "34 a")
** Any further unnamed parameter will be reported as an error. Note also, that if the statement contains an equal sign ("="), it cannot be used with an unnamed parameter. In this case, use "2=your statement text | 3=34"
* commonnames: The common name of an organism, in cases where you want to link using the scientific name.
* result: Formatted text, which will - after unformatting - also be used as the link target for the result. Example: "<nowiki>''Aus bus'' var. ''xus''</nowiki>" will display as "''Aus bus'' var. ''xus''" and link to "Aus bus var. xus" (i.e. without the apostrophes).
* resultlink: (Avoid to use! )specific link (a wiki page name, like "Lamium album") different from the result parameter (which then defines the display text). Use this option only exceptionally and try to keep "result" the linked page name (placing additional information in resultqualifiers).
* resultqualifier: an additional text appearing after results, but not becoming part of the link. Where the result is given as a common name, this may contain the scientific name, or it may contain the scientific author names. In other cases it may contain stage "(2nd instar)", sex "(♀♀)", or variety "(white form)" information. In many cases, adding brackets "()" will be desirable.

Up to 2 (j and k) larger images (default height/width = 400 x 400, preserving aspect ratio) that are always visible betwen the lead statement:
* image j, label j, caption j, image j width, image j height
* image k, label k, caption k, image k width, image k height


Up to 5 (a to e) small images may be displayed in a sidebar:
* For the first ("a") the following parameters are available:
** image a: the image name on the wiki, for example: File:YourImageName.jpg
** label a: a letter or number, placed in the lower right corner over the image, allowing the image to be referred to from the main lead text.
** caption a: Longer text describing or explaining the image. For the sidebar images, this text will only be present in a tooltip on mouse-over-wait actions.
** image a width: desired final width in pixel. The default is 80 pixels
** image a height: desired final height in pixel. The default is 80 pixels
* image b, image c, image d, image e follow the same pattern (label b etc.) 
* For all images together:
** primary images width: Default is 80 pixels
** primary images height: Default is 80 pixels, preserving aspect ratio

The following information may be displayed below the lead; it will typically be initially invisible and be shown only after clicking on a "more..." function link.
* synonyms: scientific or common names.
* description: free from additional description
* occurrence: geographic or habitat/ecological distribution. The information will be presently simply appended to the description, but this may be changed later on.
* remarks: free from additional remarks. The information will be presently simply appended to the description, but this may be changed later on.
* up to 6 (letters "m" to "r") small images. The same parameters as for the sidebar images are available. The caption will be displayed full readable.
* captionlines: due to the way image m to image r can wrap to the available space, the space for all captions together must be fixed. If undesired scrollbars appear within the caption area of some images, set captionlines to a value larger than 2
* imagesfooter: a free from text displayed below all images together.
* extra images width: like primary images width, but for "image m" to "image r", default is 200 px
* extra images height: see above, default is 200 px, preserving aspect ratio

=== Usage Examples ===

The templates [[Template:Key Start]], [[Template:Lead]], and  [[Template:Key End]] are to be used in combination. Please switch into edit or view mode using the tab on top of the screen to see the "code" calling the templates.

{{Key Start | id = MainKey | title = Example key in German | description = This key is a demo key only, containing links to the German Wikipedia | creators = Author of Key | language = de }}
{{Lead | 1 | Blätter [http://de.wikipedia.org/wiki/Phyllotaxis#Grundtypen gegenständig]  |  2
 | image m   = File:Ulistnienie.png
 | caption m = Gegenständige (a) und wechselständige (b-d) Anordnung 
 | image m width = 300  | image m height = 120
}}
{{Lead | 1 | Blätter [http://de.wikipedia.org/wiki/Phyllotaxis#Grundtypen wechselständig]  |  18}}
{{Lead | 2 | Blätter handförmig gelappt  |  3 }}
{{Lead | 2 | Blätter nicht gelappt  |  6 }}
{{Lead | 3 | Blätter mit 3 Lappen. Blüten weiß. Frucht fleischig 
 | result      = ''Viburnum opulus'' L. 
 | commonnames = Gemeiner Schneeball 
 | image a   = File:Viburnum_opulus_B.jpg
 | caption a = Flowers - just a demo here that images and caption are possible inside the key
 | image b   = File:Viburnum 01.JPG
 | caption b = Fruits - both images come from wikimedia commons
 | description=Der Strauch kann Wuchshöhen von 1,5 bis 4 m erreichen. Die gegenständigen, gestielten Laubblätter sind drei- bis fünflappig. Die weißen Blüten stehen in Trugdolden. Die erbsengroße rote Beere enthält einen Samen.

 | remarks = Bestäuber sind inbesondere Fliegen, die ähnlich wie bei den Doldenblütlern auf dem Blütenstand umherlaufen und die Bestäubung vollziehen.}}
{{Lead | 3 | Blätter mit 5 Lappen. Blüten nicht weiß. Frucht trocken, geflügelt  |  4 }}
{{Lead | 4 (3) | Blätter weniger als 10 cm lang
 | result      = ''Acer campestre'' L. 
 | commonnames = Feldahorn 
}}
{{Lead | 4 (3) | Blätter mehr 10 cm lang  |  5 }}
{{Key End}}


{{Key Start | id = Key2 | title = Start of an English Key with backlinks, links to English Wikipedia, and a footnote | description= the footnote uses the normal wiki method of using  <nowiki><ref>footnote text</ref></nowiki> inside the lead and a <nowiki><small><references/></small></nowiki> command below the key.| language = en }}
{{Lead | 1    | Trees, shrubs, or woody climbers > 50 cm high| 2 }}
{{Lead | 1    | Herbs or small shrubs (< 50 cm high) | 17 }}
{{Lead | 2 (1)| Leaves [http://en.wikipedia.org/wiki/Phyllotaxis opposite] | 3 }}
{{Lead | 2    | Leaves [http://en.wikipedia.org/wiki/Phyllotaxis alternate] | 4 }}
{{Lead | 3 (2)| Leaves bad-smelling when crushed. Fruit fleshy, red 
 |result = ''Sambucus racemosa'' L. }}
{{Lead | 3    | Leaves odourless. Fruit dry, winged 
 |result = ''Acer negundo'' L.}}
{{Lead | 4 (2)| Leaves lobed | 5 }}
{{Lead | 4    | Leaves not lobed | 6 
 |images=[[Image:EFG-logo2.jpg|thumb|50px|(demo)]] }}
{{Lead | 5 (4)| Leaves pinnately-veined. Fruit an acorn. Tree 
 |result = ''Quercus robur'' L. }}
{{Lead | 5    | Leaves palmately-veined. Fruit fleshy. Small shrub <ref>Blackcurrant juice is used for jams, sirup (French ''Cassis'')</ref> 
              | result=''Ribes nigrum'' L.
              | commonnames = Blackcurrant }}
{{Lead | 6 (4)| Leaves compound. Fruit a red mulberry 
 |result =''Rubus idaeus'' L. subsp. ''idaeus'' }}
{{Lead | 6    | Leaves entire. Fruit not mulberry-like | 7 }}
{{Key End}}
----
<small><references/></small>


Single access keys created with these templates may be strictly '''dichotomous''' (two alternatives, as above) or they may be '''polytomous''' (some couplets having more than 2 alternatives, not shown). Furthermore, it is possible to design keys in statement-style (as above) or in question-answer-style as follows:

{{Key Start | id = KeyQA | title = Example of the start of a key in question-answer-style}}
{{Lead Question | 1    | What is the life form of your plant? }}
{{Lead | a  | a tree, shrub, or a woody climber > 50 cm high| 2 }}
{{Lead | b  | a herbs or small shrubs (< 50 cm high)        | 17 }}
{{Lead Question | 2    | Are two leaves on the stem always opposite of each other?
 | image a   = File:Ulistnienie.png
 | caption a = opposite (a) and alternate (b-d) leave arrangement<br/>DEMO IMAGE at question
 | image a width = 300  | image a height = 120
}}
{{Lead | a  | yes  | 3 
 | image a   = File:Ulistnienie.png
 | caption a = DEMO for image at answer instead of question
 | image a width = 300  | image a height = 120
}}
{{Lead | b  | no, they are alternate | 4 
 | image a   = File:Ulistnienie.png
 | caption a = DEMO for image at answer instead of question
 | image a width = 300  | image a height = 120
}}
{{Key End}}

For testing, also a technical sample of a reticulated key, resulting in a Directed Acyclical Graph (this key is complete, i.e. unlike the other examples it has no dangling leads):

{{Key Start | id = KeyDAG | title = Techical example of reticulated key (lead 4 has two parents: 3 and 6)}}
{{Lead | 1| statement a| 2 }}
{{Lead | 1| statement b| 3 }}
{{Lead | 2| statement a| result=''Sambucus racemosa''}}
{{Lead | 2| statement b| 5 }}
{{Lead | 3| statement a| 6}}
{{Lead | 3| statement b| 4}}
{{Lead | 4| statement a| result=''Acer negundo''}}
{{Lead | 4| statement b| result=''Fraxinus excelsior''}}
{{Lead | 5| statement a| result=''Rubus fruticosus'' }}
{{Lead | 5| statement b| result=''Ribes nigrum''}}
{{Lead | 6| statement a| 4}}
{{Lead | 6| statement b| result=''Rubus ideus''}}
{{Key End}}

{{Key Start | id = ErrorDemo | title = Error Demo '''(the red errors are intentional here!)'''| description = The templates will report some errors already, e.g. putting text or images into an unnamed 4th or 5th parameter, including putting images or taxon description there without using the named parameter (images= or description=) for this }}
{{Lead | 1 | opposite   | 2 | This text is in the 4th parameter}}
{{Lead | 1 | alternate  | 4}}
{{Lead | 2 | pinnate    | 3 }}
{{Lead | 2 | not pinnate| 6 | image 2a=[[Image:EFG-logo2.jpg|thumb|200px]] }}
{{Key End}}


==Information for developers==

===Layout===

The key is a table with a column for lead numbers, a column for alternative codes and backlinks, a third column which in turn contains another two-column table for statement and result (next lead or final taxon) and a fourth column containing optional right-side images. The use of the embedded statement-plus-result table enables to use the available space in the best manner, allowing each row to determine the optimal distribution between statement text and result text. A long lead statement in one row (with a short number pointer) can overlap with a long taxon name in another row. Each lead is a separate row. Secondary images and text may be present in an additional row below the statement and result, which will initially be hidden through javascript (displaying a "more..." link).

* Compare a FRIDA [http://dbiodbs.units.it/carso/chiavi_pub30?usr=admin&step=2&altro=128&n=1013 html key] for comparison. One major difference is that FRIDA always places the taxon in a row of its own.

Javascript programmability: Each row contains an id attribute with "L" + lead number + "row", the lead cell itself an id attribute with "L" + lead number. The table is styled mostly using css classes, with the text span background an exception (to allow parameterization of the background).


===Known problems===

# Manual lead renumbering is laborious; this occurs in cases where a new lead must be inserted, or the sequence of leads is considered unsatisfactorily.
#* Suggestion: do not renumber leads while working on the key. Insert new leads with "High" numbers, such as 100, 101 or even 1000, 1001. Only when the key is completed, carefully renumber all leads.
#* A service-oriented solution for this: The project would have to program a "bot" program, the works through all keys that have a category like "Please renumber" set, renumbering the key in an optimal way, and then deleting (or commenting out) the category.


=== Technical Dependencies ===

* Styles in [[MediaWiki:Common.css]]. One these styles refers to a background image for the leader dots, which must be available directly on the server
* The internal link target highlighting and the hiding of secondary text and images ("more...") depends on code in [[MediaWiki:Common.js]]
* The primary templates usable by the identification key author are: [[Template:Key Start]], [[Template:Key End]], [[Template:Lead]], and optionally [[Template:Lead Question]].
* Many more generic or specific helper-templates are needed, see [[:Category: Single-access key templates]] for a list.

* The MediaWiki software must have the following extensions activated: Parser functions (standard on Wikipedia), string functions (not active on Wikipedia, but considered), and variables (not even considered). The use of variables is limited to some functionality which allows deleting it from the Template code if the function is not available. It primarily allows having multiple keys on a single wiki page, with correct linking.

<noinclude>[[Category:Single-access key templates]]</noinclude>