こんにちは。
この LABO BLOG を Liferay CE 7.2 から 7.4 へアップグレードした際に、7.2 向けに作っていたテーマも 7.4 向けに更新しました。今回は、そのテーマのアップグレード手順と、作業中につまずいたポイントをご紹介します。

Liferay 本体のアップグレード手順は、別の記事「Liferay 7.2 から 7.4 へのアップグレード手順とハマりどころ」で紹介しています。

7.2 向けのテーマは 7.4 にそのままデプロイできない

7.2 向けに作ったテーマの war ファイルを 7.4 にデプロイすると、次のエラーになります。

AutoDeployException: xxx-theme.war does not support this version of Liferay

テーマが 7.2 向けとして作られていて、7.4 に対応していないためです。Liferay Theme Generator で作ったテーマであれば、gulp upgrade で新しいバージョン向けに更新できます（Upgrading a Theme）。

今回の環境

注意点：gulp upgrade は1回で1バージョンずつ

gulp upgrade を実際に動かしているのは、テーマのプロジェクトに入っている liferay-theme-tasks です。1回の実行で上がるのは、1つ先のバージョンまでです。

• liferay-theme-tasks 9 系：7.1 → 7.2、7.2 → 7.3 に対応（7.3 → 7.4 には非対応）
• liferay-theme-tasks 11 系（今回確認したのは 11.5.6）：7.1 → 7.2、7.2 → 7.3、7.3 → 7.4 に対応

7.2 向けのテーマには 9 系が入っているので、そのまま gulp upgrade を実行しても、テーマは 7.3 向けにしかなりません。そこで、先に liferay-theme-tasks を 11 系に上げてから、gulp upgrade を2回（7.2 → 7.3、7.3 → 7.4）実行します。

また、9 系は gulp 3 と node-sass を使っていて、新しいバージョンの Node.js では動きません。最初に 11 系に上げておけば、この問題も避けられます。

アップグレード手順

1. 必要なツールを用意する

公式ドキュメントの手順に合わせて、Theme Generator と Yeoman、Gulp をインストールします。

npm install -g generator-liferay-theme@10.2.1
npm install -g yo gulp

liferay-theme-tasks 11 系は Node.js 16 以降が必要です。

2. テーマのファイルをバックアップする

gulp upgrade はテーマのファイルを書き換えるため、事前にバックアップしておきます。Git で管理している場合は、コミットしておけば十分です。

3. liferay-theme-tasks を 11 系に上げる

テーマのフォルダで、liferay-theme-tasks と gulp を新しいバージョンに上げます。

npm install --save-dev liferay-theme-tasks@11.5.6 gulp@4.0.2

4. 1回目の更新（7.2 → 7.3）

npx gulp upgrade

バックアップを取ったかどうかを聞かれるので、y で進めます。設定ファイルと依存パッケージが 7.3 向けに書き換わり、最後に npm install が自動で実行されます。

package.json の liferayTheme の version が "7.3" になっていれば成功です。

5. 2回目の更新（7.3 → 7.4）

もう一度 gulp upgrade を実行します。

npx gulp upgrade

今回は、Bootstrap 3 から 4 への互換レイヤーを追加するかどうかも聞かれます。公式ドキュメントによると、互換レイヤーは 7.4 GA1 向けのもので、それ以降のバージョンでの動作は保証されていません。テーマが Bootstrap 3 との互換を必要とする場合だけ追加します。

6. 更新された内容を確認する

次のファイルが 7.4 向けになっているかを確認します。

• src/WEB-INF/liferay-look-and-feel.xml：DOCTYPE が 7.4.0 の DTD、<version>7.4.0+</version> になっている

  <!DOCTYPE look-and-feel PUBLIC "-//Liferay//DTD Look and Feel 7.4.0//EN" "http://www.liferay.com/dtd/liferay-look-and-feel_7_4_0.dtd">
  
  <look-and-feel>
      <compatibility>
          <version>7.4.0+</version>
      </compatibility>
  

• src/WEB-INF/liferay-plugin-package.properties：liferay-versions=7.4.0+ になっている

  liferay-versions=7.4.0+
  

• package.json：liferayTheme の version が "7.4" になり、依存パッケージが 7.4 向けになっている

  "liferayTheme": {
    "version": "7.4"
  },
  "devDependencies": {
    "compass-mixins": "0.12.10",
    "gulp": "4.0.2",
    "liferay-frontend-css-common": "6.0.8",
    "liferay-frontend-theme-styled": "6.0.54",
    "liferay-frontend-theme-unstyled": "6.0.45",
    "liferay-theme-tasks": "^11.5.6"
  }
  

  7.3 までの liferay-frontend-common-css は、7.4 では liferay-frontend-css-common となり、common"と"css"の順番が入れ替わります。

Font Awesome を使っているテーマでは、liferay-font-awesome も残ります。

7. テーマのコードを修正する

テーマによっては、CSS やテンプレートの修正も必要です。今回のテーマではウィジェット設定画面で表示崩れが発生したので、次の点を直しました。

• src/css/_clay_variables.scss に $cadmin-selector: ".cadmin"; を追加する
• src/css/_imports.scss から、7.2 のころから入っていた @import "compat/mixins"; を削除する
• src/templates/portal_normal.ftl の hide-accessible クラスを、Bootstrap 4 の sr-only クラスに置き換える

依存パッケージを 7.4 向けにそろえたことと、これらの修正で、ウィジェットの設定画面の表示崩れも解消しました。

8. ビルドする

npx gulp build

dist フォルダに war ファイルが作られます。

9. デプロイして表示を確認する

war ファイルを Liferay の deploy フォルダに置いてデプロイします。

sudo cp -a dist/xxx-theme.war [Liferay Home]/deploy/

デプロイしたら、テーマを適用しているページを開いて、表示が崩れていないか確認します。ページの表示だけでなく、ウィジェットの設定画面など管理用の画面も確認しておくと安心です。ページは問題なく見えても、管理画面だけ崩れることがあります。

おわりに

テーマのアップグレードで特に大事だと感じたのは、次の点です。

• gulp upgrade は1回で1バージョンずつしか上がらず、対応できる範囲はテーマに入っている liferay-theme-tasks のバージョンで決まる
• 7.2 から上げる場合は、先に liferay-theme-tasks を 11 系にしてから gulp upgrade を2回実行する
• アップグレード後は、設定ファイルのバージョンだけでなく、package.json の依存パッケージが目的のバージョン向けになっているかも確認する
• ページの表示だけでなく、管理画面も含めて表示を確かめる

今回の紹介は以上です。テーマのアップグレードを検討されている方は、ぜひ参考にしてみてください。

※本記事の内容は Liferay CE 7.4.3.132 GA132 時点のものです。