Jump to content

Extension:Cargo/Other features

From mediawiki.org

"Purge cache" tab

[edit]

MediaWiki does extensive caching of its pages, for performance reasons. This can impact pages that display Cargo queries, in that data that has recently been added or changed will often not show up yet in other pages that query it. MediaWiki lets you purge the cache of any page by going to the URL "action=purge" for that page, after which you should see the correct, most recent data in any queries on that page. However, MediaWiki does not offer any convenient way to get to that URL. For that purpose, Cargo defines a tab/dropdown action, "Purge cache". It is viewable only to those users who have the "purge" permission, which normally is all users in the "sysop" group. (In truth, all users can purge a page's cache, though non-admins need to confirm by hitting "OK" before the purge happens; thus the "purge" permission might be better named "one-step purge".)

The "Purge cache" tab is equivalent to the "Refresh" tab from Semantic MediaWiki; in fact, if SMW is already installed, the "Purge cache" tab will not show up at all, since it is redundant.

Displaying maps

[edit]

Within templates that hold coordinates, it is usually not very helpful to simply display those coordinates; the vast majority of people will have no knowledge of where in the world a certain set of coordinates is. Rather, it is much preferable to display a map. For that, Cargo defines the parser function #cargo_display_map. It takes in coordinates, as well as a few optional parameters, and displays a map for that one point.

The parameters for #cargo_display_map are:

  • point= - takes in a set of coordinates (mandatory).
  • service= - the mapping service used; can be googlemaps (for Google Maps), leaflet (for Leaflet) or openlayers (for OpenLayers). OpenLayers is the default service.
  • zoom= - sets the zoom level. For both Google Maps and OpenLayers, the zoom level is an integer number between 1 and around 20, with higher numbers being more zoomed in. The default value for this parameter is 16 for both mapping services.
  • height= - sets the height of the map; the default value is 400px.
  • width= - sets the width of the map; the default value is 700px.
  • image= (for the leaflet service only) - sets an image to be the background for the map display, instead of a standard geographical map; specified image must be one that has been uploaded to the wiki.

If you are using Google Maps, you may need to get an API key for it to work - once you get an API key, you should set it in LocalSettings.php via the "$wgCargoGoogleMapsKey" variable.

The standard usage of #cargo_display_map is within a template, where point= takes in a template parameter. However, it can be used to display hardcoded maps as well.

Lua support

[edit]

You can call the functionality of #cargo_query, #cargo_declare and #cargo_store all from within Lua modules defined by the Scribunto extension, instead of via those parser functions.

To run a query equivalent to #cargo_query, place something like the following code in a module:

local p = {}
local cargo = mw.ext.cargo

function p.Main( frame )
    local tables = 'table1, table2, etc.'
    local fields = 'field1=alias1,field2=alias2, etc.'
    -- optional parameters are grouped in one table
    -- you can omit any or all of them, except join if you use more than one table
    local args = {
        where = 'table1.fieldE="some value", etc.',
        join = 'table1.fieldA = table2.fieldB,table2.fieldC=table3.fieldD, etc.',
        groupBy = 'table1.fieldG',
        having = 'table1.fieldG="some value", etc.',
        orderBy = 'table2.fieldF, table1.fieldE DESC, etc.',
        limit = some number,
        offset = some number,
    }
    local results = cargo.query( tables, fields, args )
    for r = 1, #results do
        local result = results[r]
        -- Do something with the result table, e.g. result.alias1
    end
end

return p

For an equivalent to #cargo_declare, call something like the following:

local p = {}
local cargo = mw.ext.cargo

function p.Main( frame )
    local table = 'Movies'
    local args = {
        'Year' = 'Date',
        'Genres' = 'List (,) of String',
        'Director' = 'Page'
    }
    local results = cargo.declare( table, args )
end

return p

For an equivalent to #cargo_store, call something like the following:

local p = {}
local cargo = mw.ext.cargo

function p.Main( frame )
    local table = 'Movies'
    local args = {
        'Year' = '1959',
        'Genres' = 'Western, Action',
        'Director' = 'Howard Hawks'
    }
    local results = cargo.store( table, args )
end

return p

Unfortunately, there is still not yet a Cargo-native method equivalent to #cargo_compound_query. If you want to call a compound query from Lua, your best option is to use the frame:callParserFunction method.

API

[edit]

Cargo defines a number of API actions, some for internal use (to be called via Ajax), and some for use by outside scripts:

  • cargoautocomplete - finds matches for a Cargo query plus a substring, for use within Special:Drilldown
  • cargofields - returns all the fields in a specified table
  • cargoformatparams - returns all the parameters for a specified format
  • cargoquery - calls the specified Cargo query, generally for use by JavaScript-based display formats
  • cargoqueryautocomplete - returns a list of table or field names matching a substing, for use within Special:CargoQuery
  • cargorecreatedata - recreates a specified Cargo table, for use from various pages
  • cargorecreatespecialtable - recreates a "special" Cargo table such as _pageData
  • cargorecreatetables - recreates all the tables associated with the specified template
  • cargotables - returns all the tables defined in the wiki