フィールドAPI

Drupalのエンティティ（ノード、ユーザーなどの概念）にカスタムデータフィールド（属性情報）を持たせる。

フィールドAPIは、Drupalのエンティティにカスタムデータフィールドを持たせ、フィールドデータの保存、ロード、編集そしてレンダリングをサポートします。フィールドAPIを利用することで、（ノード、ユーザーなどの）あらゆるエンティティタイプは、カスタムフィールドを持つことが出来るようになります。他のモジュールはウェブブラウザーからカスタムフィールドを操作するためのユーザーインターフェース、および様々な種類のデータタイプ、フォーム部品、そしてディスプレイフォーマットを提供することが出来ます。

フィールドAPIはフィールドとそのインスタンス、そしてバンドルというコンセプトの2つの主な構造を定義します。フィールドはエンティティに持たせる属性データの特定のタイプを定義します。フィールドインスタンスはひとつのバンドルに持たせたフィールドです。バンドルとは、Field Attach API によってグループとして扱われ、1つのエンティティタイプに関連付けられるフィールドのセットの事です。

例えば、サイト管理者が「記事」タイプのノードにサブタイトルと、写真の属性を持たせたいとします。フィールドAPI もしくは Field UI モジュールを使うことで、サイト管理者は「サブタイトル」いう名前のテキストタイプのフィールドと、「写真」という名前のイメージタイプのフィールドを作ることが出来ます。サイト管理者は、（繰り返しますが）ブラウザのUIから、「記事」バンドルのノードに持たせる「サブタイトル」というフィールドと、同じく「記事」バンドルのノードに持たせる「写真」というフィールドの2つのフィールドインスタンスを作成します。ノードのシステムが「記事」タイプのノードの全てのフィールドを読み込むのに Field Attach API を利用している場合、エンティティタイプ（ここではノード）とそのバンドルとしてコンテンツタイプ（ここでは「記事」）が渡されます。field_attach_load() 関数はここで「記事」バンドルのノードのフィールドとして「サブタイトル」と「写真」のフィールドを読み込みます。

フィールドの定義は「キー、値」のペアで表現されます。

array $field:

• id (integer, read-only) フィールドのプライマリIDです。field_create_field() によって自動的に割り当てられます。
• field_name (string) フィールドの名前です。Field API の中でフィールドの名前はそれぞれ固有のものでなければなりません。フィールドがエンティティに追加される際、フィールドデータは$entity->$field_name という形で格納されます。最大文字数は32文字です。
• type (string) 「テキスト」や「イメージ」といったフィールドのタイプです。フィールドタイプはhook_field_info() を実装したモジュールによって定義されます。
• entity_types (array) このフィールドのインスタンスを持たせることのできるエンティティタイプです。もし空か何も指定されていなければ、そのフィールドは全てのエンティティタイプにインスタンスを持たせることが出来ます。
• cardinality (integer) フィールドが持つことのできる値の数です。任意の正の整数もしくは無制限を表す定数 FIELD_CARDINALITY_UNLIMITED が利用可能です。
• translatable (integer) フィールドが翻訳可能かどうか。
• locked (integer) フィールドが編集可能かどうか。TRUEなら、ユーザーは UI を通じてフィールドの設定を変更したり、新たにインスタンスを作ることができない。デフォルトはFALSE。
• module (string, read-only) そのフィールドタイプを実装するモジュール名。
• active (integer, read-only) そのフィールドタイプを実装するモジュールが現在アクティブかどうか。
• deleted (integer, read-only) このフィールドが削除されているかどうか。これがTRUEなら Field Attach API においてこのフィールドは無視されます。このプロパティは削除対象のフラグ付けのためであり、実際の削除の処理は別にガベージコレクションプロセスで行われます。
• columns (array, read-only). このフィールドの値を格納するために使用するフィールドAPIのカラムの配列です。カラムのリストはフィールドのタイプごとに一定ではなく、フィールドの設定に依存します。フィールドAPIのカラムの仕様は、スキーマAPIの仕様とまったく同じですが、使用されているフィールドストレージモジュールによっては、カラム名は実際のデータベースのカラム名とは一致しないかもしれません。
• indexes (array). スキーマAPIのインデックス仕様と同じフォーマットを使用したデータカラムのインデックスの配列です。「columns」の設定に表示されたカラムだけが許可されます。フィールドタイプはデフォルトのインデックスを持ち、それはフィールドの作成時に修正追加することが出来ます。
• foreign keys: (オプション) リレーションを表す連想配列です。hook_schema() の 'foreign keys' の定義と同じ構造となっています。Note, however, that the field data is not necessarily stored in SQL. Also, the possible usage is limited, as you cannot specify another field as related, only existing SQL tables, such as filter formats.
• settings (array) フィールドタイプ固有の設定を表すキー／値のペアのサブ配列です。フィールドタイプを提供するモジュールは、その設定を定義し説明します。
• storage (array) フィールドで使用するストレージバックエンドを識別するキー／値のペアのサブ配列です。
  • type (string) フィールドで使用するストレージバックエンドです。ストレージバックエンドはhook_field_storage_info() を実装したモジュールにより定義されます。
  • module (string, read-only) ストレージバックエンドを実装したモジュールの名前。
  • active (integer, read-only) ストレージバックエンドを実装したモジュールがアクティブかどうか。
  • settings (array) 設定を表すキー／値のペアのサブ配列です。ストレージバックエンドはそれぞれ自身の設定を定義し説明します。

フィールドインスタンスの定義はキー／値のペアの配列によって表現されます。

array $instance:

