Editing Module:Tabular data/doc

{{Module rating|beta}}
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->

This module provides basic functions for interacting with [[mw:Help:Tabular Data|tabular data]] on Wikimedia Commons.

== <code>cell</code> ==
Returns the value of the cell at the given row index and column name.

Usage: {{mlx|{{BASEPAGENAME}}|''cell''|''Page name.tab''|output_row{{=}}''Index of row to output''|output_column{{=}}''Name of column to output''}}

A row index of <code>1</code> refers to the first row in the table. A row index of <code>-1</code> refers to the last row in the table. It is an error to specify a row index of <code>0</code>.

=== Examples ===

Latest death toll in [[c:Data:COVID-19 cases in Santa Clara County, California.tab]] (regardless of when the table was last updated):

{{#invoke:Demo|module|demo_module={{BASEPAGENAME}}|demo_module_func=cell|COVID-19 cases in Santa Clara County, California.tab|output_row=-1|output_column=deaths}}

== <code>lookup</code> ==
Returns the value of the cell(s) in one or more output columns of the row matching the search key and column.

This function is reminiscent of <code>LOOKUP()</code> macros in popular spreadsheet applications, except that the search key must match exactly. (On the other hand, this means the table does not need to be sorted.)

Usage: {{mlx|{{BASEPAGENAME}}|''lookup''|''Page name.tab''|search_value{{=}}''Value to find in column''|search_column{{=}}''Name of column to search in''|output_column{{=}}''Name of column to output''|output_column2{{=}}''Name of another column to output''|output_column''n''{{=}}…|output_format{{=}}''[[mw:Extension:Scribunto/Lua reference manual#string.format|String format]] to format the output''}}

If multiple columns are output without an explicit string format, this function formats the output as a human-readable list.

Some may find {{tl|Tabular query}} (which uses this module) an intuitive way to obtain cell data as it resembles a simple [[SQL]] query.

=== Parameters ===
; {{para|1}} : Page name on Commons with extension but no namespace
; {{para|search_value}} or {{para|search_pattern}} : Value to find or [[mw:Extension:Scribunto/Lua reference manual#Patterns|pattern to match]] in column
; {{para|search_column}} : Name of column to search in
; {{para|occurrence}} : Index of the match to output in case of multiple matching rows. A row index of <code>1</code> refers to the first matching row. A row index of <code>-1</code> refers to the last matching row. It is an error to specify a row index of <code>0</code>.
; {{para|output_column}} or {{para|output_column1}}, {{para|output_column2}}, ... : Names of columns to output
; {{para|output_format}} : [[mw:Extension:Scribunto/Lua reference manual#string.format|String format]] to format the output

=== Examples ===

Total confirmed case count in [[c:Data:COVID-19 cases in Santa Clara County, California.tab]] on the day that the county issued a [[stay-at-home order]]:

{{#invoke:Demo|module|demo_module={{BASEPAGENAME}}|demo_module_func=lookup|COVID-19 cases in Santa Clara County, California.tab|search_value=2020-03-16|search_column=date|output_column=cases}}

The last day that a hundred or more patients with COVID-19 were in the hospital in [[c:Data:COVID-19 cases in Solano County, California.tab]]:

{{#invoke:Demo|module|demo_module={{BASEPAGENAME}}|demo_module_func=lookup|COVID-19 cases in Solano County, California.tab|search_pattern=%d%d%d|search_column=hospitalized|occurrence=-1|output_column=date}}

Total number of administrators on all Wikimedia wikis using [[c:Data:Wikipedia statistics/data.tab]]:

{{#invoke:Demo|module|demo_module={{BASEPAGENAME}}|demo_module_func=lookup|Wikipedia statistics/data.tab|search_value=total.all|search_column=site|output_column=admins}}

Number of administrators and users on all Wikimedia wikis using [[c:Data:Wikipedia statistics/data.tab]]:

{{#invoke:Demo|module|demo_module={{BASEPAGENAME}}|demo_module_func=lookup|Wikipedia statistics/data.tab|search_value=total.all|search_column=site|output_column=admins|output_column2=users|output_format=%d out of %d users are administrators}}

''Note: Wikipedia statistics are shown as an illustration only. In practice, there is a high-performance module {{tlx|NUMBEROF}} to access Wikipedia statistics.''

== <code>wikitable</code> ==
{{Tracked|T252307}}

Returns the entire data table as a (rather plain) table.

Usage: {{mlx|{{BASEPAGENAME}}|''wikitable''|''Page name.tab''}}

=== Examples ===

{{Collapse top|COVID-19 statistics in Santa Clara County, California}}
{{#invoke:Demo|module|demo_module={{BASEPAGENAME}}|demo_module_func=wikitable|COVID-19 cases in Santa Clara County, California.tab}}
{{Collapse bottom}}

=== Implementation notes ===

The implementation of this function incorporates {{tl|n/a}} (to represent null values), {{tl|yes}} (true), and {{tl|no}} (false). The templates themselves cannot be reused because they are incompatible with the [[mw:Extension:Scribunto/Lua reference manual#HTML library|<code>mw.html</code>]] library, which builds the table using an HTML DOM instead of pure wikitext.

== Internationalization ==
You can most likely port this template to a wiki in another language without making major modifications. The <code>wikitable</code> function automatically localizes the table's description, column titles, and license name into the wiki's content language. It also formats numbers according to the content language. However, you should localize the cells representing <code>true</code>, <code>false</code>, and <code>null</code> by changing the values in the <code>messages</code>, <code>bgColors</code>, and <code>colors</code> variables to match the wiki's own {{tl|yes}}, {{tl|no}}, and {{tl|n/a}} templates, respectively.

== See also ==
* {{tl|NUMBEROF}}
* {{T|Last tab}} and {{T|Date tab}}
* [[:sv:Template:Json2table]] – shows a complete table (based on [[:sv:Module:Json2table]], in turn based on [[Wikipedia:Templates for discussion/Log/2020 June 22#Template:Json2table|a deleted module]])
* [[Template:Wdtable row]] – fetches a table row from Wikidata in realtime
* [[Template:Wikidata list]] – uses a bot to periodically fetch a complete table from Wikidata

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Modules using tabular data]]
}}</includeonly>