差分

このページの2つのバージョン間の差分を表示します。

--- apricot:usage:ja:frontend [2020/07/29 13:25]
tanaka 作成
+++ apricot:usage:ja:frontend [2020/08/12 10:07]
y2sunlight
@@ 行 6: / 行 6: @@
  --- //[[http://www.y2sunlight.com|y2sunlight]] 2020-07-29//
-[[apricot:usage:ja|Apricotの使用法 に戻る]]
+[[apricot:usage:ja|Apricot ドキュメント に戻る]]
 目次
+  * [[apricot:usage:ja:features|Apricot 特徴と概要]]
   * [[apricot:usage:ja:config|Apricot 配置と構成]]
+  * [[apricot:usage:ja:errors-logging|Apricot ログとエラー処理]]
   * [[apricot:usage:ja:http|Apricot リクエストとレスポンス]]
   * Apricot フロントエンド
@@ 行 16: / 行 18: @@
   * [[apricot:usage:ja:middleware|Apricot ミドルウェア]]
   * [[apricot:usage:ja:controller|Apricot コントローラ]]
-  * [[apricot:usage:ja:errors-logging|Apricot ログとエラー処理]]
   * [[apricot:usage:ja:utility|Apricot ユーティリティ]]
@@ 行 22: / 行 23: @@
 ===== テンプレートエンジン =====
->TODO
+==== HTMLテンプレート ====
+HTMLテンプレートは、BladeOneをラップしたViewクラスが担当します。Viewクラスはシングルトンとして実装し、以下のように使用します。BladeOneと同じメソッド使用できますが、apricotで使用するのはrun()メソッドだけです。
+使用法: **View::{メソッド}**
+^メソッド^機能^
+|string run(string $view, array $variables = [])|テンプレートエンジンの実行|
+  * $view --- テンプレート名 ( テンプレートファイル名は {$view}.blade.php になる)
+  * $variables --- ビュー変数 (['変数名'<nowiki>=></nowiki>'値']の形式の連想配列)
+  * return値 --- HTMLテキストを返す
+\\
+==== クラスエイリアス ====
+完全修飾クラス名を短くコーディングする為に、クラスのエイリアスを作成します。このエイリアスは、特にHTMLテンプレートでの使用を想定しています。
+以下に示す初期設定ファイル(aliases.setup.php)を config/setup フォルダの下に作成して下さい。
+{{fa>folder-open-o}} ** /apricot/config/setup **
+<code php aliases.setup.php>
+<?php
+/**
+ * Registers the class alias used in the view template
+ */
+return function():bool
+{
+    $aliases =
+    [
+        /* Apricot */
+        'Input' => Apricot\Input::class,
+        'QueryString' => Apricot\QueryString::class,
+        'Session' => Apricot\Session::class,
+        'Flash' => Apricot\Flash::class,
+        'Cookie' => Apricot\Cookie::class,
+        'Config' => Apricot\Config::class,
+        'Log' => Apricot\Log::class,
+        'Debug' => Apricot\Debug::class,
+        'DebugBar' => Apricot\DebugBar::class,
+        'ErrorBag' => Apricot\Foundation\ErrorBag::class,
+        /* App */
+        'ViewHelper' => App\Helpers\ViewHelper::class,
+        'ValidatorErrorBag' => App\Foundation\ValidatorErrorBag::class,
+        'AuthUser' => App\Foundation\Security\AuthUser::class,
+    ];
+    // Creates an alias for a class
+    foreach($aliases as $alias_name => $original_class)
+    {
+        class_alias($original_class, $alias_name);
+    }
+    return true; // Must return true on success
+};
+</code>
+  * よく使うコアクラスとアプリ用のヘルパークラスのエイリアスを作っています
+\\
+==== ヘルパークラス ====
+アプリ用のヘルパー関数を作る準備として 表示用のHelperクラスを作成しておきます。必要に応じて、関数やクラスを追加していきます。
+  * ViewHelper --- 表示用(主にHTMLテンプレートで使用)
+{{fa>folder-open-o}} ** /apricot/app/Helpers **
+<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='Y-m-d'):string
+    {
+        return date($format, strtotime($datetime));
+    }
+}
+</code>
+\\
+==== HTMLレイアウト ====
+apricotで採用しているテンプレートエンジン BladeOne の文法に従ってアプリ全体のレイアウトを作ります。また、cssとJavaScriptファイルも準備します。
+  * layout.blade.php --- アプリ全体のレイアウト
+  * main.css --- アプリ共通のスタイルシート
+  * main.js --- アプリ共通で使用するJavaScript
+\\
+==== 設定ファイル ====
+{{fa>folder-open-o}} ** /apricot/config/setting **
+<code php bladeone.setting.php>
+<?php
+/**
+ * This file contains BladeOne settings.
+ */
+return
+[
+    'template_path' => env('VIEW_TEMPLATE',assets_dir('views')),
+    'compile_path' => env('VIEW_CACHE',var_dir('cache/views')),
+    'mode' => \eftec\bladeone\BladeOne::MODE_AUTO,
+];
+</code>
+  * template_path --- HTMLテンプレートファイルのパス(既定値は assets/views/)
+  * compile_path --- コンパイル後のHTMLファイルのパス(既定値は var/cache/)
+  * mode --- 実行モード(既定値は MODE_AUTO)
+\\
+==== 初期設定ファイル ====
+Viewクラスには以下の初期設定ファイルが存在します。
+{{fa>folder-open-o}} ** /apricot/config/setup **
+<code php bladeone.setup.php>
+<?php
+/**
+ * Initial setting of View template (Blade One)
+ */
+return function():bool
+{
+    // @now directive
+    Apricot\View::directive('now', function()
+    {
+        return "<?php echo date('Y-m-d H:i'); ?>";
+    });
+    // @csrf directive
+    Apricot\View::directive('csrf', function()
+    {
+        $name = Apricot\Foundation\Security\CsrfToken::CSRF_KEY;
+        return '<input name="'.$name.'" type="hidden" value="{{Session(\''.$name.'\')}}">';
+    });
+    return true; // Must return true on success
+};
+</code>
+ここでは、HTMLテンプレートで使用するカスタムディレクティブを追加します。上のコードは、現在時刻を表示する @now ディレクティブの追加を行っています。CSRFトークンを出力する @csrf ディレクティブなどもここで実装する予定です。
 \\
 ===== 多言語化 =====