• id (integer, read-only) フィールドインスタンスのプライマリキーです。field_create_instance() によって自動的に割り当てられます。
• field_id (integer, read-only) このインスタンスでバンドルに追加されたフィールドの外部キー（ID）です。field_create_instance() によって自動的に入力されます。
• field_name (string) このインスタンスでバンドルに追加されたフィールドの名前です。
• entity_type (string) このインスタンスを持たせるエンティティタイプの名前です。
• bundle (string) フィールドを持たせるバンドルの名前です。
• label (string) バンドルで用いられる際のフィールドの表示用の名前です。例えば、インスタンスのフォーム要素のタイトルに使用されます。
• description (string) バンドルで用いられる際のフィールドの表示用の説明文です。例えば、インスタンスのフォーム要素のヘルプテキストに使用されます。
• required (integer) バンドルで用いられる際、このフィールドの値が必須かどうかを示します。必須ならTRUE、そうでなければFALSEとなります。現在この値はフォームAPIのみに使用されており、field_attach_load()、field_attach_insert()、field_attach_update()では使用されません。
• default_value_function (string) もしあれば、デフォルト値を提供する関数名です。
• default_value (array) default_value_functionがセットされていない場合は、固定のデフォルト値が提供されます。
• deleted (integer, read-only) このインスタンスが削除されていればTRUE、そうでなければFALSEとなります。削除されたインスタンスは Field Attach API では無視されます。このプロパティは削除対象のフラグ付けのためであり、実際の削除の処理は別にガベージコレクションプロセスで行われます。
• settings (array) フィールドタイプ固有のインスタンス設定を表すキー／値のペアのサブ配列です。フィールドタイプを提供するモジュールは、その設定を定義し説明します。
• widget (array) バンドルで使用される、Form API のフィールド入力ウィジェットを識別するキー／値のペアのサブ配列です。
  • type (string) テキストフィールドなどのウィジェットのタイプです。ウィジェットタイプはhook_field_widget_info() を実装するモジュールによって定義されます。
  • settings (array) ウィジェット型固有の設定を表すキー／値のペアのサブ配列です。フィールドウィジェットタイプを提供するモジュールは、その設定を定義し説明します。
  • weight (float) エンティティの編集フォームで、他のフォーム要素との関係を示すウェイトです。
  • module (string, read-only) ウィジェットタイプを実装するモジュールの名前です。
• display (array) エンティティタイプのデフォルトモードに加え、それぞれのビューモードにおいて、フィールドの値がどのように表示されるかを示すキー／値の配列です。管理者は Field UI を通じて、ビューモードごとに専用の表示オプションを設定するか、新しくフィールドを追加する際の、設定の手間を軽減するためのデフォルトの表示オプションにするかを決めます。ノードでは、インストールしたばかりの状態では、ただ一つ「ティーザー」がカスタム表示オプションを使用するように設定されています。そのほかのビューモードではすべて、初期状態では「デフォルト」の表示オプションとなっています。従って、プログラムからノードにフィールドインスタンスを追加する際は、少なくとも「デフォルト」か「ティーザー」の表示オプションを指定することが推奨されます。
  • default (array) デフォルトつまりカスタマイズされた表示設定を使用しない場合に適用される表示設定を表すキー／値の配列です。
    • label (string) ラベルの位置です。デフォルトのフィールドのテーマ実装では「inline」と「above」、そして「hidden」が認識されます。
    • type (string) 表示フォーマットのタイプです。非表示の場合は「hidden」を指定します。
    • settings (array) フォーマットの詳細設定のオプションを表すキー／値のペアのサブ配列です。
    • weight (float) このヒューモードでの他のエンティティコンポーネントに対するフィールドのウェイトです。
    • module (string, read-only) 表示フォーマットを実装するモジュールの名前です。
  • some_mode 「some_mode」というビューモードを使用する場合に適用される表示設定を表すキー／値の配列です。
    • …
  • other_mode
    • …

フィールドインスタンスのレンダー配列については、field_attach_view() に説明があります。

バンドルはエンティティタイプとバンドル名の2つの文字列によって表されます。

• Field Types API. フィールドタイプ、ウィジェットタイプと、ディスプレイフォーマッタを定義します。フィールドを定義するモジュールは、関連するフォーム部品やディスプレイフォーマッタと共に、テキストやノードリファレンスのようなフィールドタイプを提供するのに、このAPIを使用します。
• Field CRUD API. フィールド、バンドル(別名 "コンテンツタイプ")、そしてインスタンスの作成、編集、削除です。モジュールはカスタムデータの構築のために、通常はhook_install()でこのAPIを使用します。
• Field Attach API. エンティティタイプをフィールドAPIに接続します。Field Attach APIの機能はForm APIの構造をロード、格納、生成し、また表示し、そして個々のエンティティに持たせたフィールドデータに対し、ほかの様々な機能を実行します。ノードやユーザーなど、フィールドを持たせることの出来るエンティティタイプは、フィールドを持てるようにするために、このAPIを使います。
• Field Info API. 全てのフィールド、インスタンス、ウィジェットその他、Field API で定義された関連する情報を提供します。
• Field Storage API. 現行のフィールドデータを扱う交換可能なバックエンドストレージを提供します。デフォルトでは、field_sql_storageモジュールがフィールドデータをローカルのSQLデータベースに格納します。
• Field API bulk data deletion. field_delete_field()やfield_delete_instance()のような一括削除操作が行われたあとの、クリーンアップを行います。
• Field language API. フィールドAPIのネイティブ多言語サポートを提供します。