User:Mathglot/sandbox/Templates/xviews/doc

This is a documentation subpage for User:Mathglot/sandbox/Templates/xviews.
It may contain usage information, categories and other content that is not part of the original user template page.

May be used to generate a bar chart showing page views for a given article or page from a downloaded pageviews file. Mock-up; see § Notes.

Usage

{{xviews}}
{{xviews|pageviews file}}

Parameters

There are three optional parameters:

|1= – the pageviews file.(Default: {{SUBJECTPAGENAME}}; place on Talk page to get pageviews for the article.) See § Instructions.
|ct= – the count of page view bars to display (optional; default: 92; max: 150.) Large values may cause failure, see § Notes.
|stale= – number of days when a pageviews file becomes stale. Stale files will not generate a chart; a link to the § Update instructions is provided instead. (optional; default: 30).

Hooks are in place for additional parameters, not yet implemented:

|log= – use logarithmic data points; ideal for spiky or highly variable page view data (not implemented)
|mode= – flips the chart from horizontal to vertical (not implemented)

Examples

Example 1. page views for World War II
`{{User:Mathglot/sandbox/Templates/xviews\|Talk:World War II/pageviews}}` ⟶ The pageviews file Talk:World War II/pageviews is more than 30 days old; please see § Update instructions.

Notes

This template is a mockup of a replacement for the non-working {{annual readership}} based on {{Graph:Chart}} which was withdrawn for security reasons. It is a proof of concept and if approved, is designed to be replaced by a Lua module.

Technical limitations

There are various limitations in the template which will disappear in a Lua version, such as reaching the PEIS limit if too many statistics are charted at once. The default value of param |ct= is a throttle to help avoid this. If there are a lot of other templates on the page, you may need do reduce the value of that parameter to stay within limits. See Help:Template limits.

Troubleshooting

Chart does not display – some cases are recognized by the template and trapped with an error message; others are not.
- recognized errors:
1. missing file – if the pageviews file is missing, you should see a red error message.
2. stale data – if the data in the pageviews file is older than the 'stale' age, then a message about stale data should be emitted.
- unrecognized:
1. template limits exceeded – if there is no chart and no error message, you may have exceeded one of the template limits. Try running it in preview mode; if PEIS is exceeded, you should see the message, Warning: Post-expand include size is too large. Some templates will not be included. in a pink box at the top. Try reducing the value of |ct= until it shows output in preview mode, then save it. Reducing the pagefile size will also help; the template reads and processes all the data (multiple times, which a module won't), and if your pagefile has a year's worth of data, you may only be able to display 30 days of it, whereas if you reduce it to three months of data, you can probably display all of it.

Instructions

This template requires a pageviews file in CSV format, which is expected to be available as a subpage of the article Talk page where the template is placed. Param 1 is available as an override, to point somewhere else. The pageviews file may be placed by bot, or manually by an editor.

Contents of the pageviews file may be downloaded manually from the pageviews tool. Request output in CSV format, and copy it to a Talk subpage whose subpagename is pageviews; e.g., Talk:Cleopatra/pageviews. A good amount of data to request is three months' worth. Any amount of data may be copied to the subpage, but the template will only display at most the last 150 lines in the file to avoid issues caused by technical limitations with templates.The template has to read the whole pageviews file even if less data is displayed, and long files may exceed some technical limitations and cause the template to fail; reducing the pageviews file size may permit more of it to be displayed, than when the total filesize is larger. Empirically, the optimal amount appears to be 90 or 100 days, for Talk pages with an average number of other templates on them. Some pages will show as many as 150 days' worth; rarely much more than that.

Performance

This is a mockup intended to be replaced in the short term by a Lua module, and ultimately by repair to the Graphs problem, so performance of the template isn't really a major issue. Check WP:Parser profiling data for performance data.