Module:Database report/doc

This module provides a Lua interface to configure database reports.

If your SQL code and other config is static, you probably don't need to use this module. You can directly use {{database report}}. This module is intended for advanced use cases where you want to share parts of the report configuration across multiple reports.

The high-level usage pattern is as follows:

local Report = require('Module:Database report')

local p = {}

p.main = function()
	local report = Report:new()

	-- Write your SQL.
	report:setSQL("...WRITE YOUR SQL HERE...")

	-- Customize the report as required. See the detailed documentation below for each function 
	report:useWikilinks(2, 'c1')
	report:hideColumns(1)
	
	-- The final step: returns the serialized representation of the report. Don't change this line.
	return report:generate()
end 

return p

It is recommended to create your module as a subpage of Module:Database reports (use the preload form on that page).

Next, create the report page with the content:

{{Database report
| lua_source = Module:Database report/...name of subpage...   <!-- Module page where the report config is defined. -->

<!-- Optional parameters -->
| lua_function = main   <!-- Name of the function which returns the generated report. Default: main -->
| lua_arg_foo = bar <!-- Pass the parameter foo=bar to the Lua function -->
}}

An example of a parametrized report is Module:Database_reports/Long_pages_by_namespace. Parameters passed to {{database report}} beginning with lua_arg_ are made available to the module.

For each parameter accepted by {{database report}}, a corresponding method exists in the Report class (see below). In addition, there is the Lua-specific method setHeadContent, which can be used by parametrized reports to include some common lead text across reports. Templatestyles can also included this way.

Initialize a new database report instance. This is the constructor method that should be called to create a new report instance.

Signature:

function Report:new()

Returns:

• (Report) A new Report instance with default settings

Usage examples:

local report = Report:new()

Set the SQL query for the database report. This is a required parameter. The SQL must be a valid SELECT statement.

Signature:

function Report:setSQL(sql)

Parameters:

• sql (string) - The SQL query to execute (must be non-empty)

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setSQL("SELECT page_title FROM page LIMIT 10")

Raises:

• error if sql is nil, not a string, or empty

Configure wikilinks for one or more columns in the report. Wikilinks convert column values into clickable links to other pages. Can be called multiple times to configure different columns.

Signature:

function Report:useWikilinks(column, namespace, show)

Parameters:

• column (number|table) - Column number to be wikilinked, or table of column configurations
• namespace (number|string) - Optional namespace number for links. If the namespace number is in another column, use "c1" if it's in the first column, "c2" if it's in the second column, etc.
• show (boolean) - Whether the namespace prefix should be displayed in the link (default: false)

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:useWikilinks(1) -- Simple wikilink for column 1

report:useWikilinks(1, 0, true) -- Column 1, namespace 0, show prefix

report:useWikilinks({{column=1, namespace="c2"}, {column=3}}) -- Multiple columns

Set the width for one or more columns in the report. Controls the display width of columns using CSS width values. Can be called multiple times to set different column widths.

Signature:

function Report:setWidth(column, width)

Parameters:

• column (number|table) - Column number to set width for, or table of width configurations
• width (string) - CSS width value (e.g., "10em", "50px", "20%", "200px")

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setWidth(1, "200px") -- Set column 1 to 200px width

report:setWidth({{column=1, width="10em"}, {column=2, width="50%"}}) -- Multiple columns

Set columns to be treated as comments (edit summaries or log action summaries) in the report.

Signature:

function Report:setCommentColumns(...)

Parameters:

• ... (number) - Variable number of column numbers to mark as comments

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setCommentColumns(3, 5) -- Mark columns 3 and 5 as comments

Configure columns to have underscores removed from their values. Useful for page titles where underscores should be converted to spaces. For columns with wikilinks or excerpts configured, this will be done automatically.

Signature:

function Report:removeUnderscores(...)

Parameters:

• ... (number) - Variable number of column numbers to remove underscores from

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:removeUnderscores(1, 2) -- Remove underscores from columns 1 and 2

Hide specified columns from the report display. Hidden columns are still processed but not shown in the final output. Useful for columns used only for processing (like namespace numbers) but not for display.

Signature:

function Report:hideColumns(...)

Parameters:

• ... (number) - Variable number of column numbers to hide

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:hideColumns(2, 4) -- Hide columns 2 and 4 from display

Configure generation of article excerpts (summaries). Creates excerpts from source column that should contain page titles, and places them in a destination column.

Signature:

function Report:useExcerpt(srcColumn, destColumn, namespace, charLimit, charHardLimit)

Parameters:

