April 11, 2014

The Perforce MediaWiki Extension


If you've browsed through the Perforce Workshop (formerly known as the Public Depot) in the last six years, you've probably seen the Perforce MediaWiki extension in action, but even if you've edited one of those project pages odds are you haven't scratched the surface of what this handy little wiki plugin can do.  In today's blog post I'll be sharing a few of the interesting ways I've found to embed Perforce information into our wiki pages.

If you aren't familiar with MediaWiki (it's the software behind Wikipedia), it probably helps to understand up front that MediaWiki's page markup syntax is almost like a programming language.  Special pages called "templates" can be created that act as reusable functions; you can encapsulate a commonly-used piece of content into a template, and then invoke (or "transclude") the template on a bunch of different pages.  If the template definition is updated, all of the including pages update automatically.  Templates can also include parameters (like a function in a programming language) that modify their output.  There are also "parser functions" or "magic words" -- like templates, these can accept parameters and produce content dynamically, but instead of being created by users as special pages in the wiki they're built into the wiki software, either directly or via extensions.  Templates can invoke other templates and/or parser functions, so given the right building blocks and a little ingenuity it's possible to package a lot of very sophisticated dynamically generated content into a very simple wrapper.

The Perforce extension provides the building blocks in the form of parser functions that use the Perforce server as a data source.  For example, the {{#p4changes}} function provides a list of changelists as a block of easily styleable HTML, and we use that in the Workshop to produce this nice changelist summary on project pages:

Recent Changes display

The {{#p4diff2}} function can be used simply to display diffs, or it can used with the mathematical parser functions to generate LOC reports:

LOC bar chart

The {{#p4graph}} function translates Perforce file history into DOT, which can in turn be rendered as a Revision-Graph-like image.  As a developer I use this to generate tables of test cases that give me visual representations of each result, generated automatically from the test data itself:

Wiki rev graph

The {{#p4jobs}} function translates job queries into tables that can be sorted and styled (on subsets selected by smaller queries within the results, even):

Wiki jobs table

The {{#p4variants}} tag is one that we added specially for the Workshop, to make it easy for a project's curator to discover contributions in other branches that they haven't yet pulled in.  This list of changes is generated dynamically by queries against the integration history in the Perforce server:

Listing Perforce branches with wiki magic


For more ways you can embed Perforce information into your wiki, check out this list of Perforce-MediaWiki integrations in the Workshop.