View source for Template:Article length bar/doc

{{Documentation subpage}}
{{tsh|Albar}}
{{Template rating|alpha}}
{{Uses TemplateStyles|Template:Article length bar/styles.css}}
Generates a configurable, progress bar-style graphic that may be used to visually display the length of a given article relative to a theoretical maximum. The bar changes color when certain thresholds of appropriate or [[WP:SIZESPLIT|excessive article size]] are exceeded.

== Usage ==

: {{tlc|Article length bar |''ArticleName''}}{{br}}
: {{tlc|Article length bar |''ArticleName''|mode{{=}}vert}}
<!--
: {{tlc|Article length bar |len{{=}}123 |max{{=}}185}}
: {{tlc|Albar |len{{=}}80}}
-->

== Parameters ==

There is one required parameter, four styling params, and five configuration params:
* {{para|1}} – name of the article; required. This is used to derive the article length; see {{slink||Notes}}.

=== Styling params ===
All styling parameters are optional. Using them changes the appearance for all users viewing the page where the template appears. To alter the appearance only for yourself, see {{slink||Per-user style}}.

* {{para|mode}} – set mode to {{pval|vert}} to change the bar to a 96 x 28px vertical bar; (default: a horizontal bar, 14 x 64px)
* {{para|nokb}} – set to {{pval|yes}} to suppress display of the rounded kilobyte size in the length bar. This also suppresses the tooltip.
* {{para|spark}} – set to a non-empty value to generate an inline, [[sparkline]]-ish bar in running text. (See {{slink||Notes}}{{hairspace}}).
* {{para|style}} – you may add any [[CSS]] parameters applicable to an HTML [[inline element]] to alter the appearance of the length bar, such as size, width, border, etc.