• srcColumn (number) - Column containing page title whose excerpt should be created
• destColumn (number) - Destination column number to place the excerpt.
• namespace (number|string) - Namespace number for the page title (default: 0 for main namespace). If the namespace number is in another column, use "c1" if it's in the first column, "c2" if it's in the second column, etc.
• charLimit (number) - Optional character limit for the excerpt
• charHardLimit (number) - Optional hard character limit (truncates if exceeded)

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:useExcerpt(1, 2) -- Create excerpt for titles in column 1, place in column 2

report:useExcerpt(1, 2, 0, 200, 250) -- Create excerpt for titles in column 1 with namespace 2 (user namespace), 200 char limit, 250 hard limit

Set the CSS style for the report table. Applies custom CSS styling to the generated table element.

Signature:

function Report:setTableStyle(style)

Parameters:

• style (string) - CSS style string to apply to the table

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setTableStyle("border: 1px solid #ccc; width: 100%")

Set the CSS class for the report table. Applies a CSS class to the generated table element for styling.

Signature:

function Report:setTableClass(class)

Parameters:

• class (string) - CSS class name to apply to the table

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setTableClass("wikitable sortable")

Set the update interval for the database report. Controls how often the report is automatically refreshed with new data from the database.

Signature:

function Report:setInterval(days)

Parameters:

• days (number) - Number of days between updates (must be >= 1)

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setInterval(7) -- Update every 7 days

Raises:

• error if days is not a number or is less than 1

Set the number of rows per page for pagination. Enables pagination by limiting the number of rows displayed per page. By default, no pagination is done.

Signature:

function Report:setPagination(count)

Parameters:

• count (number) - Number of rows to display per page.

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setPagination(1000) -- Show 1000 rows per page

Raises:

• error if count is not a positive number

Set the maximum number of pages when using pagination. Limits the total number of pages that can be created in a paginated report. The default value is 5.

Signature:

function Report:setMaxPages(count)

Parameters:

• count (number) - Maximum number of pages to display. Should not be greater than 20.

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setMaxPages(10) -- Limit to 10 pages maximum

Raises:

• error if count is not a positive number

Set a template to be used for formatting each row. Allows custom formatting of individual rows using MediaWiki templates. The "Template:" prefix can be skipped.

Signature:

function Report:setRowTemplate(template)

Parameters:

• template (string) - Name of the template to use for row formatting

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setRowTemplate("MyRowTemplate")

Enable use of named parameters in the row template. When enabled, values to the row template are passed by column name instead of position. For a query with columns page_title, page_namespace and rev_len, the row template generated would be {{MyRowTemplate|page_title=...|page_namespace=...|rev_len=...}} instead of {{MyRowTemplate|1=...|2=...|3=...}}.

Signature:

function Report:useNamedParamsInRowTemplate(value)

Parameters:

• value (boolean) - Whether to use named parameters (truthy/falsy)

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:useNamedParamsInRowTemplate(true) -- Use named parameters

Skip generating the table structure for the report. Useful when row_template is used and the table structure is not needed. Useful when using custom templates for display.

Signature:

function Report:skipTable(value)

Parameters:

• value (boolean) - Whether to skip table generation (truthy/falsy)

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:skipTable(true) -- Skip table generation

Set a template to be used for generating the table header.

Signature:

function Report:setHeaderTemplate(template)

Parameters:

• template (string) - Name of the template to use for the header

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setHeaderTemplate("MyHeaderTemplate")

Set a template to be used as the report footer. This can be used to complement the header template. For example, if the header template is {{div col}}, the footer template can be {{div col end}}.

Signature:

function Report:setFooterTemplate(template)

Parameters:

• template (string) - Name of the template to use for the footer

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setFooterTemplate("MyFooterTemplate")

Set JavaScript code to be executed for postprocessing the report content. Allows for arbitrary manipulation of the report data with limited access to Wikimedia APIs. See Template:Database report#postprocess_js for more details.

Signature:

function Report:setPostprocessJS(js)

Parameters:

• js (string) - JavaScript code

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setPostprocessJS("console.log('Report loaded');")

Enable or disable silent mode. In silent mode, all visible output from the template is suppressed. Only the generated table is shown.

Signature:

function Report:setSilent(value)

Parameters:

• value (boolean) - Whether to enable silent mode (truthy/falsy)

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setSilent(true) -- Enable silent mode

Set content placed before the report. Not to be confused with setHeaderTemplate. This can be used to include some lead text before the report, templatestyles tags, etc.

Signature:

function Report:setHeadContent(value)

Returns:

• (Report) Returns self for method chaining

Usage examples:

report:setHeadContent('This appears before the report')

Generate the complete database report configuration. This is the main method that produces the output for use by the bot.

Signature:

function Report:generate()

Returns:

• (string) Complete database report template configuration

Usage examples:

return report:generate() -- Return the serialized representation of the report config

Raises:

• error if validation fails (e.g., missing SQL)