View source for Module:Piechart/doc

{{documentation subpage}}
{{Module rating|release<!-- Values: pre-alpha • alpha • beta • release • protected • semiprotected  --  If a rating not needed/relevant, delete this template call -->}}
<!-- Add categories where indicated at the bottom of this page and interwikis at Wikidata -->

Smooth piechart module. Accessed via [[Template:Piechart]].

== Usage ==

Draws charts in HTML with an accessible legend (optional). A list of all features is in the "TODO" section of the main `p.pie` function.

Most of the time you should use with a helper template that adds required CSS: {{t|Piechart}}.

== Examples ==

=== Minimalistic ===
<syntaxhighlight lang="wikitext" lang="javascript"></syntaxhighlight>
Note that you don't need to provide the second value as it's calculated (assuming they sum up to 100).
<syntaxhighlight lang="wikitext">
{{Piechart| [ {"value":33.3},  {} ] }}
</syntaxhighlight>
{{Piechart| [ {"value":33.3},  {} ] }}

=== Labels and Legend ===
Here we add some custom labels. Also note that we add a meta option to add legend on the side.
<syntaxhighlight lang="wikitext">
{{Piechart| [
 {"label": "women: $v", "value": 33.3},
 {"label": "men: $v"}
]
| meta = {"legend":true}
}}
</syntaxhighlight>
{{Piechart| [
 {"label": "women: $v", "value": 33.3},
 {"label": "men: $v"}
]
| meta = {"legend":true}
}}

=== Automatic Scaling ===
In cases where you don't have calculated percentages, you can use automatic scaling. Just provide both values in this case.

<syntaxhighlight lang="wikitext">
{{Piechart| [
 {"label": "women: $v", "value": 750},
 {"label": "men: $v", "value": 250}
]
| meta = {"legend":true}
}}
</syntaxhighlight>
{{Piechart| [
 {"label": "women: $v", "value": 750},
 {"label": "men: $v", "value": 250}
]
| meta = {"legend":true}
}}

=== Multiple Values ===
The module allows displaying multiple values, not just 2.
<syntaxhighlight lang="wikitext">
{{Piechart| [
 {"label": "sweets: $v", "value": 5, "color":"darkred"},
 {"label": "sandwiches: $v", "value": 3, "color":"wheat"},
 {"label": "cookies: $v", "value": 2, "color":"goldenrod"},
 {"label": "drinks: $v", "value": 1, "color":"#ccf"}
]
|meta={"autoscale":true, "legend":true}
}}
</syntaxhighlight>
{{Piechart| [
 {"label": "sweets: $v", "value": 5, "color":"darkred"},
 {"label": "sandwiches: $v", "value": 3, "color":"wheat"},
 {"label": "cookies: $v", "value": 2, "color":"goldenrod"},
 {"label": "drinks: $v", "value": 1, "color":"#ccf"}
]
|meta={"autoscale":true, "legend":true}
}}

Note that in this case, it was necessary to provide the additional option <code>"autoscale":true</code>. This is necessary when the sum is less than 100.

=== Links ===
{{Piechart| [
 {"label": "[[candy|sweets]]: $v", "value": 5, "color":"darkred"},
 {"label": "[[sandwich]]es: $v", "value": 3, "color":"wheat"},
 {"label": "[[cookie]]s: $v", "value": 2, "color":"goldenrod"},
 {"label": "[[drink]]s: $v", "value": 1, "color":"#ccf"}
]
|meta={"autoscale":true, "legend":true}
}}

== Legend and Its Position ==

The legend is added using the meta property ''legend'' as shown. However, you can also change the order using ''direction''. Possible values include:
* row (default) – order is list, chart;
* row-reverse – reverse order, i.e., chart, list;
* column – column layout (vertical).
* column-reverse – column layout, reversed (chart on top).
<syntaxhighlight lang="wikitext">
{{Piechart| [
 {"label": "cookies: $v", "value": 2, "color":"goldenrod"},
 {"label": "drinks: $v", "value": 1, "color":"#ccf"},
 {"label": "sweets: $v", "value": 5, "color":"darkred"},
 {"label": "sandwiches: $v", "value": 3, "color":"wheat"}
]
|meta={"autoscale":true, "legend":true, "direction":"row-reverse"}
}}
</syntaxhighlight>

