Commit d073fa2a authored by webchick's avatar webchick

#664136 by plach, sun, yched: Enhance TF code documentation.

parent 8911c4ef
......@@ -3,7 +3,61 @@
/**
* @file
* Multilingual field API helper functions.
* Functions implementing Field API multilingual support.
*/
/**
* @defgroup field_language Field language API
* @{
* Handling of multilingual fields.
*
* Fields natively implement multilingual support, and all fields use the
* following structure:
* @code
* $entity->{$field_name}[$langcode][$delta][$column_name]
* @endcode
* Every field can hold a single or multiple value for each language belonging
* to the available languages set:
* - For untranslatable fields this set only contains LANGUAGE_NONE.
* - For translatable fields this set can contain any language code. By default
* it is the list returned by field_content_languages(), which contains all
* enabled languages with the addition of LANGUAGE_NONE. This default can be
* altered by modules implementing hook_field_available_languages_alter().
*
* The available languages for a particular field are returned by
* field_available_languages(). Whether a field is translatable is determined by
* calling field_is_translatable(), which checks the $field['translatable']
* property returned by field_info_field(), and whether there is at least one
* translation handler available for the field. A translation handler is a
* module registering itself via hook_entity_info() to handle field
* translations.
*
* By default, _field_invoke() and _field_invoke_multiple() are processing a
* field in all available languages, unless they are given a language
* suggestion. Based on that suggestion, _field_language_suggestion() determines
* the languages to act on.
*
* Most field_attach_*() functions act on all available languages, except for
* the following:
* - field_attach_form() only takes a single language code, specifying which
* language the field values will be submitted in.
* - field_attach_view() requires the language the entity will be displayed in.
* Since it is unknown whether a field translation exists for the requested
* language, the translation handler is responsible for performing one of the
* following actions:
* - Ignore missing translations, i.e. do not show any field values for the
* requested language. For example, see locale_field_language_alter().
* - Provide a value in a different language as fallback. By default, the
* fallback logic is applied separately to each field to ensure that there
* is a value for each field to display.
* The field language fallback logic relies on the global language fallback
* configuration. Therefore, the displayed field values can be in the
* requested language, but may be different if no values for the requested
* language are available. The default language fallback rules inspect all the
* enabled languages ordered by their weight. This behavior can be altered or
* even disabled by modules implementing hook_field_language_alter(), making
* it possible to choose the first approach. The display language for each
* field is returned by field_language().
*/
/**
......
......@@ -88,6 +88,10 @@ function hook_hook_info_alter(&$hooks) {
* uri elements of the entity, e.g. 'path' and 'options'. The actual entity
* uri can be constructed by passing these elements to url().
* - fieldable: Set to TRUE if you want your entity type to be fieldable.
* - translation: An associative array of modules registered as field
* translation handlers. Array keys are the module names, array values
* can be any data structure the module uses to provide field translation.
* Any empty value disallows the module to appear as a translation handler.
* - entity keys: An array describing how the Field API can extract the
* information it needs from the objects of the type. Elements:
* - id: The name of the property that contains the primary id of the
......@@ -165,6 +169,9 @@ function hook_entity_info() {
'revision table' => 'node_revision',
'uri callback' => 'node_uri',
'fieldable' => TRUE,
'translation' => array(
'locale' => TRUE,
),
'entity keys' => array(
'id' => 'nid',
'revision' => 'vid',
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment