View source for Vorlage:Lead/doc

'''See [[Template:Key Start/doc| Key Start]] for the main documentation.'''

== Changes in recent versions ==
(The main documentation for all parts of the single-access key is under [[Template:Key Start/doc]]!)

<div class="mw-collapsible" style="width:800px">
'''Version 3.11.'''
<div class="mw-collapsible-content">
added parameters:
* <code>life form=</code>list of life forms
* <code>occurrence ecology typo=</code>, <code>occurrence ecology values=</code>, <code>plant sociology</code>
* <code>presence territory=</code>
* <code>result id list=list of ids</code> presently &lt;span> tags that are styled by CSS
* <code>references=</code>
* <code>toxicity=</code> (temporarily at display:none 2017-08-07)
* <code>xenophyte=</code>
* <s>floristic regions=</s> use <code>floristic zones=</code>
added comment parameters:
* <code>altitudinal zone comment=</code>, <code>flowering period comment</code>, <code>plant height comment=</code>
</div>
</div>

<div class="mw-collapsible mw-collapsed" style="width:800px">
'''Version 3.10.'''
<div class="mw-collapsible-content">
added parameters for plant details:
* <code>plant height formula min-from-to-max-unit=''formula''</code> or generally as complete string: <code>plant height=</code><br/>(case: size for plants only)
* <code>flowering period formula min-from-to-max=''formula''</code> or generally as complete string: <code>flowering period=</code> 
* <code>altitudinal zone formula min-from-to-max=''formula''</code> or generally as complete string: <code>altitudinal zones=</code> 
* <code>occurrence status=</code> 
* <code>floristic regions=</code> 
* <code>floristic zones=</code> 
* <code>organism size formula min-from-to-max-unit=''formula''</code> or generally as complete string: <code>organism size=</code><br/>(case: general size, if it's not clear what was meant whether height or length or width)
</div>
</div>

<div class="mw-collapsible mw-collapsed" style="width:800px">
'''Version 3.9.'''
<div class="mw-collapsible-content">
* comments changed, partly refactored
* removed the br in front of the resultqualifier if sidebar image a etc. present
* result layout variants better integrated to save memory
* general minor optimizations
* next-lead-pointer (number on right side) now always in same row as statement, even if results are also present
</div>
</div>

<div class="mw-collapsible mw-collapsed" style="width:800px">
'''Version 3.8.'''
<div class="mw-collapsible-content">
* moved from own jKey-collapsible mechanism to MediaWiki’s mw-customcollapsible
* introduced scientificname and new rules of the result-layout
* saving properties for commonnames, scientificname, synonyms
</div>
</div>

<div class="mw-collapsible mw-collapsed" style="width:800px">
'''Version 3.7.'''
<div class="mw-collapsible-content">
Length estimate based on resulttext instead of resultlink (for empty result!!!)

Previous changes:
* nested works now on parents with backlinks and alternatives (1 and 1*, 1 and 1'). 1 and 1- NEEDS TESTING!
* result text+ empty result supported (non-linking result).
* nowrap on result/qualifier reworked!
* result=http:... now works.
* Nested subkey ok. Resultqualifier no longer in ()
</div>
</div>

<div class="mw-collapsible">'''Version 3.3:'''
<div class="mw-collapsible-content">
* added <code>scientific name</code> and new layout for result
</div>
</div>

<div class="mw-collapsible mw-collapsed">'''Version 3.2:'''
<div class="mw-collapsible-content">
* Added error category: Category:Internal - Error in Lead template
* removed: resultlink
* resulttext deprecated, "result text" is preferred! 
* resultqualifier deprecated, "result qualifier" is preferred! 
* common names allowed (and should perhaps be preferred over commonnames! -- TODO: also allow common names in Key Start

'''Older version changes:'''

Nested subkey. STATUS: Tested, result text and image j/k working. 

New parameters: nested (the first lead number of a nested key that identifies the current lead as its parentlead. parentlead = identifying a lead as nested within the parentlead (the leads are indented, and the parentlead identifier become part of the nested lead id/next-lead values).

a) Simplified, no more image-no-resize-parameter (manually set size for very small images), no more link to next/result behind image, no more little metadata icons (which were necessary because of redirecting the main links. Javascript runs almost everywhere, former solution was very complicated and removed by javascript code! -- b) new image k, intended to be always displayed (no autohide) BELOW the statement text (for larger, wide in-key images). -- c) obsolete -- d) new parameter "result qualifier=" for male/female/white form, etc.; may also be used for scientific names, if result is desired to link to the common name. -- c) Image numbering adjusted to simplify creating a decision-based template (one template covering all leads, like the decision horizontal template. Called by outer template, Collapsible/collapsed added, lead images in right sidebar (up to five primary, "image a" to "image e", images side-by-side), non-hideable below statement (2 images, "image j"/"image k") and hidable below (secondary, "image m" to "image r" etc, max 6 images, wrapping gallery style).

PROCESS: a) Handle the subheading parameter directly (creating a visual separator (bold) above a couplet, usually summarizing identification progress and highlighting "sections" of a key). b) Error handling and combining detail text already occurs here. c) Call [[Template:Lead/Inner]], passing calculated fields like the parsed lead-ID to be used multiple times. 
</div>
</div>

