Vorlage:Key Start

Aus Offene Naturführer
Wechseln zu: Navigation, Suche

VERSION 3.17
English (standardized) properies:

VERSION 3.16

  • Fixing the min-width/max-width problem

VERSION 3.15

  • Micro-change, one label in German only

VERSION 3.14

Only English (standardized) properies:

OLDER VERSIONS

VERSION 3.13

VERSION 3.12

  • dt-caption now as div instead of table, jkey controls as floating diff inserted by js. With table problems occurred with Safari and Chrome when the controls were hidden/shown and the table was 100% width; it would then exceed the out jkeyCanvas in which it was embedded. Plus minor changes.

VERSION 3.11

  • adjusted collapsible mechanism to use the MediaWiki's collapsible class ↔ id pairs with corresponding .mw-customtoggle-myKey ↔ #mw-customcollapsible-myKey (the default MediaWiki toggle mechanism can not be triggered by a toggler outside the toggle-content-box)

VERSION 3.10

  1. added "recommendation group" to recommend keys for beginners
  2. added "publicity" to have some “advertisement” for the author’s web page or an associations
  3. audience to SMW-property
  4. language to SMW-property
  5. geoscope to SMW-property

VERSION 3.9

  • Added "taxon name", to increase similarity with template:Switch

VERSION 3.8

  • Status optional, creator moved into metadata header. Previous version: New Multilingual, SplitLink for Creators added.

VERSION 3.7

[Bearbeiten] [Aktualisieren] Template-info.svg Dokumentation der Vorlage
Diese Dokumentation ist von Vorlage:Key Start/doc transkludiert. (Bearbeiten | Versionen)

Current version: 3.14 This set of templates enables 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: The Key Start infobox on top is collapsible, with new Key Start parameter: "collapsed=1" it can be set to be initially collapsed. This should make the Key Start No Heading template redundant!
  • Keys work better in combinations with floating images due to adding "clear:both" at the top.
  • category field in Key Start supported
  • new combination in Lead to differentiate between the result target and the result display text: the old resultlink is no longer supported, and the new option is to use "result=" plus "result text=". (pagename+display-text).
  • result text preferred, resulttext is deprecated.
  • result qualifier preferred, resultqualifier is deprecated.
    • Question: probably need to support "result qualifier" with blank?
  • If result text is supplied, result may be unformatted and contain a "#(id-code)" at the end (for internal links!)
  • new: parent taxon sets the default parent key page, which can be modified by parent key or the displayed text with parent key text
    • 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" (or, deprecated, "commonnames")are both supported (in Lead and Key start)
  • The 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 "{{Lead | subheading = The heading title | 1 a | statement text... }}")

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 "scientific name=". In addition, the named parameters "images" and "description" allow additional information to be given. In edit view, keys looks like: 

{{Key Start | title = Example key | description = Only a demo }}
{{Lead | 1 | Blätter gegenständig    |  2 }}
{{Lead | 1 | Blätter wechselständig  | 18   
  | image a =Image:xyz.jpg 
  | caption a=A caption for the first image }}
 ... any number of leads ...
{{Key End}}
(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 [Key to Nature metadata fields] or MRTG fields). All list values should be given as comma separated list.

