ドキュメントモジュール

このドキュメントは、コンテンツを構成するドキュメントモジュールの定義を含んだ、FESSが規定する標準のコーディング規則について説明します。

INDEX

ロール(役割)の定義
設計方針
ターゲットデバイスについての考え方
文字セットと改行コード
- 文字セット
- 改行コード
命名規則
共通ドキュメントモジュール
- ドキュメントモジュールの4つの分類
コンテンツ独自モジュールを定義する場合の規則

ロール(役割)の定義

このドキュメントでは、2種類のロール(役割)が登場します。

設計者: 設計者は、ウェブサイト全体の構造を設計する役割を担います。多くの場合は、1人〜3人程度で構成される少人数の役割です。制作者へ制作の手順やコーディング規則、ドキュメントモジュール仕様などについて指示し、サイト全体のクオリティを集中的に管理します。役割の呼称は設計者ですが、コンテンツエリア外の領域については設計者が制作を担当します。
制作者: 制作者は、コンテンツ(ページ)個別の制作を行います。サイトの規模にもよりますが、通常は設計者に対して人数は多く、5人前後から、大規模なサイトでは数十人規模になることもあります。

設計方針

ドキュメントモジュールおよびコーディング規則は、次の方針に基づいて設計されます。

少数(多くの場合1人)の設計者と、大勢の制作者との間の約束事であり、設計者が全体を効率よく管理できることを主目的として設計する。
学習しやすさを重視する。可能な限り、素のHTMLの構造のままでマークアップできるように設計する。
なるべくドキュメントの分量を圧縮できるように設計する。初めてドキュメントを読む人に負担をかけないよう配慮する。また、必要以上の規則を設けることは、個々人の作業効率を下げてしまう原因となる。

ターゲットデバイスについての考え方

ターゲットデバイスの種類については、意識しない(=マルチデバイスに対応できるように設計する)ものとします。

文字セットと改行コード

文字セット

テキスト系のファイルタイプ全般において、文字セットは UTF-8(BOMなし) で統一します。

改行コード

テキスト系のファイルタイプ全般において、改行コードは CRLF で統一します。

命名規則

次の命名規則を原則とします。

PHP

アンダースコア記法で統一する。
すべて小文字を使用する。
例: get_page_info()

CSS

アンダースコア記法を基本とする。
すべて小文字を使用する。
数字を使用する場合に、アンダースコアで区切るか否かは任意とする。
例: module_name

ただし、サブモジュール(モジュールの一部として使用されることが前提となるクラス)については、属するモジュール名の後ろにハイフンでサブモジュール名を付加するように命名します。この場合、サブモジュール名は1つだけ指定できます(ハイフンは1度しか使えません)。
例：モジュール module_name に属するサブモジュール module_name-sub1, module_name-sub2 など

次にあげるのは、慣例です。

*_box: 枠がつく・または異なる空間に見えるようにデザインされるモジュールに用います。
*-last: 最後の要素につける場合は、このサブモジュール名を用います。

JavaScript

キャメル記法に統一する。
例:hogeHoge()

サブモジュールの定義指針

サブモジュールは、モジュールの一部として使用されることが前提となるクラスです。属するモジュールの名前を冠し、後ろにハイフンでサブモジュール名を付加するように命名します。

基本的な指針としては、属するモジュールの名前領域の内で有効になるよう設計します。

次の例は、モジュール .module と、.module に属するサブモジュール .module-submodule の関係について表しています。

<style type="text/css">
.module{
	/* style */
}
.module .module-submodule{
	/* style */
}
</style>
<div class="module">
    <div class="module-submodule">
    	テキスト
    </div>
</div><!-- / .module -->

サブモジュールは、属するモジュールと併記するように設計することもできます。

<style type="text/css">
.module{
	/* style */
}
.module.module-submodule{
	/* style */
}
</style>
<div class="module module-submodule">
	テキスト
</div><!-- / .module -->

この場合のサブモジュールの定義は、.module.module-submodule とすることが望ましいですが、IE6などの古い環境を考慮する場合、単に .module-submodule と定義しても構いません。

接頭辞 cont について

接頭辞 cont は、設計者と制作者の名前領域を分ける目的で、コンテンツ独自のモジュールに対してつける予約語です。

PHPの例: cont_get_page_info()
CSSの例: cont_module_name
JavaScriptの例: contHogeHoge()

名称の省略について

クラス名等の命名に省略形を使用するべきかどうかについて、厳密な取り決めは設けませんが、次のような基準を設け、適切な名称を検討するようにします。

名称は省略せず、フルスペルで命名することを基本とします。これは、フレームワークに慣れない新しいメンバーでも、ソースコードを見るだけである程度の意味や効果を把握できるように配慮するためです。
特に頻繁に使用するクラス名には、省略形を用います。これは、タイプする機会が多くなるためミスタイプを防止することにつながること、頻繁に利用するため意味や効果を記憶しやすく、名前から判別しにくくても問題となりにくいことの2点からです。
頻繁に使うクラスでも、構造が複雑なモジュールには、フルスペルの名称が適しています。これは、モジュール集からコピー＆ペーストしてコーディングする運用が想定されるため、タイピングのコストやミスタイプのリスクが低いと考えられるためです。

共通ドキュメントモジュール

ドキュメントモジュールは、構成要素単位で構造化されたHTMLとCSSのセットであり、サイト全体の管理者(=設計者)により定義され、コンテンツ個別の制作者に配布されるものです。

