UTSUWA は写真やコンテンツを入力すればそのまま企業サイトとして成り立つ構成を備えた、実用的でモダンなテーマです。また、CSS変数でカラーを変更するだけで手軽にサイト全体の雰囲気を変えることができます。こうした特長から、Web の初学者の方、a-blog cms の初心者の方にとっても即戦力となるテーマなので、ぜひ広く使っていただきたいと考えています。このエントリーでは、そういった初学者、初級者の方を対象としながら、中級者、上級者の方にもご紹介したい UTSUWA テーマの豊富なユニット類についても解説していきます。

UTSUWAテーマサンプル を確認しながら読み進めてください。

CSS 変数で色を変更する

/include/head/css-variables.css で CSS 変数を変更することによって簡単にサイト全体のカラーリングを変更することができます。

主な変数

• 同じ色を使いたい場合 CSS ファイル内では var(--color-primary)のように指定できます。
• Sass では、/src/scss/global/_variables.scss で CSS 変数をいったん Sass の変数に渡しています。

カラー変更のコツ

• 初期設定の色と明度があまり変わらない色を指定するとコントラストを維持できます。
• --color-white、--color-black、--color-grayxx といった無彩色の指定をニュアンスを持った色に変更するのもお勧めです。

テンプレートが分かりやすく、コンテンツの編集も簡単

UTSUWA は全体的にワンカラムのレイアウトで、すべて /_layouts/base.html を ベースにしているのでテンプレートもシンプルで分かりやすくなっています。

たとえば /_top.html でも、パーツ毎に @include 文とコメントがあるので、不要なパーツをコメントアウトしたり、順番を入れ替えたりするのも簡単です。トップページのそれぞれのパーツのコンテンツは表示画面側からも編集、設定しやすくなっています。

エントリーコードが空のエントリーではエントリータイトルが表示されない

デモデータの企業情報、お問い合わせ、採用情報カテゴリーのようにエントリーコード（ファイル名）が空のエントリーではエントリータイトルが表示されなくなっています。カテゴリートップをエントリー扱いにする場合にはカテゴリー名とエントリータイトルを揃えておくと管理画面においても分かりやすくなります。

エントリーサマリーのスタイルの種類

UTSUWAではエントリーサマリーにさまざまなスタイルがあります。すべてのエントリーサマリーでhover時にサムネイルが拡大されます。

事業紹介（/include/module/template/Entry_Summary/thumbnail.html)

事業紹介（service）カテゴリーインデックスのエントリーサマリーはサムネイルを大きくとったスタイルです。このスタイルはモジュールユニットにおいても thumbnail.html を選択すればそのまま使用できます。

お知らせ（/include/entry/summary.html）

画像がないエントリーも多いことが想定されるお知らせ（news）カテゴリーのインデックスでは、サムネイルがあってもなくても美しくレイアウトされるように工夫されています。CSS Grid が使用されています。

スタッフブログ（/include/entry/summary-blog.html）

スタッフブログ（blog）カテゴリーのインデックスはオーソドックスなカードスタイルでPC時4カラムです。

お問い合わせ

お問い合わせ（contact）カテゴリーには「お問い合わせ」「お問い合わせ完了ページ」の2件のエントリーがあり、それぞれ赤枠で囲った箇所がエントリーのユニットとして編集可能です。

フッター上CTAについて

CTA 関連のエリアが、どのように表示されているかを見ていきます。

グローバルな フッター上 CTA

/_layouts/base.html からインクルードされているグローバルな CTA のモジュールIDは MF_cta_visual_global（主要なCTA） です。サイト内のほとんどのエントリーテンプレート、インデックステンプレートでは footer-cta セクションを上書きしていないのでこの CTA がフッター上に表示されています。

トップページの CTA

トップページでは footer-cta セクションは上書きされ、テンプレートはグローバルなものと同じですがモジュールIDは MF_cta_visual_top で設定されています。グローバルな CTA より余白のサイズがゆったりめにとられ、吹き出しがない代わりにリード文や概要文、ボタンの文言がより詳細になっています。確認してみてください。

お問い合わせ、採用情報、事業紹介エントリーの CTA

お問い合わせ（contact）カテゴリーのエントリーテンプレートでは、footer-cta セクションは上書きによって空になっています。お問い合わせフォームでは実際の案件でもこのようにユーザーが入力に集中できるようになっていることが多いでしょう。

採用情報、事業紹介エントリーの CTA は上書きされて、グローバルな CTA ではなく、 /include/parts/cta.html をインクルードしてエントリーフィールドやカテゴリーフィールドを表示しています。

独自に書き換えられているテキストユニットについて

