Module talk:Cycling race/doc

Please don´t translate this documentation.

The aim of this documentation is to make it more easy for those who want to understand the code. Feel free to improve the documentation and if you change the code in a major way, please, document your changes here, so that this doc is up to date.

The module 'Cycling race'

• Last text update:

This module has four main functions, which could be called from Wikipedia: p.listofwinners(frame), p.listofstages(frame), p.infobox(frame) and p.teamroster(frame).

The module 'Cycling race/lang'

• Last text update:

Main functions

functions p.listofwinners and p.listofstages

• Last text update:
• uses functions:

Both functions are similar, but listofstages was developed first and was therefore coded in a different way. The functions perform four tasks: 1) Read the data from Wikidata, but don´t await to get the data. 2) Transform the data (e.g. just use the year from the time data), search for other data if the data you want is not available. For example: Since there is no Wikipedia article in this Wiki, look for the label and if there is no label in this language take a label in another language. 3) Build the table, add in the data and show the table in the Wikipedia article. 4) Add in special code for each Wiki.

A major difference between both functions is that listofstages uses variables like sitelinks1 (Wikilink to Wikipedia article about the starting place) and number2 (Link to Wikidata item of the overall leader at the end of the stage), while listofwinners uses a complex lua table (t) and Lua functions like table.insert to insert data into the table.

For example, this row of code inserts the overall leader of a race into the table.

table.insert(t.vainqueur, winner(t, 20882667))

function p.infobox

• Last text update:
• uses functions:

This is the main function for showing an infobox. The module starts with a big block of Lua tables for storing Wikidata data.

The code follows that reads data from Wikidata and put a qnumber into the tables t, tt, ttt, tttt and ref (declaration is at the top of this function). The difference between t and tt is, that t is only for qnumbers, while in tt data like file data, numbers and text is stored. ttt is for an array in tables and tttt for some data that comes from the local Wiki, not the Wikidata database.

This function can get data not only from Wikidata database, but as an alternative from the local Wikipedia article too. This way it is possible to override some Wikidata information in the "Généralités" section of the infobox in the Wikipedia article, while data in "Résultats" is added to the data from Wikidata. There are some data you can´t change locally, for example "Course" or the name of the race. It is even possible to insert two new informations into the infobox (Special 1 and Special 2), which you don´t find in Wikidata. To address the data in the infobox use the words on the left side of the infobox like "Lieu de départ" in frWiki or in function infobox_translate in the module. That means, that each wiki tells the function in the own language to add info into the infobox. There is the option that someday the translations move from this module to the local wikis into the templates (similar to Special 1 and 2).

The part where you see something like if winner == "Q20882667" then t.first = qnumber end is a bit different, because of this code: then note = 'f' else note = 'q' end. The point is that the qnumber (id) is not added a "Q" (items are written like Q...) but a "q" or a "f", to inform the next code block to process those special qnumbers different. "f" is used to switch off the wikidata icon in fr:WP, that is a wikilink to the item in Wikidata. "q" is used to tell the code, that flags should be shown to indicate the nationality of the winners plus the wikilink to Wikidata. After some small adaptions in the next code block, the code block that follows creates the infobox in your Wikipedia. There are some adaptions, for example, to show "country" and not "countries" (translation in function infobox_translate) at the left side of the infobox, if there is only one country.

function p.teamroster

• Last text update:
• uses functions:

This function shows the team members of a cycling team for a certain year.

function p.stageinfobox

• Last text update:
• uses functions:

function p.listofteams

• Last text update:
• uses functions:

classification functions

• Last text update:
• uses functions:

Help Functions

functions foo

• Last text update:
• uses functions: -
• used by functions:

There are several foo functions, for example: foo1, foo2, 'foo3 and fooA. All those functions are about error handling (Error Handling and Exceptions in Programming in Lua at lua.org ). To call those functions somewhere else there is a pcall function (protected call) with several parameters and the first parameter is one of those foo functions.

if pcall(foo2, tt[2], "P585", 1) then .. end

Each foo-functions tests one row of code. For example foo1 tests entity = mw.wikibase.getEntity( arg ) This code is a Lua Scribunto interface to access data from the Wikidata database. There are more such functions, see Extension:Wikibase Client/Lua at Mediawiki. foo2 and foo3 don´t use an interface to access the database, they go direct to the database (for example, to read a time data of a qualifier (foo3)). You can look into Wikidata database with Special:ApiSandbox (action: wbgetclaims) to understand how to read the value of a property out of Wikidata database. The parameter "property" of the foo-functions is a string that gets the property (e.g. "P585"), the parameter "quali" the qualifier and the parameter "entity_var" the entity. The parameters var1 and var2 are used to test if a property has more than one value, more than one qualifier or more then on references. fooA is the latest foo function, that differs in the way, that it returns the data it gets from the Wikidata database if available. Parameter a has the value true or false, depending on the availability of the data. Parameter b is the returned data, if parameter a has the value true, and the value of parameter c is the rank (Help:Ranking).

a, b, c = pcall(fooA, 'amount', entity, 'P2052', 1)
if a == true and t.speed == "" then t.speed = b end

Why is such a test necessary? If the module tries to access data from the Wikidata database, but there is no such data in Wikidata, an error would happen and without error handling the module would stop showing anything in Wikipedia.

There is an alternative to the foo-functions, you can call pcall with an anonymous function. This is done in the old function listofstages. You can see the disadvantage: There is more code to write and read.

function getSquadTableColumn

• Last text update:
• uses functions:
• used by functions:

function WPlink

• Last text update:
• uses functions:
• used by functions:

