Extension:DebugTemplates
 Release status: beta |
|
|---|---|
| Implementation | Special page, API |
| Description | A special page to give a pseudo-debugging interface for interactive expansion of template nests |
| Author(s) | Clark Verbrugge (clumptalk) |
| Latest version | 0.6 |
| MediaWiki | 1.25.1+ |
| Database changes | No |
| License | Creative Commons Attribution Share Alike 3.0 |
| Download | |
| Quarterly downloads | 4 (Ranked 121st) |
| Translate the DebugTemplates extension if it is available at translatewiki.net | |
The DebugTemplates extension provides an interactive pseudo-debugging interface for better understanding and exploring the expansion of template nests.
Installation
edit- Download and move the extracted
DebugTemplatesfolder to yourextensions/directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/DebugTemplates - Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'DebugTemplates' );
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Usage
editAfter installation, there is a "DebugTemplates" option in the "Data and tools" section of the special pages list. The page this opens is divided into a few different areas:
Input area
editThe Input area is where you specify what you are debugging. The rest of the page is automatically updated once focus leaves this area (ie you click somewhere else, or tab out.)
- You can type or paste the raw wikitext you wish to debug into the large Input text area (or pre-initialize it to the contents of page "Foo" by loading "Special:DebugTemplates/Foo").
- The Page title field lets you specify a page title for the text you are debugging. This is used for context, such as in expanding {{PAGENAME}}.
- The URL field is informational only, showing you the URL used in making API calls during the interactive debugging. (This may be removed in future versions.)
- The Parameters list shows a list of template parameters found in the code in the Input text area. This list will have scrollbars if necessary. Each parameter is given 4 fields:
- The Set? column indicates whether that parameter is defined at all. When you first start all parameters are assumed unset; click on the icon to toggle it (or use the "Set/unset all' button to make all of them set). When a parameter is unset, its value is ignored.
- The Name column shows the name of that parameter. Note that for parameter names not fully represented in the wikitext this will will be a fake, constructed name.
- The Value column shows the value associated with that parameter. This is a full text area, so you can include newlines in the definition.
- The Eval all column gives a button for each parameter to force every instance of that parameter to be evaluated in the Debugging pane—see below.
Debugging pane
editThe Debugging pane has some interface elements at the top, a line for a "stack trace" of template invocations with a funny symbol at the start, and an output area showing the result of expansions of the input.
- The output area is where you will do most of your interaction once you enter the input wikitext. This area is a rendering of the parsed input text. You can hover over the start symbols of templates {{ or parameters {{{ to highlight the area and parts within and the ending symbol as well. The 3 radio buttons at the top of the Debugging pane define what happens when you click on something in this area:
- In evaluate mode (the default), clicking on the start of a template or parameter will evaluate it and replace it with the evaluated wikitext. Evaluated wikitext is shown in a monospace font to distinguish it, and can be toggled back-and-forth to its non-evaluated form by clicking on it for easy reference. This is meant to be analogous to code debuggers doing a 'step-over' action.
- In descend mode, clicking on the start of a parameter acts the same as in evaluate mode, but clicking on the start of a template causes that template's page to replace the text in Input text and become the new debugging input. This is meant to be analogous to code debuggers doing a 'step-into' action. Note:
- The template text will be stripped according to the use of <noinclude>, <includeonly>, and <onlyinclude> tags, the same as if it had been actually transcluded.
- The list of parameters will be rebuilt from the arguments that were passed into the template invocation, including their values, which will all be set (defined) by default. Any additional parameters found in the template code will be added to the list as unset parameters.
- A new, non-clickable stack element will be added to end of the stack trace line above the output area, making the prior entry clickable.
- In nothing mode, clicking on the starts of templates or parameters does nothing. This is just to make cut-and-paste easier.
- Each parameter's Eval button can be used to cause evaluation of each instance of that parameter.
- The stack trace area shows the history of templates you have descended into. All entries but the last one are clickable, and doing so erases the entire history below it and restores you to the state just before you descended below that entry.
- The buttons give you further control over evaluations done on within the output area:
- The Evaluate all button evaluates the entire text and replaces it with the final wikitext output.
- The Undo evaluation button undoes the last template or parameter or Evaluate all evaluation.
- The Undo all evaluations button undoes all evaluations you have done on this input text.
Error messages
edit- Between the Input area and the Debugging pane is an initially empty area where arguably useful error messages will appear. If any do appear, a little button on the right will also show up that you can use to make all the error messages go away.
Limitations
edit- As its experimental status indicates this is still a work in progress, and you may find bugs or find features and design changed in future versions.
- The Special page provided is little more than a raw shell for a JavaScript/Ajax interface that makes extensive use of the MediaWiki action API:
- It has been verified with a current version of Firefox, but there may be compatibility issues for other browsers.
- It adds a new API action that is used to support the interactive parsing, and so in your API help page you will find a new expandframe action. This is similar to the expandtemplates action, but with a simplified set of options and allowing for argument-value pairs to be explicitly provided.
- You cannot descend into templates that are not defined as wiki pages (such as magic words or parser functions that are built in or provided by extensions).
- Custom tag extensions will probably not parse properly in the output and thus not work.