<div class="wikiflex" style="display:flex; gap: 1em; flex-wrap: wrap;"><!-- top -->
<div class="wikiflex" style="display:flex; gap: 1em; align-items: flex-start; flex-wrap: wrap;"><!-- -->
<div style="border:1px solid darkgreen; padding: 0 .5em .5em">
'''row''' (default ''direction'')
{{Piechart| [
 {"label": "cookies: $v", "value": 2, "color":"goldenrod"},
 {"label": "drinks: $v", "value": 1, "color":"#ccf"},
 {"label": "sweets: $v", "value": 5, "color":"darkred"},
 {"label": "sandwiches: $v", "value": 3, "color":"wheat"}
]
|meta={"autoscale":true, "legend":true, "direction":"row"}
}}
</div>
<div style="border:1px solid darkgreen; padding: 0 .5em .5em">
'''row-reverse'''
{{Piechart| [
 {"label": "cookies: $v", "value": 2, "color":"goldenrod"},
 {"label": "drinks: $v", "value": 1, "color":"#ccf"},
 {"label": "sweets: $v", "value": 5, "color":"darkred"},
 {"label": "sandwiches: $v", "value": 3, "color":"wheat"}
]
|meta={"autoscale":true, "legend":true, "direction":"row-reverse"}
}}
</div>
<!-- --></div>
<div class="wikiflex" style="display:flex; gap: 1em; align-items: flex-start; flex-wrap: wrap;"><!-- -->
<div style="border:1px solid darkgreen; padding: 0 .5em .5em">
'''column'''
{{Piechart| [
 {"label": "cookies: $v", "value": 2, "color":"goldenrod"},
 {"label": "drinks: $v", "value": 1, "color":"#ccf"},
 {"label": "sweets: $v", "value": 5, "color":"darkred"},
 {"label": "sandwiches: $v", "value": 3, "color":"wheat"}
]
|meta={"autoscale":true, "legend":true, "direction":"column"}
}}
</div>
<div style="border:1px solid darkgreen; padding: 0 .5em .5em">
'''column-reverse'''
{{Piechart| [
 {"label": "cookies: $v", "value": 2, "color":"goldenrod"},
 {"label": "drinks: $v", "value": 1, "color":"#ccf"},
 {"label": "sweets: $v", "value": 5, "color":"darkred"},
 {"label": "sandwiches: $v", "value": 3, "color":"wheat"}
]
|meta={"autoscale":true, "legend":true, "direction":"column-reverse"}
}}
</div>
<!-- --></div>
<!-- top --></div>
Green frames added for clarity in examples. They are not normally added.

== Direct functions ==
In case you want to use without the {{t|Piechart}} template, you can use this main functions:
* <code><nowiki>{{</nowiki>#invoke:Piechart|''pie''<nowiki>|json_data|meta=json_options}}</nowiki></code>
* <code><nowiki>{{</nowiki>#invoke:Piechart|''color''<nowiki>|number}}</nowiki></code>

Note that direct calls to the ''pie'' function require adding CSS:
<syntaxhighlight lang="javascript">
<templatestyles src="Piechart/style.css"/>
{{#invoke:Piechart|pie| [ {"value":33.3},  {} ] }}
</syntaxhighlight>

Example of '''json_data''':
<syntaxhighlight lang="javascript">
[
		{ "label": "pie: $v", "color": "wheat", "value": 40 },
		{ "label": "cheese pizza $v", "color": "#fc0", "value": 20 },
		{ "label": "mixed pizza: $v", "color": "#f60", "value": 20 },
		{ "label": "raw pizza $v", "color": "#f30" }
]
</syntaxhighlight>
* Note that the last value is missing. The last value is optional as long as the values are intended to sum up to 100 (as in 100%).
* Notice <code>$v</code> label, this is a formatted number (see `<code>function prepareLabel</code>`).
* Colors are hex or names. Default palette is in shades of green.

Example of meta='''json_options''':
<syntaxhighlight lang="javascript">
|meta = {"size":200, "autoscale":false, "legend":true}
</syntaxhighlight>

All meta options are optional (see `<code>function p.setupOptions</code>`).

== Feature requests ==
For feature requests and bugs write to me, the author of the piecharte module: [[User:Nux|Maciej Nux]].

== See also ==
* {{tl|Pie chart}}, also pie, but with classic template parameters (enumerated); that chart is shown on the right (like a thumbnail image).

{{Template:Graph, chart and plot templates}}

<includeonly>{{Sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Chart, diagram and graph formatting and function templates]]
[[Category:Graph, chart and plot templates]]
[[Category:Modules]]
}}</includeonly><noinclude>
[[Category:Module documentation pages]]
</noinclude>