Commit ca250782 authored by catch's avatar catch
Browse files

Issue #1326638 by sven.lauer, jhodgdon: Clean up API docs for field_ui() module.

parent 07b29cba
/**
* @file
* Right-to-left specific stylesheet for the Field UI module.
*/
/* 'Manage fields' overview */
table.field-ui-overview tr.add-new .label-input {
......
......@@ -6,7 +6,11 @@
*/
/**
* Menu callback; lists all defined fields for quick reference.
* Page callback: Lists all defined fields for quick reference.
*
* Path: admin/reports/fields
*
* @see field_ui_menu()
*/
function field_ui_fields_list() {
$instances = field_info_instances();
......@@ -51,7 +55,7 @@ function field_ui_fields_list() {
}
/**
* Helper function to display a message about inactive fields.
* Displays a message listing the inactive fields of a given bundle.
*/
function field_ui_inactive_message($entity_type, $bundle) {
$inactive_instances = field_ui_inactive_instances($entity_type, $bundle);
......@@ -72,9 +76,9 @@ function field_ui_inactive_message($entity_type, $bundle) {
}
/**
* Helper function: determines the rendering order of a tree array.
* Determines the rendering order of an array representing a tree.
*
* This is intended as a callback for array_reduce().
* Callback for array_reduce() within field_ui_table_pre_render().
*/
function _field_ui_reduce_order($array, $a) {
$array = !isset($array) ? array() : $array;
......@@ -91,8 +95,9 @@ function _field_ui_reduce_order($array, $a) {
/**
* Returns the region to which a row in the 'Manage fields' screen belongs.
*
* This function is used as a #row_callback in field_ui_field_overview_form(),
* and is called during field_ui_table_pre_render().
* This function is used as a #region_callback in
* field_ui_field_overview_form(). It is called during
* field_ui_table_pre_render().
*/
function field_ui_field_overview_row_region($row) {
switch ($row['#row_type']) {
......@@ -109,8 +114,9 @@ function field_ui_field_overview_row_region($row) {
/**
* Returns the region to which a row in the 'Manage display' screen belongs.
*
* This function is used as a #row_callback in field_ui_field_overview_form(),
* and is called during field_ui_table_pre_render().
* This function is used as a #region_callback in
* field_ui_field_overview_form(), and is called during
* field_ui_table_pre_render().
*/
function field_ui_display_overview_row_region($row) {
switch ($row['#row_type']) {
......@@ -121,7 +127,12 @@ function field_ui_display_overview_row_region($row) {
}
/**
* Pre-render callback for field_ui_table elements.
* Render API callback: Performs pre-render tasks on field_ui_table elements.
*
* This function is assigned as a #pre_render callback in
* field_ui_element_info().
*
* @see drupal_render().
*/
function field_ui_table_pre_render($elements) {
$js_settings = array();
......@@ -274,9 +285,17 @@ function theme_field_ui_table($variables) {
}
/**
* Menu callback; listing of fields for a bundle.
* Form constructor for the 'Manage fields' form of a bundle.
*
* Allows fields and pseudo-fields to be re-ordered.
* Path: BUNDLE_ADMIN_PATH/fields, where BUNDLE_ADMIN_PATH is the path stored in
* the ['admin']['info'] property in the return value of hook_entity_info().
*
* The resulting form allows fields and pseudo-fields to be re-ordered.
*
* @see field_ui_menu()
* @see field_ui_overview_form_validate().
* @see field_ui_overview_form_submit().
* @ingroup forms
*/
function field_ui_field_overview_form($form, &$form_state, $entity_type, $bundle) {
$bundle = field_extract_bundle($entity_type, $bundle);
......@@ -630,7 +649,9 @@ function field_ui_field_overview_form($form, &$form_state, $entity_type, $bundle
}
/**
* Validate handler for the field overview form.
* Form validation handler for field_ui_field_overview_form().
*
* @see field_ui_field_overview_form_submit()
*/
function field_ui_field_overview_form_validate($form, &$form_state) {
_field_ui_field_overview_form_validate_add_new($form, $form_state);
......@@ -638,9 +659,9 @@ function field_ui_field_overview_form_validate($form, &$form_state) {
}
/**
* Helper function for field_ui_field_overview_form_validate.
* Validates the 'add new field' row of field_ui_field_overview_form().
*
* Validate the 'add new field' row.
* @see field_ui_field_overview_form_validate()
*/
function _field_ui_field_overview_form_validate_add_new($form, &$form_state) {
$field = $form_state['values']['fields']['_add_new_field'];
......@@ -702,9 +723,9 @@ function _field_ui_field_overview_form_validate_add_new($form, &$form_state) {
}
/**
* Helper function for field_ui_field_overview_form_validate.
* Validates the 'add existing field' row of field_ui_field_overview_form().
*
* Validate the 'add existing field' row.
* @see field_ui_field_overview_form_validate()
*/
function _field_ui_field_overview_form_validate_add_existing($form, &$form_state) {
// The form element might be absent if no existing fields can be added to
......@@ -740,7 +761,9 @@ function _field_ui_field_overview_form_validate_add_existing($form, &$form_state
}
/**
* Submit handler for the field overview form.
* Form submission handler for field_ui_field_overview_form().
*
* @see field_ui_field_overview_form_validate()
*/
function field_ui_field_overview_form_submit($form, &$form_state) {
$form_values = $form_state['values']['fields'];
......@@ -846,7 +869,18 @@ function field_ui_field_overview_form_submit($form, &$form_state) {
}
/**
* Menu callback; presents field display settings for a given view mode.
* Form constructor for the field display settings for a given view mode.
*
* Paths:
* - BUNDLE_ADMIN_PATH/display
* - BUNLDE_ADMIN_PATH/display/%view_mode
* where BUNDLE_ADMIN_PATH is the path stored in the ['admin']['info'] property
* in the return value of hook_entity_info().
*
* @see field_ui_menu()
* @see field_ui_display_overview_multistep_submit()
* @see field_ui_display_overview_form_submit()
* @ingroup forms
*/
function field_ui_display_overview_form($form, &$form_state, $entity_type, $bundle, $view_mode) {
$bundle = field_extract_bundle($entity_type, $bundle);
......@@ -1198,7 +1232,7 @@ function field_ui_display_overview_form($form, &$form_state, $entity_type, $bund
/**
* Form submit handler for multistep buttons on the 'Manage display' screen.
* Form submission handler for buttons in field_ui_display_overview_form().
*/
function field_ui_display_overview_multistep_submit($form, &$form_state) {
$trigger = $form_state['triggering_element'];
......@@ -1238,13 +1272,13 @@ function field_ui_display_overview_multistep_submit($form, &$form_state) {
}
/**
* Ajax handler for multistep buttons on the 'Manage display' screen.
* Ajax handler: Handles multistep buttons in field_ui_display_overview_form().
*/
function field_ui_display_overview_multistep_js($form, &$form_state) {
$trigger = $form_state['triggering_element'];
$op = $trigger['#op'];
// Pick the elements that need ro receive the ajax-new-content effect.
// Pick the elements that need to receive the ajax-new-content effect.
switch ($op) {
case 'edit':
$updated_rows = array($trigger['#field_name']);
......@@ -1276,7 +1310,7 @@ function field_ui_display_overview_multistep_js($form, &$form_state) {
}
/**
* Submit handler for the display overview form.
* Form submission handler for field_ui_display_overview_form().
*/
function field_ui_display_overview_form_submit($form, &$form_state) {
$form_values = $form_state['values'];
......@@ -1354,7 +1388,7 @@ function field_ui_display_overview_form_submit($form, &$form_state) {
}
/**
* Helper function for field_ui_display_overview_form_submit().
* Populates display settings for a new view mode from the default view mode.
*
* When an administrator decides to use custom display settings for a view mode,
* that view mode needs to be initialized with the display settings for the
......@@ -1363,8 +1397,6 @@ function field_ui_display_overview_form_submit($form, &$form_state) {
* them. It also modifies the passed-in $settings array, which the caller can
* then save using field_bundle_settings().
*
* @see field_bundle_settings()
*
* @param $entity_type
* The bundle's entity type.
* @param $bundle
......@@ -1374,6 +1406,9 @@ function field_ui_display_overview_form_submit($form, &$form_state) {
* @param $settings
* An associative array of bundle settings, as expected by
* field_bundle_settings().
*
* @see field_ui_display_overview_form_submit().
* @see field_bundle_settings()
*/
function _field_ui_add_default_view_mode_settings($entity_type, $bundle, $view_mode, &$settings) {
// Update display settings for field instances.
......@@ -1398,7 +1433,7 @@ function _field_ui_add_default_view_mode_settings($entity_type, $bundle, $view_m
}
/**
* Return an array of field_type options.
* Returns an array of field_type options.
*/
function field_ui_field_type_options() {
$options = &drupal_static(__FUNCTION__);
......@@ -1420,7 +1455,7 @@ function field_ui_field_type_options() {
}
/**
* Return an array of widget type options for a field type.
* Returns an array of widget type options for a field type.
*
* If no field type is provided, returns a nested array of all widget types,
* keyed by field type human name.
......@@ -1456,7 +1491,7 @@ function field_ui_widget_type_options($field_type = NULL, $by_label = FALSE) {
}
/**
* Return an array of formatter options for a field type.
* Returns an array of formatter options for a field type.
*
* If no field type is provided, returns a nested array of all formatters, keyed
* by field type.
......@@ -1484,7 +1519,7 @@ function field_ui_formatter_options($field_type = NULL) {
}
/**
* Return an array of existing field to be added to a bundle.
* Returns an array of existing fields to be added to a bundle.
*/
function field_ui_existing_field_options($entity_type, $bundle) {
$options = array();
......@@ -1522,7 +1557,15 @@ function field_ui_existing_field_options($entity_type, $bundle) {
}
/**
* Menu callback; presents the field settings edit page.
* Form constructor for the field settings edit page.
*
* Path: BUNDLE_ADMIN_PATH/fields/%field/field-settings, where BUNDLE_ADMIN_PATH
* is the path stored in the ['admin']['info'] property
* in the return value of hook_entity_info().
*
* @see field_ui_menu()
* @see field_ui_settings_form_submit()
* @ingroups forms
*/
function field_ui_field_settings_form($form, &$form_state, $instance) {
$bundle = $instance['bundle'];
......@@ -1576,7 +1619,7 @@ function field_ui_field_settings_form($form, &$form_state, $instance) {
}
/**
* Save a field's settings after editing.
* Form submission handler for field_ui_field_settings_form().
*/
function field_ui_field_settings_form_submit($form, &$form_state) {
$form_values = $form_state['values'];
......@@ -1603,7 +1646,15 @@ function field_ui_field_settings_form_submit($form, &$form_state) {
}
/**
* Menu callback; select a widget for the field.
* Form constructor for the widget selection form.
*
* Path: BUNDLE_ADMIN_PATH/fields/%field/widget-type, where BUNDLE_ADMIN_PATH is
* the path stored in the ['admin']['info'] property in the return value of
* hook_entity_info().
*
* @see field_ui_menu()
* @see field_ui_widget_type_form_submit()
* @ingroup forms
*/
function field_ui_widget_type_form($form, &$form_state, $instance) {
drupal_set_title($instance['label']);
......@@ -1647,7 +1698,7 @@ function field_ui_widget_type_form($form, &$form_state, $instance) {
}
/**
* Submit the change in widget type.
* Form submission handler for field_ui_widget_type_form().
*/
function field_ui_widget_type_form_submit($form, &$form_state) {
$form_values = $form_state['values'];
......@@ -1677,7 +1728,15 @@ function field_ui_widget_type_form_submit($form, &$form_state) {
}
/**
* Menu callback; present a form for removing a field instance from a bundle.
* Form constructor for removing a field instance from a bundle.
*
* Path: BUNDLE_ADMIN_PATH/fields/%field/delete, where BUNDLE_ADMIN_PATH is the
* path stored in the ['admin']['info'] property in the return value of
* hook_entity_info().
*
* @see field_ui_menu()
* @see field_ui_delete_form_submit()
* @ingroup forms
*/
function field_ui_field_delete_form($form, &$form_state, $instance) {
$bundle = $instance['bundle'];
......@@ -1707,9 +1766,10 @@ function field_ui_field_delete_form($form, &$form_state, $instance) {
}
/**
* Removes a field instance from a bundle.
* Form submission handler for field_ui_field_delete_form().
*
* If the field has no more instances, it will be marked as deleted too.
* Removes a field instance from a bundle. If the field has no more instances,
* it will be marked as deleted too.
*/
function field_ui_field_delete_form_submit($form, &$form_state) {
$form_values = $form_state['values'];
......@@ -1743,7 +1803,19 @@ function field_ui_field_delete_form_submit($form, &$form_state) {
}
/**
* Menu callback; presents the field instance edit page.
* Form constructor for the field instance settings form.
*
* Paths:
* - BUNDLE_ADMIN_PATH/fields/%field
* - BUNDLE_ADMIN_PATH/fields/%field/edit
* where BUNDLE_ADMIN_PATH is the path stored in the ['admin']['info'] property
* in the return value of hook_entity_info().
*
* @see field_ui_menu()
* @see field_ui_field_edit_form_validate()
* @see field_ui_field_edit_form_submit()
* @see field_ui_field_edit_form_delete_submit()
* @ingroup forms
*/
function field_ui_field_edit_form($form, &$form_state, $instance) {
$bundle = $instance['bundle'];
......@@ -1908,7 +1980,7 @@ function field_ui_field_edit_form($form, &$form_state, $instance) {
}
/**
* Handle the 'Delete' button on the field instance edit form.
* Form submission handler for 'Delete' button in field_ui_field_edit_form().
*/
function field_ui_field_edit_form_delete_submit($form, &$form_state) {
$destination = array();
......@@ -1921,11 +1993,14 @@ function field_ui_field_edit_form_delete_submit($form, &$form_state) {
}
/**
* Pre-render function for field instance settings.
* Render API callback: Merges instance, widget and other settings.
*
* Combines the instance, widget, and other settings into a single fieldset so
* that elements within each group can be shown at different weights as if they
* all had the same parent.
*
* This function is assigned as a #pre_render callback in
* field_ui_field_edit_form().
*/
function field_ui_field_edit_instance_pre_render($element) {
// Merge the widget settings into the main form.
......@@ -1948,7 +2023,7 @@ function field_ui_field_edit_instance_pre_render($element) {
}
/**
* Build default value fieldset.
* Builds the default value fieldset for a given field instance.
*/
function field_ui_default_value_widget($field, $instance, &$form, &$form_state) {
$field_name = $field['field_name'];
......@@ -1977,7 +2052,9 @@ function field_ui_default_value_widget($field, $instance, &$form, &$form_state)
}
/**
* Form validation handler for field instance settings form.
* Form validation handler for field_ui_field_edit_form().
*
* @see field_ui_field_edit_form_submit().
*/
function field_ui_field_edit_form_validate($form, &$form_state) {
// Take the incoming values as the $instance definition, so that the 'default
......@@ -2012,7 +2089,9 @@ function field_ui_field_edit_form_validate($form, &$form_state) {
}
/**
* Form submit handler for field instance settings form.
* Form submission handler for field_ui_field_edit_form().
*
* @see field_ui_field_edit_form_validate().
*/
function field_ui_field_edit_form_submit($form, &$form_state) {
$instance = $form_state['values']['instance'];
......@@ -2052,7 +2131,9 @@ function field_ui_field_edit_form_submit($form, &$form_state) {
}
/**
* Helper functions to handle multipage redirects.
* Extracts next redirect path from an array of multiple destinations.
*
* @see field_ui_next_destination()
*/
function field_ui_get_destinations($destinations) {
$path = array_shift($destinations);
......@@ -2064,7 +2145,7 @@ function field_ui_get_destinations($destinations) {
}
/**
* Return the next redirect path in a multipage sequence.
* Returns the next redirect path in a multipage sequence.
*/
function field_ui_next_destination($entity_type, $bundle) {
$destinations = !empty($_REQUEST['destinations']) ? $_REQUEST['destinations'] : array();
......
......@@ -132,7 +132,7 @@ function hook_field_widget_settings_form($field, $instance) {
/**
* Returns form elements for a formatter's settings.
* Specify the form elements for a formatter's settings.
*
* @param $field
* The field structure being configured.
......@@ -170,7 +170,7 @@ function hook_field_formatter_settings_form($field, $instance, $view_mode, $form
}
/**
* Returns a short summary for the current formatter settings of an instance.
* Return a short summary for the current formatter settings of an instance.
*
* If an empty result is returned, the formatter is assumed to have no
* configurable settings, and no UI will be provided to display a settings
......
/**
* @file
* Stylesheet for the Field UI module.
*/
/* 'Manage fields' and 'Manage display' overviews */
table.field-ui-overview tr.add-new .label-input {
float: left; /* LTR */
......
/**
* @file
* Attaches the behaviors for the Field UI module.
*/
(function($) {
Drupal.behaviors.fieldUIFieldOverview = {
......
<?php
/**
* @file
* Allows administrators to associate custom fields to fieldable types.
* Allows administrators to attach custom fields to fieldable types.
*/
/**
......@@ -195,7 +194,7 @@ function field_ui_menu() {
}
/**
* Menu loader; Load a field instance based on field and bundle name.
* Menu loader callback: Loads a field instance based on field and bundle name.
*
* @param $field_name
* The name of the field, as contained in the path.
......@@ -207,6 +206,11 @@ function field_ui_menu() {
* The position of $bundle_name in $map.
* @param $map
* The translated menu router path argument map.
*
* @return
* The field instance array.
*
* @ingroup field
*/
function field_ui_menu_load($field_name, $entity_type, $bundle_name, $bundle_pos, $map) {
// Extract the actual bundle name from the translated argument map.
......@@ -235,14 +239,25 @@ function field_ui_menu_load($field_name, $entity_type, $bundle_name, $bundle_pos
}
/**
* Menu title callback.
* Title callback: Returns the name of a given instance.
*
* Path: BUNDLE_ADMIN_PATH/fields/%field, where BUNDLE_ADMIN_PATH is the path
* stored in the ['admin']['info'] property in the return value of
* hook_entity_info().
*
* @see field_ui_menu()
*/
function field_ui_menu_title($instance) {
return $instance['label'];
}
/**
* Menu access callback for the 'view mode display settings' pages.
* Access callback: Checks access for the 'view mode display settings' pages.
*
* Path: BUNDLE_ADMIN_PATH/display, where BUNDLE_ADMIN_PATH is the path stored
* in the ['admin']['info'] property in the return value of hook_entity_info().
*
* @see field_ui_menu()
*/
function _field_ui_view_mode_menu_access($entity_type, $bundle, $view_mode, $access_callback) {
// First, determine visibility according to the 'use custom display'
......@@ -307,7 +322,7 @@ function field_ui_field_attach_create_bundle($entity_type, $bundle) {
}
/**
* Helper function to create the right administration path for a bundle.
* Determines the adminstration path for a bundle.
*/
function _field_ui_bundle_admin_path($entity_type, $bundle_name) {
$bundles = field_info_bundles($entity_type);
......@@ -318,7 +333,7 @@ function _field_ui_bundle_admin_path($entity_type, $bundle_name) {
}
/**
* Helper function to identify inactive fields within a bundle.
* Identifies inactive fields within a bundle.
*/
function field_ui_inactive_instances($entity_type, $bundle_name = NULL) {
if (!empty($bundle_name)) {
......@@ -345,7 +360,12 @@ function field_ui_inactive_instances($entity_type, $bundle_name = NULL) {
}
/**
* Add a button Save and add fields to Create content type form.
* Implements hook_form_FORM_ID_alter().
*
* Adds a button 'Save and add fields' to the 'Create content type' form.
*
* @see node_type_form()
* @see field_ui_form_node_type_form_submit()
*/
function field_ui_form_node_type_form_alter(&$form, $form_state) {
// We want to display the button only on add page.
......@@ -360,7 +380,9 @@ function field_ui_form_node_type_form_alter(&$form, $form_state) {
}
/**
* Redirect to manage fields form.
* Form submission handler for the 'Save and add fields' button.
*
* @see field_ui_form_node_type_form_alter()
*/
function field_ui_form_node_type_form_submit($form, &$form_state) {
if ($form_state['triggering_element']['#parents'][0] === 'save_continue') {
......
......@@ -6,7 +6,7 @@
*/
/**
* Helper class for Field UI test classes.
* Provides common functionality for the Field UI test classes.
*/
class FieldUITestCase extends DrupalWebTestCase {
......@@ -34,10 +34,10 @@ class FieldUITestCase extends DrupalWebTestCase {
}
/**
* Create a new field through the Field UI.
* Creates a new field through the Field UI.
*
* @param $bundle_path
* Path of the 'Manage fields' page for the bundle.
* Admin path of the bundle that the new field is to be attached to.
* @param $initial_edit
* $edit parameter for drupalPost() on the first step ('Manage fields'
* screen).
......@@ -74,10 +74,10 @@ class FieldUITestCase extends DrupalWebTestCase {
}
/**
* Add an existing field through the Field UI.
* Adds an existing field through the Field UI.
*
* @param $bundle_path
* Path of the 'Manage fields' page for the bundle.
* Admin path of the bundle that the field is to be attached to.
* @param $initial_edit
* $edit parameter for drupalPost() on the first step ('Manage fields'
* screen).
......@@ -105,10 +105,10 @@ class FieldUITestCase extends DrupalWebTestCase {
}
/**
* Delete a field instance through the Field UI.
* Deletes a field instance through the Field UI.
*
* @param $bundle_path
* Path of the 'Manage fields' page for the bundle.
* Admin path of the bundle that the field instance is to be deleted from.
* @param $field_name
* The name of the field.
* @param $label
......@@ -131,7 +131,7 @@ class FieldUITestCase extends DrupalWebTestCase {
}
/**
* Field UI tests for the 'Manage fields' screen.
* Tests the functionality of the 'Manage fields' screen.
*/
class FieldUIManageFieldsTestCase extends FieldUITestCase {
public static function getInfo() {
......@@ -152,7 +152,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
}
/**
* Main entry point for the field CRUD tests.
* Runs the field CRUD tests.
*
* In order to act on the same fields, and not create the fields over and over
* again the following tests create, update and delete the same fields.
......@@ -165,7 +165,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
}
/**
* Test the manage fields page.
* Tests the manage fields page.
*/
function manageFieldsPage() {
$this->drupalGet('admin/structure/types/manage/' . $this->hyphen_type . '/fields');
......@@ -190,7 +190,7 @@ class FieldUIManageFieldsTestCase extends FieldUITestCase {
}
/**
* Test adding a new field.
* Tests adding a new field.
*
* @todo Assert properties can bet set in the form and read back in $field and