where is the xhtml-macro documented ?

[Brendan Patterson]

Is the xhtml-macro itself documented anywhere?

There are several tutorials showing how to use it, but it seems like it would be documented alongside these:

https://developer.atlassian.com/display/CONFDEV/Confluence+Plugin+Module+Types

Specifically I'm wondering about the "paramater types" available?

Another way to make is info available would be an XSD for atlassian-plugin.xml

thanks!!

Brendan

[Joe Clark · Accepted solution]

Well, put me in a dress and call me Daisy! I could have sworn we had documentation for the xhtml-macro module. I'll add this to my list of things to fix up in the "probably should have been documented when we released Confluence 4" category.

Brendan, do you have the source accessible? I'm pretty sure there is a big chunk of code somewhere that lists all the built-in parameter types that we support. I'll see if I can find it.

[David Peterson]

Don't forget Transformer modules, while you're at it. Still waiting on that one too...

[Joe Clark]

Yep, still got a draft for that one.

[Brendan Patterson]

Thanks Joseph. I do have access to the source and was planning on looking there as a 5th step in my quest for knowledge, though it's not always clear in the 17,368 files where to look :)

After quite a bit of searching including grepping across all the Confluence 4.1 source code I did find documentation on the macro / xhtml-macro (I assume) parameters:

https://developer.atlassian.com/display/CONFDEV/Including+Information+in+your+Macro+for+the+Macro+Browser

From what I've read perhaps the xhtml-macro is meant to be mostly like the 'macro' , so I started broadening my searches for information along those lines.

I'm realizing that many of the questions I had about the xhtml-macro are probably answered by 'macro' documentation, but still glad you're adding it to your list.

It's also not mentioned that you don't have a <parameters/> element in your xhtml-macro it won't show up in the macro browser and everything will just kind of quietly fail - at least in some cases, but seemingly not all cases for some reason.

[David Peterson]

Yeah, I think all this stuff should be in the main module documentation, since it is basically compulsory now.

[Joe Clark]

I agree - the information is there, it just needs to be restructured out of its "getting ready for Confluence 4" and into a "this is how you do macros now" style.

So that it's easier to find and clearly the canonical reference.

[Brendan Patterson]

I certainly don't want to make more effort for Atlassian when the docs are there somewhere already. I'm trying to think of light weight improvements - like in this case just having some more links in the existing examples to things like "macro parameters".

@david-peterson

Also, something documenting more formally ways to wire custom parameter types into the Macro Browser.

David is that documented anywhere - custom parameter types in the Macro Browser? I need to do that as well.

The elements of the Macro Browser's view of a plugin are a bit hard to come by. My current dream scenario would be to have a screen shot of the Macro Browser with image-map links to the relevant docs about how to populate the various parts of it in various ways. I know there are an infinite number of things to document so this is not a criticism - just an observation. Indeed we are empowered to update the docs so perhaps I'll take a swing at that when I learn more.

[Joe Clark]

David is that documented anywhere - custom parameter types in the Macro Browser? I need to do that as well.

David Taylor did a presentation at AtlasCamp 2010 that included some custom macro parameter jiggery at the end, here's the video & the slides. AFAIK it's not documented anywhere though (oh look! Another item to add to the list :)).

No problem criticising, Brendan - it's definitely an area where we can improve. :)

EDIT: Oh crap, the video is currently down because episodic.com is no longer. :( I believe our marketing team is working on a Plan B, but no news at this stage.

[Brendan Patterson]

Alas there are a ton of great videos that are currently unavailable. In fact I feel like a good 50% of key info for developers is in the videos only (nowhere else) currently 'locked up'. I know it's a lot of work to get them re-uploaded.........but if you guys send me the DVDs or hard drive with the videos I WILL upload them all to youtube myself. I think they're that important :) Its been a few months now. I've watched "big modular plugins" from A.C. 2010 a few times and need to watch it a few more to give one example.

[David Peterson]

Yeah, both those things would be handy. Also, something documenting more formally ways to wire custom parameter types into the Macro Browser. There was a demo at an AtlasCamp a while back, but nothing actually documented...