View source for Module:Performances/doc

<noinclude>{{doc subpage}}[[Category:Module documentation]]</noinclude><includeonly>{{module page box}}</includeonly>

This module is supposed to provide access to the list of [[performances]] Angelina did. At the heart of it is a very generic, configurable table-generator, that could also be used in different contexts.

== Usage ==

=== Overview ===

<pre>
&#123;{#invoke: Performances | createTable       -- createTable is the generic table generator
  |page=Data:Performances.json              -- link to page with JSON data
  |supplements=Data:VideoMetaData.json;url  -- supplemental data sources
  |headers=Song,Date,Type,With,Video        -- List of titles used in the group section headers
  |keys=[[<song>]],{{d|<date>}},<type>,<with>,[<url> <song> - <event>] -- computed data items corresponding to those titles
  |sort=<date>                              -- computed sort keys for sorting outer table
  |sort1=<date>                             -- (optional): outer sortkey, same as inner if omitted
  |filters=date:2018,event:Kongsberg        -- filters to select what items are displayed
  |char_limit=7                             -- The amount of characters of the sort key considered for grouping the sections
  |char_limit1=4                            -- (optional): outer char limit, no outer grouping if ommited 
  |caption=Kongsberg 2018 by Month          -- Title displayed in Header of outer Table
  |group_sort=<date> ! <type> ! <pos>       -- how the group section sub-tables are sorted
  |id=1                                     -- Id needed if multiple tables are generated within a page
}}
</pre>

=== Options ===

'''page''': Provides page that contains JSON formated input data.

