Change record status: 
Project: 
Introduced in branch: 
8.x
Description: 

A new type of form element was introduced in the form API, for the 8.x branch of the Drupal core project. The name of the element is "language_select". This form element allows module developers to assign a language to entities, for example, (or to whatever piece of data they want).

What the new form element does, is to actually print a select box with the language options. By default, if the Language module is not enabled and no default value is provided, the select box will not be printed in the form, and the value submitted will always be LANGUAGE_NOT_SPECIFIED. If the Language module is enabled, a select form field will be printed in the form and will contain a set of languages as options.

All the element options that a select field can use, can be also used for this new form element. In addition, there is a new option, “#languages”, that is actually a set of flags to specify what languages should appear as options. The value of the #languages property is directly passed to language_list(), and is therefore used to populate the #options list by default. The following language constants can be used: LANGUAGE_CONFIGURABLE, LANGUAGE_LOCKED, LANGUAGE_ALL.

In earlier versions, if you wanted to have a select box with a language field, as was the case for the Node module for example, the code would look something like this:

<?php
if (module_exists('language')) {
 
$languages = language_list(LANGUAGE_ALL);
 
$language_options = array();
  foreach (
$languages as $langcode => $language) {
   
// Make locked languages appear special in the list.
   
$language_options[$langcode] = $language->locked ? t('- @name -', array('@name' => $language->name)) : $language->name;
  }

 
$form['langcode'] = array(
   
'#type' => 'select',
   
'#title' => t('Language'),
   
'#default_value' => $node->langcode,
   
'#options' => $language_options,
   
'#access' => !variable_get('node_type_language_hidden_' . $node->type, TRUE),
  );
}
else {
 
$form['langcode'] = array(
   
'#type' => 'value',
   
'#value' => $node->langcode,
  );
}
?>

Using the new form element, the code now looks like this:

<?php
$form
['langcode'] = array(
 
'#title' => t('Language'),
 
'#type' => 'language_select',
 
'#default_value' => $node->langcode,
 
'#languages' => LANGUAGE_ALL,
 
'#access' => !variable_get('node_type_language_hidden_' . $node->type, TRUE),
);
?>

The whole logic of getting the options for the element is now handled by a form element process callback; this gives us smaller code which is also reusable.

Moreover, in the #languages option of the form element, the flags can be combined (bitwise), so you can have something like this:

<?php
$form
['languages_config_and_locked'] = array(
 
'#type' => 'language_select',
 
'#languages' => LANGUAGE_CONFIGURABLE | LANGUAGE_LOCKED,
);
?>
Impacts: 
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done