Yamato DaiwaFrontend (2.0.0-beta.4)
English
日本語
Русский

RegularWebPageTemplate

殆どの場合に御勧めのHTML5ページ制作専用主なPugテンプレート。

Pugファイルを当テンプレートから継承しただけで、 其れ以外コードを一切書かなくても、妥当なHTMLドキュメントを代表している下記の コードが生成される。

htmlタグにとってlang 属性が必須に成っていると、titleタグ が妥当なHTMLページに記載されてなければいけないいけないので、此れ等が 規定の設定を元に生成された。 特に日本語又は英語以外の言語でページを作成している場合、此の設定を変えないといけなくなる。 其の為、PugプリプロセッサのJavaScriptブロック からRegularWebPageTemplate__YDFと言う JavaScriptクラスを利用し、上記の設定も、上記以外の設定も変えられる。

RegularWebPageTemplate__YDFコンフィグレーションクラス

汎用HTMLコード生成の設定のに使われる。 当クラスは Functionalityと言う Pugブロックの末尾 以降利用可能に成ってはいるが、殆どの設定は メタタグと関連しているか、 本質的ににメタデータに成っているので、 Metadataブロック からアクセスする推薦。

設定を行うにはconfigureと言う静的なメソッドを 呼び出し、多層オブジェクト型の単一 引数で設定を指定する事。

metadata.locale
タグhtmlのlang属性を 埋めるのに使われる。 htmlタグの場合当属性は 必須なので、「"en"」と言う規定の値が 用意してあるが、非英語のページの場合別の値に置き換えなければいけない。 実は、lang属性の値は「language tag」と正式的に呼ばれるが、 HTMLタグと混同してはならないので、此処でlocaleと言う名前が付けられた。
metadata.title
titleタグを埋めるのに使われる。 当タグは必須なので、"Untitled"と言う規定の 値が用意してある。
metadata.description
指定すると、name="description"属性付きの metaタグが生成され、 content属性が指定された値に埋められる。
metadata.keywords
指定すると、name="keywords"属性付きの metaタグが生成され、 content属性が指定された値に埋められる。
metadata.author
指定すると、name="author"属性付きの metaタグが生成され、 content属性が指定された値に埋められる。
faviconURI
指定すると、linkタグ２個生成され、 一個目はrel="icon"属性が有り、２個目は rel="shortcut icon"属性が有ると他に、 両方のhref属性が指定された値で埋められる。 当値はブラウザーのタグで表示される様に成るアイコンファイルに参照している妥当なURI でなくてはならない。
AMP_VersionURI
指定すると、rel="amphtml"属性付きのlink タグが追加され、href属性が指定された値で埋められる。 此の値は同じページのAMP版への妥当なURI でなければいけない。
stylesSheetsURIs
配列で指定すると、此れの各要素にとって rel="stylesheet"属性付きのlink タグが追加され、href属性が当要素で埋められる。 全要素が文字列でなければいけなく、 CSSファイルへの妥当なURIを代表しなくてはならない。
scripts.atEndOfHead

配列で指定すると、此れの各要素にとって scriptタグがhead タグ内の後方に追加され、 src属性が要素で埋められる。 全要素が文字列でなければいけなく、 JavaScriptファイルへの妥当なURIを代表 しなくてはならない。

  • 追加の対策がなければ、headタグのにスクリプトを追加すると、 当スクリプトがロードされる限りページの描画が一時停止するので、一般的に headタグの中にはスクリプトを追加する事は非推薦。 然し、分析専用の第三者のスクリプトの様に例外は有る。
  • 此の様に追加されたscriptタグはsrc タグ以外の属性は持っていない。 其の他の属性が必要な場合、scriptタグ HeadScriptsと言う Pugブロック へ手動で追加して下さい。
scripts.atEndOfBody