== Additional- and subtemplates, dependencies ==
 Lead
  ├ [[Template:Lead/SplitNumber|Lead/SplitNumber]]
  ├ [[Template:Lead/Inner|Lead/Inner]]
  ├ [[Template:Lead/doc|Lead/doc]]
  ├ [[Template:Lead/GalleryItem|Lead/GalleryItem]]
  └ [[Template:Lead/GalleryItemNoCaption|Lead/GalleryItemNoCaption]]
  + [[Template: StripFormatting]] to get just text
  + [[Template: Pixel2Number]] eg. 300px → 300
  + {{Tlx|Lead/Formfield occurrence status}} (German terms)

=== CSS ===

See [[MediaWiki:Common.css]] section “Decisiontree and Lead templates”. Display of ids in parameter <code>result list ids</code>:
<syntaxhighlight lang="css">
/* Template:Lead show or hide result ids via CSS. <span> tags should have no space in between */
span.result-id-list span.show::before { content: attr(data-prefix) " "}
span.result-id-list span.show ~ span.show::before { content: ", " attr(data-prefix) " "}
span.result-id-list span.hide { display: none}
</syntaxhighlight>

== Technical Documentation ==

=== Parameters ===

==== Statements and next IDs ====

This can be given simply with 3 unnamed parameters (those not starting with a "fieldname=" construction, unless an equal sign (=) is contained in the value text!). Example: {{Tlx|{{#titleparts:{{PAGENAME}}|1}}| 2 | statement text | 34}}. Those unnamed parameters are, in order:
<div class="definition-inline code-bold-only">
; <code>1=</code> : couplet ID (can be unnamed/unspecified unless an equal sign is present in the text)
; <code>2=</code> : lead statement (can be unnamed/unspecified unless an equal sign is present in the text)
; <code>3=</code> : next couplet ID (can be unnamed/unspecified unless an equal sign is present in the text)
</div>

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 "{{Tlx|{{#titleparts:{{PAGENAME}}|1}}|1&#61;30 | 2&#61;statement text (&#61;the lead text) | 3&#61;34}}"

==== Media ====

{| class="vertical-align-top"
|-
! Primary 
! Large Primary
! Collapsed
|-
| style="text-align:center;"| (small at right column) 
| style="text-align:center;"| (large, below text & details) 
| style="text-align:center;"| (below text & details)
|-
|<div class="definition-inline code-bold-only">
; <code>image a=</code> to <code>image e=</code> : up to 5 images as primary media
; <code>caption a=</code> to <code>caption e=</code> : up to 5 captions of primary media
; <code>label a=</code> to <code>label e=</code>: 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.
; <code>primary images width=</code> : (default: 80)
; <code>primary images height=</code> : (default: 80), preserving aspect ratio
; <code>image a height=</code> to <code>image e height=</code>: (default: value of <code>primary images height=</code>)
; <code>image a width=</code> to <code>image e width=</code> : (default: value of <code>primary images width=</code>)
</div>
|<div class="definition-inline code-bold-only">
; <code>image j=</code> to <code>image k=</code> : up to 2 images as large primary media
; <code>caption j=</code> to <code>caption k=</code> : up to 2 captions of large primary media
; <code>label j=</code> to <code>label k=</code>: 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.
; <code>image j height=</code> to <code>image k height=</code>: (default: 400)
; <code>image j width=</code> to <code>image k width=</code> : (default: 600)
</div>
|<div class="definition-inline code-bold-only">
; <code>image m=</code> to <code>image r=</code> : up to 6 images as collapsed media. The caption will be displayed full readable.
; <code>caption m=</code> to <code>caption r=</code> : up to 6 captions of collapsed media
; <code>label m=</code> to <code>label r=</code>: 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.
; <code>image m height=</code> to <code>image r height=</code>: (default: value of <code>extra images height=</code>)
; <code>image m width=</code> to <code>image r width=</code> : (default: value of <code>extra images width=</code>)
; <code>extra images width=</code>:  (default: 200) like primary images width, but for “image m” to “image r”
; <code>extra images height=</code>: (default: 200) like primary images height, preserving aspect ratio
; <code>captionlines=</code> : (default: 3)  due to the way <code>image m</code> to <code>image r</code> 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
; <code>imagesfooter=</code>: a free from text displayed below all images together.
</div>
|}


==== Results ====

<div class="definition-inline code-bold-only">
; <code>common names=</code>:  (as comma separated list) The common name(s) of an organism, in cases where you want to link using the scientific name.
; <code>scientific name=</code>: scientific name and common names will replace result in the future, so prefer common and scientific name instead of using result; <code>result text=</code> can be used to format it differently
; <code>synonyms=</code> <code>scientific name synonyms=</code>: (as semicolon list) scientific synonym names
; <code>result=</code>: 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 formatting apostrophes).
; <code>result text=</code>: text to be displayed (overrides the other result parameters). If <code>result=</code> is missing, no link will be generated. If both are present, <code>result=</code> defines the link target, result text the display text. Thus, only using <code>result=</code> is a shortcut, defining both as the same.
; <code>result qualifier=</code>: 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.
</div>

==== Details ====

For order of appearance see [[#HTML Structure|section HTML Structure]].

<big>General text details (not handled by other detail parameters)</big>
<div class="definition-inline code-bold-only">
; <code>description=</code>: free text, additional description
; <code>occurrence=</code>: free text, geographic or habitat/ecological distribution. The information will be presently simply appended to the description, but this may be changed later on.
; <code>remarks=</code>: 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.
</div>

<big>Additionally specific parameters in order of appearance:</big>

If parameter <code>plant height=</code> and its detail-variants are not applicable, than you can use instead the rather general „organism size“:
<div class="definition-inline code-bold-only">
; <code>organism size=</code> : the whole organism sizes, e.g. "(5-)10-20 cm". Either this as a whole string or in detail as formula:
; <code>organism size formula min-from-to-max-unit=</code> : (formula) example “NA/12/30/90/cm” or “/12/30//cm”. The formula must ''always'' be complete, i.e. 5 positions separated by “/”. NA means not available.
; <code>organism size comment=</code> : free text comment
</div>
<div class="definition-inline code-bold-only">
; <code>life form=</code> : life form after FI or Nyffeler<ref>please add any literature, reference that</ref>
</div>
Plant height:
<div class="definition-inline code-bold-only">
; <code>plant height=</code> : the whole plant heights, e.g. "(5-)10-20 cm". Either this as a whole string or in detail as follows:
; <code>plant height formula min-from-to-max-unit=</code> : (formula)  example “NA/12/30/90/cm” or “/12/30//cm”. The formula must ''always'' be complete, i.e. 5 positions separated by “/”. NA means not available.
; <code>plant height comment=</code> : free text comment
</div>
<div class="definition-inline code-bold-only">
; <code>flowering period=</code> : (string), as complete string e.g. "1-2" or "II-IV" or as formula:
; <code>flowering period formula min-from-to-max=</code> : (formula), example “1/3/4/NA” or “1/3/4/”. The formula must ''always'' be complete, i.e. 4 positions separated by “/”. NA means not available.
; <code>altitudinal zones=</code> : (string), as a complete string e.g. "(montan-)subalpin-alpin" or as formula:
; <code>altitudinal zone formula min-from-to-max-unit=</code> : (formula), example “montan/subalpin/alpin/NA” or “montan/subalpin/alpin/”. The formula must ''always'' be complete, i.e. 4 positions separated by “/”. NA means not available.
; <code>altitudinal zone comment=</code> : free text comment
; <code>occurrence=</code> : free text
; <code>occurrence status=</code> : status of naturalness (natural, weed, etc.) see also http://terms.tdwg.org/wiki/dwc:occurrenceStatus or [http://offene-naturfuehrer.de/web/Benutzer:Andreas_Plank/Erweiterte_Vorlagenparameter_für_Key-Templates?oldid=53828#Attribut.2FProperty_.28Status_Indigenat.29 discussion at Offene Naturführer]
; <code>occurrence ecology typo=</code> : phytosociology
; <code>occurrence ecology values=</code> : based on FI/FH and reviewed by AGY<ref>please add any literature, reference to that</ref>
; <code>presence territory=</code> : absence of taxon on the territory (allowed values: no value=present, X = absent, ? = doubtful)
; <code>floristic zones=</code> : (string), e.g. "submeridional" or a comma separated list
; <code>toxicity=</code> : class of toxicity of a taxon according to Flora Helvetica (+, ++, +++)
; <code>result id list=</code> : list of tagged result ids (without blanks in between). To make some ids visible and others not, it is proposed to wrap the id in a &lt;span> tag and style the display via CSS classes “show” or “hide”:<br/><code style="color:gray;">&lt;span class="<span style="color:black;">show</span>" data-term="florahelvetica_id" data-prefix="<span style="color:blue;">FH</span>"><span style="color:darkgreen;">2013479</span>&lt;/span></code> is shown and data-prefix="FH" will prefix the value, so “<span style="color:blue;">FH</span> <span style="color:darkgreen;">2013479</span>” is shown. However, <code style="color:gray;">&lt;span class="<span style="color:black;">hide</span>" data-term="infoflora_id" data-prefix="infoflora">2013479&lt;/span></code> will not be shown because CSS class "hide" here is defined in [[MediaWiki:Common.css]] with "display:none". The attribute <code>data-term</code> corresponds to the data column in the original data matrix
; <code>remarks=</code> : free text
; <code>references=</code> :  free text
</div>


==== Nested sub-keys within a couplet ====

In a usual couplet a nested couplet can be used, e.g. for sub species
<div class="definition-inline code-bold-only">
; <code>nested=</code>: what is the next identifier for a sub-key? (e.g. “a”). This must be given only at the starting point where you want to start a nested-key
; <code>parentlead=</code>: the parent lead identifier, all the nested statements are pointing to. For instance if we started a nested sub-key at “5*”, this value must be given as <code>parentlead=5*</code>
</div>

Example:
: <span><code><span style="color:grey;">&#123;&#123;Lead&nbsp;|&nbsp;<span style="color:brown;"><b>5*</b></span> |&nbsp;statement text |</span>&nbsp;<i>nested&nbsp;=</i>&nbsp;<span style="color:#4e80bc;"><b>a</b></span>&#125;&#125;</code></span><br><code><span style="color:grey;">&#123;&#123;Lead&nbsp;|</span>&nbsp;<span style="color:#4e80bc;"><b>a&nbsp;</b></span> |&nbsp;<i>parentlead&nbsp;=</i>&nbsp;<span style="color:brown;"><b>5*</b></span> <span style="color:grey;">|&nbsp;…&nbsp;</span> |&nbsp;f<span style="color:grey;">&#125;&#125;</span></code><br><code><span style="color:grey;">&#123;&#123;Lead&nbsp;|</span>&nbsp;<span style="color:#4e80bc;"><b>a-</b></span> |&nbsp;<i>parentlead&nbsp;=</i>&nbsp;<span style="color:brown;"><b>5*</b></span> <span style="color:grey;">|&nbsp;…&nbsp;</span> |&nbsp;b<span style="color:grey;">&#125;&#125;</span></code><br><code><span style="color:grey;">&#123;&#123;Lead&nbsp;|</span>&nbsp;<span style="color:#4e80bc;"><b>b&nbsp;</b></span> |&nbsp;<i>parentlead&nbsp;=</i>&nbsp;<span style="color:brown;"><b>5*</b></span> <span style="color:grey;">|&nbsp;…&nbsp;</span> |&nbsp;c<span style="color:grey;">&#125;&#125;</span></code><br><code><span style="color:grey;">&#123;&#123;Lead&nbsp;|</span>&nbsp;<span style="color:#4e80bc;"><b>b-</b></span> |&nbsp;<i>parentlead&nbsp;=</i>&nbsp;<span style="color:brown;"><b>5*</b></span> <span style="color:grey;">|&nbsp;…&nbsp;</span> |&nbsp;d<span style="color:grey;">&#125;&#125;</span></code>

==== Sectioning ====

<div class="definition-inline code-bold-only">
; <code>subheading=</code>: 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.
; <code>subheadingstyle=</code>: either a set of css definitions, or one of the following symbolic styles: <span style="background-color:#FCFFEC; border:1px solid #ffc51a;white-space:nowrap;display:inline-block;">orange</span>, <span style="background-color:#e5febe; border:1px solid #c5de9e;white-space:nowrap;display:inline-block;">green</span>, <span style="background-color:#FCFFEC; border:2px solid #ffc51a;white-space:nowrap;display:inline-block; font-size:120%;">bigorange</span> oder<span style="background-color:#e5febe; border:2px solid #c5de9e;white-space:nowrap;display:inline-block; font-size:120%;">biggreen</span><span style="">simple</span> (=no background)
</div>

==== Parameter that are not evaluated ====

The following parameter shall be kept in the template but are not evaluated at all. They are needed for a re-export:
* <code>taxon treatment hidden comment=</code>
* <code>map comment=</code>

=== HTML Structure ===

Lead/Inner produces a table row with 6 &lt;td>

 Legend:
 tr#something → id="something"
 td.something → class="something"
 {something}  → <nowiki>{{{something}}}</nowiki>
 [something]  → optional
 ‹1-2›        → colspan
 
 ┌ tr#L{keyID}_{leadID}_{decisiontreeAlternative}_row ───────────────────┐
 │  [td] ┬ if {parentlead}                                               │
 │  [td] ┘                                                               │
 │  td.dt-nodeid                                                         │
 └───────────────────────────────────────────────────────────────────────┘
 
 ┌ tr.dt-subheading ─────────────────────────────────────────────────────┐
 └───────────────────────────────────────────────────────────────────────┘
 
 ┌  tr.dt-row#L{keyID}_{leadID}_row ─────────────────────────────────────┐
 │   [td] ┬ if {parentlead}                                              │
 │   [td] ┘                                                              │
 │   td.dt-nodeid#L{keyID}_{leadID}                                      │
 │   td.leadalt                                                          │
 │ ┌ td.lead-row1 ─────────────────────────────────────────────────────┐ │
 │ │  table.nested                                                     │ │
 │ │  ├ tr                                                             │ │
 │ │  │  td.leadtext span.leadspan                                     │ │   │   <span class="comment-gray">│ ► │</span>
 │ │  │  [td.leadresult span.leadon]                                   │ │   
 │ │  ├ tr                                                             │ │
 │ │  │  td.leadresult                                                 │ │   │       │
 │ │  │     span.commonnames                                           │ │
 │ │  │     span.leadresults                                           │ │
 │ │  │       span.leadout                                             │ │
 │ │  │       span.resultqualifier                                     │ │
 │ │  │     span.leadon                                                │ │
 │ │  ├ tr                                                             │ │
 │ │  │  th.leaderror                                                  │ │   │       │
 │ │  └ tr                                                             │ │
 │ │     td.leadextras                                                 │ │   │       │
 │ │       div.leadextras[.mw-collapsible]                             │ │
 │ │         span.synonmys                                             │ │
 │ │         span.description                                          │ │
 │ │         span.organism-size                                        │ │
 │ │         span.life-form                                            │ │
 │ │         span.plant-height                                         │ │
 │ │         span.flowering-period                                     │ │
 │ │         span.altitudinal-zones                                    │ │
 │ │         span.description                                          │ │
 │ │         span.occurrence-status                                    │ │
 │ │         span.occurrence                                           │ │
 │ │         span.occurrence-ecology-typo                              │ │
 │ │         span.occurrence-ecology-values                            │ │
 │ │         span.presence-territory                                   │ │
 │ │         span.floristic-zones                                      │ │
 │ │         span.xenophyte                                            │ │
 │ │         span.toxicity                                             │ │
 │ │         span.result-id-list                                       │ │
 │ │         span.remarks                                              │ │
 │ │         span.references                                           │ │
 │ │         table                                                     │ │
 │ │          tr                                                       │ │
 │ │           table (containing image m,n,o,p,q,r) → [[Template:Lead/GalleryItem|Lead/GalleryItem]] │ │
 │ │  table.nested                                                     │ │
 │ │  └ tr                                                             │ │
 │ │     td                                                            │ │
 │ │       div (float:left) image j,k                                  │ │
 │ └───────────────────────────────────────────────────────────────────┘ │
 │   td                                                                  │
 │    table                                                              │
 │    tr                                                                 │
 │      td (containing image a,b,c,d,e) → [[Template:Lead/GalleryItemNoCaption|Lead/GalleryItemNoCaption]]      │
 │        div.overlaywrapper                                             │
 │          div.overlaylabel                                             │
 └───────────────────────────────────────────────────────────────────────┘   

'''Notes:''' 

1. The first column contains the lead number plus an anchor (id="") to which internal links may point. Here and further below, the first Lead parameter is split into two parts using the Lead/SplitNumber template.

2. Retrieving the id-parameter of the earlier "Key Start" template from a variable depends on the "Variables" extension being installed. On Wiki installations where this is not the case, remove the template code "<nowiki>{{#var: decisiontreeID}}</nowiki>" (here, in Lead itself and Lead/SplitNumber).

3. Temporarily, the template supports two versions for formatting results, depending on whether Scientific Name is present (new) or not (old). If most keys have a scientific name, then the old version may be dropped. Please attempt to create all new keys for the new format!
  ############### NEW OLD RESULT layout rules: ####################
  // ? scientificname
  // yes: (new layout format)
  //    ? resulttext
  //    yes: resulttext [, resultlink] [, next]
  //    no :
  //        ? commonnames
  //        yes: commonnames - scientificname [, next]
  //        no : scientificname [, next]
  // no : (old layout)
  //    ? commonnames
  //    yes: commonnames
  //        ? resulttext
  //        yes: commonnames - resulttext [, resultlink] [, next]
  //        no : commonnames [, next]
  // Note: [, next] can appear in all layout variants
  ############################################################

  
<references/>

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