Snippets
この投稿は Atlassian Advent Calendar 2015 の 3日目 の記事です。 せっかくなので、Bitbucket Snippets を利用してみます :)
- 12/2の記事は、tnagasawaさん の JIRAとインベーダーゲーム でした!
- 12/4の記事は、ninuyama さんです。どうぞ宜しくお願いいたします!
#『最終更新日から1年以上が経過しています』的な表示を出したい!
きっかけ:情報の鮮度を保ちたい!
職場でのConfluence利用を開始してから、すでに3年くらい経過しました。 とうぜん、自分の書いたいろんなコンテンツも棚卸ししないとどんどん溜まっていきますし、内容的にだいぶ古くなってしまっているものもあります。
パーソナルスペースだと、あまりニーズはないかもしれませんが、業務に使って日々皆さんが見るようなところ、ルールや手順をまとめているページについては、コンテンツの定期的な更新を行ったり、鮮度を保つことは大切だと思っています。
職場で2年くらいConfluenceの管理者をしていたのですが、その際に、こんな意見がありました。
- コンテンツが古くなって更新されないままでは良くない
- 検索してたどり着いた側にとっても、古過ぎな情報は役にたたないかもしれない
- 「 このページはX年更新されてません 」的なメッセージを表示でるといいのでは
実際、お外のサイトとかブログでは、そういう表示が入ったページを見かけますよね。 (こちらのQiitaもそうですね)
一応 ページの上部に最終更新日は入っていますが、もうちょっとわかりやすくしてみたい...。
そう思いながらも、いまひとつ方法が思いつかなかったりで実行できないまま、管理者担当から離れたため、うかつなことはできなくなりました^^;
考えてみたこと
さて、異動後はフロントエンドのお仕事(といっても、本当に質が低くて申し訳ない...) をしています。
これが幸いしてか、それまでは「プラグインとかサーバサイドでの調整をしないと、上記のようなカスタマイズは無理だよね....」と思っていたのですが、フロントの調整でもいろんなことが出来ることがわかりました。
フロント部分だけの対応だと、もちろんブラウザやデバイスによっては期待している結果が出ないこともありますが、それでもエンタープライズ(企業内)であれば大部分は拾えます。
お世話になっている、リックソフト様のこちの記事を参考に、ちょっとやってみました。
スペースのカスタマイズで対応
ひとまず自分のスペースに対して、フロントでの調整のみで対応してみました。 方法は、以下の通りです。
注意点:
- ドキュメンテーションテーマを使っている場合は、この方法は使えません。(プラグインでの対応になってしまうかもしれないので、要調査)
- リックソフト様のブログにある通り、Tryする場合は自己責任で!
- 消しちゃっても良いスペースとか、検証環境などでいったん試しましょう。
- 失敗すると、対象のスペースが表示されず、コントロールもできない状態になります。(操作用のUIが見えなくなってしまうなど)
わたしもうっかりやって失敗してしまい、Web上からは操作できなくなってしまいました...。 (最終的には、他のスペースで設定をリセットする処理をブラウザでキャプチャして、パラメータを変えてcurlでAPI的にリクエストを出してリセット、という方法で復旧させました)
% curl 'http://confluenceのURL/spaces/resetdecorator.action?decoratorName=decorators/page.vmd&key=スペースキー&atl_token=トークン....' ¥
-H 'Cookie: クッキー' --compressed
方法:
- スペースツールから、「スペースの管理」 -> ルックアンドフィール を調整。
- スペース全体の調整ではなく、スペース以下の特定のコンテンツを修正してみて、結果を確認するほうがベター。
- この記事の場合は、「ページ」に該当するコンテンツをカスタマイズしています。
- 具体的には、JavaScriptを使って、クライアントサイドで『この記事は....』というメッセージをタイトルの下に描画させます。
- CSSもついでに調整します。
幸い、ページの最終更新日時は、APIで改めて取得しなくとも、ページのHTMLの中に埋め込まれています。 この値をDOMで抽出して、スペースのヘッダに仕込んだJavaScriptを使って更新から1年経っているかどうかを判断させて、メッセージを表示するようにしました。
設定例
今回差し込んだスクリプトは、以下のようなものです。
- スペースツール -> ルックアンドフィール -> レイアウト -> ページレイアウト で編集フォームを開きます。
- わたしのの場合は "## MODE SPECIFIC DECORATING ENDS" の後くらいに差し込みました。
あんまり綺麗なコードでなくてすみません...。
..............
#ページデコレーターの途中にJavaScriptを差し込み
#end
## MODE SPECIFIC DECORATING ENDS
</div>
<script type="text/javascript">
AJS.toInit(function(){
diff = getDiff();
if (diff >= 365) {
AJS.$('div.page-metadata').append('<div class="alert alert-warning"><i class="aui-icon aui-icon-small aui-iconfont-time"></i>最終更新日から1年以上経過しています / This page has not been updated in over a year.</div>');
} else {
AJS.$('div.page-metadata').append('<div class="alert alert-success"><i class="aui-icon aui-icon-small aui-iconfont-time"></i>この記事は最終更新日から1年未満です</div><br/>');
}
}); function getDiff() {
last_modified = AJS.$(".last-modified");
updated_at = last_modified.attr("title");
today = new Date();
msDiff = today.getTime() - new Date(updated_at).getTime();
daysDiff = Math.floor(msDiff / (1000 * 60 * 60 * 24));
return ++daysDiff;
}
</script>
## GENERAL PAGE DECORATING ENDS
Cofluenceでは、jQueryのような形で、AJSというものが使えます。
上記だと、ページの.last-modified というクラスのオブジェクトの所に、最終更新日時の値が入っているので、そちらを取り出して日付掲載し、結果をHTMLで差し込んでいます。
CSSを調整する
うまく設定が反映されると、ページのタイトルの下に、更新状況を判定したメッセージが表示されます。 ただし、このままでは綺麗なスタイルも適用されておらず、Qiitaの画面にもほど遠い....
ということで、CSSを調整します。 こちらは スペースツール -> ルックアンドフィール -> スタイルシート で編集画面を開きます。
上記のJavaScriptで生成したHTMLに合わせて、以下のようなCSSを追加しました。
/* --- 更新状況Message -- */
#content > div.page-metadata > div.alert {
padding: 10px;
padding-left: 12px;
margin-top: 10px;
border: 1px solid transparent;
border-radius: 4px;
}
#content > div.page-metadata > div.alert-warning {
background-color: #fcf8e3;
border-color: #faebcc;
color: #8a6d3b;
}
#content > div.page-metadata > div.alert-warning > i {
right: 5px;
color: #8a6d3b;
}
div.alert-warning > div.message-content {
color: #8a6d3b;
}
#content > div.page-metadata > div.alert-success {
background: #f3f9f4;
border-color: #91c89c;
color: #333;
}
#content > div.page-metadata > div.alert-success > i {
right: 5px;
color: #2D7273;
}
アイコンを工夫したい
さて、差し込むHTMLの色などはスペースのCSSでカスタマイズが可能ですが、Qiitaのように時計のアイコンも付けたい場合はどうしましょう? フロントに詳しい方なら、Bootstrapやfontawesomeのような「アイコンフォントを使えれば...!」とお気づきかもしれませんね。
こちらですが、シンプルなアイコンであれば、わざわざページに画像ファイルを添付たり外部から取得しなくとも、Atlassian側で組み込んであるアイコンフォントを利用することができます。
一覧はこちらになりますので、よかったら参考にしてみてくださいね。 Confluenceのバージョンの関係で、下記のページに載っていても使えないものもあるかもしれませんが、少なくとも「時計」は大丈夫でした。
上記で差し込んでいるHTML中のように、aui-icon, aui-icon-大きさ, aui-iconfont-使いたいアイコンフォント で設定できます。
<span class="aui-icon aui-icon-small aui-iconfont-time">Icon</span>
ということで、適用結果はこのような感じです。(1年経ってないものも確認のためメッセージを出すようにしています)
まとめ
フロントだけで表示を調整させる場合は、いくぶんConfluence本体には優しいのかな...と思いつつ、実際計測していないので分かりませんが、表示されている情報だけでもいろいろ加工が可能です。
- HTMLのソースの中にでてこないメタデータなどは、Ajaxでapiを叩いて取得してから差し込む、といった工夫が必要になります。
- i18n対応したいという場合も含め、もうちょっと頑張るにはプラグイン化が必要かなと思っています。
- バージョンが変わると、ベースのタグや要素名が変更になったりするので、バージョンアップの際には自己責任での修正が必要です。
- 今回のJSとCSSは、Confluence 5.4, 5.6, 5.9.1 で確認しました。
ドキュメントは更新して育てていかないと、すぐに陳腐化してしまいます。 更新状況の『見える化』のために、少しだけ工夫を加えることで、ユーザのみなさんの更新のモチベーションUPにつながればなあ...と思う次第です _ _
Comments (2)
You can clone a snippet to your computer for local editing. Learn more.
Qiitaから来ました。 Confluence 5.9.4で動かしたら動きませんでした。 下記のように修正したら直りました。
AJS部分を修正しました、ありがとうございます! jQuery的な書き方にしています。また、同じくConfluence5.9.4で確認しました。(Atlasssian SDKでの開発用Confluenceにて)