読者です 読者をやめる 読者になる 読者になる

tohokuaikiのチラシの裏

技術的ネタとか。

Confluenceのプラグイン開発を承ります。ご連絡はこちらのホームページからお願いいたします。

Confluenceのマクロパラメータについて調べてみた

confluence

XHTMLマクロやマクロを作るときにatlassian-plugins.xmlで定義したいのだけど、イマイチ定義一覧みたいのが見つかられなくて、ソースから解析してみた。

手っ取り早くはDTDがあるんだけど。。。

confluence-project/confluence-core/confluence/src/etc/java/com/atlassian/confluence/macro/macro-fallback.xml
DTDっぽいのがある。

<!DOCTYPE atlassian-plugins [
        <!ELEMENT atlassian-plugins    (atlassian-plugin+)>
        <!ELEMENT atlassian-plugin      (macro+)>
        <!ATTLIST atlassian-plugin key CDATA #REQUIRED>
        <!ELEMENT macro    (alias*, category*, parameters+)>
        <!ATTLIST macro name CDATA #REQUIRED>
        <!ATTLIST macro documentation-url CDATA #IMPLIED>
        <!ATTLIST macro icon CDATA #IMPLIED>
        <!ATTLIST macro hide-body (true|false) "false">
        <!ATTLIST macro hidden (true|false) "false">
        <!ELEMENT category EMPTY>
        <!ATTLIST category name (confluence-content|media|communication|formatting|navigation|external-content|admin|reporting|visuals|development|other) #REQUIRED>
        <!ELEMENT parameters (default?, parameter*)>
        <!ATTLIST parameters name CDATA #IMPLIED>
        <!ELEMENT parameter (alias*,value*,option*)>
        <!ATTLIST parameter name CDATA #REQUIRED>
        <!-- Update MacroParameterType enum when adding to this list -->
        <!ATTLIST parameter type (string|boolean|username|int|enum|spacekey|relativedate|percentage|confluence-content|url|color|attachment|label|date|group) #REQUIRED>
        <!ATTLIST parameter required (true|false) "false">
        <!ATTLIST parameter multiple (true|false) "false">
        <!ATTLIST parameter default CDATA #IMPLIED>
        <!ATTLIST parameter format CDATA #IMPLIED>
        <!ATTLIST parameter documentation-url CDATA #IMPLIED>
        <!ELEMENT value EMPTY>
        <!ATTLIST value name CDATA #REQUIRED>
        <!ELEMENT alias EMPTY>
        <!ATTLIST alias name CDATA #REQUIRED>
        <!ELEMENT option EMPTY>
        <!ATTLIST option key CDATA #REQUIRED>
        <!ATTLIST option value CDATA #REQUIRED>
        ]>

これ見れば分かるよねっていうのもあるんだけど、とりあえずソースも調べる。必ずもこのDTDチェックしてるとは思えないし、DTD自体拡張してる気がするので。

全体像

取りうるすべてのものを含んだmacroのXML要素はこんな感じかな?

<xhtml-macro
	name="マクロを入力するKeyword"
	key="マクロを唯一で指定する文言"
	class="実装するJavaクラス"
	documentation-url="説明(propertiesファイルで指定する)"
	hidden="trueで隠しパラメータ?"
	icon="アイコンの設定パス"
	hide-body="本文を隠す?"
	>
	<description>このマクロの説明</description>
	<parameters>
		<parameter
			name="パラメータ名"
			type="パラメータの型"
			required="trueで入力必須"
			documentation-url="説明(propertiesファイルで指定する)"
			default="デフォルト値"
			multiple="複数選択が可能?"
			format="書式フォーマット(YYYY/mm/dd以外は使用例なし)"
			>
			<value name="選択肢1(パラメータの型がenumの場合)"/>
			<value name="選択肢2(パラメータの型がenumの場合)"/>
			<option key="不明" value="不明"/>
			<alias name="不明"/>
		</parameter>
		<parameter name="パラメータ名2" type="パラメータの型" />
	</parameters>
</xhtml-macro>

各要素について

では、以下各要素について。

xhtml-macro/macroの属性値
属性名称 意味(推測) 値サンプル
key 必須:見分けするキー loremipsum
multimedia
gadget
spacejump-xhtml
expand
unmigrated-wiki-markup
unmigrated-inline-wiki-markup
xhtml-include
xhtml-page-list
xhtml-user-status
test-noparameters
test-livesearch
compatibility-multimedia
gadget-old
spacejump
expand-migration
spaces-list
spaces
recently-updated-dashboard
space-details
global-reports
welcome-message
create-space-button
index
network
profile
status-list
color
bob
blog-posts
mycolour
name 必須:一般的にマクロを入力する文字 loremipsum
multimedia
gadget
spacejump
expand
unmigrated-wiki-markup
unmigrated-inline-wiki-markup
include
page-list
user-status
test-noparameters
test-livesearch
spaces-list
spaces
recently-updated-dashboard
space-details
global-reports
welcome-message
create-space-button
content-by-user
search
index
excerpt
junitreport
doc
change-history
popular-labels
contentbylabel
favpages
related-labels
recently-updated
recently-used-labels
navmap
listlabels
cheese
note
warning
info
tip
pagetree
pagetreesearch
widget
web-widget
section
column
livesearch
code
html
html-include
rss
im
repository-plugin
recentlyupdated-plugins
popular-plugins
download-stat
confluence-status
plugin-status
plugin-repository
plugins-supported
plugin-compatibility-matrix
network
profile
status-list
chart
contributors
contributors-summary
usage
popular
topusers
userlister
testmacro
color
bob
blog-posts
mycolour
class 必須:Javaのクラス名 com.atlassian.confluence.plugins.macros.core.LoremIpsumMacro
com.atlassian.confluence.plugins.macros.core.MultimediaMacro
com.atlassian.confluence.plugins.gadgets.GadgetMacro
com.atlassian.confluence.plugins.doctheme.SpaceJumpMacro
com.atlassian.confluence.plugins.expand.ExpandMacro
com.atlassian.confluence.macro.wiki.UnmigratedBlockWikiMarkupMacro
com.atlassian.confluence.macro.wiki.UnmigratedInlineWikiMarkupMacro
com.atlassian.confluence.macro.NoBodyMacro
com.atlassian.confluence.plugins.seleniumtest.NoformatMacro
com.atlassian.confluence.plugins.macros.core.OldMultimediaMacro
com.atlassian.confluence.plugins.expand.ExpandV2Macro
com.atlassian.confluence.plugins.macros.dashboard.SpacesListMacro
com.atlassian.confluence.plugins.macros.dashboard.recentupdates.RecentlyUpdatedContentMacro
com.atlassian.confluence.plugins.macros.dashboard.SpaceDetailsMacro
com.atlassian.confluence.plugins.macros.dashboard.GlobalReportsMacro
com.atlassian.confluence.plugins.macros.dashboard.WelcomeMessageMacro
com.atlassian.confluence.plugins.macros.dashboard.CreateSpaceButtonMacro
com.atlassian.confluence.util.FakeTestingMacro
com.atlassian.confluence.macro.profile.NetworkMacro
com.atlassian.confluence.macro.profile.ProfileMacro
com.atlassian.confluence.macro.userstatus.StatusListMacro
com.atlassian.renderer.macro.macros.ColorMacro
documentation-url propertiesファイルで指定するとこの文言が出てくる help.multimedia.macro
http://confluence.atlassian.com/display/DOC/Expand+Macro
help.content.by.user.macro
help.search.macro
help.excerpt.macro
help.include.page.macro
help.junit.report.macro
help.documentation.link.macro
help.change.history.macro
help.popular.labels.macro
help.content.by.label.macro
help.favourite.pages.macro
help.related.labels.macro
help.recently.updated.macro
help.recently.used.labels.macro
help.navmap.macro
help.labels.list.macro
help.cheese.macro
help.note.macro
help.warning.macro
help.info.macro
help.tip.macro
help.pagetree.macro
help.pagetree.search.macro
help.widget.macro
help.section.macro
help.column.macro
help.livesearch.macro
help.code.block.macro
help.html.macro
help.html.include.macro
help.rss.feed.macro
help.im.presence.macro
http://confluence.atlassian.com/display/CONFEXT/Confluence+Repository+Client
help.chart.macro
help.contributors.macro
help.contributors.summary.macro
http://confluence.atlassian.com/display/CONFEXT/Confluence+Usage+Tracking+Plugin
help.user.list.macro
help.blog.posts.macro
hidden trueにすると隠しパラメータ? TRUE
icon アイコンのパス /download/resources/com.atlassian.confluence.plugins.expand-macro/images/expand.png
/images/icons/macrobrowser/livesearch.png
/images/icons/macrobrowser/blog-posts.png
bodyDeprecated テストの1個だけなので普通は使わない? TRUE
hide-body 本文を隠す TRUE
documentationUrl タダの間違い? http://foo
state 未使用:サンプル1個だけ disabled

ちなみに80個のうち、key=nameなのは24個。ぴったり3割。

parameter要素の属性値について
属性名称 意味(推測) 値サンプル
name 必須:パラメータ名 page
name
width
height
autostart
foo
space
alias
title

id
spaceKey
spaces
types
labels
users
showProfilePic
size
query
maxLimit
spacekey
type
lastModified
contributor
hidden
url
directory
reportdetail
debug
count
style
author
showLabels
showSpace
max
excerpt
operator
sort
reverse
maxResults
hideHeading
theme
scope
wrapAfter
cellWidth
cellHeight
icon
root
searchBox
expandCollapseAll
startDepth
rootPage
border
lang
borderStyle
borderColor
borderWidth
bgColor
titleBGColor
showTitlesOnly
titleBar
service
showid
key
profile
suppressHeader
product
mode
range
rangeStart
rangeEnd
version
increment
format
update-only
profileKey
by
productStart
productEnd
majorVersionsOnly
rows
showBrokenBuilds
xLabel
yLabel
legend
orientation
stacked
3D
colors
rangeAxisLowerBound
rangeAxisUpperBound
dataOrientation
include
order
limit
showAnonymous
showCount
showLastTime
contentType
publishDate
showPages
noneFoundMessage
groupby
columns
showZeroCounts
events
timespan
period
display
groups
online
stringparam
intparam
boolparam
enumparam
content
type パラメータの型 confluence-content
attachment
int
boolean
enum
spacekey
string
username
percentage
relativedate
url
color
label
date
group
required 必須パラメータかどうか true
false
documentation-url propertiesファイルで指定するとこの文言が出てくる help.multimedia.macro.autoplay
default デフォルト値 pie
Click here to expand...
foo
100%
large
all
100
list
true
15
false
OR
10
global
5
90px
60px
position
1
java
overview-table
table
month
daily
full
default
vertical
300
horizontal
authors
count
inline
contributors
edits,comments,labels
edits
view
event
1d
title,count

excerpts
multiple 複数選択が可能? false
true
format 書式フォーマット YYYY/mm/dd
parameter内の要素として取る値

これはparameterタイプがenumの場合しか良く分からない。
もしかしたら、pageをparameter typeにした場合にページを選択できるようなParameter設定ができるのかもしれない。

タグ名 親のparameter name 親のparameter type 属性値 意味(推測) 取りうる値
option page
root
rootPage
title
confluence-content
string
key 不明 includeDatePath
showValueInPlaceholder
type
option page
root
rootPage
title
confluence-content
string
value 不明 page
true
alias labels
lang
name
spaces
stringparam
attachment
enum
spacekey
string
name 不明 label
maxResults
space
stringparameter
value content
display
enumparam
groupby
include
increment
lang
mode
online
operator
reportdetail
scope
service
size
sort
style
theme
type
types
enum name パラメータを選択式にする descendants
description
excerpts
failuresonly
false
flat
full
heatmap
large
list
modified
new
position
sidebar
spacedesc
table
three
vertical
xml
yahoo
yearly