配列で指定すると、此れの各要素にとって scriptタグがbody タグ内の後方に追加され、 src属性が要素で埋められる。 全要素が文字列でなければいけなく、 JavaScriptファイルへの妥当なURIを代表 しなくてはならない。

  • 此の様に追加されたスクリプトは描画を妨げないので、推薦の方法だ。
  • 此の様に追加されたscriptタグはsrc タグ以外の属性は持っていない。 其の他の属性が必要な場合、scriptタグ EndBodyScriptsと言う Pugブロック へ手動で追加して下さい。

configureメソッドを何度も呼び出しても良い が、以前と同じプロパティを指定すると、上書きされるの、以前と違うプロパティを指定するべき。 例えば、貴方とサイト・アプリケーションが単一の（世界の）言語（例えば、日本語）で、ページの作成者も同じなら、下記の様に該当している設定を別のファイルに 指定すると良い（例えば、CommonMetadata.pug）。

上記のファイルをページのファイルに含み、共通ではなく、特定のページに該当しているメタデータのみ指定すれば良い。

Pugブロック

Pugテンプレートの改善・カスタマイズは Pugブロックを用いて実行される。 RegularWebPageTemplateテンプレートには下記のPugブロックが用意してある。

Functionality

Pug内のJavaScriptで 機能をを書きたい場合、当ブロックを活用すれば良い。

当ブロックに 「Yamato Daiwa ECMAScript Extensions」ライブラリの機能が含まれているので此のブロックへの参照の際appendキーワードを指定すれば以下ライブラリの機能が使える様に成る。

Data

後程マークアップの生成の為JavaScript型のデータを用意したいなら、当ブロック内に用意すれば 良い。

Requirements

Pugミックスインや何れかの理由で以前のブロックで書かなかったPug内のJavaScriptコードを追加したいなら、当ブロックに追加すれば良い。

Metadata

JavaScript変数でHTMLページのメタデータを定義したい場合、当 ブロックで定義すれば良い。 特に、RegularWebPageTemplate__YDF.configure({})を此の ブロックこそにで呼び出す推薦。

StatesSimulations

動的なページを作る予定なら、マークアップ・スタイル制作段階ではPugの条件レンダリング を用いて、何れかの要素の有無に応じて表示が崩れていないか、確認出来るのだ。 特に、様々な状態を条件的に表示出来る。 例えば、AJAXで取得されるデータのコレクションを表示させる場合、ページが下記の状態が有る。

  • データが取得中
  • データ取得エラー
  • データが無い
  • データは有るが、検索結果は無い
  • データが取得され、表示されている

上記の状態を真偽型の変数の活用（下記の例だと、クラスを用いた実装であり、 statesSimulationsと言う連想配列型の 静的フィルドの各プロパティが特定の状態に該当している）で条件的な表示が確保出来る。

状態の間に切り替えるには、Pugの再実行が必要。 然し、JavaScript列挙・サーバー側実装段階の前に上記の全状態をページ毎別けた上で依頼側に提示したく、 但し手動で各ページを作る様なルーチンを避けたいなら、 静的プレビュー概念 及びYamato Daiwa Automation (略： YDA)と言うプロジェクト構成ツールを推薦し、 此の様な場合専用の機能が有るのだ。

HeadBegin

タグheadタグ内の 先頭に追加したい場合、此のブロックを用いると良い。

headタグに関して子要素の順番が影響を与える 事はとても少なく（主にスタイルやスクリプトの順番に依って表示・振る舞いが変わる事が有る）、 一般的には開始こそへ内容を追加しないといけない場合は滅多に無い。

Styles

何れかの理由でRegularWebPageTemplate__YDF.configure({})でスタイルへのリンクの 指定機能が足りないか、headタグ内で直接スタイルを書きたいなら、此の ブロックを使うと良い。 特に、コンフィギュレーションの指定に応じて生成されたlinkタグは rel="stylesheet"及びhref以外の 属性が無いので、其の他の属性が必要な場合、下記の様に Stylesブロックにlinkタグ を直接宣言すれば良い。