ここで定義されるドキュメントモジュールは、サイト全体の管理者(=設計者)により、将来の環境や要件の変化を想定して設計されたものであり、制作者には、そのルールに従ってコンテンツを構築することが求められます。

制作者は、ここに定義されていないドキュメントモジュールを独自に開発することができます(独自ドキュメントモジュール設計規則についてはコンテンツ独自ドキュメントモジュールの定義を参照)が、これは通常推奨されません。独自ドキュメントモジュールを多く開発すると、サイト全体のルールが次第に崩れてくる恐れがあり、管理効率が著しく低下するためです。極力、このドキュメントに定義された、設計者によって設計、提供されたドキュメントモジュールのみを使ってコンテンツを構築するようにしてください。

ドキュメントモジュールの4つの分類

共通ドキュメントモジュールは、それぞれユニットモジュール、パーツモジュール、スタティックモジュール、ボックスモジュールの4種類のグループに分類されます。

ユニットモジュール: ユニットモジュールは、水平貫通(コンテンツ領域に対して幅100%)の矩形ブロックで、上下に適切なマージンを与えられたモジュールです。パーツモジュールを内包する入れ物のような役割を果たします(ただし、ユニットモジュール内にユニットモジュールを配置することはできません)。端末の状態(スクリーンの幅など)に合わせて、スタイルが変化する場合があります。
パーツモジュール: パーツモジュールは、ユニットモジュール内に入れ込んで使うことができます。端末の状態(スクリーンの幅など)に合わせて、スタイルが変化する場合があります。スタティックモジュールと異なり、ある程度複雑な構造のパーツが含まれます。
スタティックモジュール: スタティックモジュールは、端末の状態(スクリーンの幅など)に影響されず、常に固定の効果を提供します。主に特に基本的でシンプルなショートハンド的なモジュールが含まれます。
ボックスモジュール: ボックスモジュールは、箱型に囲われたビジュアルスタイルを持ち、前後の流れから独立した文脈に用います。ユニットモジュールに内包されることができ、ユニットモジュールを内包することもできる特殊なモジュール群です。

コンテンツ独自モジュールを定義する場合の規則

サイト全体(テーマ)で一元的に管理されているモジュールと干渉しあわないように、いくつかの規則が用意されています。
コンテンツ独自のCSS、JavaScriptを定義する場合の規則についても含みます。

独自ファイル格納ディレクトリ

コンテンツファイルと同じ階層に、コンテンツファイルと同じ名前の拡張子を _files に変えた名前のディレクトリが、コンテンツ独自のファイル格納場所です。
例えば、/abc/def/fhi.html というコンテンツの場合、/abc/def/fhi_files/* を独占的に使うことができます。

外部CSS、画像などのリソースファイルはこの中に管理するようにしてください。また、このディレクトリ内での格納規則や命名規則は設けません。

※ディレクトリ共通の独自ファイルを設計する必要がある場合、そのディレクトリの管理者を決めるなど運用ルールを設けたうえで、この規則を調整してください。
例えば、/abc/def/*.html という複数のコンテンツで使う独自ファイルを、/abc/def/common/* とするなどしてください。

コンテンツ独自CSSを定義する

コンテンツが独自に定義するCSSは、サイト全体(テーマ)で一元的に管理されているCSSと干渉し合っては不都合があります。この問題を避けるため、次の規則が設けられました。

コンテンツは、<div class="contents"></div> の内側に設置される約束なので、コンテンツが独自に定義するCSSクラスは、.contents 以下にのみ効果があるように記述しなければならない。
コンテンツが独自に定義するCSSクラスには、接頭辞 cont を付加しなければならない。
テーマが提供するCSSモジュールの一部を改変して使うことはできない。ただし、テーマが明示的に許可している場合は、その範囲で改変することができる。

テーマによって特に認められている項目を除き、テーマの共通モジュールの一部を拡張して利用してはいけません。この場合、まずは設計者に拡張してよいか相談した上で問題ない内容で拡張を行うか、またはモジュール単位で全体をコピーし、サブモジュールも含めて、接頭辞 cont を付加した別のモジュールとして再定義して変更するようにします。

例:colsを独自CSSとして定義する場合

<div class="cont_cols unit">
	<div class="cont_cols-col cont_cols-1of2"><div class="cont_cols-pad">
		<!-- insert parts modules -->
	</div></div>
	<div class="cont_cols-col cont_cols-1of2 cont_cols-last"><div class="cont_cols-pad">
		<!-- insert parts modules -->
	</div></div>
</div><!-- / .cont_cols -->

コンテンツ独自JavaScriptを定義する

コンテンツは独自にJavaSctiptを記述し、埋め込むことができます。
ただし、次の規則に従うようにしてください。

ローカルなJavaScriptメソッドには、接頭辞contを付加する。
コンテンツのHTMLソースは<div class="contents"></div>に内包される規則のため、それ以外のDOMエレメントを改変するようなスクリプトを記述してはならない。
コンテンツが独自に定義したエレメントのid属性は、接頭辞contを付加する。

JavaScriptライブラリの利用

テーマがロードするJavaScriptライブラリ

以下のライブラリは、テーマにより標準的にロードするため、コンテンツが明示的にロードする必要はありません。

jQuery (1.10.1)

コンテンツによって必要な場合にロードできる共有ライブラリ

以下のライブラリは、共有リソースとしてテーマによって用意されていますが、特にコンテンツが必要としない限り、ロードはされません。

未定義(必要に応じて設計者が追加)