使ったスクリプト

解析したスクリプトPHPです。

<?php
// <macro>および<xhtml-macro>のパラメータを探す
$files=<<<EOF
5.3.1/confluence-project/confluence-plugins/confluence-misc-plugins/confluence-core-macros/src/main/resources/atlassian-plugin.xml
5.3.1/confluence-project/confluence-plugins/confluence-bundled-plugins/confluence-gadgets/gadgets-plugin/src/main/resources/atlassian-plugin.xml
5.3.1/confluence-project/confluence-plugins/confluence-bundled-plugins/doctheme/src/main/resources/atlassian-plugin.xml
5.3.1/confluence-project/confluence-plugins/confluence-bundled-plugins/confluence-expand-macro/src/main/resources/atlassian-plugin.xml
5.3.1/confluence-project/confluence-plugins/confluence-bundled-plugins/confluence-dashboard-macros/src/main/resources/atlassian-plugin.xml
5.3.1/confluence-project/confluence-core/confluence/src/etc/java/com/atlassian/confluence/macro/macro-fallback.xml
5.3.1/confluence-project/confluence-core/confluence/src/etc/java/plugins/user-status.xml
5.3.1/confluence-project/confluence-core/confluence/src/etc/java/plugins/macro-browser-metadata-providers.xml
5.3.1/confluence-project/confluence-core/confluence/src/etc/java/plugins/profile-macros.xml
5.3.1/confluence-project/confluence-core/confluence/src/test/etc/com/atlassian/confluence/macro/test-macro-fallback.xml
5.3.1/confluence-project/confluence-core/confluence/src/test/etc/module-descriptors/sample-macro-plugin.xml
5.3.1/confluence-project/confluence-test/confluence-acceptance-test/src/main/resources/mycolourmacro.xml
5.3.1/confluence-project/confluence-plugins/confluence-misc-plugins/confluence-core-macros/src/main/resources/atlassian-plugin.xml
5.3.1/confluence-project/confluence-core/confluence/src/etc/java/services/pluginServiceContext.xml
5.3.1/confluence-project/confluence-core/confluence/src/etc/java/plugins/wiki-markup.xml
5.3.1/confluence-project/confluence-core/confluence/src/test/etc/testPluginSubsystemContext.xml
5.3.1/confluence-project/confluence-core/confluence/src/test/etc/plugins/test-macros.xml
5.3.1/confluence-project/confluence-test/confluence-selenium-test/src/main/resources/selenium-test-plugin/atlassian-plugin.xml
EOF;

$v = array(
    'xhtml-macro' => array(),
    'wiki' => array(),
    );
foreach (explode("\n", $files) as $file){
    $file = trim($file);
    $dom = new DOMDocument('1.0');
    if (@$dom->loadXML(file_get_contents($file))){
        $xpath = new DOMXpath($dom);
        foreach (array('xhtml-macro', 'macro') as $macrotype) {
            foreach ($xpath->query('//'.$macrotype) as $xhtmlmacro){
                $macroname = $xhtmlmacro->getAttribute('name');
                $v[$macrotype][$macroname] = array(
                    'file' => $file,
                    'attr' => array(),
                    'param' => array(),
                    );
                foreach ($xpath->query('@*', $xhtmlmacro) as $attr){
                    $v[$macrotype][$macroname]['attr'][$attr->name] = $attr->value;
                }
                foreach ($xpath->query('parameters/parameter', $xhtmlmacro) as $param){
                    $v[$macrotype][$macroname]['param'][$param->getAttribute('name')] = array();
                    foreach ($xpath->query('@*', $param) as $attr){
                        $v[$macrotype][$macroname]['param'][$param->getAttribute('name')][$attr->name] = $attr->value;
                    }
                }
                foreach ($xpath->query('parameters/parameter/*', $xhtmlmacro) as $paramChild){
                    if (!isset($v[$macrotype][$macroname]['param']['child'])){
                        $v[$macrotype][$macroname]['param']['child'] = array();
                    }
                    if (!isset($v[$macrotype][$macroname]['param']['child'][$paramChild->tagName])){
                        $v[$macrotype][$macroname]['param']['child'][$paramChild->tagName] = array(
                            'parentName' => $paramChild->parentNode->getAttribute('name'),
                            'parentType' => $paramChild->parentNode->getAttribute('type'),
                            'attr' => array(),
                            );
                    }
                    foreach ($xpath->query('@*', $paramChild) as $attr){
                        $v[$macrotype][$macroname]['param']['child'][$paramChild->tagName]['attr'][$attr->name] = $attr->value;
                    }
                }
            }
        }
    }
}
// var_export($v);exit;