此のスタイルの宣言方法自体はコンフィギュレーション上の指定方法と対立していないが、 スタイルのカスケーディングの際、宣言の順番を考慮してはならない。 CSSに於いて優先順位は複数の因子に依存しているので、順番を変えるだけでは表示が変わるとは 言い切れないが、順番は一つの因子として影響が有る事は事実。

  • コンフィギュレーションで宣言されたスタイルの前にスタイルを宣言するには、 Stylesブロックの改善の際、prepend キーワードを使うと良い。
  • コンフィギュレーションで宣言されたスタイルの後にスタイルを宣言するには、 Stylesブロックの改善の際、append キーワードを使うと良い。

HeadScripts

何れかの理由でRegularWebPageTemplate__YDF.configure({})でスクリプトへのリンク の指定機能が足りないか、headタグ内で直接スクリプトを書きたいなら、 此のブロックを使うと良い。 特に、コンフィギュレーションの指定に応じて生成されたscriptタグは src以外の属性が無いので、其の他の 属性が必要な場合、下記の様にHeadScriptsブロックに scriptタグを直接宣言すれば良い。

一般的に描画を妨げない様に、スクリプトをbody タグ内の後方に追加推薦。 然し、headタグこそにスクリプトを追加する事が必要な場合が有り、特に 下記の様にGoogle Analyticsの様に第三者の分析・情報収集専用スクリプトの場合。

此のスクリプトの宣言方法自体はコンフィギュレーション上の指定方法と対立していなく、 スクリプトが互い依存していなければ（現代のサイト・アプリケーションだと普通は 其の様になっているが、レガシなサイトやアプリケーションだと、なっていない事が多い）、２つの方法を両立しても良い。

  • コンフィギュレーションで宣言されたスクリプトの前にスクリプトを宣言するには、 HeadScriptsブロックの改善の際、 prependキーワードを使うと良い。
  • コンフィギュレーションで宣言されたスクリプトの後にスクリプトを宣言するには、 HeadScriptsブロックの改善の際、 prependキーワードを使うと良い。

PageContent

ページの見える内容を此のブロックの中に追加する事。 内容はbodyタブの直下に生成される。

EndBodyContent

モーダルダイアログの様に固定配置された要素を其の他の要素の後で追加するべき（でも無論、 bodyタグ内）と言う方法論が在る。 当考え方に従っているなら、EndBodyContentブロックを利用すれば良い。 此のブロックの追加された内容はPageContentのブロックの 直後に行く。

EndBodyScripts

何れかの理由でRegularWebPageTemplate__YDF.configure({})でスクリプトへのリンク の指定機能が足りないか、bodyタグ内で直接スクリプトを書きたいなら、 此のブロックを使うと良い。 特に、コンフィギュレーションの指定に応じて生成されたscriptタグは src以外の属性が無いので、其の他の 属性が必要な場合、下記の様にEndBodyScriptsブロックに scriptタグを直接宣言すれば良い。

此のスクリプトの宣言方法自体はコンフィギュレーション上の指定方法と対立していなく、 スクリプトが互い依存していなければ（現代のサイト・アプリケーションだと普通は 其の様になっているが、レガシなサイトやアプリケーションだと、なっていない事が多い）、２つの方法を両立しても良い。

  • コンフィギュレーションで宣言されたスクリプトの前にスクリプトを宣言するには、 EndBodyScriptsブロックの改善の際、 prependキーワードを使うと良い。
  • コンフィギュレーションで宣言されたスクリプトの後にスクリプトを宣言するには、 EndBodyScriptsブロックの改善の際、 prependキーワードを使うと良い。

多階層継承

貴方のプロジェクトで複数ページが有り、此れらの中に共通の部分が有った（例えば共通ヘッダーやフッターやサイドバー等）、直接ファイル RegularWebPageTemplateからではなく、 共有テンプレートからから継承すると良い。 一般的に主要テンプレート、管理画面専用テンプレート、認証専用テンプレート等有る。

下記の例は一段のページレイアウトである。 ページに依って違う内容を導入するには、追加でSpecificContentと言う Pugブロックが定義された。

今後、下記の様に当ページレイアウトが特定のページが継承出来る。

© 2023 Yamato Daiwa Co., Ltd.