->TODO
+==== トランスレーション ====
+トランスレーションは Translationクラスに実装されており、このクラスも基本的な機能だけをシンプルに作成しています。
+Translationクラスの実装コードを以下に示します。ユーザはこのクラスを直接利用するのではなく、次節に示す Langクラスを使用して下さい。
+{{fa>folder-open-o}} ** /apricot/core/Foundation **
+<code php Translation.php>
+<?php
+namespace Apricot\Foundation;
+/**
+ * Plain Translation Class
+ */
+class Translation
+{
+    /**
+     * @var string Language code(ISO 639-1)
+     */
+    private $lang;
+    /**
+     * @var array Messages
+     */
+    private $messages = [];
+    /**
+     * Constructor
+     *
+     * @param string $lang language code(ISO 639-1)
+     */
+    public function __construct(string $lang='en')
+    {
+        $this->lang = $lang;
+        // Reads messages.
+        foreach(glob(assets_dir("lang/{$lang}/*.php")) as $file)
+        {
+            $arr = explode('.', basename($file));
+            if (is_file($file)) $this->read($file, $arr[0]);
+        }
+    }
+    /**
+     * Gets the language code(ISO 639-1).
+     *
+     * @return string
+     */
+    public function getLangCode():string
+    {
+        return $this->lang;
+    }
+    /**
+     * Checks if the given key is present.
+     *
+     * @param string $key
+     * @return bool
+     */
+    public function has(string $key):bool
+    {
+        return array_key_exists($key, $this->messages);
+    }
+    /**
+     * Gets the message specified by the key.
+     *
+     * @param string $key
+     * @param string $params
+     * @return string
+     */
+    public function get(string $key, array $params = []):string
+    {
+        if ($this->has($key))
+        {
+            $message = $this->messages[$key];
+            if (!empty($params))
+            {
+                $message = str_replace(array_keys($params), array_values($params), $message);
+            }
+        }
+        else
+        {
+            $message = $key;
+        }
+        return $message;
+    }
+    /**
+     * Reads messages.
+     *
+     * @param string $lang_file
+     * @param string $top_key
+     */
+    private function read(string $lang_file, string $top_key)
+    {
+        $messages = require_once $lang_file;
+        if (is_array($messages) && count($messages))
+        {
+            $dot_arr = array_dot($messages, $top_key.'.');
+            $this->messages = array_merge($this->messages, $dot_arr);
+        }
+    }
+}
+</code>
+\\
+==== 言語テキスト ====
+アプリの作成過程で使用する共通の言語テキストを準備します。個別の画面については、その都度に追加して行きます。
+{{fa>folder-open-o}} ** /apricot/assets/lang/ja **
+<code php messages.php>
+<?php
+return [
+    'app'=>[
+        'title'=>env('APP_NAME'),
+        'menu'=>[
+            'menu1'=>'menu1',
+            'menu2'=>'Menu2',
+            'menu3'=>'Menu3',
+            'logout'=>'Logout',
+            'about_me'=>'About Me',
+        ],
+    ],
+    'success' => [
+        'db' => [
+            'insert' => 'データを登録しました',
+            'update' => 'データを更新しました',
+            'delete' => 'データを削除しました',
+        ],
+    ],
+    'error'=>[
+        'unknown'=>'エラーが発生しました',
+        'db' => [
+            'access' => 'データアクセスが失敗しました',
+            'insert' => 'データの登録が失敗しました',
+            'update' => 'データの更新が失敗しました',
+            'delete' => 'データの削除が失敗しました',
+            'optimisstic_lock'=>'データが他のユーザによって更新されています',
+        ],
+    ],
+];
+</code>
+  * app --- アプリケーションのタイトルやメニュー
+  * success --- 処理が成功した場合のメッセージ
+  * error --- エラー用のメッセージ
+\\
+==== Langクラス ====
+Langクラスは 上のTranslationクラスをシングルトンにしたもので、以下のメソッドがあります。
+使用法: ** Lang::{メソッド} **
+^メソッド^機能^
+|bool has(string $key)|キーの存在確認|
+|string get(string $key, array $params = [])|言語テキストの取得|
+\\
+=== ヘルパー関数 ===
+Langクラスのget()メソッドは良く使用されるのでヘルパー関数に追加しておきます。
+{{fa>folder-open-o}} ** /apricot/core/helpers **
+<code php boilerplates.php>
+if (! function_exists('__'))
+{
+    /**
+     * Returns the translated message specified by the dot-notation key.
+     *
+     * @param string $key dot-notation key
+     * @param string $params
+     * @return string translated Message
+     */
+    function __($key, $params = [])
+    {
+        return Apricot\Lang::get($key, $params);
+    }
+}
+</code>
+> この関数名は <nowiki>__</nowiki> です。２つ並んだアンダースコアはPythonプログラマーの間では ''dunders'' (double underscoreの意) と呼ばれ特別なクラス内メンバに付加されますが、ここではそのような意味はなくトランスレータを表す関数名としてLaravelに準じました。
 \\

Ground Sunlight

ユーザ用ツール

サイト用ツール

差分

ページ用ツール