Nov 222011

One problem we’ve had for some time now is that due to a quirk in how the MindTouch software MDN is currently using for its wiki, when a user that isn’t logged in clicks a link to a page that doesn’t exist, they’re rather unhelpfully rerouted to the MDN home page. This is obviously suboptimal, but we’ve never had a solution.

Late last week, I was listening to my daughter read a book to me when a possible (partial) solution popped into my head (why at that time remains a mystery for the ages).

The Solution

On Friday, I spent some time coding up a few tests, which worked even better than I expected, and yesterday and today I’ve been putting my idea in action. I thought I’d share my solution, since it needs to be applied specifically when links are generated by templates. This doesn’t cover all cases, but does cover a lot of them (probably even most of them).

Those of you familiar with how we do things on the documentation wiki are probably aware of the templates such as Template:Interface, which generates a link to the appropriate page in the interface reference given the name of an interface. It intelligently looks for the interface given the old and new hierarchies of interfaces in our docs (since some older docs haven’t been moved yet), and builds the link on the fly, as well as applying appropriate styling to the text.

This is well and good unless the interface’s documentation hasn’t been written yet, in which case you get a link to a page that doesn’t exist, resulting in the problem I mentioned above.

My solution, which works for any automatically-generated links generated by templates updated to support this new mechanism, involves an intermediate template that can be used when pages don’t exist, as well as a page that actually does the rendering of a special new “article not found” page, which looks something like this:

Screenshot of the article not found page

This is what appears at present for a link generated by {{interface(“nsIJumpListShortcut”)}}. This offers some particularly handy features. First, it explains that the page doesn’t exist. Second, it prompts the user that if they’d like to log in, they can create the new page. Clicking the “Log in” link will provide a log in screen, which, when filled out, then immediately takes the user into the editor for the target page.

Third, it offers a link to search MXR (it says LXR but it’s really MXR) for the ID “nsIJumpListShortcut”. This search is performed on mozilla-central.

Fourth, although not seen here, the new system lets templates specify the URL of a specific file on mozilla-central; if specified, that URL is offered as another option.

The log in and create the page option is always provided; the other options are provided if the relevant information is passed to the new Template:NotFound template.

Using the Not Found System

Using the new “not found” system actually doesn’t directly involve using the NotFound template; instead, upon detecting that a page doesn’t exist, you create a link to the Article not found page, with query terms providing the parameters needed. The “Article not found” page converts the query terms into a call to the NotFound template for you, thereby providing a standardized interface to the code. There are three query terms you can provide:

  1. “uri”: The local URI of the page the user tried to visit; this should be /language/path/to/article, with spaces replaced with underscores.
  2. “ident”: The identifier on MXR to offer to search for; if you don’t provide one, no MXR search is offered.
  3. “source”: The sub-path on mozilla-central of a file to offer a link to; for example, this might be “xpfe/appshell/public/nsIAppShellService.idl”. If you don’t provide this, no file link is offered.

In general, you won’t use this directly. Instead, templates should be updated to use it whenever possible. I’ve already updated the following templates to use the new not found system:

  • interface
  • ifmethod
  • HTMLElement
  • XULElem
  • XULAttr
  • XULProp
  • XULMeth
  • XULMeth2
  • MathMLElement
  • SVGElement
  • cssxref
  • domxref

I’m certain there are other templates that would benefit from being updated, but this is a good start. While I was at it, I tidied up a few bugs in some of those templates, mostly related to case-sensitivity problems. I hope this is as helpful as I think it will be! If you want to help update any existing templates, don’t hesitate to ask if you run into problems.

 Posted by at 3:44 PM

  3 Responses to “Helping people when content isn’t there”

  1. I just tried the link in my name, a bookmark from long ago, and it still redirects to the MDN homepage. The new version is the same URL with a / instead of a :

  2. Mardeg: That’s expected. If you read my post, you’ll see that only links created by specific templates are affected by this change.

  3. Cool! Hopefully that will help some users. I don’t think we can catch them all unless we’re willing to make our own patch for MindTouch (again).