User:Innesw/sandbox/Module:Charts SVG/doc

This module creates charts by the generation of code for an SVG file.

The module exposes five functions: barChart, lineChart, mixedChart, scatterChart and pieChart.

Setup & Usage
This module is not intended to be used in Wikipedia articles. It is best used in a page in your own userspace, or in a sandbox. On an existing page, add (with further parameters) to the page, and click Preview. When you do, the module will show a box that includes a lot of text, starting with .

The process of using the module from there involves a number of steps:
 * on your computer, create a file with the filename extension '.svg' (eg: mychart.svg)
 * open this file with a text editor (eg: Notepad)
 * back in your browser, use your mouse to select the text within the box. It will start with  and end with.
 * copy this text, paste it into the file on your computer, and save the file.
 * To test the file is producing the image you want, you can view the file directly in some web browsers, or go to the Labs SVG Checker.
 * Note that results in web browsers, and in the Wikimedia Labs checker, may be different from the final Wikimedia rendering. Currently the only way to be absolutely sure of the final rendering is to upload the file and view it on a Wikipedia page. See.


 * Once you are happy with the image, upload the .svg file, then you can use it in a Wikipedia article using a [[File:]] link.
 * If you upload the image to commons, which is preferred to uploading to individual wikis, please add to the bottom of the file description page for the image.
 * It is also good practice to include the module-call that produced the image on the file description page.

Invoking the Module
The first parameter in the module call must be one of the following function names:

Without further parameters the module will produce (for barChart, lineChart, mixedChart and scatterChart) a chart with X and Y axes and gridlines, but no other content. For a pieChart, it will produce a completely blank image.

A note on terminology: throughout this documentation 'image' means the whole area produced by the SVG code produced by this module, while 'chart' refers to the area bounded by the X and Y axes (or, for pie charts, the rectangle that includes the pie). Most texts appear (by default) outside the area of the 'chart'.


 * for some parameters named using the style eg: SeriesValues, parameters are ignored beyond the first value of  that does not have a parameter defined: eg: if only Series1Values, Series2Values and Series4Values are defined, only series 1 and 2 will be used. This is noted in the parameter descriptions as "Must be in sequence."

Script Errors and Messages
Instead of the SVG code, you may get some red text saying Script error. You can click on that text to get the details of the error. If the details simply say 'Script error: No such module.', the module name is in error. WP is case-sensitive about module names, so make sure the name is 'Charts SVG'. If the details say 'Script error: The function you specified did not exist.', the first parameter is not one of the exposed function names.

Any other Script errors are errors in the module script itself. Hopefully these do not occur, but if they do, please report them at Module talk:Charts SVG, including the backtrace information and details of the module call.

Output may also, instead of SVG code, be messages headed "Charts SVG - Messages", containing messages from the module about issues with the supplied parameters. This can include a list of parameters whose names are not recognised. A maximum of 10 issues are reported at a time.

Grid Lines
Grid lines are shown on charts with axes by default, though defining any data groups will hide the XAxis grid lines. The default grid interval is that of the major tick-marks, which is equal to the ValueStep parameter for the axis.

Second Y Axis
A second Y axis can be shown on the right hand side of the chart. The switch to show this axis is setting Y2Max to any value. However if Stack or Stack100 are set, a second Y Axis will not be shown.

Note that the zero points of the left and right Y axes will only automatically align if both YMin and Y2Min are zero.

Data Series
Be aware that data series are displayed in reverse order, so series 1 is shown in front of series 2.

Chart Variations
In a lineChart, setting Stack or Stack100 will set Area to 'on'.

Parameters - Pie Charts
For pie charts, the chart size is calculated from the PieRadius.

SVG File Descriptive Elements
These parameters set values that are written to the SVG file, but are not displayed in the image.

Chart Texts
Additional texts can be shown on the chart. Appropriately placed, they can be a substitute for a legend.

In all cases the position specifies the baseline and left end of the text.

Colors
These are the defult colors for data series and pie segments. To set any color, use either a number from this table or an SVG color term.

Markers
To set a marker for series , set the SeriesMarker parameter to one of these numbers.



Dash Patterns
To set a dash pattern for series , set the SeriesDash parameter to one of these numbers, or to an SVG dash pattern term.



Fill Patterns
To set a fill pattern for series , set the SeriesPattern parameter to one of these numbers.



SVG Color Terms
Colors in SVG files can be specified in a number of ways:


 * as a 3- or 6-digit hexadecimal number, prefixed with'#', eg:, or   (which are equivalent).
 * in rgb functional notation, eg: rgb(255, 0, 128) or rgb(100%, 0, 50%) (which are equivalent).
 * as keywords, eg: blue, red. SVG recognises 147 color keywords, which are listed in the SVG specification.

In all cases an SVG color term should be entered in a parameter without surrounding quotes, eg:  or.

SVG Dash Pattern Terms
Dash patterns in SVG are specified by a series of space- or comma-separated numbers, which specify the lengths of the drawn or empty sections of the pattern. Eg: '8,2' specifies a dash of length 8 units, followed by a space of 2 units.

Dash pattern terms should be entered in a parameter without surrounding quotes, eg:.

Spaces in Parameters
Some parameters (especially Series1Values, ...) contain multiple values, separated by spaces. The SeriesValues parameters are written into the SVG code as comments (subject to the IncludeOriginalData parameter). Eg:

Groups of spaces and line-breaks are regarded as a single space when separating values.

User-supplied SVG code
There a number of parameters where the text of the parameter is written directly to the SVG output, with the expectation it is valid SVG code. If it is not, this will only be known when the SVG file is viewed as an SVG image. This may produce an error, or all or part of the SVG code may be ignored.

The parameters handled this way are:
 * ImageBackgroundSVG
 * ImageForegroundSVG
 * LegendSVG
 * all Color and Dash parameters that are not numeric values

Known Rendering Issues
Some SVG elements will not be rendered properly, or at all, when the SVG image is shown on a Wikipedia page. In part this is because the displayed image is in fact a PNG (bitmap) image - the SVG code is not sent to the user's browser.
 * Texts in the SVG may contain web addresses, but be aware the displayed PNG will not contain text that can be either clicked or copied-and-pasted. Actual links will need to be elsewhere.
 * Texts in the SVG should not contain wiki-markup, as it will not be interpreted as such when the SVG image is rendered on a Wikipedia page.
 * It appears the renderer simply ignores SVG xlink: references. Parameters where SVG code is supplied (eg: ImageForegroundSVG) should avoid them.

Examples
Consistent with the various chart types, these examples use almost identical data.



For more complex examples, see User:Innesw/sandbox/Module:Charts SVG/doc/further examples.

Development
If you have questions or suggestions, share them at Module talk:Charts SVG.