あなたも作れる！Redmine テーマ/redmine-theme-can-you-make

redmine.tokyo 17 登壇時のスライドです。

Transcript

1. あなたも作れる！
   Redmine テーマ
   @akabekobeko redmine.tokyo 17, 2019/11/2
   1
   

   View Slide

2. もくじ
   Redmine テーマとは？
   作ってみる
   リリース
   2
   

   View Slide

3. Redmine テーマとは？
   Redmine テーマとは？ 3
   

   View Slide

4. どのようなものか？
   Redmine を拡張するための⽅法です
   Redmine の⾒た⽬を変化させます
   CSS と JavaScript で構成されます
   Redmine テーマとは？ 4
   

   View Slide

5. 参考例:
   Redmine テーマとは？ 5
   

   View Slide

6. プラグインと⽐べて...
   Redmine 本体の機能やデータベースには触れません
   基本的に⾒た⽬だけを拡張します
   そのためド派⼿な機能追加はできません
   そのかわりに壊れても⾒た⽬が崩れるだけ = 安全
   気軽に作れます！！
   Redmine テーマとは？ 6
   

   View Slide

7. 作ってみる
   作ってみる 7
   

   View Slide

8. テーマの構成ファイル
   主要なものは以下。これらと CSS から参照する画像、Web フォントなどのリソースで構成
   されます。
   stylesheets/
   application.css
   ...通常表⽰の外観を定義
   responsive.css
   ...Web ブラウザー表⽰幅が狭い状態の外観を定義
   favicon/
   favicon.ico
   ...ファビコン
   javascripts/
   theme.js
   ...動的な処理をするための JavaScript
   作ってみる 8
   

   View Slide

9. 環境構築
   テーマのファイル構成⾃体は単純ですが、ゼロから CSS/JS を作り始めるのは厳しいかもし
   れません。そのためスターター キットを⽤意しました。
   これを使うためには以下をインストールする必要があります。
   Node.js (+ npm)
   https://nodejs.org/
   Docker Desktop (Windows/Mac)
   https://www.docker.com/products/docker-desktop
   どちらも公式インストーラーに従ってセットアップすれば OK です。
   作ってみる 9
   

   View Slide

10. スターターの⼊⼿
    スターターは以下に公開しています。
    akabekobeko/redmine-theme-starter
    https://github.com/akabekobeko/redmine-theme-starter
    Git 操作に慣れていれば git clone
    、馴染みがなければ ZIP ファイルをダウンロード & フ
    ォルダーに展開します。フォルダーは好みの名前に変更しても⼤丈夫です。
    作ってみる 10
    

    View Slide

11. スターターの起動
    スターターはコマンドラインで操作します。そのため
    Windows: PowerShell など
    Mac: Terminal、iTerm など
    を起動 (以降、これらをターミナルと呼びます) して以下のコマンドを実⾏します。
    $ cd "
    スターターのフォルダー"
    $ npm install
    これでスターターに必要なものがインストールされます。
    作ってみる 11
    

    View Slide

12. スターターの構成
    .
    └── src/
    ├── assets/
    │ ├── images/
    │ └── stylesheets/
    │ ├── application.css
    │ └── responsive.css
    └── scss/
    ├── App.scss
    ├── Responsive.scss
    └── default/
    ├── application.css
    └── responsive.css
    作ってみる 12
    

    View Slide

13. スターターの構成 2
    フォルダー 役割
    src/assets/ Redmine からテーマとして参照される場所。
    src/assets/images/ テーマの画像ファイル置き場。
    src/assets/stylesheets/ SCSS から変換された CSS ファイルの出⼒先。
    scss/ SCSS ファイル置き場。
    scss/default/ Redmine 標準 CSS 置き場。
    作ってみる 13
    

    View Slide

14. 補⾜ : SCSS とは⼀体？
    SCSS は CSS の強化版です。
    好きな単位で CSS/SCSS ファイルを分割・参照する
    ⾊やサイズの指定に名前をつけて共通する
    などの便利な機能があります。以下はその例。
    @import "./default/application"; //
    外部 CSS/SCSS
    参照
    $color_white: #fff; //
    ⾊の定義
    $size_full: 100%; //
    サイズ
    スターターは SCSS を編集して保存すると CSS に変換する仕組みを提供しています。
    作ってみる 14
    

    View Slide

15. テーマを編集してみる
    それでは実際にスターターを起動して Redmine テーマを作ってみましょう。ターミナルから
    以下のコマンドを実⾏します。
    $ npm start
    すると SCSS ファイルの変更監視モードが起動されます。この状態で SCSS ファイルを編集
    して保存すると、それを察知して⾃動的に CSS へ変換してくれます。
    監視モードを終了させる場合はターミナル上でキーボードから Ctrl
    + C
    を押してくださ
    い。
    作ってみる 15
    

    View Slide

