Is there an easy-to-set up Xwiki equivalent to what Mediawiki calls "templates"?

Help / Discuss
1

Mediawiki use the word “template” to mean something different than Xwiki means by the word. In Xwiki a template is for page outlook. In Mediawiki it’s basically a macro. As one of the simpler examples we have links to Jira tickets handled by a template whose code is this:

[https://jira.obfiscated.net/browse/{{{1}}} {{{1}}}]

which is then invoked like this in Mediawiki markup:

{{Jira|IT-123}}

where the part before the fence specifies the template’s name, and the part after the variable to fill in in the macro.

In the converted pages these show up as “Unknown macro” under Xwiki, so the conversion filter hasn’t converted them. It’s not too long a list to set up by hand. Can that be done as simply as it is in Mediawiki?

2

The mediawiki filter convert the templates calls as macro calls because that’s the closest in XWiki world, but it does not convert the implementation of those templates because it’s would be very hard (PHP and use manipulation of mediawiki APIs).

The simplest to resolve those missing macros errors is to actually implement those macros. See https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/ for more details on how to do that.

3

Thanks. Reading that page, I’m not seeing how to write the equivalent of the simple macro to link to Jira from text on the wiki page which shows a simple link consisting of the Jira ticket number, such as I quoted above. No doubt it can be done, but the examples on the howto page look to be of a different sort of use. What’s the syntax to have a macro take a variable from the wiki page text? What should that invocation look like on the wiki page? Can it be handled in the WYSIWIG editor or (like Mediawiki) does it require dropping down to text mode? Probably if I read a lot more of the manual it would all come into focus. It would be nice if there were more examples of simple macro usage on the howto page.

4

Well in the context of the import the easiest IMO if to so that the other way around: try an import and see how the filter converts your example, and then you will know what exactly to implement.

There is plenty of example on the macro syntax in the macro creation document I gave you but here is a more syntax oriented documentation: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/?syntax=2.1&section=Macros.

And here is how the standard XWiki Jira macro is working: https://extensions.xwiki.org/xwiki/bin/view/Extension/JIRA%20Macro.

Yes, you can add and edit macros in the WYSIWYG.

As you saw in the documentation, you can pass parameters in a macro call (as in {{mymacro param="value1"}}), but maybe you mean something else ? The macro implementation has access to the whole content, where the macro call is executed in a form of a XWiki DOM (or plain text source).

5

There is plenty of example on the macro syntax in the macro creation document I gave you but here is a more syntax oriented documentation: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/?syntax=2.1&section=Macros .

Thomas, Thanks for that pointer, which I’m sure provides some clue to my question. Yet I confess I can’t follow it. Something I’ve learned from years in IT is that even in a firm where half our staff is seriously engaged in programming, people with deep capabilities in one area are still beginners in other. My question quite specifically, which I’d like to find an example for, is how to write a simple Xwiki macro which other staff can easily use as a shortcut to creating links to an arbitrary URL. You say, “See how the filter converts your example” on import, but didn’t you tell me elsewhere that the filter does not convert Mediawiki macros? Indeed, wherever we have Mediawiki macros, importing has inserted “missing macro” messages.

Assuming that the correct translation of our current {{Jira|IT-1234}} macro invocations in Mediawiki is {{Jira param=“IT-1234”}}, how is the variable to be expressed in the macro so included? From the import translation I see them as {{jira}}IT-1234{{/jira}} which I take as equivalent, and which staff should find understandable. If that’s correct, how is the variable that will express the parameter to be specified in the macro? I’m sure it might be obvious if I regularly used Java, but my regular languages are bash, php, python, perl, sql

Your Jira macro looks great for including a table of Jira issues in Xwiki. We look forward to making use of it. But meanwhile we have several hundred pages which rely on direct links to individual Jira issues. Assuming that the construction {{jira}}IT-1234{{/jira}} the conversion made of the links will work, I’m looking for a step-by-step understanding of how to write the macro that will restore the links – not just for Jira, but for other instances were we have similar macros (by other names) cross-referencing to internal sites.

Looking at https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/ nothing there seems to cover this. And when I search on “Macro” I don’t find such a guide to writing them either. What I’m trying to do is a simpler case than those shown on https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/. I’m just trying to learn to write an Xwiki macro that will take a single input from the user writing a wiki page, such that {{jira}}IT-1234{{/jira}} will be rendered as a link to

<a href=https://jira.obfuscated.net/browse/IT-1234&gt;IT-1234&lt;/a&gt;".

I expect that can be done simply. But in my ignorance of how Xwiki should handle the single variable here (“IT-1234”) I’m still at a loss.

This also is hazy to me: “creating a new wiki page and attaching to it an object of type XWiki.WikiMacroClass”. I’m not an object-oriented programmer. For those of us who are not, it would be useful to have a recipe which demonstrates how to do each step. I have just created a new page. I see nowhere in it’s menus an option to attach an object to it. How is that to be done?

Thanks,
Whit

6

No, I told you that the implementation is not converted, but you will see how the macro (a macro you will have to implement) is called. According to what you said, the macro call seems to be {{jira}}IT-1234{{/jira}}.

I don’t actually understand your question, what variable are you exactly referring to ? Are you asking how the macro implementation can access what is between {{jira}} and {{/jira}} ?

Sorry, but that’s the simplest documentation we have to write a rendering macro. The first example (the usual “hello world”) is quite a simple example, and it should be detailed enough for you to just do what’s indicated in it and see the result. Then right after it, you have an example on how to access the macro content which is exactly what you are trying to access in your {{jira}}IT-1234{{/jira}}. Maybe the part you missed is that the macro is itself implemented using wiki syntax so anything dynamic (like generating a link based on some input) is done through a script macro (and most of the example use Velocity scripting language because it’s a very simple templating language) so it means that your macro implementation will look something like

{{velocity}}
[[$wikimacro.content>>https://jira.obfuscated.net/browse/$wikimacro.content]]
{{/velocity}}

which use Velocity scripting to generate a XWiki syntax external link to the jira issue.

7

Thanks, that makes sense, that “$wikimacro.content” is the variable name then.

Where are instructions for “attaching to [a new page] an object of type XWiki.WikiMacroClass”? I expect they’re somewhere, but my search for them so far has not been successful. Once it’s clear how to do that, I can turn our XWiki over to staff for testing and appraisal.

8

You need to be “Advanced” to see a link to the object editor in the UI, see https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/PageEditing#HAdvancedProfile for more details on how to enable this in your user profile.

9

Got the macro to work, mostly. Next puzzle is because we invoke it commonly in tables. For a reason I can’t figure, it’s putting two returns before the macro, breaking the table. To clarify, that’s on the imported tables. The returns may have been added on import, just where it saw a macro it didn’t have defined (because a Mediawiki template).