UTSUWA テーマでは、ユニットの表示側のテンプレートが /include/unit.html で独自に書き換えられています。ここでは特に使用頻度が高く、影響が大きいテキストユニットの書き換えについて解説します。

テキストユニットは全て

 <div class="entry-text-unit is-xx"></div>

で囲われます。

• div で囲うことによって不要な回り込みを防いでいます。
• .entry-text-unit クラス内の要素にスタイルを適用することによって、エントリー内のテキストユニット以外のカスタムユニットなどの要素にスタイルがあたってしまうことを防いでいます。
• .is-xx の部分には .is-p などテキストタグセレクトの内容が入り、 /src/scss/_entry.scss においてスタイルの調整に使用されています。

カスタムユニットの種類について

UTSUWA に用意されているカスタムユニットは次の 5種類です。

メッセージ

デモデータでの使用箇所は 採用情報トップ です。

余白

デモデータではユニットによる要素の掲載例の画像間に使われています。

罫線

デモデータではユニットによる要素の掲載例のリストの間に使われています。

価格表

デモデータではユニットによる要素の掲載例のエントリー末尾近くに使われています。

目次

デモデータではユニットによる要素の掲載例の冒頭に使われています。 目次ユニットは a-blog cms の組み込みJSのひとつで、エントリー内の見出し要素に自動でアンカーリンクを生成、表示します。

ユニットグループの種類

ユニットグループも豊富に用意されています。デモデータではたとえばユニットによる要素の掲載例の価格表には「背景色：グレイ（全幅）」が使われています。

まとめ

UTSUWA はそのままで企業サイトとして使える工夫が随所にあり、その分初心者にとっても使いやすく、中級者、上級者にとってはカスタマイズのベースとしたり、他のテーマを使うときにもカスタマイズのヒントが得たりすることができるテーマです。ぜひご活用ください。

Beginnerテーマ以外の公式テーマには、 webpack のビルド環境が用意されています。このエントリーでは、webpack に馴染みがない方を対象に、導入の手順を解説します。

導入する前にはとっつきにくい印象のある webpack ですが、いったん慣れてしまうと意外に簡単でとても便利です。特に a-blog cms の公式テーマに同梱されているビルド環境はすべて設定済みであとは「使うだけ」なので最初の一歩として最適です。

（このエントリーの末尾で webpack を使用しない場合の注意点 についても触れています。）

webpack 導入のメリット

• 文法チェックやプロパティ順の整理を自動でやってくれるのでコードが読みやすく、メンテナンスしやすくなる
• スタイルや機能のモジュール化をしやすいので他案件への転用が簡単になる
• 使用しているエディタやツールに依存しないのでチームでの開発環境を揃えることができる
• LiveReload ( npm run start )を使うとファイルを保存すればブラウザが自動でリロードされるので開発効率が上がる
• CSSは /dest/bundle.min.css、JavaScript は /dest/bundle.js にまとめられ、パフォーマンスが向上する
• 慣れてくると外部のライブラリを読み込んで利用することも簡単にできるようになる

webpack 導入の手順

node.js をまだインストールしていない場合は .node-version でバージョンを確認し、node.js をインストールする

2022年8月現在、UTSUWA同梱のビルド環境の .node-version ファイルを開くと v14.16.0 になっています。

公式サイトのインストーラを使ってインストールする場合は、バージョン一覧から該当のバージョンを選んでください。コマンドでの操作に慣れている場合は、nodenv (Mac)、fnm (Windows) などの node バージョン管理ツールを使用するのがお勧めです。

インストールした後、ターミナルやコマンドプロンプトで

$ node -v （ または node --version ）

と打って該当のバージョン番号が表示されればオーケーです。

package.json でローカル環境のアドレスとテーマ名を設定する

LiveReload ( npm run start ) を使う場合に基準となる設定です。LiveReload を使わない場合はこの手順は飛ばしてかまいません。

"config": {
  "local": "acms.lab", （ http:// や https:// は不要です ）
  "theme": "テーマ名" （ テーマ名を utsuwa 以外にする場合は変更します ）
},

cd コマンドで themes/テーマ名 に移動して npm を使ってパッケージをインストールする

cd は change directory の略です。今いる場所が分からない場合は pwd ( present working directory ) コマンドで確認できます。

$ cd www/themes/テーマ名 （ パスはローカル環境のフォルダ構成や現在地によって異なります ）
$ npm i（ または npm install ）

必要なパッケージがインストールされると themes/テーマ名/node_modules というフォルダができて中にたくさんのファイルがダウンロードされます。ダウンロードが終わったらメッセージを見て、必要そうであれば

$ npm audit fix

しておきましょう。

※ 子テーマを使用する場合でも、ビルド環境は親テーマだけでまとめておきましょう。

