 | Please help achieve the goal of unifying macro parameters in confluence by contributing to this list |
Purpose
- A list of common and reserved macro parameter names from built-in and 3rd-party macros for confluence plugins.
- For end-users and plugin developers alike, it makes sense to have some common terminology for macros parameters.
- Currently, every plugin chooses it's own parameters at will, and the meaning is often different for the same parameter, or the same for different parameters.
- Developers, please choose consistent names if your parameter concept is already in use.
See also:
Guidance
- Rather than attempt to design or force consensus on a set of standardized parameters for user macros, this page aims to first document what is being used successfully in the most common macros, where and how.
- New macro developers can also use this so that they may not re-invent the wheel. It might also point you towards code, discussion or documentation you can use for specific implementations.
- Please create links rather than create large discussion or debate directly here.
- If there are conflicts, simple add multiple rows for various uses of a common parameter.
- Parameter name proposals and reserving parameter names are welcome, but of course, nothing is enforced. Feature requests, however, should be done in JIRA or at the Plugin Wishlist.
- This is not a complete list.
Parameters
Parameter Typical Meaning Built-in Macros 3rd-Party Macros Notes count truncate output to a specific number of items [recently-used-labels] [css] specified a css class that will be used by the main html output tag of the macro [div] [excerpt] Set to true or false to show or hide excerpts next to listed pages, etc. [contentbylabel] [pagetree] [children] [undefined-links] [height] Specify the height of the area rendered by the macro [chart] [create-space-button] [global-reports] [key] Restricts content to a certain space by spacekey [search-box] [contentbylabel] [label] singular form of labels parameter [labels] Filter results to the listed labels (each label separated by a comma) [blog-posts] [recently-updated] [related-labels] [labels] Filter results to the listed labels (query language where + and , indicate and/or etc.) [metadata-report] [limit] truncate output to a specific number of items [contributors-summary] [contributorsbylabel] [match-labels] When filtering by labels, determines whether AND or OR matching is used [blog-posts] [max] truncate output to a specific number of items [order] specifies how a list output will be displayed [contributors-summary contributors contributorsbylabel] [page] Specifies the page from which to gather content [children] [pages] a page or list of pages which a macro may act on [-param0-] limit to a specific space by key [listlabels] [reverse] Reverses the sort order [children] [scope] set, restrict or extend the limits of which pages a macro acts on, or acts as a content filter, by spacekey [recently-used-labels] Metadata Plugin Unified Page Searching Tags [showExcerpt] indicate if excerpts should be included for pages in the output [showLabels] Set to true or false to show or hide labels against listed pages, etc. [contentbylabel] [showSpace] Set to true or false to show or hide the space name against listed pages, etc. [contentbylabel] [sort] Choose how items are sorted [children] [pagetree] [space] singular form of spaces parameter [spaceKey] limit to a specific space by key [include] [livesearch] [spaces] Restricts content to be from one of the specified spaces [recently-updated] [src] a http url for specifying content or destination [iframe] style specifies an inline css style that will be used by the main html output tag of the macro [div] style specify an macro-specific internal style (non CSS) [popular-labels] [undefined-links] style Specify how a macro will be rendered - has multiple uses, for example on {children} it defines heading style whereas other macros use it to define list style and others use it to define a stylesheet class, etc. Rargh! [children] [recently-used-labels] [title] Specify the title for an area [code] [chart] [gallery] [panel] [info] [warning] [tip] [note] [type] Restricts content to a certain type (all included by default) [contentbylabel] [url] a http url for specifying content or destination [rss] [excel] [jiraissues] [jiraportlet] [width] Specify the width of the area rendered by the macro [chart] [create-space-button] [global-reports] [spaces]
Inconsistencies
The current set of macros have a number of inconsistencies that it would be great to resolve.
- Some macros use key while others use spaceKey and yet others use spaces
- Parameters are inconsistenly capitalized – showSpace versus match-labels versus showid
- Not all macros support style and those that do don't support consistent values
Comments (12)
May 29, 2006
Kelsey Grant says:
There's a discussion going on over hereThere's a discussion going on over here http://confluence.atlassian.com/display/DISC/Unified+Page+Searching+Tags about unifying a lot of these parameters to make life easier.
May 29, 2006
Mark Michaelis says:
The link is broken. Another try with the WikiStyle Syntax: DISC:Unified Page Sea...The link is broken. Another try with the Wiki-Style Syntax: Unified Page Searching Tags
May 29, 2006
Mark Michaelis says:
Am I wrong or does the table currently only list default macros included in Conf...Am I wrong or does the table currently only list default macros included in Confluence? If so, I would like to see it extended by macro arguments for the user provided plugins. But I also would put an emphasis on Atlassian's macros (e. g. make the macros bold). What do you think?
And about style: You are right, it's awkward that it is used in that many different ways (e. g. {div} and {style} macro directly map it to CSS attribute style). Perhaps it would be useful to make the description less restrictive: Influences the display/layout of the rendered macro result. I think this sums up all we need to know. As different macros have different layout it would only make sense to unify this argument a bit more for macros with equal output. Such as a list of pages provided by children and contentbylabel for example. For those macros of one category the values should have the same meaning.
May 29, 2006
Guy Fraser says:
We're hoping that all macros will get added to this page, it's just a matter of ...We're hoping that all macros will get added to this page, it's just a matter of time and finding enough people in the community willing to help with this task.
Regarding style, it's a bit more tricky than that - ideally all macros should have class and style params to allow control over their style sheets. Using the style param to change display modes is something quite different and should ideally be called something else (eg. outputFormat or similar?).
May 29, 2006
Mark Michaelis says:
This is an interesting suggestion. Although at least the styleattribute is somew...This is an interesting suggestion. Although at least the style-attribute is somewhat more diffucult to handle as it might be hard to decide where to apply the attributes to when you have nested HTML elements rendered.
The class-argument is somewhat easier. It is enough for writing CSS information if the outer element will get this attribute.
Mar 14, 2007
James Mortimer says:
oops, I duplicated this sentiment in my own page in a different section because ...oops, I duplicated this sentiment in my own page in a different section because I couldn't find this. I've attached it here as a child instead.
We shouldn't have to build this manually, at least not the part about what is being used!
Perhaps someone would jump-start this by writing a simple remote regx parser that generates, for the site, a summary of:
which can be summarized by space
If this was written, then we'd have a quick summary of what people were using. I'd run it on my site and contribute the stats collected from atlassian. Then all we'd have somewhere to start to see what the usage patterns are and where commonalities and differences are.
Any takers?
Mar 14, 2007
Alain Moran says:
Have you thought about parsing the notation guide, its in a pretty common format...Have you thought about parsing the notation guide, its in a pretty common format so would make a good base at least.
Mar 14, 2007
James Mortimer says:
even that would be a good start as it has most of the most common used tags my ...even that would be a good start as it has most of the most common used tags
my first question is, does anyone else care? especially at atlassian, about unifying these parameters? are there already something else in the works to deal with this, or is this effort worthwhile here, or is it not really a concern for most people?
Mar 14, 2007
Alain Moran says:
It would definitley make wiki markup easier for newbies to learn if a parameters...It would definitley make wiki markup easier for newbies to learn if a parameters with a given name only had one meaning.
Mar 15, 2007
Don Willis says:
Definitely unifying the parameters is a worthy aim and it would be great for the...Definitely unifying the parameters is a worthy aim and it would be great for the atlassian plugins to use more consistent parameters. I guess it would help if more people voted for the abovementioned CONF-7952. Although that issue doesn't quite cover the aim here.
Mar 16, 2007
James Mortimer says:
I think it's because it's new so not many people have seen it yet, and it's big,...I think it's because it's new so not many people have seen it yet, and it's big, so people are hesitant to have the vision required to make a major change or there are other major changes that outweigh it.
But it is in the same thread of standardizing macro parameters for common meanings, and the two aims would facilitate each other.
Sep 19, 2007
Guy Fraser says:
One other benefit that I envisage is that at some point in the future there will...One other benefit that I envisage is that at some point in the future there will likely be a much better wysiwyg editor that allows macros to be added and their params edited through some sort of UI.
By standardising the param names with specific meanings and formats you:
a) make it easier for everyone to learn
b) can provide a consistent UI
c) can re-use any UI editing for a given param in multiple macros
d) streamline documentation
e) make me happy because I like to see everything "tie together" nicely