Jump to content

Extension:Cargo/Browsing data

From mediawiki.org

Cargo provides a number of ways to generically view stored data; these are all publicly-available, but some are intended for regular users, some for administrators, and some for both.

Drill-down interface[edit]

The display of Special:Drilldown for one table, after one filter value has been selected, and a text search term has been entered.

The main mechanism that Cargo provides for browsing data is the page Special:Drilldown, which shows a listing of each table and its contents, and a set of filters for drilling down on that information. Its interface is similar to, and is based in part on, that of the extension Semantic Drilldown. The main difference is that, unlike with Semantic Drilldown, filters do not have to be defined; instead, Cargo sets the filters automatically, based on the types of the fields for each table. Fields of type String and Page, Integer, plus all the number and date types, get turned into filters, with the input type used dependent on the field type; while fields of type Text, File, Coordinates, URL, Email, Wikitext and Searchtext are not. (Any fields marked as "hidden" similarly will not be shown as filters.)

The following settings can be applied for Special:Drilldown, in LocalSettings.php:

  • $wgCargoDrilldownUseTabs - display set of table names as tabs at the top instead of a vertical list on the side (default is true)
  • $wgCargoDrilldownSmallestFontSize - if set to a positive number, sets the smallest font size, in pixels, for a tag-cloud-style display of filter values (default is -1)
  • $wgCargoDrilldownLargestFontSize - if set to a positive number, sets the largest font size, in pixels, for a tag-cloud-style display of filter values (default is -1)
  • $wgCargoDrilldownMinValuesForComboBox - sets the minimum number of values before values are displayed in a combo box instead of as individual links (default is 40)
  • $wgCargoDrilldownNumRangesForNumbers - for fields/filters of type "Integer" or "Float", specifies the number of "buckets" into which values are divided (default is 5)
  • $wgCargoMaxVisibleHierarchyDrilldownValues - if set to a positive integer, specifies the maximum number of values that can be shown at a time for any "hierarchy" field. (All the top-level values are always shown irrespective of the value of this variable.) The values are hidden beyond a certain depth of the hierarchy such that the count of total visible values is at most this number (default is 30).


Depending on the set of fields in the table, Special:Drilldown may automatically display tabs for viewing the results in formats other than the default display:

  • Timeline format, if any field in the table is of type Date or Datetime.
  • Calendar format, if any field in the table is of type Date or Datetime, and the data is not too "sparse" (i.e., on average, there are 4 or more events per month).
  • Map format, if any field in the table is of type Coordinates.
  • Gallery format, if any field in the table is of type File.

However, you can also customize the display of tabs, by adding a _drilldownTabs parameter to the #cargo_declare call; see here. This parameter gives you complete freedom to customize your tabs: you can specify any number of tabs, and for each tab specify which format will be used, and which field(s) will be displayed in the results.

Full-text search[edit]

You can see in the example image that, in addition to the data filters, there is also a text search input at the top, which can be used in conjunction with the filters. This search input shows up if either of the following are true:

  • Storage of page text is enabled; see Storing page data.
  • The table being browsed has one or more fields of type "File", and storage of file text is enabled; see Storing file data.

If both are true, then the text search will search on the contents of both pages and files, and will display both.

Query form[edit]

The Special:CargoQuery page. You can see here an example of autocompletion (in the "Fields" input), as well as additional query parameters that are displayed because the user specified the query format (in this case, "dynamic table")

If you go to the page Special:CargoQuery, you can see a form that that lets you create and run queries (with the same structure as #cargo_query) by filling out the form inputs. These inputs provide help like autocompletion and validation in order to make the task easier.

Viewing tables[edit]

The page Special:CargoTables shows a listing of all tables in the wiki, and some helpful links for each one. The page does double duty: for users and administrators, it's a convenient way of seeing the overall layout of the data; while for administrators, it's also a sort of dashboard for maintaining all the tables. For users, Special:CargoTables has, for each Cargo table, a link to the table itself, as well as a "drilldown" link for it. For administrators, each table also gets "recreate" and "delete" links, making it easier to manage all the data from a single location.

The main link for each table goes to the page "Special:CargoTables/tableName". Going to such a subpage will show a table displaying the full contents (again, except for "hidden" fields), as well as a listing of all the fields and their types.

This page has one global setting: $wgCargoTablesPrioritizeReplacements, which, if set to true in LocalSettings.php, will first display all tables that have a replacement table for them, at the top, instead of simply listing all tables in alphabetical order.

Table diagram[edit]

You can view an entire database-schema-style diagram of all the Cargo tables, by going to Special:CargoTableDiagram. This diagram will show the connections between tables, for any tables whose #cargo_declare call contains a "_parentTables" parameter.

Values for a single page[edit]

Cargo provides a new MediaWiki action, "action=pagevalues", that shows the set of table rows defined for any specific page. This action is accessible from the "Page values" link at the bottom of the sidebar. The "page values" display can show rows from multiple tables, if more than one type of Cargo-based template is called on a page.