ファイルを watch してコンパイルする

 $ npm run dev

あるいは

 $ npm run start

で src フォルダ内のファイルを watch して dest フォルダにコンパイルし始めます。npm run start は LiveReload の機能を含んでいるので、src フォルダ内のファイルを変更して保存するたびに自動的にブラウザがリロードされます。LiveReload 使用時にはブラウザのURL欄には「localhost::3000」が表示されます。これらのコマンドを止めるには「Ctrl + C」を押します。

ファイルを build する

納品時やリモートへの反映時などには

 $ npm run build

でファイルを build することによって、最適化されたコンパイルになります。このコマンドは実行に少しだけ時間がかかり、終わったら自動的に止まります。

JavaScript について

/src/js/index.js からさまざまなファイルを読み込んで /dest/bundle.js にコンパイルされています。その内容については各テーマフォルダに同梱されている README.md をご確認ください。

エラーが出たら

コマンドが問題なく実行されているときにはターミナルの画面に実行結果がスラスラと表示され続けていますが、赤字でエラーが表示された場合は、エラーメッセージを読んで対処しましょう。

Sass のルールは .stylelintrc、 JavaScript のルールは .eslintrc の rules のブロックに追記することでそれぞれ個別にオンオフすることができます。.stylelintrc では true / null で、.eslintrc では 0 / 1（警告を出す） / 2（エラーを出す）という値で設定します。たとえば、.stylelintrc の rules ブロックに

 "block-no-empty": null,

と追記すると、Sass ファイルに空のブロックがあってもエラーがでなくなります。

より高度な内容について

これだけで一通りのビルドはできますが、全CSSのインライン化や組み込みJSの整理、各ファイルの役割など、より高度な内容についてはこちらもご確認ください。

webpack を使用しない場合の注意点

補足として、webpack を使用しない場合に抑えておいたほうが良い点について説明します。

独自カスタマイズ用の CSS と JavaScript

/include/head/link.html において

<link rel="stylesheet" href="/dest/bundle.min.css">
<link rel="stylesheet" href="/css/style.css">

/include/head/js.html において

<script src="/dest/bundle.js" defer></script>
<script src="/js/script.js" defer></script>

のように独自カスタマイズ用の CSS ファイル、JS ファイルへのパスを追記して、追加した CSS ファイルでスタイルを上書き、追加していきます。script タグでは JSファイルの実行順を担保するため、async属性ではなく、defer属性を使います。

不要なファイルを削除する

不要なファイルはそのままにしておいても問題はありませんが、削除するとファイル構成が分かりやすくなります。コンパイルによる予期せぬ先祖がえりを防ぐためにも削除しておくことをお勧めします。

utsuwa/ 直下の不要なファイル

• .eslintrc
• .node-version
• .stylelintrc
• babel.config.js
• package-lock.json
• package.json
• webpack.analyze.js
• webpack.common.js
• webpack.dev.js
• webpack.prod.js
• webpack.uncompress.js

/src/ フォルダ

Sassを使用しない場合はフォルダごと削除してください。Sassを使用する場合は /src/scss を残して、お使いのコンパイルツールにあった設定にしてください。

Square の Webhook API を活用することで、Square のダッシュボードから Oauth 認証を解除することができます。この記事では、Square のWebhook API と連携する手順を説明します。Webhook APIと連携することで、 Square の販売者用ダッシュボードから OAuth 認証を解除することができるようになります。

Webhook API との連携手順

Webhook API との連携は以下の手順で設定することができます。

1. Square Developer で Webhook を登録する
2. ShoppingCart設定に Signature Key を設定する

Square Developer で Webhook を登録する

まず、Square Developer にログインし、連携する（ご利用の） アプリケーションを選択してアプリケーションの個別ページに移動してください。次に、左のパネルから Webhooks > Subscriptions​をクリックして、Webhook subscriptions のページに移動します。Webhook subscriptions のページに移動できたら、Add subscription ボタンをクリックします。すると、Webhook の登録に必要な項目を入力するためのフォームが表示されるので入力して保存してください。

URLの入力フィールドには、https://ドメイン/bid/ブログID/webhook/shopping-cart/square/ ​を入力してください。

Events の項目は oauth.authorization.revoked の項目にチェックを付けて保存してください。また、Sandbox モードと Production モードで Webhook の設定が異なるため注意してください。

Eventsの項目で oauth.authorization.revoked の項目を選択する

Webhook の登録が完了すると、Webhooks 一覧に表示されるようになります。一覧に表示された Webhook をクリックすると詳細情報が表示されるので、「Signature Key」をメモ帳などに控えておいてください。

