Help:Cargo

From Disney•Pixar CARS Wiki
Jump to navigation Jump to search
This article or section is under construction.
Some or all info on this page is unfinished or inaccurate; Please help contribute by improving and proofreading the article.

Cargo is a MediaWiki extension developed by Yaron Koren. It allows wiki page data to be stored inside customizable database tables, which other pages may then access and output its contents as part of their own text. This is essentially an abridged version of the official Cargo documentation, tailored toward the most relevant features and information for our wiki – that said, unless you want to utilize the query feature in your personal userspace content, this information won't be of much use. Particularly for the die-cast project, other templates help simplify the code aspects to make them more user-friendly. You should see the respective template page (e.g. {{series list}}) for documentation.

Overview

Cargo creates and utilizes new database tables; this wiki uses MySQL. You can view the list of existing Cargo tables here. Its main benefit is drastic versatility in data interaction, while not increasing (and in fact minimizing) the workload required to maintain. To a community as tight-knit as ours, this is invaluable.

Creation

Basic implementation of Cargo involves three key steps, each tied to their own parser function: declare, store, and query. The former two establish a table and govern what info it should collect and how, while the latter can access and display that data. Starting with declare, we first must create the actual database table. This must be on a template page, and within <noinclude/> tags.

Declaring

<noinclude>
{{#cargo_declare:_table=Table1
}}
</noinclude>

Here, Table1 is the name of the table we're making. Note the underscore (_) character; unlike the query function, this one and store both require it, or will return a syntax error.

Each parameter within the function will define the name of a column, along with how the input data should be handled. 

{{#cargo_declare:_table=Table1
|Column1=String
|Column2=Wikitext string
|Column3=Integer
}}
String Wikitext string
<div style="border:2px solid black;">[[File:Nitroade No 28 Aiken Axler personality pose.png|150px]]</div>

There are many possible settings, but the above three are most common. The major thing to know is that String will store the raw input (Integer behaves similarly, but only accepts numerical digits), while Wikitext follows parsing language. (See the table to the right for a visual comparison). Some tables occasionally use other configurations: for instance the Characters table (used on the list of characters) stores images in the File format, a requirement when using the gallery display format (covered later).

Storing

Using our example... This function instead must be wrapped in <includeonly/> tags, as this is what will be passing the page data into the table.

In template On page Table output 
{{#cargo_store:_table=Table 1
|Column1={{{okuni|}}} and {{{shigeko|}}}
|Column2=[[File:{{{tamiko|}}}|100px]]
}}

{{Wasabi
|okuni= Red
|shigeko= Blue
|tamiko= Tamiko Diecast.png
}}
Column1 Column2
Red and Blue

Not every declared column has to be used (although doing so will have been pointless), and if a column specified here was never declared, it simply won't do anything.

It is worth noting that while more than one template can store rows into the same table, they cannot store into the same row. If templates {{wasabi}} and {{same-o}} contain |Column1=Okuni |Column2=Shigeko and |Column1=Okuni |Column3=Tamiko respectively, you'll end up with:

Column1 Column2 Column3
Okuni Shigeko
Okuni Tamiko

Rather, combining row data instead must be done in the query phase, using the join on= parameter and setting one pair of identical columns (one in each table) to be equivalent. The simplest way to do this is by setting _pageName or _pageID, which are default columns universal across every Cargo table. See more about this in the query section.

Lastly, once both a declare and store statement are intact and the template is published, a staff member must then click "Create Data" (next to the Edit tabber button) to approve and "populate" the table. This process runs through every page (via job queue) in which the declaring template is transcluded. For that reason, if a template uses a store function but not the declare, it will not be automatically retrieved. An edit (null ones work) must manually be made for that data to store.

A table must be re-created whenever the column names or type declarations are changed. While edits to the template parameter specifications (input formatting) do not require a full reset, they also won't update automatically, meaning again the individual page must be edited. Unless you can (or are willing to) quickly update all the affected pages, you should just re-create the table. The caveat is that the active table will become read-only, meaning page edits will only update the replacement table, not the active one anymore. Once the table is fully re-populated, you can click the checkmark icon at Special:CargoTables to delete the old one and swap in the new.