'''cargo_query''': Alternative way to access data via Cargo query ([[#Use of Cargo queries for input|see below]] for details)

'''supplements''' (optional): comma seperated list of supplemental JSON data source entries of "supplementalDataPage;keyName:charLimit;targetKeyName", with charLimit and targetKeyName being optional. Data from the supplemental source will be matched based on the keys (if the target's key name is ommitted, the same will be used). The charLimit option shortens the primary key value to this amount of characters. The target data can also be in a form, where the matching key data is used as keys itself instead of value of a "key" field.

'''headers''': Comma seperated list of titles used in the group section headers.

'''keys''': Comma seperated list of computed fields used for the colums in group sections defined by the corrosponding headers. Number of entries should match the number of headers.

Key names representing data are enclosed in "<",">" brackets. Each field can reference multiple keys. Other text will be still interpreted e.g. as templates. For the key's values, substitions can be defined by appending them with colons. A pair of strings will be interpretated as the search and replacement strings for a gsub() substition with lua pattern matching. The special keywords "toUpper", "toLower", and "toTitleCase" will perform the appropriate conversions, "limit:n" will limit the resresult to n characters. Several substitutions can be concatenated.

'''sort''': Computed sort fields for sorting outer table, and for labeling of section names. Same syntax as for keys.

'''group''' (optional): Definition of how to label section names differently from 'sort' definition.

'''char_limit''' (optional): The amount of characters of the sort key considered for grouping the sections. This will also affect the displayed section name if 'group' is not provided.

'''filters''': Comma seperated list of filters to select what items are displayed. A filter is described by "keyname:values". 
Alternatives within an filter value item can be described with "/". Negations can be described with "!( . )". 
 
'''sort1''' (optional): Outer sortkey. If ommited, the inner sort key will be used.

'''group1''' (optional): Definition of how to label outer section names differently from 'sort1' definition.

'''char_limit1''' (optional): The amount of characters of the sort key considered for the outer grouping. This will also affect the displayed section name, if 'group1' is ommited.

If ommited, no outer grouping will be performed.

'''id''': A unique Id for each table is needed if multiple tables are generated within a page, to provide a basis for unique section ids.

'''caption''' (optional): Title displayed in the header of the outer table

'''group_sort''': Computed field.  that determines how the group section sub-tables are sorted. Same syntax as for keys.

== Features ==

The generated table may have one or two levels of grouping, and up to three levels of sorting. It has the follwing structure, with the outer grouping being optional (click on the <span style="color:blue;">'''[n Items]'''</span> buttons to reveal the inner collapsed tables):

<div style="width: 55%">
{| class="wikitable" style="width: 100%; margin: 0;"
 |-
 ! colspan="4" style="text-align:left;" | Caption (provided as parameter)
 |-
 | style="text-align:center;" | <span id="1">1 (outer grouping level seperator)</span>
 |-
 | colspan="4" style="background-color:#f5f5f5; text-align:left;" | <span id="A">A (inner grouping level header) <span class="mw-customtoggle-8-1-1 mw-customtoggle" style="cursor:pointer; color:blue;" aria-expanded="true" tabindex="0">'''[2 Items]'''</span>
 |- class="mw-collapsible mw-made-collapsible mw-collapsed" id="mw-customcollapsible-8-1-1" style="display:none">
 | 
  {| class="wikitable" style="width: 100%; margin: 0;" 
   |-
   ! Inner Titel One !! Two !! ... !! N
   |-
   | Item 1 Value one || value two|| ... || value N
   |-
   | Item 2 value one || two|| ... || N
   |}
 |-
 | colspan="4" style="background-color:#f5f5f5; text-align:left;" | <span id="B">B (inner grouping level header) <span class="mw-customtoggle-8-1-2 mw-customtoggle" style="cursor:pointer; color:blue;" aria-expanded="true" tabindex="0">'''[1 Item]'''</span>
 |- class="mw-collapsible mw-made-collapsible mw-collapsed" id="mw-customcollapsible-8-1-2" style="display:none">
 | 
  {| class="wikitable" style="width: 100%; margin: 0;" 
   |-
   ! Inner Titel One !! Two !! ... !! N
   |-
   | Item 3 Value one || value two|| ... || value N
   |}
 |-
 | style="text-align:center;" | <span id="2">2 (outer grouping level seperator)</span>
 |-
 | colspan="4" style="background-color:#f5f5f5; text-align:left;" | <span id="C">C (inner grouping level header) <span class="mw-customtoggle-8-2-1 mw-customtoggle" style="cursor:pointer; color:blue;" aria-expanded="true" tabindex="0">'''[1 Item]'''</span>
 |- class="mw-collapsible mw-made-collapsible mw-collapsed" id="mw-customcollapsible-8-2-1" style="display:none">
 | 
  {| class="wikitable" style="width: 100%; margin: 0;" 
   |-
   ! Inner Titel One !! Two !! ... !! N
   |-
   | Item 4 Value one || value two|| ... || value N
   |}
|}
</div>

The inner tables are enclosed in 
<pre>
<div youtube-player-placeholder> ... </div> 
</pre>
tags, which can optionally be used by Javascript code contained in a Gadget ([[MediaWiki:Gadget-embeddedYouTubePlayer.js]]) to attach an embedded YouTube player to each section, that is loaded with a playlist of any YouTube video link contained in that section. Clicking on those links will then also load and start the linked video in that player.

Each grouping separator/header will set an anchor id, so that the table rows can be jumped at with internal references, e.g. [[#C|C]].

There is also code [[User:most2dot0/common.js|available]], that will expand the inner table of a jump target when jumped to.

== Use of Cargo queries for input ==

This was recently added as an alternative source for input. It supports:

* Multiple Cargo tables with configurable fields
* Nested child tables (1–3+ levels)
* List field splitting (# or ,)
* Optional pretty-printed JSON
* Flexible configuration in JSON or Lua-like syntax

The '''getJSON()''' function generates nested JSON structures from Cargo tables. It is meant to verify that queries produce the right structures before using them in the '''createTable()''' function.  

All table and field configuration is contained in a single parameter: '''cargo_query'''.

<syntaxhighlight lang="wikitext">
{{#invoke:CargoQueryTest|getJSON
 |cargo_query=<JSON or Lua-like table>
 |pretty=true
}}
</syntaxhighlight>

* '''cargo_query''' – required; configuration of tables, fields, nesting, and root table.  
* '''pretty''' – optional; if "true", outputs indented JSON (requires mw.text.JSON_PRETTY).  

=== cargo_query Parameters ===

{| class="wikitable"
! Parameter !! Type !! Description
|-
| tables || array of strings || List of Cargo table names (CamelCase). Order does not determine root.
|-
| fields || table || Map of tableName → comma-separated list of field names to return. Fields can be lowercase.
|-
| where || table || Map of tableName → Cargo WHERE clause for filtering rows. Empty string for no filter.
|-
| nest || array of tables || Each table describes a parent-child nesting rule: <nowiki>{ parent = "ParentTable", child = "ChildTable", parentKey = "ParentField", childKey = "ChildField", as = "ChildLabel" }</nowiki>
|-
| listFields || array of strings || Field names that should be returned as arrays (split on # or ,).
|-
| root || string || The Cargo table to use as the top-level JSON object.
|}

=== Field Splitting Rules ===

* '''#''' delimiter → splits Cargo lists into an array, preserves empty entries.  
  Example: "Concert##US Concert" → ["Concert","","US Concert"]  
* ''','' delimiter → splits only if there are no spaces around the comma.  

=== Example 1 — Two-level nesting (Performances → Videos) ===

<syntaxhighlight lang="wikitext">
{{#invoke:CargoQueryTest|getJSON
 |cargo_query={
   "tables": ["PerformancesDevel","VideosDevel"],
   "fields": {
     "PerformancesDevel": "song,event,context,date,type,pos,partners,comment,perfID",
     "VideosDevel": "perfID,url,duration,quality"
   },
   "where": {
     "PerformancesDevel": "",
     "VideosDevel": ""
   },
   "nest": [
     { "parent": "PerformancesDevel", "child": "VideosDevel", "parentKey": "perfID", "childKey": "perfID", "as": "videos" }
   ],
   "listFields": ["context","partners"],
   "root": "PerformancesDevel"
 }
 |pretty=true
}}
</syntaxhighlight>

==== Lua-like table style (sanitized) ====

<syntaxhighlight lang="wikitext">
{{#invoke:CargoQueryTest|getJSON
 |cargo_query={
   tables = ['PerformancesDevel','VideosDevel'],
   fields = {
     PerformancesDevel = 'song,event,context,date,type,pos,partners,comment,perfID',
     VideosDevel = 'perfID,url,duration,quality'
   },
   nest = {
     { parent = 'PerformancesDevel', child = 'VideosDevel', parentKey = 'perfID', childKey = 'perfID', as = 'videos' }
   },
   listFields = ['context','partners'],
   root = 'PerformancesDevel'
 }
 |pretty=true
}}
</syntaxhighlight>

=== Example 2 — Three-level nesting (Songs → Performances → Videos) ===

<syntaxhighlight lang="wikitext">
{{#invoke:CargoQueryTest|getJSON
 |cargo_query={
   tables = ['SongsDevel','PerformancesDevel','VideosDevel'],
   fields = {
     SongsDevel = 'songID,title,artist',
     PerformancesDevel = 'song,event,context,date,type,pos,partners,comment,perfID',
     VideosDevel = 'perfID,url,duration,quality'
   },
   nest = {
     { parent = 'SongsDevel', child = 'PerformancesDevel', parentKey = 'songID', childKey = 'song', as = 'performances' },
     { parent = 'PerformancesDevel', child = 'VideosDevel', parentKey = 'perfID', childKey = 'perfID', as = 'videos' }
   },
   listFields = ['context','partners'],
   root = 'SongsDevel'
 }
 |pretty=true
}}
</syntaxhighlight>

=== Tips ===

# Always specify '''root''' in cargo_query to avoid ambiguity.  
# Use '''listFields''' for any Cargo field that should become a Lua/JSON array.  
# '''pretty=true''' is optional but recommended for debugging and readability.  
# Lua-table style is allowed inline — single quotes ' are fine; the module sanitizes them into valid JSON.  
# Multi-level nesting must specify both '''parent''' and '''child''' explicitly in each rule.
# Use the [[AJW:Cargo_query_test]] page to develop your query and check if it delivers the expected JSON equivalent structure.

== ToDo ==

* Make sorting more flexible, e.g. by applying regex substitutions to data values before being sorted.
* Have an option, to not start collapsed (usefull for small tables)
* Implement access to sublists below keys.
* provide default values for empty fields of computed fields, e.g. like <keyName=defaultValue>
* Provide a means to print additional data behind the sort field that does not effect the id-anchor

== Examples ==


=== Multiple Filters, combined as AND ===

<pre>
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |headers=Song,Date,Type,With,Video
  |keys=[[<song>]],{{d|<date>}},<type>,<with>,[<url> <song> - <event>]
  |sort=<date>
  |filters=date:2018,event:Kongsberg
  |char_limit=7
  |caption=Kongsberg 2018 by Month
  |group_sort=<date> ! <type> ! <pos>
  |id=1
}}
</pre>

<div style="display:inline-block">
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |headers=Song,Date,Type,With,Video
  |keys=[[<song>]],{{d|<date>}},<type>,<with>,[<url> <song> - <event>]
  |sort=<date>
  |filters=date:2018,event:Kongsberg
  |char_limit=7
  |caption=Kongsberg 2018 by Month
  |group_sort=<date> ! <type> ! <pos>
  |id=1
}}
</div>

<!-- === Kongsberg by date (Year / Day) ===

<div style="display:inline-block">
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |headers=Song,Type,Pos,With,Comment,Video
  |keys=[[<song>]],<type>,<pos>,<with>,<comment>,[<url> <song> - <event>]
  |sort=<date>
  |char_limit1=4
  |filters=event:Kongsberg
  |caption=Kongsberg by Year/Day
  |group_sort=<event>!<date>!<type>!<pos>
  |id=2
}}
</div>
-->

=== Single Event with Supplemental Video Metadata ===

<pre>
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |supplements=Data:VideoMetaData.json;url:43
  |headers=Song,Date,Type,Video
  |keys=[[<song>]],{{d|<date>}},<type>,[<url> <url-title>; <url-User>]
  |sort=<event>
  |group_sort=<date> ! <type> ! <pos> ! <song>
  |filters=event:Bjerke
  |id=2
}}
</pre>

<div style="display:inline-block">
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |supplements=Data:VideoMetaData.json;url:43
  |headers=Song,Date,Type,Video
  |keys=[[<song>]],{{d|<date>}},<type>,[<url> <url-title>; <url-User>]
  |sort=<event>
  |group_sort=<date> ! <type> ! <pos> ! <song> 
  |filters=event:Bjerke
  |id=2
}}
</div>

=== Alternatives in Filters, combinded as OR ===

<pre>
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |headers=Song,Date,Type,Comment
  |keys=[[#<song>|<song>]],{{d|<date>}}: <pos>,<type> <duration> [<url> play],<comment>; <with>
  |sort=[[<event>]]
  |caption=Repetitive Live Events
  |group_sort=<date> ! <type> ! <pos> ! <song>
  |filters=event:Allsang på Grensen/TV 2's Artist Gala
  |id=3
}}
</pre>

<div style="display:inline-block">
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |headers=Song,Date,Type,Comment
  |keys=[[#<song>|<song>]],{{d|<date>}}: <pos>,<type> <duration> [<url> play],<comment>; <with>
  |sort=[[<event>]]
  |caption=Repetitive Live Events
  |group_sort=<date> ! <type> ! <pos> ! <song>
  |filters=event:Allsang på Grensen/TV 2's Artist Gala
  |id=3
}}
</div>

=== Demonstrating Different Outer Sorting/Grouping and Negation in Filters ===

In the following example, the highest level (sort1) is sorted by year, then the middle one (sort) by date, as well as the inner table one, which also features secondary sorting keys (type, pos, song). The seperator "!" that was chosen for these has no special meaning, but it is the lowest character encoding value above a space, which should ensure that the correct sorting is applied.

"duration:'''!('''fragment''')'''" is used for filtering for those videos, that are '''not''' fragments.

Also, wie use substitutions to the computed "url" field

<pre>
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |headers=Song,Date,Type,Comment,Video
  |keys=[[#<song>|<song>]],{{d|<date>}}; <pos>,<type> <duration>, <comment>; <with>,[<url> <url:.*www.: :.com.*: >]
  |sort=[[<event>]]
  |sort1=<date>
  |char_limit1=4
  |filters=type:live,duration:!(fragment)
  |caption=Live Events by Year, excluding fragments
  |group_sort=<date> ! <type> ! <pos> ! <song>
  |id=4
}}
</pre>

<div style="display:inline-block">
:<small class="noexcerpt">Jump to… [[#2013|2013]]&nbsp;– [[#2014|2014]]&nbsp;– [[#2015|2015]]&nbsp;– [[#2016|2016]]&nbsp;– [[#2017|2017]]&nbsp;– [[#2018|2018]]&nbsp;– [[#2019|2019]]&nbsp;– [[#2020|2020]]&nbsp;– [[#2021|2021]]&nbsp;– [[#2022|2022]]&nbsp;– [[#2023|2023]]&nbsp;– [[#2024|2024]]</small>
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |headers=Song,Date,Type,Comment,Video
  |keys=[[#<song>|<song>]],{{d|<date>}}; <pos>,<type> <duration>, <comment>; <with>,[<url> <url:.*www.: :.com.*: >]
  |sort=[[<event>]]
  |sort1=<date>
  |char_limit1=4
  |filters=type:live,duration:!(fragment)
  |caption=Live Events by Year, excluding fragments
  |group_sort=<date> ! <type> ! <pos> ! <song>
  |id=4
}}
:<small class="noexcerpt">Jump to… [[#2013|2013]]&nbsp;– [[#2014|2014]]&nbsp;– [[#2015|2015]]&nbsp;– [[#2016|2016]]&nbsp;– [[#2017|2017]]&nbsp;– [[#2018|2018]]&nbsp;– [[#2019|2019]]&nbsp;– [[#2020|2020]]&nbsp;– [[#2021|2021]]&nbsp;– [[#2022|2022]]&nbsp;– [[#2023|2023]]&nbsp;– [[#2024|2024]]</small>
</div>

=== Demonstrating Same Type Sorting, with Different Grouping Levels, and Supplemental Data ===

Here, the different char_limits on the sorting of song lead to two different grouping levels, by 1st character and by unique title.

<pre>
{{AtoZ}}
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |supplements=Data:Songs.json;song;title,Data:VideoMetaData.json;url:43  |headers=Event,Date,Type,Video,Pos,With,Comment
  |keys=[[#<event>|<event>]],{{d|<date>}},<type> <duration>,[<url> play <song-type>],<pos>,<with>,<comment>; <url-channelName>
  |sort=[[<song>]]
  |char_limit1=1
  |caption=Live Songs, excluding fragments
  |group_sort=<date> ! <type> ! <pos>
  |filters=duration:!(fragment),type:live
  |id=5
}}
{{AtoZ}}
</pre>
<div style="display:inline-block">
{{AtoZ}}
{{#invoke: Performances | createTable
  |page=Data:Performances.json
  |supplements=Data:Songs.json;song;title,Data:VideoMetaData.json;url:43  |headers=Event,Date,Type,Video,Pos,With,Comment
  |keys=[[#<event>|<event>]],{{d|<date>}},<type> <duration>,[<url> play <song-type>],<pos>,<with>,<comment>; <url-channelName>
  |sort=[[<song>]]
  |char_limit1=1
  |caption=Live Songs, excluding fragments
  |group_sort=<date> ! <type> ! <pos>
  |filters=duration:!(fragment),type:live
  |id=5
}}
{{AtoZ}}
</div>

<includeonly>{{end of module documentation}}[[Category:Modules]]
[[Category:Modules not ready for use]]
</includeonly>