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:
- Are in the main namespace, and
- Are detected to be Song pages (via template or category checks), and
- Pass a secondary Cargo row check (performed only when the link is clicked)
If any 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.
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 redirects you to the edit form in add-new-section-mode using a preload that contains the fully formatted output according to the "start of line" formatting.
Validation
Before inserting or redirecting, the gadget checks:
Mandatory Fields
- Video URL
- For new performances:
- Event
- Context
- Date (must begin with ISO)
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:
- Not a main-namespace page
- Title contains a colon
- Page does not include `
`
- Page is not categorized as a Song
Popup says the page has no Songs Cargo row
This means:
- Template:Song did not store Cargo data
- Or the page is missing required parameters
Check:
```
```
or the page’s hidden `
Filtering does not show expected contexts
Context selection uses the unsplit `contextstr` field, so ensure performances store a correct full string.