これで、 Square Developer で Webhook を登録する作業は完了です。

ShoppingCart設定に Signature Key を設定する

次に、ShoppingCart拡張アプリに先ほど控えた「Signature Key」を設定します。ShoppingCart 設定 の決済サービスとの連携タブを表示して、Signature Key の項目に、先程控えた「Signature Key」を入力して保存してください。

ShoppingCart 拡張アプリに「Signature Key」を設定する。

これで、ShoppingCart設定に Signature Key を設定する作業は完了です。

Webhook の動作を確認する

ここまでの設定が完了したら、無事 Webhook API との連携が完了しています。実際に Webhook が正常に動作しているか確認しましょう。Square の販売者用ダッシュボードから OAuth 認証を解除したときに、ShoppingCart 拡張アプリでも OAuth 認証が解除されているかを確認します。Square の販売者用ダッシュボードから OAuth 認証を解除は、販売者用ダッシュボード > 設定 > アプリ外部ツール から行うことができます。

また、Square Developer では、Webhook API の イベントログを確認できます。イベントログから、Webhook のリクエストがうまくいっているかどうかを確認することができます。詳しくは Square Event Logs のドキュメントを参照してください。

まとめ

Webhook API を利用することで Square のダッシュボードから Oauth 認証を解除するということができるようになります。Webhook 連携をしていない場合、Square のダッシュボードから Oauth 認証を解除しても、ShoppingCart 拡張アプリでは、Oauth 認証が解除されたことにならず、よきせぬ不具合が起こる可能性がありますので、設定することをおすすめいたします。

Square との OAuth 認証で使用されているアクセストークンを cron から更新する方法を紹介します。

OAuth 認証を行う場合、APIを提供する側のサーバー（リソースサーバー）のAPIを利用するためにアクセストークンというトークンが発行されます。アクセストークンには有効期限が設定されているため、有効期限が切れる前に新しいアクセストークンを取得する必要があります。

Squareでは、7日以内ごとに OAuth のアクセストークンを自動的に更新することを推奨しています。7日以内に更新することで、エラーを発見し解決するための十分な時間を確保できます。アクセストークンの更新を行わない場合、アクセストークンの更新の失敗を見逃し、Webサイトの運用者やその顧客に予期せぬ経験をもたらすリスクが高くなります。

ShoppingCart 拡張アプリでは、インストール時から標準で用意されている a-blog cms をスタンドーアローン起動できるプログラムを利用して、cron から OAuth 認証のアクセストークンを定期的に自動更新することができます。

a-blog cms インストールした時点で、cron/example.php に a-blog cms をスタンドーアローン起動できるプログラムを利用するためのサンプルファイルが用意されています。この記事ではこの cron/example.php を利用することを前提として説明します。

cron/example.php を以下のように記述します。

<?php

// デフォルトではBID=1の文脈で実行されるため、
// OAuth認証を行っているブログのBIDが1以外の場合、
// php/standalone.php を読み込むより前にBIDを設定してください。
define('BID', 2);

// 設置場所に合わせて、php/standalone のパスを合わせてください。
require_once dirname(__FILE__) . '/../php/standalone.php';

use Acms\Plugins\ShoppingCart\ServiceProvider;

set_time_limit(0);
ini_set('memory_limit', '512M');

acmsStandAloneRun(function () {
    acmsStdMessage('[Start] 処理を開始しました');
    try {
        // ShoppingCart拡張アプリを初期化
        $App = new ServiceProvider();
        $App->init();

        App::make('square.service.oauth');

        acmsStdMessage('[Success] 処理を完了しました');
    } catch (\Exception $e) {
        acmsStdMessage('[Error] ' . $e->getMessage());
        return false;
    }
    return true;
});

実行時にアクセストークンの更新が必要かどうかを判定し、必要であればアクセストークンの更新を行います。

次に、サーバーでcronの設定を行います。7日おきに実行されるように設定したいため、例えば以下のように設定します。

0 0 */7 * * php path/to/cron/example.php

これで7日おきに、cronが実行され、アクセストークンの更新が必要かどうかを判定し、必要であればアクセストークンの更新を自動で行う事ができるようになります。

＊ この内容は Ver. 3系では、この機能自体廃止されているので発生しません。

サーバーの構成変更時などに、エントリー保存や設定変更などPOST操作を行うと固まってしまい、タイムアウトエラーが出る時があります。

この場合、ダッシュボードから設定できる「キャッシュ生成リスト」が設定されていないかご確認をお願いします。 この機能は、POST時に自動的にキャッシュを生成するようにHTTPリクエストが飛ぶようになっているのですが、 サーバーの変更でこの機能が動作しなくなってタイムアウトしている可能性が考えられます。