=== Configuration params ===
All configuration params are optional. Configuration params alter variables with predefined default values which govern color transition points within the length bar. By default, these are designed to reflect the length of articles that "probably" or "definitely" should be split (see {{slink||Notes}}{{hairspace}}). Altering these values changes the point where color transitions begin in the length bar.
* {{para|T1}} – green up to this byte length, then switches to yellow; (default: {{formatnum:{{Alb/c|T1}}}} bytes)
* {{para|T2}} – yellow until this byte length, then red; (default: {{formatnum:{{Alb/c|T2}}}} bytes)
* {{para|TMAX}} – articles this size fill the bar to 100%; (default: {{formatnum:{{Alb/c|TMAX}}}} bytes). Larger values do not extend color past the box border, but trigger a color gradient from red to dark red. 
* {{para|L0MAX}} –  max size of the green area in percent; derivable from T1; see note [[#config-note|below]];  (default: {{Alb/c|L0MAX}}{{hairspace}})
* {{para|L1MAX}} –  high point of the yellow area in percent; see [[#config-note|note]]; (default: {{Alb/c|L1MAX}}{{hairspace}})

Normally, there is no reason to change these from the default values, and the recommendation is not to use them. One reason to do so might be to compare articles within a skewed sample set, such as comparing a set of stub articles, or comparing a set of articles appearing near the top of the [[Special:LongPages|longest articles]] list.

{{anchor|config-note}}'''Note:''' L0MAX and L1MAX are derivable as a raw byte size converted to a percent, and thus locked to the values of T1 and T2, respectively. If you change either T1 or T2, please also change the former to match:
* L0MAX is derived as: (T1 * 100 / TMAX), round to 0 decimal places
* L1MAX is derived as: (T2 * 100 / TMAX) round 0

== Meaning of the colors ==

Article length bar graphics may have up to three colors: green, yellow, and red, and their placement is influenced by the [[Wikipedia:Article size|article size guideline]], with green intended to indicate, "no need to split", yellow = "might need to be split", and red "almost certainly" should be split. (For technical reasons, these thresholds are calculated as a function of raw article size in bytes; an upgrade to base it on [[WP:WORDCOUNT|prose words]] is envisaged, but not imminent.)

The thresholds where the colors change from green to yellow (currently {{formatnum:{{alb/c|T1}}}} bytes), and from yellow to red ({{formatnum:{{alb/c|T2}}}}b) are given by [[Template:Article length bar/c#Parameters|predefined variables]]; these variables are [[#Configuration params|configurable]] so that you can move the point where the color changes up or down (left or right in the graphic). The current [[Template:Article length bar/c#Parameters|variable defaults]] are a compromise (discussed [[Template talk:Article length bar#Arbitrariness of what length should fill the bar 100% (TMAX)|here]]). If you are displaying a table, say, of the [[Special:LongPages|longest pages]] at Wikipedia, you would increase the variable values; and if you are comparing only the size of lead sections in various articles, you would reduce them.

An article whose length exactly equals variable [[#Configuration params|TMAX]] fills the rectangular graphic completely. What happens when a given article exceeds the default or configured TMAX value?  It cannot exceed the rectangle border, so instead, the last part of the red section has a gradient from red to dark red; this is a flag that the article size is greater than the configured value for a completely filled rectangle (i.e., byte length > TMAX). A possible upgrade to use logarithmic length bars instead of linear would obviate need for the dark red gradient.

By appropriate adjustment of the [[#Configuration params|configurable variables]], it is possible to reduce the number of colors displayed to two (see [[#example 2|code example 2]]), or even just one. The color hex values are currently non-configurable.

== Examples ==
{{hatnote|Hovering over the figures gives the size in bytes.}}
: {{tlc|Article length bar |Battle of Kitcheners' Wood |code=y |_show_result=y}} 
: {{tlc|Article length bar |Second Battle of Ypres |code=y |_show_result=y}} 
: {{tlc|Article length bar |Assassination of Archduke Franz Ferdinand |code=y |_show_result=y}} 
: {{tlc|Article length bar |Battle of Jutland |code=y |_show_result=y}} 
: {{tlc|Article length bar |World War I |code=y |_show_result=y}} 
: {{tlc|Article length bar |France |code=y |_show_result=y}} 
: {{tlc|Article length bar |France |style{{=}}height:2px; |nokb{{=}}y |code=y |_show_result=y}} 
: {{tlc|Article length bar |France |spark{{=}}y |code=y |_show_result=y}} 
: {{tlc|Article length bar |France |style{{=}}height:24px; width:128px; padding:3px 0 0 3px|code=y |_show_result=y}}
: {{tlc|Article length bar |France |mode{{=}}vert |code=y |_show_result=y}} 
: {{tlc|Article length bar |2022 in science |code=y |_show_result=y}} 
<!--
: <code><nowiki>{{Article length bar |len={{formatnum:{{PAGESIZE:Battle of Verdun}}|R}} |max=250000}}</nowiki></code> ⟶ {{Article length bar |len={{formatnum:{{PAGESIZE:Battle of Verdun}}|R}} |max=250000}} <small>Same as above</small>
: {{tlg|Article length bar |len{{=}}123 |max{{=}}185 |code=y |_show_result=y}}
: {{tlg|Article length bar |len{{=}}80 |code=y |_show_result=y}}
-->
Parameters: T1, T2, TMAX
: {{tlc|Article length bar|France|code=y |_show_result=y}}
: {{tlc|Article length bar|France|T1{{=}}100000|T2{{=}}150000|TMAX{{=}}200000 |code=y |_show_result=y}} 
: {{tlc|Article length bar|France|T1{{=}}200000|T2{{=}}275000|TMAX{{=}}425000 |code=y |_show_result=y}}
{{cot|align=left|indent=1.6em|bg=darkseagreen|{{anchor|example 1}}Code example 1: For loop, passing a dozen country name articles to <code>Albar</code> styled to 40em wide}}
{{hatnote|Hover over kb size for article name and exact size in bytes}}
{{cot|bg=cornsilk|Code for this}}
<pre>
{{for loop || call = Albar
 | France | Germany | Italy | Sudan | Nigeria | Uzbekistan | New Zealand | Colombia | Argentina | Canada | Mexico | Australia
 |pc1n=style |pc1v=width:40em 
}}
</pre>
{{cob}}
{{for loop || call = Albar
 | France | Germany | Italy | Sudan | Nigeria | Uzbekistan | New Zealand | Colombia | Argentina | Canada | Mexico | Australia
 |pc1n=style |pc1v=width:40em 
}}
{{cob}}

{{cot|indent=1.6em|bg=darkseagreen|align=left|{{anchor|example 2}}Code example 2: show the ratio of lead to article size for seven Featured articles:}}
{{hatnote|Green represents the lead section, and yellow is the rest of the article. Total size of the article in kb given in the bar at left; percentage occupied by the lead is given at the end of each line.}}
{{cot|bg=cornsilk|Code for this}}
<pre>
{{albar|The Cabinet of Dr. Caligari |T1=4202 |T2=131953 |TMAX=131953 |L0MAX=3.2 |L1MAX=100 |style=width:70%}} [[The Cabinet of Dr. Caligari]] = 3.2%{{br}}
{{albar|Caesar cipher |T1=2138 |T2=19310 |TMAX=19310 |L0MAX=6.4 |L1MAX=100 |style=width:70%}} [[Caesar cipher]] = 6.4%{{br}}
{{albar|Caroline Island |T1=2230 |T2=55355 |TMAX=55355 |L0MAX=4 |L1MAX=100 |style=width:70%}} [[Caroline Island]] = 4.0%{{br}}
{{albar|Casablanca (film) |T1=10748 |T2=108919 |TMAX=108919 |L0MAX=9.9 |L1MAX=100 |style=width:70%}} [[Casablanca (film)]] = 9.9%{{br}}
{{albar|Castle |T1=5901 |T2=114539 |TMAX=114539 |L0MAX=5.2 |L1MAX=100 |style=width:70%}} [[Castle]] = 5.2%{{br}}
{{albar|Cerro Blanco (volcano) |T1=3462 |T2=82588 |TMAX=82588 |L0MAX=4.2 |L1MAX=100 |style=width:70%}} [[Cerro Blanco (volcano)]] = 4.2%{{br}}
{{albar|Chagas disease |T1=8308 |T2=68423 |TMAX=68423 |L0MAX=12.1 |L1MAX=100 |style=width:70%}} [[Chagas disease]] = 12.1%
</pre>
{{cob}}
{{albar|The Cabinet of Dr. Caligari |T1=4202 |T2=131953 |TMAX=131953 |L0MAX=3.2 |L1MAX=100 |style=width:70%}} [[The Cabinet of Dr. Caligari]] = 3.2%{{br}}
{{albar|Caesar cipher |T1=2138 |T2=19310 |TMAX=19310 |L0MAX=6.4 |L1MAX=100 |style=width:70%}} [[Caesar cipher]] = 6.4%{{br}}
{{albar|Caroline Island |T1=2230 |T2=55355 |TMAX=55355 |L0MAX=4 |L1MAX=100 |style=width:70%}} [[Caroline Island]] = 4.0%{{br}}
{{albar|Casablanca (film) |T1=10748 |T2=108919 |TMAX=108919 |L0MAX=9.9 |L1MAX=100 |style=width:70%}} [[Casablanca (film)]] = 9.9%{{br}}
{{albar|Castle |T1=5901 |T2=114539 |TMAX=114539 |L0MAX=5.2 |L1MAX=100 |style=width:70%}} [[Castle]] = 5.2%{{br}}
{{albar|Cerro Blanco (volcano) |T1=3462 |T2=82588 |TMAX=82588 |L0MAX=4.2 |L1MAX=100 |style=width:70%}} [[Cerro Blanco (volcano)]] = 4.2%{{br}}
{{albar|Chagas disease |T1=8308 |T2=68423 |TMAX=68423 |L0MAX=12.1 |L1MAX=100 |style=width:70%}} [[Chagas disease]] = 12.1%
{{cob}}

== Notes ==

The length value retrieved for a given article is the raw size of the wikicode in bytes ({{tl|PAGESIZE}}). Pagesize is easier to compute than prose word count, and can be a rough proxy for relative [[WP:article size|article size]], but should be used with caution.

[[Sparkline]]s are useful for embedding very small graphics in running text. For example, a Talk page discussion about a country article:
: {{talk quote|...can be seen in the relative sizes of [[France]] {{Albar|France|spark=y}}, [[Germany]] {{Albar|Germany|spark=y}}, and [[Italy]].{{Albar|Italy|spark=y}}}}
with the bars appearing at the same size as the surrounding text, and remaining proportionate under zooming. Use [[#Parameters|§&nbsp;param]] {{para|spark|y}} to generate a sparkline chart.

=== Per-user style ===

You can modify the appearance of the bar for yourself only without affecting anyone else, or make the bar disappear completely through the use of predefined [[CSS class]]es {{pval|aab-bar}} and {{pval|aab-bar-vert}} defined on the article length bar graphic by appropriate modification of your [[Special:MyPage/common.css]]. (t.b.a. ...)

== Known issues ==

* A bug related to articles shorter than the first size threshold with style parameter; see [[{{TALKPAGENAME}}#Bg color and width anomaly in interaction of style with article size < green-yellow threshold|Talk]].

== See also ==
{{div col|colwidth=30em}}
* {{tl|Article length rating}}
* {{tl|PAGESIZE}}
* [[WP:Article size]]
* [[WP:MARKUPSIZE]]
* [[WP:Prose size]]
* [[WP:SIZESPLIT]]
{{div col end}}

{{Progress templates}}
{{Graph, chart and plot templates|state=collapsed}}

<includeonly>{{sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Wikipedia progress templates]]
}}</includeonly>