Editing Template:Module:Graph/doc

Module with helper functions for the [[Module:Graph|Graph]] extension.

== Functions for templates ==
=== <code>map</code> ===
Creates a JSON object for <code><nowiki><graph></nowiki></code> to display a political map with colored highlights. 

Maps can be found at [[Special:PrefixIndex/Module:Graph/]] and new maps should also be saved under Modul:Graph/.

'''Parameters:'''
* '''basemap:''' sets the base map. The map definitions must follow the [https://github.com/mbostock/topojson/wiki TopoJSON] format and if saved in Wikipedia are available for this module. Maps in the default directory [[Special:PrefixIndex/Module:Graph/]] should only be referenced by their name while omitting the Module:Graph/ prefix to allow better portability. The parameter also accepts URLs, e.g. maps from other Wikipedia versions (the link should follow the scheme of <code>//en.wikipedia.org/w/index.php?title=''mapname''&action=raw</code>, i.e. protocol-relative without leading http/s and a trailing action=raw to fetch the raw content only). <small>URLs to maps on external sites should be avoided for the sake of link stability, performance, security, and should be assumed to be blocked by the software or browser anyway.</small>
* '''scale:''' the scaling factor of the map (default: 100)
* '''projection:''' the [[:en:map projection|map projection]] to use. Supported values are listed at https://github.com/mbostock/d3/wiki/Geo-Projections. The default value is <code>equirectangular</code> for an [[:en:equirectangular projection|equirectangular projection]].
* ids of geographic entities: The actual parameter names depend on the base map. For example, for the above mentioned world map the ids are [[:en:ISO country codes|ISO country codes]]. The values can be either colors or numbers in case the geographic entities should be associated with numeric data: <code>DE=lightblue</code> marks Germany in light blue color, and <code>DE=80.6</code> assigns Germany the value 80.6 (population in millions). In the latter case, the actual color depends on the following parameters.
** '''colorScale:''' the color palette to use for the color scale. The palette must be provided as a comma-separated list of color values. The color values must be given either as <code>#rgb</code>/<code>#rrggbb</code> or by a [[:en:Web colors#X11 colour names|CSS color name]]. Instead of a list, the built-in color palettes [https://github.com/mbostock/d3/wiki/Ordinal-Scales#categorical-colors <code>category10</code> and <code>category20</code>] can also be used.
** '''scaleType:''' supported values are <code>linear</code> for a linear mapping between the data values and the color scale, <code>log</code> for a log mapping, <code>pow</code> for a power mapping (the exponent can be provided as <code>pow 0.5</code>), <code>sqrt</code> for a square-root mapping, and <code>quantize</code> for a quantized scale, i.e. the data is grouped in as many classes as the color palette has colors.
** '''domainMin:''' lower boundary of the data values, i.e. smaller data values are mapped to the lower boundary
** '''domainMax:''' upper boundary of the data values, i.e. larger data values are mapped to the upper boundary
** '''legend:''' show color legend (does not work with <code>quantize</code>)
* '''defaultValue:''' default value for unused geographic entities. In case the id values are colors the default value is <code>silver</code>, in case of numbers it is 0.
* '''formatjson:''' format JSON object for better legibility
=== <code>chart</code> ===
Creates a JSON object for <code><nowiki><graph></nowiki></code> to display charts. In the article namespace the template {{tl|Graph:Chart}} should be used instead. See its page for use cases.

'''Parameters:'''
* '''width:''' width of the chart
* '''height:''' height of the chart
* '''type:''' type of the chart: <code>line</code> for [[:en:line chart|line chart]]s, <code>area</code> for [[:en:area chart|area chart]]s, and <code>rect</code> for (column) [[:en:bar chart|bar chart]]s, and <code>pie</code> for [[:en:pie chart|pie chart]]s. Multiple series can stacked using the <code>stacked</code> prefix, e.g. <code>stackedarea</code>.
* '''interpolate:''' [[:en:interpolation|interpolation]] method for line and area charts. It is recommended to use <code>monotone</code> for a [[:en:monotone cubic interpolation|monotone cubic interpolation]] – further supported values are listed at https://github.com/vega/vega/wiki/Marks#area.
* '''colors:''' color palette of the chart as a comma-separated list of colors. The color values must be given either as <code>#rgb</code>/<code>#rrggbb</code>/<code>#aarrggbb</code> or by a [[:en:Web colors#X11 colour names|CSS color name]]. For <code>#aarrggbb</code> the <code>aa</code> component denotes the [[:en:alpha channel|alpha channel]], i.e. FF=100% opacity, 80=50% opacity/transparency, etc. (The default color palette is [//github.com/mbostock/d3/wiki/Ordinal-Scales#categorical-colors <code>category10</code>]).
* '''xAxisTitle''' and '''yAxisTitle:''' captions of the x and y axes
* '''xAxisMin, xAxisMax, yAxisMin,''' and '''yAxisMax:''' minimum and maximum values of the x and y axes
* '''xAxisFormat''' and '''yAxisFormat:''' changes the formatting of the axis labels. Supported values are listed at https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#numbers for numbers and https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md for date/time. For example, the format <code>%</code> can be used to output percentages.
* '''xAxisAngle:''' rotates the x axis labels by the specified angle. Recommended values are: -45, +45, -90, +90
* '''xType''' and '''yType:''' Data types of the values, e.g. <code>integer</code> for integers, <code>number</code> for real numbers, <code>date</code> for dates (e.g. YYYY/MM/DD), and <code>string</code> for ordinal values.
* '''x''': the x-values as a comma-separated list (if a value itself contains a comma it must be escaped with a backslash, i.e. it needs to be written as <code>\,</code>)
* '''y''' or '''y1, y2,''' …: the y-values for one or several data series, respectively. For pie charts <code>y2</code> denotes the radiuses of the corresponding sectors.
* '''legend:''' show legend (only works in case of multiple data series)
* '''y1Title, y2Title,''' …: defines the label of the respective data series in the legend
* '''linewidth:''' line width for line charts or distance between the pie segments for pie charts
* '''showValues:''' Additionally, output the y values as text. (Currently, only (non-stacked) bar and pie charts are supported.) The output can be configured used the following parameters provided as <code>name1:value1, name2:value2</code>:
** '''format:''' Format the output according to https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#numbers for numbers and https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md for date/time.
** '''fontcolor:''' text color
** '''fontsize:''' text size
** '''offset:''' move text by the given offset. For bar charts and pie charts with <code>midangle</code> this also defines if the text is inside or outside the chart.
** '''angle''' (pie charts only): text angle in degrees or <code>midangle</code> (default) for dynamic angles based on the mid-angle of the pie sector.
* '''innerRadius:''' For pie charts: defines the inner radius to create a ''doughnut chart.''
* '''formatjson:''' format JSON object for better legibility

=== Template wrappers ===
The functions <code>mapWrapper</code> and <code>chartWrapper</code> are wrappers to pass all parameters of the calling template to the respective <code>map</code> and <code>chart</code> functions.

'''Note:''' In the editor preview the graph extension creates a [[:en:canvas element|canvas element]] with vector graphics. However, when saving the page a [[:en:Portable Network Graphics|PNG]] raster graphics is generated instead.

'''Note to developers:''' New functionality can be tested with the [https://vega.github.io/vega-editor/index.html?mode=vega Vega Editor], that also contains a large amount of example code.

<noinclude>[[Category:Template documentation]]</noinclude>