このページの2つのバージョン間の差分を表示します。
次のリビジョン | 前のリビジョン | ||
apricot:usage:ja:frontend [2020/07/29 13:25] tanaka 作成 |
apricot:usage:ja:frontend [2020/09/10 23:27] (現在) y2sunlight [Bladeの拡張] |
||
---|---|---|---|
行 1: | 行 1: | ||
- | > 編集中 | ||
- | |||
- | ---- | ||
- | |||
====== Apricot フロントエンド ====== | ====== Apricot フロントエンド ====== | ||
--- // | --- // | ||
- | [[apricot: | + | [[apricot: |
目次 | 目次 | ||
+ | * [[apricot: | ||
* [[apricot: | * [[apricot: | ||
+ | * [[apricot: | ||
* [[apricot: | * [[apricot: | ||
* Apricot フロントエンド | * Apricot フロントエンド | ||
- | * [[apricot: | + | * [[apricot: |
+ | * [[apricot: | ||
* [[apricot: | * [[apricot: | ||
* [[apricot: | * [[apricot: | ||
- | * [[apricot: | + | * [[apricot: |
+ | * [[apricot: | ||
+ | * [[apricot: | ||
* [[apricot: | * [[apricot: | ||
---- | ---- | ||
- | ===== テンプレートエンジン ===== | + | ===== HTMLテンプレート ===== |
- | >TODO | + | |
+ | ==== テンプレートエンジン ==== | ||
+ | |||
+ | Apricotでは、テンプレートエンジンにLaravelと同じBladeを使用しています。実際に使用しているライブラリは [[https:// | ||
+ | |||
+ | テンプレートの詳しい使用方法については、以下のドキュメントを参照して下さい。 | ||
+ | |||
+ | * https:// | ||
+ | * https:// | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== レンダリング | ||
+ | |||
+ | Apricotでは、BladeOneを直接使う代わりに、それをラップしてシングルトンにしたViewクラスを使用します。ViewシングルトンはBladeOneと同じメソッド使用できますが、Apricotで主に使用するのはrun()メソッドだけです。 | ||
+ | |||
+ | 使用法: **View:: | ||
+ | |||
+ | ^メソッド^機能^ | ||
+ | |string run(string $view, array $variables = [])|テンプレートエンジンの実行| | ||
+ | |||
+ | * $view --- テンプレート名 | ||
+ | * $variables --- テンプレート変数 | ||
+ | * return値 --- HTMLテキストを返す | ||
+ | |||
+ | Apricotのアプリケーションでは、直接Viewシングルトンを使用する代わりに、ボイラープレート'' | ||
+ | |||
+ | <code php> | ||
+ | public function index() | ||
+ | { | ||
+ | $users = $this-> | ||
+ | return render(" | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | render() の第1引数にはHTMLテンプレート名、第2引数にはテンプレート変数を[変数名 ⇒ 値]の形で渡します。 | ||
+ | |||
+ | テンプレートファイルは、''/ | ||
+ | |||
+ | 以下は、テンプレートファイル '' | ||
+ | |||
+ | <code php user.index.php> | ||
+ | |||
+ | @foreach($users as $user) | ||
+ | <tr data-href=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | @endforeach | ||
+ | </ | ||
+ | |||
+ | |||
+ | === render()関数の実装 === | ||
+ | |||
+ | render() 関数は、Apricotコア部分下の '' | ||
+ | |||
+ | <code php boilerplates.php> | ||
+ | /** | ||
+ | * Renders HTML via the given template and returns a response object. | ||
+ | * | ||
+ | * @param string $view Template name | ||
+ | * @param array $variables An array of template variables | ||
+ | * @return \Apricot\Foundation\Response\RenderResponse | ||
+ | */ | ||
+ | function render(string $view=null, array $variables=[]): | ||
+ | { | ||
+ | $variables[' | ||
+ | $html = isset($view) ? Apricot\View:: | ||
+ | return new Apricot\Foundation\Response\RenderResponse($html); | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | render() 関数の2つの引数は View シングルトンのrun()メソッドに渡わたされ、テンプレートを介してHTMLをレンダリングし、その結果を使ってレンダーレスポンスを生成して返しています。ボイラープレート [[# | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== テンプレート変数 $errors ==== | ||
+ | |||
+ | '' | ||
+ | |||
+ | <code php> | ||
+ | // テンプレート変数 $errors | ||
+ | [' | ||
+ | </ | ||
+ | |||
+ | '' | ||
+ | |||
+ | <code php> | ||
+ | @if($errors-> | ||
+ | @foreach($errors as $key=> | ||
+ | | ||
+ | @endforeach | ||
+ | @endif | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== ビューヘルパー ==== | ||
+ | |||
+ | Aprocotのアプリ部分では、ヘルパークラスを ''/ | ||
+ | |||
+ | テンプレート内で使用するヘルパークラスはビューヘルパーと呼ばれ、以下は、初期実装されている ViewHelperクラス で、文字列の日付をフォーマットするメソッドだけが実装されています。必要に応じて、ここにメソッドを追加して下さい。 | ||
+ | |||
+ | {{fa> | ||
+ | <code php ViewHelper.php> | ||
+ | <?php | ||
+ | namespace App\Helpers; | ||
+ | |||
+ | /** | ||
+ | * View Helper | ||
+ | */ | ||
+ | class ViewHelper | ||
+ | { | ||
+ | /** | ||
+ | * Returns a formatted date string. | ||
+ | * | ||
+ | * This method is an example of a view helper. | ||
+ | * | ||
+ | * @param string $datetime | ||
+ | * @param string $format | ||
+ | * @return string | ||
+ | */ | ||
+ | static function formatDatetime(string $datetime, string $format=' | ||
+ | { | ||
+ | return date($format, | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== クラスエイリアス ==== | ||
+ | |||
+ | Apricotでは、シングルトンとビューヘルパーのエイリアスを作っています。これによって、完全修飾クラス名を短くコーディングできます。クラスエイリアスの設定については、「[[apricot: | ||
+ | |||
+ | |||
+ | 以下はテンプレート内でのクラスエイリアスの使用例です。この例では、フラッシュにキーがmsgのデータがあればそれを出力しています。 | ||
+ | |||
+ | <code php> | ||
+ | @if(Flash:: | ||
+ | <div class=" | ||
+ | @endif | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== テンプレートファイル ==== | ||
+ | |||
+ | テンプレートファイルは、''/ | ||
+ | |||
+ | Apricotのアプリ部分として提供しているテンプレートファイルの構成を以下に示します。 | ||
+ | |||
+ | < | ||
+ | your-project | ||
+ | | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | </ | ||
+ | |||
+ | 1つのコントローラーが複数のHTMLテンプレートを持っている場合、ユーザコントローラのように、サブディレクトリ―にはコントローラ名に関連した名前付けを推奨します。上のユーザ新規登録ページのテンプレート名は '' | ||
+ | |||
+ | '' | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== マスターレイアウト ==== | ||
+ | |||
+ | 通常のアプリケーションでは、ページの全体的なレイアウトの中に個別のレイアウトを表示します。この全体的なレイアウトをマスターレイアウトと呼びます。以下は、マスターレイアウトのテンプレート ( layout.blade.php ) の例です。 | ||
+ | |||
+ | {{fa> | ||
+ | <code php layout.blade.php> | ||
+ | {{-- This is an example of master layout --}} | ||
+ | < | ||
+ | <html lang=" | ||
+ | < | ||
+ | <meta charset=" | ||
+ | <meta name=" | ||
+ | < | ||
+ | <!-- Here are stylesheets and scripts such as jquery and bootstrap --> | ||
+ | {!! DebugBar:: | ||
+ | @stack(' | ||
+ | </ | ||
+ | < | ||
+ | < | ||
+ | | ||
+ | </ | ||
+ | < | ||
+ | < | ||
+ | @yield(' | ||
+ | |||
+ | {{-- error --}} | ||
+ | @if($errors-> | ||
+ | <div class=" | ||
+ | @foreach($errors as $key=> | ||
+ | | ||
+ | @endforeach | ||
+ | </ | ||
+ | @endif | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | {!! DebugBar:: | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | マスターレイアウトの例に従ってBladeによるテンプレートの書き方を確認してみましょう。 | ||
+ | |||
+ | === コメント === | ||
+ | |||
+ | Bladeのコメントは ''< | ||
+ | |||
+ | <code php> | ||
+ | {{-- This is an example of master layout --}} | ||
+ | </ | ||
+ | |||
+ | === データ表示 === | ||
+ | |||
+ | Bladeからデータを表示するには、''< | ||
+ | |||
+ | <code php> | ||
+ | < | ||
+ | {{$value}}< | ||
+ | </ | ||
+ | |||
+ | HTMLをエスケープしたくない場合は以下のように、''< | ||
+ | |||
+ | <code php> | ||
+ | {!! DebugBar:: | ||
+ | {!! DebugBar:: | ||
+ | </ | ||
+ | |||
+ | === セクションの宣言 === | ||
+ | |||
+ | Bladeでは、@で始まるディレクティブと呼ばれる構文があります。'' | ||
+ | |||
+ | <code php> | ||
+ | @yield(' | ||
+ | @yield(' | ||
+ | </ | ||
+ | |||
+ | === スタックの宣言 === | ||
+ | |||
+ | '' | ||
+ | |||
+ | <code php> | ||
+ | @stack(' | ||
+ | </ | ||
+ | |||
+ | === 制御構文 === | ||
+ | |||
+ | PHPの制御構造と同様に、Blade でも '' | ||
+ | |||
+ | <code php> | ||
+ | @if($errors-> | ||
+ | <div class=" | ||
+ | @foreach($errors as $key=> | ||
+ | | ||
+ | @endforeach | ||
+ | </ | ||
+ | @endif | ||
+ | </ | ||
+ | |||
+ | === PHPコード === | ||
+ | |||
+ | @phpディレクティブを使えば、任意のPHPコードを実行できます。 | ||
+ | |||
+ | <code php> | ||
+ | @php | ||
+ | /* Do something. */ | ||
+ | @endphp | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== テンプレートの継承 ==== | ||
+ | |||
+ | 前項のマスターテンプレートを継承した例を以下に示します。これはユーザコントローラーのcreateアクションで、ユーザの新規登録を行うページです。 | ||
+ | |||
+ | {{fa> | ||
+ | <code php create.blade.php> | ||
+ | {{-- Parent layout --}} | ||
+ | @extends(' | ||
+ | |||
+ | {{-- Additional script --}} | ||
+ | @push(' | ||
+ | <script src=" | ||
+ | @endpush | ||
+ | |||
+ | {{-- title --}} | ||
+ | @section(' | ||
+ | |||
+ | {{--content --}} | ||
+ | @section(' | ||
+ | <form method=" | ||
+ | @csrf | ||
+ | {{-- account --}} | ||
+ | < | ||
+ | <label for=" | ||
+ | <input type=" | ||
+ | | ||
+ | </ | ||
+ | |||
+ | {{-- Show other input elements here --}} | ||
+ | </ | ||
+ | </ | ||
+ | @endsection | ||
+ | </ | ||
+ | |||
+ | 上の例に従ってBladeによるテンプレートの書き方を確認してみましょう。 | ||
+ | |||
+ | === テンプレートの継承 === | ||
+ | |||
+ | マスターテンプレートを継承するには、@extendsディレクティブを使用します。このディレクティブを使えばマスターテンプレートの中に個別のコンテンツを表示することができます。 | ||
+ | |||
+ | <code php> | ||
+ | @extends(' | ||
+ | </ | ||
+ | |||
+ | === スタックへのプッシュ === | ||
+ | |||
+ | マスターテンプレートで宣言されている@stackに個別のコンテンツをプッシュするには、@pushディレクティブを使います。下の例では、マスターテンプレートのHEAD要素内に個別のJavascriptを差し込んでいます。 | ||
+ | |||
+ | <code php> | ||
+ | @push(' | ||
+ | <script src=" | ||
+ | @endpush | ||
+ | </ | ||
+ | |||
+ | === セクションの定義 === | ||
+ | |||
+ | マスターテンプレートで宣言されている@yieldに個別のコンテンツを表示するには、@sectionディレクティブを使います。以下は個別のタイトルを表示する例です。 | ||
+ | |||
+ | <code php> | ||
+ | @section(' | ||
+ | </ | ||
+ | |||
+ | また、複数行のセクションを定義するには以下の構文を使います。 | ||
+ | |||
+ | <code php> | ||
+ | @section(' | ||
+ | {!-- Display the form element here. --} | ||
+ | @endsection | ||
+ | </ | ||
+ | |||
+ | === CSRF対策 === | ||
+ | |||
+ | @csrfは、CSRF対策用のトークンフィールドを出力するカスタムディレクティブです。@csrfの作り方については「[[# | ||
+ | |||
+ | <code php> | ||
+ | <form method=" | ||
+ | @csrf | ||
+ | {!-- Display input elements here. --} | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ===== Bladeの設定 ===== | ||
+ | |||
+ | |||
+ | ==== Bladeの設定ファイル ==== | ||
+ | |||
+ | Bladeの設定ファイルは、'' | ||
+ | |||
+ | {{fa> | ||
+ | <code php bladeone.setting.php> | ||
+ | <?php | ||
+ | /** | ||
+ | * This file contains BladeOne settings. | ||
+ | */ | ||
+ | return | ||
+ | [ | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ]; | ||
+ | </ | ||
+ | |||
+ | * template_path --- HTMLテンプレートファイルのパス(初期設定値は assets/ | ||
+ | * compile_path --- コンパイル後のHTMLファイルのパス(初期設定値は var/ | ||
+ | * mode --- 実行モード(初期設定値は MODE_AUTO(=0)) | ||
+ | |||
+ | 実行モードが MODE_AUTO の場合、テンプレートはPHPへコンパイルされ、変更があるまで '' | ||
+ | |||
+ | 実行モードには以下の種類があるます: | ||
+ | |||
+ | * MODE_AUTO(=0) --- テンプレートが変更されている場合のみ、コンパイルします。 | ||
+ | * MODE_SLOW(=1) --- ファイルは常にコンパイルされます。 | ||
+ | * MODE_FAST(=2) --- ファイルは常にコンパイルされません。 | ||
+ | * MODE_DEBUG(=5) --- ファイルは常にコンパイルされ、ファイル名は識別可能です。 | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== Bladeのセットアップ ==== | ||
+ | |||
+ | Bladeには以下のセットアップファイルが存在します。 | ||
+ | |||
+ | {{fa> | ||
+ | <code php bladeone.setup.php> | ||
+ | <?php | ||
+ | /** | ||
+ | * Initial setting of View template (Blade One) | ||
+ | */ | ||
+ | return function(): | ||
+ | { | ||
+ | // @now directive | ||
+ | Apricot\View:: | ||
+ | { | ||
+ | return "<? | ||
+ | }); | ||
+ | |||
+ | // @csrf directive | ||
+ | Apricot\View:: | ||
+ | { | ||
+ | $name = Apricot\Foundation\Security\CsrfToken:: | ||
+ | return '< | ||
+ | }); | ||
+ | |||
+ | return true; // Must return true on success | ||
+ | }; | ||
+ | </ | ||
+ | |||
+ | このセットアップファイルの目的は、HTMLテンプレートに新しいカスタムディレクティブを追加することです。ここでは以下のディレクティブを追加しています。 | ||
+ | |||
+ | === @now === | ||
+ | |||
+ | 現在時刻を表示するディレクティブです。これはカスタムディレクティブのサンプルです。 | ||
+ | |||
+ | === @csrf === | ||
+ | |||
+ | CSRF対策用のトークンフィールドを出力するディレクティブです。セッションからCSRFトークンを取得して、hidden タイプの input 要素の中に設定しています。 | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ===== Bladeの拡張 ===== | ||
+ | |||
+ | Apricotで使用しているテンプレートエンジン [[https:// | ||
+ | |||
+ | 例: | ||
+ | < | ||
+ | @form() | ||
+ | @input(type=" | ||
+ | @button(type=" | ||
+ | @endform() | ||
+ | </ | ||
+ | |||
+ | インストール方法や使い方は、以下を参照して下さい: | ||
+ | |||
+ | * https:// | ||
\\ | \\ | ||
===== 多言語化 ===== | ===== 多言語化 ===== | ||
- | >TODO | + | |
+ | Apricotは多言語をサポートしてます。これはアプリケーションで各言語毎にメッセージをファイルを作成することによって行い、このファイルの事を[[# | ||
+ | |||
+ | アプリケーションの実行時に、Apricotがどの言語を選択するかは、利用者がブラウザで使用している言語とアプリケーションで準備されている言語ファイルによって自動的に決定されます。デフォルトの言語は、環境変数 APP_LANG で指定してます。この変数が指定されていない場合は英語になります。 | ||
\\ | \\ | ||
+ | |||
+ | ==== 言語ファイル ==== | ||
+ | |||
+ | 言語ファイルは ''/ | ||
+ | |||
+ | < | ||
+ | your-project [プロジェクトディレクトリー] | ||
+ | | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | </ | ||
+ | |||
+ | メッセージの識別は、ドット表記のキーで行います。最初のキーは、言語ファイルの '' | ||
+ | |||
+ | 以下は、言語ファイル(messages.php)の例です。このファイル内のメッセージを取得するドット表記のキーは '' | ||
+ | |||
+ | {{fa> | ||
+ | <code php messages.php> | ||
+ | <?php | ||
+ | return [ | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ], | ||
+ | ]; | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 言語メッセージの取得 ==== | ||
+ | |||
+ | === Langクラス === | ||
+ | |||
+ | Langクラスはドット表記で指定されたキーから各言語用のメッセージを取得するシングルトンです。このクラスは '' | ||
+ | |||
+ | 使用法: ** Lang:: | ||
+ | |||
+ | ^メソッド^機能^ | ||
+ | |string getLangCode()|言語コード(ISO 639-1)の取得| | ||
+ | |bool has(string $key)|キーの存在確認| | ||
+ | |string get(string $key, array $params = [])|言語テキストの取得| | ||
+ | |||
+ | 以下は、ホームコントローラのindexアクションです。この例では、前項の例の言語ファイル( messages.php )から ' | ||
+ | |||
+ | <code php> | ||
+ | public function index() | ||
+ | { | ||
+ | $message = Lang:: | ||
+ | return render(' | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | === ボイラープレート === | ||
+ | |||
+ | '' | ||
+ | |||
+ | <code php> | ||
+ | public function index() | ||
+ | { | ||
+ | $message = __(' | ||
+ | return render(' | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | > この関数名は < | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ===== アセットファイルのバージョニング ===== | ||
+ | |||
+ | 通常のブラウザでは、静的なアセットファイル( '' | ||
+ | |||
+ | 簡単なキャッシュ・バスティングの方法としては、アセットファイルのURLに現在日時をクエリー文字列として付加する方法があります。 | ||
+ | |||
+ | < | ||
+ | <link href=" | ||
+ | <script src=" | ||
+ | </ | ||
+ | |||
+ | しかし、この方法では、アクセスする度にブラウザがアセットファイルを取得してしまい、ブラウザのキャッシュ機構が上手く機能しません。従って、現在日時の代わりにアプリケーションのバージョン番号を付加すれば、この問題を解決することができます。これがアセットファイルのバージョニングです。 | ||
+ | |||
+ | Apricotではバージョニング用のボイラープレート [[apricot: | ||
+ | |||
+ | < | ||
+ | <link href=" | ||
+ | <script src=" | ||
+ | </ | ||
+ | |||
+ | アプリケーションのバージョン番号は、[[apricot: | ||
+ | |||
+ | \\ | ||
+ | |||