16. Redmine で表⽰してみる
    テーマを Redmine で表⽰してみましょう。ターミナルから Docker を起動します。
    $ docker-compose up -d
    これで Redmine 関連が起動されました。Web ブラウザーから http://localhost:8080/ にア
    クセスすると、Redmine が動作していることを確認できるはずです。
    Redmine にログインしたら管理画⾯から⾃作したテーマを選べるので、動作確認してみまし
    ょう。Redmine を終了させる場合は以下を実⾏してください。
    $ docker-compose stop
    作ってみる 16
    

    View Slide

17. 補⾜ : Docker とは⼀体？
    Docker とはコンテナと呼ばれる⼩さな OS 環境を複数、同時に制御するためのソフトウェア
    です。と⾔うと難しく感じるかもしれませんが、ざっくり要約するとこんな感じです。
    誰かが作った環境を⼿軽に利⽤できる
    環境構築の難しい Redmine も「誰かが」作ったものを利⽤すればいい
    Redmine 公式イメージもあります https://hub.docker.com/_/redmine
    テキストで環境や設定を管理できる
    編集や流⽤が簡単で Git などの履歴管理とも相性がよい
    慣れるまでは誰かの鉄板構成をコピペでも OK
    とても便利なので最近の Web 開発でもよく使われています。
    作ってみる 17
    

    View Slide

18. Live Coding
    これまで解説した操作を実際に私のマシンで実⾏します。更に
    1. Redmine にログイン
    2. テーマを⾃作するものに変更
    3. テーマを編集して Redmine に反映
    して Redmine テーマ作成の雰囲気を味わってみましょう。
    作ってみる 18
    

    View Slide

19. リリース
    リリース 19
    

    View Slide

20. 作ったテーマを配布する
    作ったテーマの配布⽤イメージを作成します。まずはスターターの package.json
    を編集し
    ましょう。
    {
    "name": "mytheme",
    "version": "1.0.0",
    "author": "author"
    }
    name
    = テーマ名、 version
    = バージョン、 author
    = 作者です。これを⾃分⽤に編集し
    て保存します。
    リリース 20
    

    View Slide

21. 作ったテーマを配布する
    ターミナルから以下のコマンドを実⾏します。
    $ npm release
    少し待つとスターターのフォルダー内に テーマ名-
    バージョン.zip
    というファイルが出⼒さ
    れます。これが配布⽤イメージです。
    この ZIP を展開して Redmine のテーマ フォルダー内に配置することで、ユーザーはあなた
    のテーマを利⽤できます。
    リリース 21
    

    View Slide

22. テーマ開発
    よもやま話
    テーマ開発よもやま話 22
    

    View Slide

23. HTML/CSS 構造の調査⽅法 1
    テーマ作成にあたり、どの CSS がどこに適⽤されるかを知る必要があります。これをどう調
    べているか。まずは redmine.org の資料を読んでみます。
    http://www.redmine.org/projects/redmine/wiki/HowTo_create_a_custom_Redmine_t
    heme
    しかしこれは基本部分の解説にとどまり、HTML/CSS の階層やクラス名などにはほとんど⾔
    及していません。
    そもそも詳細な HTML/CSS の資料を Redmine のバージョン更新に追従しながら書くのも難
    しいでしょうから、仕⽅のないことです。
    テーマ開発よもやま話 23
    

    View Slide

24. HTML/CSS 構造の調査⽅法 2
    ではどのように調査すればよいか。私の場合は以下のようにしています。
    1. Redmine を Chrome や Firefox の開発ツールで開く
    2. 変更したい箇所を開発ツールで選択して HTML/CSS を特定
    地道な作業になりますが、Redmine 標準テーマの CSS でもクラス定義などは表⽰部分で⼤
    まかにまとまっているので、意外にいけます。
    テーマ開発よもやま話 24
    

    View Slide

25. theme.js
    テーマは基本的に CSS で定義します。しかしボタン追加など UI の構造に踏み込んで拡張し
    たい場合は theme.js
    を使います。
    私の開発している minimalflat2 というテーマでは、Redmine のプロジェクト⼀覧をツリー表
    ⽰するのに利⽤しています。
    ちなみに Redmine は jQuery を利⽤している (= 読み込んでいる) ので、 theme.js
    からも
    参
    照できます。
    テーマ開発よもやま話 25
    

    View Slide

26. 参考例 :
    テーマ開発よもやま話 26
    

    View Slide

27. redmine.org
    テーマを作成して公開する場合、redmine.org の Wiki にある Redmine theme list へ掲載す
    ることをオススメします。現在、ここが実質的な公式のテーマ⼀覧ページだと思われます。
    http://www.redmine.org/projects/redmine/wiki/Theme_List
    redmine.org は Redmine で運⽤されています。そのるため、まずはアカウント登録しましょ
    う。テーマ情報として記述する内容については、先⾏例を参考にしてください。
    このページは年ごとに区切られているので、テーマを公開する年にあった場所へ掲載しま
    す。テーマを更新したら Latest release などにも反映してゆきましょう。
    テーマ開発よもやま話 27
    

    View Slide

28. 質疑応答
    テーマ開発よもやま話 28
    

    View Slide

29. ご清聴
    ありがとうございました
    あなたも作れる！Redmine テーマ 29
    

    View Slide