どのようにFusionAuthの高度な登録フォームのテーマ

ユーザーが登録しているとき、あなたがしたい最後のことは、彼らの方法で取得したり、それらを混乱させる.このチュートリアルでは、テーマを変更することで高度な登録フォームの表示を改善します.
以前は、我々はself service registration form 不動産webappとauthサーバーとして使用fusionauth.それは彼らの家の購入ニーズについての情報を取得した2つのステップ形式だった.しかし、その形はわずかな要素があった.特に、どのデータフィールドがどのフォームフィールドに入るのかはどちらのデータであったかは明らかではなかった.
このチュートリアルではprevious one そして、テーマを変えることを歩きます.このチュートリアルでは前のフォームを参照しますが、作成したフォームにも適用できます.

fusionauthセットアップ

“設定”に移動し、“APIキー”に行くことによってAPIキーを作成します.このキーを使ってテーマ管理のいくつかをスクリプト化します.つまり、このエンドポイントの許可が必要です.

/api/theme : 全方法

エンドポイントやメソッドもチェックできません.これはスーパーユーザキーを作成します.さて、少なくともすべてのfusionauth APIにアクセスすることができます.これは、チュートリアルのための罰金ですが、生産のために、アクセスを制限してください.

単一または複数のテナントの設定のカスタムテーマを作成する

次のステップは、新しいテーマを作成することです.あなたは、ユーザーエクスペリエンスを向上させるメッセージのいくつかを変更され、デフォルトのテーマは読み取り専用です.テーマはテナントでテナントに割り当てられているので、いずれかのデフォルトテナントのテーマを変更することができます(このチュートリアルは何か)または新しいテナントを作成し、それに新しいテーマを割り当てる.FusionAuthは、ボックスから複数のテナントをサポートしていますので、いずれかの方法が動作します.

This is the theme you’ll modify throughout the rest of this blog post.

“カスタマイズ”と“テーマ”に移動します.既存の“fusionauth”テーマを複製します.“不動産アプリケーション”などの何か有意義なテーマに名前を変更します.青いアイコンをクリックして保存する前に、次のようにします.

“テナント”に移動し、“デフォルト”テナントを編集します.“一般的な”タブに移動し、新しいテーマに設定“ログインテーマ”を更新します.画面が表示されるときに設定を保存します.

テーマのカスタマイズ

テーマをカスタマイズすると、ユーザーが見ているものを完全に制御できます.リマインダーとして、登録フローの最初のステップはフォーム作成ポストの最後にあります.

我々は理解できるプレースホルダーとラベルを追加しようとしているが、より多くのことができますより多くのためにチェックしてください.
開始するには、管理ユーザーインターフェイスで、“カスタマイズ”と“テーマ”に移動します.あなたが上に作成し、そのIDをコピーするテーマを見つけます私はde03191a-9369-4732-a9c4-0467d1f26482 .

API経由でテーマを変更する

ヒントと妥当性検査メッセージを変更するには、メッセージを含むファイルを編集する必要があります.これは、Javaのプロパティファイルであり、管理ユーザーインターフェイスまたはAPIを介して変更することができます.この投稿では、APIを使用して変更を行います.これは、FusionAuthが取るAPI最初のアプローチの力を示します、そして、あなたがそうしなければならないように、ファイルをバージョン管理する方法を提供してください.
これらのスクリプトは、http://localhost:9011 ; そうでなければ、それに応じて調整してください.これらのスクリプトはalso available on GitHub . また、あなたが持っている必要がありますjq Python 3がローカルにインストールされています.

ローカル編集用のテーマファイルの取得

まず、メッセージを取得します.あなたが簡単に編集するためのテキストファイルにします.以下はJSONを改行されたファイルに変換するシェルスクリプトです:

API_KEY=<your api key>
THEME_ID=<your theme id>

curl -H "Authorization: $API_KEY" 'http://localhost:9011/api/theme/'$THEME_ID|jq '.theme.defaultMessages' |sed 's/^"//' |sed 's/"$//' |python3 convert.py > defaultmessages.txt

The convert.py スクリプトは改行文字を実際のものに変えます:

import sys

OUTPUT = sys.stdin.read()
formatted_output = OUTPUT.replace('\\n', '\n')
print(formatted_output)

このスクリプトは、メッセージファイルのためだけに動作しますが、HTMLテンプレートファイルなどのテーマの他の部分を処理するために調整できます.これは、読者のための演習として残っている;プル要求は歓迎です.

メッセージファイルの変更

APIキーとテーマIDを加え、スクリプトを実行します.あなたはAで終わるでしょうdefaultmessages.txt カレントディレクトリのファイル:

#
# Copyright (c) 2019-2020, FusionAuth, All Rights Reserved
#
# Licensed under the Apache License, Version 2.0 (the \"License\");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0

# ...

# Webhook transaction failure
[WebhookTransactionException]=One or more webhooks returned an invalid response or were unreachable. Based on your transaction configuration, your action cannot be completed.

それは約200行です以上が抜粋である.あなたの好きなテキストエディタで開きます.

If you are interested in localized messages, check out the fusionauth-localization project.

登録フォームを改善するには、「カスタム登録」セクションに値を追加します.このプロパティファイルのセクションを維持することは強制されません.ini しかし、必要なものだけを変更するのは良い考えです.FusionAuthへのアップグレードは、プロパティファイルを変更し、変更をマージする必要がありますので、より簡単です.以下に行を追加するセクションを示します.

# ...
#
# Custom Registration forms. These must match the domain names.
#
user.email=Email
user.password=Password
user.birthDate=Birthdate

#
# Custom Registration form validation errors.
#
[confirm]user.password=Confirm password
# ...

メッセージファイルのキーは、登録フォームのフィールドキーと一致します.ここでは、不動産申請登録フォームのプレースホルダーを設定するために追加するものです

user.firstName=Your first name
user.mobilePhone=Your mobile phone num
registration.data.minprice=Minimum home price
registration.data.maxprice=Maximum home price
registration.data.geographicarea=Where are you looking?

あなたはプレースホルダーに限定されません.妥当性検査メッセージを次のセクションに追加できます.# Custom Registration form validation errors . あなたはDefault validation errors 利用可能なすべてのエラーの例のセクション.
指定したフォームフィールドの特定のエラーを提供するためにキーを追加します.たとえば、価格範囲情報が省略されたときにユーザーフレンドリーなエラーメッセージを表示するには、次のプロパティーを追加します.

[invalid]registration.data.minprice=Minimum home price required
[invalid]registration.data.maxprice=Maximum home price required

あなたが加える価値のどれかdefaultmessages.txt ダブルクォートしてエスケープします.\" . これは、このファイルがJSONに変換されたときに問題を防ぎます.これは変更がfusionAuthに反映される前に起こります.

FusionAuthのテーマの更新

あなたのすべての変更をした後defaultmessages.txt , APIが期待するJSON形式に戻す必要があります.また、以前に削除されたキーと引用符を追加する必要があります.最後に、更新要求をfusionAuthにする必要があります.更新のためにPATCH メソッドは、オブジェクトの要素のみを更新します.
このスクリプトはdefaultmessages.txt ファイル

API_KEY=<your api key>
THEME_ID=<your theme id>

FILE_NAME=out.json$$

awk '{printf "%s", $0"\\n"}' defaultmessages.txt |sed 's/^/{ "theme": { "defaultMessages": "/' | sed 's/$/"}}/' > $FILE_NAME

STATUS_CODE=`curl -XPATCH -H 'Content-type: application/json' -H "Authorization: $API_KEY" 'http://localhost:9011/api/theme/'$THEME_ID -d @$FILE_NAME -o /dev/null -w '%{http_code}' -s`

if [$STATUS_CODE -ne 200]; then
  echo "Error with patch, exited with status code: "$STATUS_CODE
  exit 1
fi

rm $FILE_NAME

このスクリプトをdefaultMessages.txt ファイル.これはあなたのテーマに変更を適用します.
変更を表示するには、FusionAuth管理ユーザーインターフェイスの「アプリケーション」タブに移動して登録URLを見つけます.アプリケーションを表示し、登録URLをコピーします.

忍者ウィンドウを開き、このURLを参照してください.最初のページにあなたの光沢のある新しいプレースホルダを見るべきです.

最初の手順を入力すると、2番目のページに正しいヒントが表示されます.

検証とテーマ

2番目の画面で、価格範囲を指定せずに登録フォームを送信する場合は、上記のエラーメッセージが表示されます.

フォームラベルの追加

あなたのフィールドの表示をカスタマイズすることができますcustomField マクロ.これはあなたのテーマの“ヘルパー”のセクションです.APIを使用するのではなく、管理ユーザーインターフェイスで直接編集しましょう.
“テーマ”に移動し、テーマを編集します.をクリックして“ヘルパー”と下部にスクロールします.あなたは修正されますcustomField マクロ.これがデフォルトの実装ですFreeMarker macro :