// マクロ属性値
$macro_attr = array();
$keyeqname = array("Y" => 0, "N" => 0);
foreach ($v as $macrotype=>$m){
    foreach ($m as $macroname => $prop){
        $keyeqname[@$prop['attr']['key'] == $prop['attr']['name'] ? 'Y' : 'N']++;
        foreach ($prop['attr'] as $k=>$_v){
            if (!isset($macro_attr[$k])){
                $macro_attr[$k]= array();
            }
            $macro_attr[$k][] = $_v;
        }
    }
}
echo "|* 属性値 |* 取りうる値 |\n";
foreach ($macro_attr as $k=>$_v){
    $_v = array_unique($_v);
    printf("%s\t\t%s\n", $k, implode("<br>", $_v));
}
echo "\n\n";

// パラメータ
$param_attr = array();
$param_child = array();
foreach ($v as $macrotype=>$m){
    foreach ($m as $macroname => $prop){
        foreach ($prop['param'] as $prop_name => $param){
            if ($prop_name != 'child'){
                foreach ($param as $k=>$_v) {
                    if (!isset($prop_attr[$k])){
                        $prop_attr[$k]= array();
                    }
                    $prop_attr[$k][] = $_v;
                }
            }
            else {
                foreach ($param as $tagName=>$attr) {
                    if (!isset($param_child[$tagName])){
                        $param_child[$tagName] = array(
                            'parentType' => array(),
                            'parentName' => array(),
                            'attr' => array(),
                            );
                    }
                    $param_child[$tagName]['parentType'][] = $attr['parentType'];
                    $param_child[$tagName]['parentName'][] = $attr['parentName'];
                    foreach ($attr['attr'] as $k=>$_v){
                        if (!isset($param_child[$tagName]['attr'][$k])){
                            $param_child[$tagName]['attr'][$k] = array(
                                );
                        }
                        $param_child[$tagName]['attr'][$k][] = $_v;
                    }
                }
            }
        }
    }
}

echo "|* 属性値 |* 取りうる値 |\n";
foreach ($prop_attr as $k=>$_v){
    $_v = array_unique($_v);
    printf("%s\t\t%s\n", $k, implode("<br>", $_v));
}
echo "\n\n";

// parameter内要素
echo "\t* タグ名 \t* 親のparameter name \t* 親のparameter type \t* 属性値 \t\t* 取りうる値 \n";
foreach ($param_child as $tagName=>$attr){
    $parameterType = array_filter(array_unique($attr['parentType']));
    sort($parameterType);
    $parameterName = array_filter(array_unique($attr['parentName']));
    sort($parameterName);
    foreach ($attr['attr'] as $attr_name => $_v){
        $_v = array_filter(array_unique($_v));
        sort($_v);
        printf("%s\t%s\t%s\t%s\t%s\n", 
               $tagName,
               implode("<br>", $parameterName),
               implode("<br>", $parameterType),
               $attr_name,
               implode("<br>", $_v));
    }
}
echo "\n\n";