MediaWiki:Gadget-CargoHelper - User Handbook
A helper tool for adding Performance and Video entries to Cargo tables.
Overview
The CargoHelper gadget provides an easy interface for adding new Performance and Video template calls to song pages. It helps users create consistent Cargo entries and reduces manual template editing.
The gadget appears as an "Add video" link in the page’s Page tools, but only on pages that
- can be edited by the user,
- are in the main namespace, and
- are detected to be Song pages (via template or category checks).
It will only continue if a secondary Cargo row check is passed (which is performed only when the link is clicked). If the check fails, the gadget shows a helpful popup instead of running.
How to Use
Opening the Gadget
Click Add video in the page tools.
If the page is missing a Songs Cargo entry, a popup explains the issue instead of opening the dialog.
Note that you can do this both on the normal "read" version of the page, as well in its "edit" dialog. For the latter to work, you have to edit the whole article, not just a section.
Using the "edit" page is the recommended way, as it gives you the best control over the result, and you can check the effect before the final changes get submitted to the wiki.
The Dialog Window
The gadget opens an OOUI dialog with two modes:
Use existing performance
Choose this if:
- The performance already exists in the Cargo 'Performances' table
- You only want to add a new video to it
The dialog will show:
- A dropdown of existing performances for the page
- All performance fields greyed out, showing the stored data
- Editable fields for the new video
Create new performance
Choose this if:
- You want to create a brand-new performance and add a video for it
The dialog will:
- Disable the existing-performance dropdown
- Clear and enable performance fields
- Require:
- Event
- Date (must begin with ISO format: 'YYYY', 'YYYY-MM', or 'YYYY-MM-DD')
- Context
- Video URL
Validation is performed before submission.
Context Selection
The Context field uses an auto-filtering combobox:
- Type any text → the list filters dynamically
- Filtering is case-insensitive
- Context strings come from the 'contextstr' Cargo field (whole strings, not split)
URL, Duration, Quality
The Video section asks for:
- URL
- Duration
- Options: full, short, fragment
- Quality
- Options: best, good, acceptable, poor
- Comment (optional)
Inserting the Result
When pressing Insert, the gadget does one of two things depending on context:
If you are on an edit page (wikitext editor open)
The gadget inserts the templates directly at the cursor position.
Insertion rules:
If the cursor is at the start of a line
- New performance → inserted as:
'''
* {{Performance|...}}
*: {{Video|...}}
'''
- Existing performance → only video inserted:
'''
{{Video|...}}
'''
If the cursor is not at the start of a line
- Templates are inserted inline, with no bullets and no extra line breaks
This allows:
- Adding entries to lists
- Inserting inline for custom formatting
If you are on a view page
The gadget will open a new dialog, where you can choose to add the entry either at the end of a specific page, or with a newly created sections at its end. You can edit the preloaded section title for the latter case.
Note that you likely need to "purge" or at least reload the page to see the result.
Validation
Before inserting or redirecting, the gadget checks:
Mandatory Fields
- Video URL
- For new performances:
- Event
- Context
- Date (must begin with ISO date, additonal text can be appended after a space)
Date Validation
Valid forms include:
- '2023'
- '2023-09'
- '2023-09-14'
- '2023-09 extra info'
Invalid examples:
- '2019xx'
- '2023-99-99'
- 'today'
Invalid fields are highlighted, and a popup lists all problems.
Existing Performance Mode
When selecting an existing performance:
- All performance fields become read-only
- Their values reflect the stored Cargo data
- Only video-related fields remain editable
- The local performance ID (after the last '_') is used automatically
Notes and Limitations
- Only one video is inserted at a time
- The gadget does not modify or update existing Cargo entries
- Performance IDs are auto-generated based on page name and existing IDs
- The gadget does not handle VisualEditor mode
- Cargo database connection or template mistakes may prevent detection
Troubleshooting
“Add video” does not appear
Possible reasons:
- No edit rights, e.g. because not logged in
- Not a main-namespace page
- Title contains a colon
- Page does not include '
{{Infobox song}}' - Page is not categorized as a Song
Popup says the page has no Songs Cargo row
This means:
{{Infobox song}}did not store Cargo data- Or the page is missing required parameters
Check (usually at the top of the page):
'''
{{Infobox song}}
'''