Querying

Querying is the real fun of Cargo. {{#cargo_query:table=TableName}} An intuitive experience for the common user will require wrapping within a template, likely many. The more a parameter directly corresponds to its output effect, the better.

  • |fields= Use an equals sign to give each an alias. |named args=yes output requires template parameters to represent underscores in default column names as a space. If you wish to correct this, just set a field name to itself i.e. Model_Name=Model_Name - The alias becomes the parameter name.
  • |group by= to combine rows using the specified field. Set |group by=_pageID to get around duplication glitches. Use over _pageName for integer-only comparisons. If your page-by-page structure involves one page holding multiple items, a basic {{#vardefine:n| {{#expr:{{#var:n}} + 1}} }} calculated on each loop can pair with {{PAGEID}} magic word to create a replacement system. (Be sure to bridge them with a non-integer).
  • |join on= applies an outer left addon which must be considered in terms of data overlay. where conditions etc. run after combination
  • |where= Use simple equals checks wherever possible; avoid like to prevent full table scans. Consider choosing a global {{cargo null}} value (e.g. ZZZ to place in template {{{parameters|{{cargo null}}}}} to make not like work more reliably - issue of blank columns treated as defined; whitespace and/or field types potentially relevant. Set only to COUNT(*) for a row-based total number.
  • |order by=, |limit=, |offset= mostly self-explanatory

Consider boolean dichotomy or numeric assignments whenever possible - easier to remember and work with in conditional expressions

Anything requiring curly brackets will struggle to compute should a CONCAT() seek to inject a field value between the opening {{ and closing }} curly brackets, parser functions especially so due to complicated circumstances of escaping a {{number sign}}. Nest the desired function in a template and feed the value, escaping the curly bracket calls by way of {{!}} methodology.

Advanced

Cargo in conjunction with extensions like Loops and Variables is nothing short of cracked. By mastering MediaWiki's order of evaluation, your data becomes your own personal dictionary.

  • Use inside subst: to perform by-match swaps in AutoWikiBrowser. Feed the capture group(s) into a query and commandeer the output, which can be subjected even to further transformations using conditional expressions or custom parser functions a la Regex Functions
  • Make creative use of CONCAT() and variable wrappers to create fully dynamic numbered parameters. See {{makeSeriesColumn}} (of {{series list}}) for example.
  • Use <nowiki/> around table keys |, |- etc. in an output templates to easily obtain a (possibly exact) wikitext copy of a large table display.

PageImages - "merge similar cells" fix

Simultaneously using the PageImages extension involves a minor incompatibility, to do with the merge similar cells option.

By design, PageImages assigns a "score" to each individual image on any content-namespace page, and does so by printing comments – which are subsequently removed once they've done their job – into the HTML. Enter the problem: The comments gets inserted before Cargo's getHelperDataForMerging() hook runs, and aren't removed until after the cell contents have already been checked against one another. That means the score appended to every parsed file will prevent the contents from appearing the "same" as they typically would. (This will happen regardless if it's concatenated or queried through a wikitext-defined column).

The most painless workaround seems to be adding the following line in function getFormattedQueryResults() of /Cargo/includes/CargoQueryDisplayer.php. This will match each comment string within the query (leaving the rest of the page alone) at the relevant processing stage. 

	if ( array_key_exists( 'max display chars', $this->mDisplayParams ) && ( $fieldType == 'Text' || $fieldType == 'Wikitext' ) ) {
		$maxDisplayChars = $this->mDisplayParams['max display chars'];
		if ( strlen( $text ) > $maxDisplayChars && strlen( strip_tags( $text ) ) > $maxDisplayChars ) {
			$text = '<span class="cargoMinimizedText">' . $text . '</span>';
		}
	}
+
 
	$text = preg_replace( '/<!--MW-PAGEIMAGES-CANDIDATE-([0-9]+)-->/', '', $text );
Retrieved from "https://dpcarswiki.com/index.php?title=Help:Cargo&oldid=499730"