This is a function that gets the Qnumber of an item and returns the Wikipedia Link (if available) of that item, or the label in the language of your Wiki (if available), or a fallback label (in French, if available) or the text "(label missing)" if there is no information at all. This function has an optional second parameter (see the three dots: function WPlink(Qnumber, ...) ). This optional parameter (a boolean parameter with the value true) is used to tell the function that it is a Qnumber of a cycling team, not of a rider. In this case the function can´t just give back the Wikilink, instead, the function has to add a label to the Wikilink: [[Sitelink|Label]].

function winner

• Last text update:
• uses functions:
• used by functions:

This function looks for the first three overall winners of the general classification. It is possible that there are more then one winner, because one could be disqualified. It is assumed that in this case the former winner gets the rank "Deprecated rank" and the current winner is added. Help:Ranking says: The deprecated rank is used for statements that are known to include errors or that represent outdated knowledge. Information with this rank is not seen by the code, therefore no code was written for that case.

function getNationalityOnDate

• Last text update:
• uses functions:
• used by functions:

This function is used to find the nationality to show the right flag for persons with more than one nationality during lifetime. That means, the values of property "P27" (country of citizenship) should have qualifiers. There are two examples: Q15966059 and Q445037. The first item has three qualifiers, while the second has none. This shows once again, that we can´t be sure that the information in Wikidata is complete (and correct, by the way). This function is rather clever, it consist of a generic for loop and uses a relational operator to compare two strings: "+1985-05-20T00:00:00Z" <= "+1999-05-20T00:00:00Z" to calculate the nationality at a certain time. Lua compares strings in alphabetical order, which follows the locale set for Lua. says lua.org. This way, the mathematics is part of the way the time string is build.

function timeStartEnd

• Last text update:
• uses functions:
• used by functions:

This function is used to find the Wikidata information that has the matching qualifiers (start time and end time). If the data data is just the year - no month and day data - this functions transforms the "wrong" Wikidata data into the "right" data. The start time will be 01 January, if there is no month and day, and the end time will be 31 December, if both, month and day, are zero or one.

function func_date

• Last text update:
• uses functions:
• used by functions:

This function is the central place for translating the time data from Wikidata using the Mediawiki function lang:formatDate(). More information about that function is here available.

function references

• Last text update:
• uses functions:
• used by functions:

function property

• Last text update:
• uses functions:
• used by functions:

This function is used in function infobox. You can tell the infobox in edit mode to overwrite Wikidata information. For example, to show a picture different then the one stored in the Wikidata item write in the article in your local Wikipedia (example for fr:WP):

{{#invoke:Cycling race|infobox|1=Q18574623


| image = 20150705 Tour onder de Dom-30.jpg

| légende = Passage sous la tour de la [[cathédrale Saint-Martin d'Utrecht]].

}}

"image" and "légende" are words described in this function. The translations "picture" and "caption" do the same in en:WP and in your Wikipedia, as long as you don´t add a translation in your language. If you have wikicode for an infobox template that you intend to continue using, just adapt this function to your wikicode. Hint: It is possible that not all infobox rows could be overwritten this way. For example "country" might have a problem, because the value could be a list of countries and it is unclear if the code can handle that at the moment.

function func_prologue

• Last text update:
• uses functions:
• used by functions:

This function enables the translation for the rows that shows the prologue (en:Glossary of cycling#prologue) in the function listofstages. If this module is used in a Wikipedia that has no translation, the french translation is chosen.

function stageLink

• Last text update:
• uses functions:
• used by functions:

This function enables the translation for the column that shows the stage in the function listofstages. If this module is used in a Wikipedia that has no translation, the french translation is chosen.

function func_month

• Last text update:
• uses functions:
• used by functions:

This function enables the translation for the column that shows the date in the function listofstages. If this module is used in a Wikipedia that has no translations, the french translations are chosen.

function typeofstage

• Last text update:
• uses functions:
• used by functions:

This function returns the wikicode of a picture. The tooltip (which is shown if the user hovers the pointer over the picture, without clicking it) is language dependent. The parameter x is a string that tells the function which picture to choose. If x is "time trial stage" there are three possible tooltips for the three possible time trial stages. If this module is used in a Wikipedia that has no translations, the french tooltips are chosen.

function flag

• Last text update:
• uses functions:
• used by functions: all main functions
• Stable code update: Special:Permalink/411921504 (27 Nov 2016), ...
• Todo:

The parameter date is a string that gets the value of a time datatype, for example +2013-01-01T00:00:00Z. This information is used to show an old flag instead of the current flag.

The function consists of three parts: The first part is a table of Wikimedia Commons files for often used flags. If a certain flag is not in this table the module will take the information which flag to use from Wikidata. There are two possibilities for this: The item of that country and the item of the flag of that country. The second solution is used in the second code block and the first solution in the third code block. The difference is that the item of the country is a very large file and it has information about older flags, while the other item is small and has no further information.

This function has a cache to store each flag data, therefore for each table the flag data is read only once from Wikidata.

Translation functions

function infobox_translate

• Last text update:

This function is used in function infobox. This are the words you will see in the infobox on the left side and at the bottom of the infobox. If you have not translated them you will see the English words in your local version.

At the bottom of the infobox you see a wikilink to the documentation.

[[d:Module:Cycling race/doc|Documentation of the module]]

If you have moved the documentation to your own Wikipedia, change the wikilink, otherwise it is enough to translate the right part of that wikilink.

function headoftable

• Last text update:

There are some headoftable functions: headoftable(x), headoftableII(x), headoftableIII(x) and headoftableIV(x). They enable the translations for the header rows. If this module is used in a Wikipedia that has no translations, the french header rows are chosen.