Parameters:

  • id = optional key id necessary for a multiple-keys-page (1-10 characters, no blank) to ensure step-by-step determination accross linked keys NOTE: all other keys pointing to this one need to point to the defined id here, e.g. "wiki_key_page#myspecialkey". Best practise is to set the id not for the first key of a multiple-keys-page but on subsequent keys on that Wiki page. The id is saved as variable {{#var: decisiontreeID}} for {{Lead}}. (K2N/MRTG: Resource ID)
  • title = The title of the key, presented as a heading above the key (K2N/MRTG: Title)
  • 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. (K2N/MRTG: Language, recommended: property:dc:language)
  • geoscope = geographic scope (K2N/MRTG: Locality (not fully matching, any better?, recommended: property:dcterms:spatial)
  • audience = the intended audience: 12 yr old school children, 6th grade, university students, general public, experts, etc. (K2N/MRTG: Audience, recommended: property:dcterms:audience)
  • description = optional, full text description, elaborating information not yet captured in title, geoscope, audience etc. (K2N/MRTG: Description, recommended: property:dc:description)
  • publicity = optional: advertise for an association, e.g. the German Deutscher Jugendbund für Naturbeobachtung or the author’s web page
  • rating = optional: 1 … 5 (0 = fehlend, 1 = am schlechtesten, 5 = am besten) (recommended: property:xmp:Rating)
  • recommendation group = optional: a single use case the key is recommended for, e.g. elementary school activities, birds; saved internally in property:recommendation group
  • taxon name = optional, unformatted
  • common names = optional (K2N/MRTG: ?common names)
  • 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. (K2N/MRTG: Published Source)
  • collaboration limited to = a list of names, to which the collaboration shall be limited. Else "collaboration: open" is shown. (K2N/MRTG: NOT APPLICABLE?)
  • status = Progress and status, e.g. "incomplete", "finished" (K2N/MRTG: NOT APPLICABLE?)
  • creators = The main creator(s) of a key, i.e. the ones to be cited as primary authors in the title line. (K2N/MRTG: Creators, recommended: property:dc:creator)
  • initiated by = Initiator(s) of a key project, who does not wish to be cited as primary author (K2N/MRTG: Contributors (pro parte))
  • edited by = DEPRECATED: USE CONTRIBUTORS INSTEAD A list of editors desiring editor-authorship (K2N/MRTG: Contributors (pro parte))
  • contributors = A list of later co-authors or editors who contributed significantly to the improvement of the key. This includes contributors adding images. (K2N/MRTG: Contributors (pro parte), recommended: property:dc:contributor)
  • general review by = Persons that have acted as reviewers and quality control editors (K2N/MRTG: Reviewer Names (pro parte))
  • nomreview by = Nomenclatural review (K2N/MRTG: Reviewer Names (pro parte)
  • expert review by = Review by a taxonomic expert of the group. (K2N/MRTG: Reviewer Names (pro parte))
  • parent taxon = the next higher taxonomic level. By default it creates the parent key-page link. If this is different parent key should at least be specified.
    • parent key = page name (displayed as link) of the key for the next higher taxonomic level, from which the present key is reached as result
    • parent key text = display text for the link to the parent key, works only if parent key is supplied
  • category = a list of categories, like Flora, Fauna
  • icon = an icon floating right either just the file name “File:xy.jpg” (default height 22px) or in MediaWiki syntax [[File:xy.jpg|great icon]]. This icon will be used for exporting the mobile key, so it should represent the key somehow.
  • flags = special flags added to the key (multiple flags are separated by Blank, not comma). Primarily evaluated by javascript, but other uses are possible. Flags evaluated by MediaWiki:JKey.js: jkey-nocontrols (OK), jkey-autostart (OK, but FAIL nested keys), jkey-hidekeymetadata (OK, initially key start metadata box is hidden), jkey-simplified (NEEDS TESTING).

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...

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"
  • common names =: The common name(s) of an organism, in cases where you want to link using the scientific name.
  • scientific name =: scientific name and common names will replace result in the future, so prefer both instead of using result; result text can be used to format it differently
  • result = Formatted text, which will - after unformatting - also be used as the link target for the result. Example: "''Aus bus'' var. ''xus''" will display as "Aus bus var. xus" and link to "Aus bus var. xus" (i.e. without the apostrophes).
  • result text = text to be displayed. If result = is missing, no link will be generated. If both are present, result = defines the link target, result text the display text. Thus, only using result = is a shortcut, defining both as the same.

Use this option only exceptionally: it is good if the page name and the link shown are identical. 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 100 pixels
    • image a height = desired final height in pixel. The default is 100 pixels

Example: | image a = xyz.jpg | label a = xyz | caption a = abc | image a width = 100

  • image b, image c, image d, image e follow the same pattern (label b etc.)
  • For all images together:
    • primary images width = Default is 100 pixels
    • primary images height = Default is 100 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 text for additional remarks, including historic or current uses by humans, clues to help to memorize characteristics of the organism, etc. 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


Nested/embedded subkeys

TODO, add more documentation!

  • In the a parentlead, add a "nested =" parameter, containing the number or letter of the first lead in the subkey. For example, if the main leads are numbered 1, 1*, 2, 2*, the subkey leads may be numbered a, a*, b, b* (it is possible to use numbers for both though!)
  • For each of the leads that shall be indented as a nested/embedded subkey, set "parentlead =" to the number of the normal lead which contains the nested-parameter. Example: if the subkey follows from a lead numbered "3*", all leads in the subkey must carry a "parentlead =3*".

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.

Example key in German
Von: Author of Key
This key is a demo key only, containing links to the German Wikipedia
(Geltungsbereich nicht angegeben) — Zusammenarbeit: offen
1
Blätter gegenständig   ► 2
Gegenständige (a) und wechselständige (b-d) Anordnung
Gegenständige (a) und wechselständige (b-d) Anordnung
1
Blätter wechselständig   ► 18
2
Blätter handförmig gelappt   ► 3
2
Blätter nicht gelappt   ► 6
3
Blätter mit 3 Lappen. Blüten weiß. Frucht fleischig 
 Gemeiner Schneeball  –  Viburnum opulus L.
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.
Bestäuber sind inbesondere Fliegen, die ähnlich wie bei den Doldenblütlern auf dem Blütenstand umherlaufen und die Bestäubung vollziehen.
Flowers - just a demo here that images and caption are possible inside the key
Fruits - both images come from wikimedia commons
3
Blätter mit 5 Lappen. Blüten nicht weiß. Frucht trocken, geflügelt   ► 4
4 (3)
Blätter weniger als 10 cm lang 
 Feldahorn  –  Acer campestre L.
4 (3)
Blätter mehr 10 cm lang   ► 5


Der eingegebene Wert wurde nicht verstanden.
Start of an English Key with backlinks, links to English Wikipedia, and a footnote
the footnote uses the normal wiki method of using <ref>footnote text</ref> inside the lead and a <small><references/></small> command below the key.
(Geltungsbereich nicht angegeben) — Zusammenarbeit: offen
1
Trees, shrubs, or woody climbers > 50 cm high   ► 2
1
Herbs or small shrubs (< 50 cm high)   ► 17
2 (1)
Leaves opposite   ► 3
2
Leaves alternate   ► 4
3 (2)
Leaves bad-smelling when crushed. Fruit fleshy, red 
  Sambucus racemosa L.
3
Leaves odourless. Fruit dry, winged 
  Acer negundo L.
4 (2)
Leaves lobed   ► 5
4
Leaves not lobed   ► 6
Error: You may have an erroneous 4th unnamed parameter (vertical bar without a field name), or you may use "commonname/common name/remark/results/synonym/image/images" instead of "common names/remarks/result/synonyms/image a" etc. The content is:
Datei:EFG-logo2.jpg
(demo)
. To add descriptions use |description=Your text|; to add one or several synonyms use |synonmys=Synonym 1; Synonym 2|; to add images use |image 1a=Image:YourImage.jpg |caption 1a=Your Caption (images a to e are in the sidebar, j following below lead text, with j/k always visible and, images m to r in the "more"-information area below the lead).
5 (4)
Leaves pinnately-veined. Fruit an acorn. Tree 
  Quercus robur L.
5
Leaves palmately-veined. Fruit fleshy. Small shrub [1] 
 Blackcurrant  –  Ribes nigrum L.
6 (4)
Leaves compound. Fruit a red mulberry 
  Rubus idaeus L. subsp. idaeus
6
Leaves entire. Fruit not mulberry-like   ► 7
  1. ↑ Blackcurrant juice is used for jams, sirup (French Cassis)


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:

Example of the start of a key in question-answer-style
1
What is the life form of your plant?  
a
a tree, shrub, or a woody climber > 50 cm high   ► 2
b
a herbs or small shrubs (< 50 cm high)   ► 17
2
Are two leaves on the stem always opposite of each other?  
a
yes   ► 3
DEMO for image at answer instead of question
b
no, they are alternate   ► 4
DEMO for image at answer instead of question

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):

Techical example of reticulated key (lead 4 has two parents: 3 and 6)
1
statement a   ► 2
1
statement b   ► 3
2
statement a 
  Sambucus racemosa
2
statement b   ► 5
3
statement a   ► 6
3
statement b   ► 4
4
statement a 
  Acer negundo
4
statement b 
  Fraxinus excelsior
5
statement a 
  Rubus fruticosus
5
statement b 
  Ribes nigrum
6
statement a   ► 4
6
statement b 
  Rubus ideus
Error Demo (the red errors are intentional here!)
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
(Geltungsbereich nicht angegeben) — Zusammenarbeit: offen
1
opposite   ► 2
Error: You may have an erroneous 4th unnamed parameter (vertical bar without a field name), or you may use "commonname/common name/remark/results/synonym/image/images" instead of "common names/remarks/result/synonyms/image a" etc. The content is: This text is in the 4th parameter . To add descriptions use |description=Your text|; to add one or several synonyms use |synonmys=Synonym 1; Synonym 2|; to add images use |image 1a=Image:YourImage.jpg |caption 1a=Your Caption (images a to e are in the sidebar, j following below lead text, with j/k always visible and, images m to r in the "more"-information area below the lead).
1
alternate   ► 4
2
pinnate   ► 3
2
not pinnate   ► 6


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 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

  1. 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

The MediaWiki software must have the following extensions activated:

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.

See also Category: Single-access key templates for a list.
Properties Templates JavaScript CSS

The template is partly multi-lingual and reacts to language choice of user (see Template:Multilingual).

For a discussion on German translations see the talk page.

Quelle: Offene Naturführer, Das Wiki zu Bestimmungsfragen: Vorlage:Key Start. Abgerufen am 12. Dezember 2024, 18:46 von https://offene-naturfuehrer.de/web/Vorlage:Key_Start