[#macro customField field key autofocus=false placeholder=""]
  [#assign fieldId = field.key?replace(".", "_") /]
  [#local leftAddon = field.data.leftAddon!'info' /]
  [#if field.control == "checkbox"]
    [#if field.options?has_content]
      [@checkbox_list field=field id="${fieldId}" name="${key}" required=field.required autofocus=autofocus options=field.options /]
    [#else]
      [@checkbox field=field id="${fieldId}" name="${key}" required=field.required autofocus=autofocus /]
    [/#if]
  [#elseif field.control == "number"]
    [@input id="${fieldId}" type="number" name="${key}" leftAddon="${leftAddon}" required=field.required autofocus=autofocus placeholder=theme.optionalMessage(placeholder) /]
  [#elseif field.control == "password"]
    [@input id="${fieldId}" type="password" name="${key}" leftAddon="lock" autocomplete="new-password" autofocus=autofocus placeholder=theme.optionalMessage(placeholder)/]
  [#elseif field.control == "radio"]
    [@radio_list field=field id="${fieldId}" name="${key}" required=field.required autofocus=autofocus options=field.options /]
  [#elseif field.control == "select"]
    [@select id="${fieldId}" name="${key}" required=field.required autofocus=autofocus options=field.options /]
  [#elseif field.control == "textarea"]
    [@textarea id="${fieldId}" name="${key}" required=field.required autofocus=autofocus placeholder=theme.optionalMessage(placeholder) /]
  [#elseif field.control == "text"]
    [#if field.type == "date"]
      [@input id="${fieldId}" type="text" name="${key}" leftAddon="${leftAddon}" required=field.required autofocus=autofocus placeholder=theme.optionalMessage(placeholder) class="date-picker" dateTimeFormat="yyyy-MM-dd" /]
    [#else]
      [@input id="${fieldId}" type="text" name="${key}" leftAddon="${leftAddon}" required=field.required autofocus=autofocus placeholder=theme.optionalMessage(placeholder) /]
    [/#if]
  [/#if]
[/#macro]

あなたがそれに慣れていないならば、ちょっと不思議に見えます、しかし、これはユーザーインターフェースが生成されているように、すべてのカスタムフィールドに対して実行されるif/then文のシリーズです.マクロは各フィールド定義を見て、正しいHTML要素を作成します.さて、技術的に、それはもう1つのマクロを呼びますinput or select , しかし、あなたは私が意味するものを得ます.例えば、password フィールドはHTML入力フィールドとしてタイプpassword .
ラベルを各フィールドに加えましょう.右後[#assign fieldId = field.key?replace(".", "_") /] , 以下を追加します.

<label for="${fieldId}">${theme.optionalMessage(field.key)}:</label>

忍者ウィンドウを開き、再度登録フローを通過します.両方のステップのラベルを参照してください.これらのラベルの値は、メッセージバンドルからプルされるので、他のメッセージのいずれかと同じ方法でローカライズすることができます.ボーナスとしてlabel HTML要素を使用すると、テキストラベルをクリックするとブラウザがテキスト入力フィールドにカーソルを置きます.ユーザーエクスペリエンスを獲得!

最初の手順を完了すると、2番目のステップにもラベルが表示されます.

テーマのプレビュー

これは、一般的には、これはユーザー登録経験のための感触を与えるので、インゴットウィンドウのテーマを確認する良いアイデアです.しかし、時には、全体の登録プロセスを通過せずに表示するテーマの変更を行う必要があります.簡単にテーマをプレビューすることができます.
“テーマ”に“カスタマイズ”に移動します.あなたのテーマを選択し、プレビューリンクをクリックします.

これを行うと新しいタブが開きます.左手のナビゲーションで“OAuth Register”をクリックすると、それがレンダリングされるように、テーマが表示されます.あなたも、ステップの間を切り替えることができます.以下は2ステップ目のプレビューです.

結論

このポストは、FusionAuthテーマの完全な柔軟性を垣間見ることができます.Apache Freemarker、ResourceBallles、CSS、およびJavaScriptのパワーを使用してこれらのページをカスタマイズし、ローカライズできます.前述のように、それはまた、チェックアウトする価値があるtheme documentation .
FusionAuth登録フォームを使用している場合は、ユーザーの経験を改善するために既定のテンプレートをカスタマイズしてください.FusionAuthのテーマは、管理ユーザーインターフェイスとAPI呼び出しで操作することができます.
しかし、登録の後、どうですか?この情報は、fusionauth APIを通して利用できますuser.data and registration.data フィールド.また、管理用ユーザーインターフェイスでは表示できません.
彼らのデータを見るために、小さなポータルページを構築しましょう.を使用してユーザーデータを取得および変更できますAPIs そして、将来のブログ記事で、我々は正確にそれをする方法を見ます.