The Problem
Phriction and Remarkup throughout Phabricator offers very good integration with bundled programs. You can shortcut links to differentials, task tickets, changesets and more. The linking to external resources is not as powerful or as feature rich as you are often limited to basic static external links.
This may in part be by design. Rich internal integration and lesser external encourages the centralised use of the tool. Rather than things splintering off into a dozen platforms for a dozen tools the Phabricator suit does a great job of providing a good single place to come to cooperate.
A commonly used external link might to an RFC definition. On day one you may wish to encourage users to always link to the text version of an RFC as hosted on the ieft.org's website. Presently the only way to make that link is to enter the text [[ https://tools.ietf.org/rfc/rfc123.txt | RFC123 ]] and update both the label and the link number every time a new RFC is used. What if in the future:
- you want to include both the Text and HTML versions of RFCs, you must update every instance on every page separately.
- The ietf.org might change their URL to https://rfc.ietf.org/rfc123.txt, you must update every instance on every page separately.
What if instead of writing a seperate link for an RFC on every page a user could define a new tag, say {{rfc|123}} that would automatically be translated into the [[ https://tools.ietf.org/rfc/rfc123.txt | RFC123 ]] markup when the page is rendered? If this new tag is defined in a single place and is avaiable throughout your instance it becomes trivial to edit it to point at a new URL or produce multiple links.
Other possibly common external link scenarios:
- You move to Phabricator and have a legacy bug system full of old resolved bugs that you would like to link to simply using {{bugz|123}} instead of [[ https://bugzilla.acme.biz/show_bug.cgi?id=12345 | Legacy Bug 12345 ]]. Yes you could migrate them but is there value in that?
- You have a database of test results that you commonly refer to.
- You often do inter-wiki linking to something like Wikipedia
This same system could take no parameters and allow the generation of boiler plate. You might want the same "Introduction Of Product Widget 2000" section at the start of a summary page, how to write code page and hardware design page. If you put that into a Macro it could be included in all three pages and only edited in one place. That or you could transclude pages or sections of pages but that is a different kettle of fish.
The Current Solution
When I asked in chat about whether a template or macro like feature existed, @avivey responded with a plausible solution for those the can meddle about with the server side code. For a few simple cases this is a workable answer that I will in all likelihood use. It is much more limited than allowing users to generate their own macros as and when they find a need to though.
avivey 20:55
@TafThorne: You can write your own Remarkup syntax rule like this:
<?php final class RFCRemarkupCodeRule extends PhabricatorRemarkupCustomInlineRule { public function apply($text) { return preg_replace_callback( '(RFC(\d*?)\b)s', array($this, 'markupInlineRFC'), $text); } public function markupInlineRFC($matches) { $engine = $this->getEngine(); $id = $matches[1]; $link = sprintf('[[https://tools.ietf.org/html/rfc%s | RFC %s]]', $id, $id); $link = phutil_tag( 'a', array( 'href' => sprintf('https://tools.ietf.org/html/rfc%s', $id), 'target' => '_blank', ), sprintf('RFC %s', $id)); return $engine->storeText($link); } }
(Dump it in the src/extensions dir)
MediaWiki Template Behaviour
I used a MediaWiki for a number of years and came to really appreciate the power that their Templates feature. This makes generating some boilerplate (like a copyright notice or page footer with helpful links) as simple as creating a new article and adding a single line of markup to the target page.
Within MediaWiki the Templates feature allows you to insert boiler plate markup using a pseudonym such as {{foo}}. This is a user definable entry that causes instances of {{foo}} on a page to be replaced by markup text such as A simple example bit of _data_ to fill a space.
More complex templates can be created by nesting one template inside another. A call to {{foo}} might include a call to {{bar}} within it and so on. This allowed you to form complex bits of text from simple lumps.
The really interesting feature of templates is in using parameters with them. Ideally this is what I would like to use within Phriction, if possible. A template with a parameter is called by something like {{foo|var1}}. Now inside the text you can insert the 'var1' into the generated text to give you something such as var1 is a simple example bit of _data_ to fill a space.
What you really use this for is something like an RFC link template. You can add {{rfc|123}} to a page then have the template generate some markup like [[ https://tools.ietf.org/rfc/rfc123.txt | RFC123 ]]. What is the advantage of this? Well perhaps you decide next week that you want all your RFC's to reference the copies on https://www.rfc-editor.org/ instead. Or you decide that you want links to both the .txt on ietf.org and rfc-editor.org. By using the template you can create a single article to edit in the future to make a consistent view across your wiki.