From 1cb4760a4d1e70b0d0a53baf3dde7beca44e5a73 Mon Sep 17 00:00:00 2001 From: Lars Toomre Date: Mon, 24 Sep 2012 15:13:07 -0400 Subject: [PATCH] Issue 1793510-4 by Lars Toomre: Documentation improvement to three more files. --- .../views/Plugin/views/wizard/WizardInterface.php | 2 +- .../views/Plugin/views/wizard/WizardPluginBase.php | 73 ++++++- views_ui.module | 219 +++++++++++++++----- 3 files changed, 224 insertions(+), 70 deletions(-) diff --git a/lib/Drupal/views/Plugin/views/wizard/WizardInterface.php b/lib/Drupal/views/Plugin/views/wizard/WizardInterface.php index cd340fb..7cf9e81 100644 --- a/lib/Drupal/views/Plugin/views/wizard/WizardInterface.php +++ b/lib/Drupal/views/Plugin/views/wizard/WizardInterface.php @@ -29,7 +29,7 @@ interface WizardInterface { function build_form(array $form, array &$form_state); /** - * Validate form and values. + * Validates the form and its values. * * @param array $form * The full wizard form array. diff --git a/lib/Drupal/views/Plugin/views/wizard/WizardPluginBase.php b/lib/Drupal/views/Plugin/views/wizard/WizardPluginBase.php index 990a40c..2b80eef 100644 --- a/lib/Drupal/views/Plugin/views/wizard/WizardPluginBase.php +++ b/lib/Drupal/views/Plugin/views/wizard/WizardPluginBase.php @@ -111,6 +111,13 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { /** * Constructs a WizardPluginBase object. + * + * @param array $configuration + * ??? + * @param ??? $pugin_id + * ??? + * @param Drupal\Component\Plugin\Discovery\DiscoveryInterface $discovery + * The discovery interface object. */ public function __construct(array $configuration, $plugin_id, DiscoveryInterface $discovery) { parent::__construct($configuration, $plugin_id, $discovery); @@ -139,11 +146,11 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { /** * Gets the pathField property. * - * @return array - * The pathField array. - * * @todo Rename this to be something about jump menus, and/or resolve this * dependency. + * + * @return array + * The pathField array. */ public function getPathField() { return $this->pathField; @@ -152,9 +159,10 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { /** * Gets the pathFieldsSupplemental property. * - * @return array() - * * @todo Rename this to be something about jump menus, and/or remove this. + * + * @return array + * ??? */ public function getPathFieldsSupplemental() { return $this->pathFieldsSupplemental; @@ -164,6 +172,7 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { * Gets the filters property. * * @return array + * The filters array. */ public function getFilters() { $filters = array(); @@ -182,6 +191,7 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { * Gets the availableSorts property. * * @return array + * ??? */ public function getAvailableSorts() { return $this->availableSorts; @@ -191,6 +201,7 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { * Gets the sorts property. * * @return array + * The sorts array. */ public function getSorts() { return $this->sorts; @@ -475,6 +486,11 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { * * By default, this adds "of type" and "tagged with" filters (when they are * available). + * + * @param array $form + * The full wizard form array. + * @param array $form_state + * The current state of the wizard form. */ protected function build_filters(&$form, &$form_state) { // Find all the fields we are allowed to filter by. @@ -506,6 +522,11 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { * Builds the form structure for selecting the view's sort order. * * By default, this adds a "sorted by [date]" filter (when it is available). + * + * @param array $form + * The full wizard form array. + * @param array $form_state + * The current state of the wizard form. */ protected function build_sorts(&$form, &$form_state) { $sorts = array( @@ -543,7 +564,12 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { /** * Instantiates a view object from form values. * - * @return Drupal\views\ViewExecutable + * @param array $form + * The full wizard form array. + * @param array $form_state + * The current state of the wizard form. + * + * @return Drupal\views\ViewUI * The instantiated view object. */ protected function instantiate_view($form, &$form_state) { @@ -572,6 +598,11 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { /** * Builds an array of display options for the view. * + * @param array $form + * The full wizard form array. + * @param array $form_state + * The current state of the wizard form. + * * @return array * An array whose keys are the names of each display and whose values are * arrays of options for that display. @@ -606,6 +637,14 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { /** * Alters the full array of display options before they are added to the view. + * + * @param array $display_options + * An array whose keys are the names of each display and whose values are + * arrays of options for that display. + * @param array $form + * The full wizard form array. + * @param array $form_state + * The current state of the wizard form. */ protected function alter_display_options(&$display_options, $form, $form_state) { foreach ($display_options as $display_type => $options) { @@ -617,6 +656,16 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { /** * Adds the array of display options to the view, with appropriate overrides. + * + * @param Drupal\views\ViewStorage + * The view object being worked with. + * @param array $display_options + * An array whose keys are the names of each display and whose values are + * arrays of options for that display. + * @param array $form + * The full wizard form array. + * @param array $form_state + * The current state of the wizard form. */ protected function addDisplays(ViewStorage $view, $display_options, $form, $form_state) { // Display: Master @@ -657,8 +706,8 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { /** * Assembles the default display options for the view. * - * Most wizards will need to override this method to provide some fields - * or a different row plugin. + * Most wizards will need to override this method to provide some fields or a + * different row plugin. * * @return array * Returns an array of display options. @@ -840,9 +889,8 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { } // If the input is invalid, for example when the #default_value contains - // created from node, but the wizard type is another base table, make - // sure it is not added. This usually don't happen if you have js - // enabled. + // created from node, but the wizard type is another base table, make sure + // it is not added. This usually don't happen if you have js enabled. $data = views_fetch_data($table); if (isset($data[$column]['sort'])) { $sorts[$column] = array( @@ -1027,7 +1075,8 @@ abstract class WizardPluginBase extends PluginBase implements WizardInterface { * @param array $form_state * The current state of the wizard form. * @param bool $unset - * Should the view be removed from the list of validated views. + * (optional) Indicates whether the view should be removed from the list of + * validated views. Defaults to TRUE. * * @return Drupal\views\ViewUI $view * The validated view object. diff --git a/views_ui.module b/views_ui.module index c6dfae1..4ec9472 100644 --- a/views_ui.module +++ b/views_ui.module @@ -182,7 +182,15 @@ function views_ui_theme() { return array( // edit a view 'views_ui_display_tab_setting' => array( - 'variables' => array('description' => '', 'link' => '', 'settings_links' => array(), 'overridden' => FALSE, 'defaulted' => FALSE, 'description_separator' => TRUE, 'class' => array()), + 'variables' => array( + 'description' => '', + 'link' => '', + 'settings_links' => array(), + 'overridden' => FALSE, + 'defaulted' => FALSE, + 'description_separator' => TRUE, + 'class' => array(), + ), 'template' => 'views-ui-display-tab-setting', 'path' => "$path/theme", ), @@ -192,7 +200,12 @@ function views_ui_theme() { 'path' => "$path/theme", ), 'views_ui_edit_item' => array( - 'variables' => array('type' => NULL, 'view' => NULL, 'display' => NULL, 'no_fields' => FALSE), + 'variables' => array( + 'type' => NULL, + 'view' => NULL, + 'display' => NULL, + 'no_fields' => FALSE, + ), 'template' => 'views-ui-edit-item', 'path' => "$path/theme", ), @@ -220,7 +233,7 @@ function views_ui_theme() { 'file' => 'includes/admin.inc', ), - // tab themes + // Tab themes. 'views_tabset' => array( 'variables' => array('tabs' => NULL), ), @@ -232,7 +245,7 @@ function views_ui_theme() { 'file' => 'includes/admin.inc', ), - // On behalf of a plugin + // On behalf of a plugin. 'views_ui_style_plugin_table' => array( 'render element' => 'form', ), @@ -268,6 +281,12 @@ function views_ui_custom_theme() { /** * Page title callback for the Edit View page. + * + * @param Drupal\views\ViewUI $view + * The view being edited. + * + * @return string + * The title of the page. */ function views_ui_edit_page_title(ViewUI $view) { module_load_include('inc', 'views_ui', 'includes/admin'); @@ -324,8 +343,13 @@ function views_ui_cache_load($name) { } /** - * Specialized cache function to add a flag to our view, include an appropriate - * include, and cache more easily. + * Sets the cached copy of a view. + * + * This specialized cache function adds a flag to our view, includes an + * appropriate include, and caches more easily. + * + * @param Drupal\views\ViewUI $view + * The view being edited. */ function views_ui_cache_set(ViewUI $view) { if (!empty($view->locked)) { @@ -351,22 +375,26 @@ function views_ui_cache_set(ViewUI $view) { /** * Theme preprocess for views-view.tpl.php. + * + * @param array $variables + * Array of key/value pairs passed by reference and used in the theme + * sub-system. */ -function views_ui_preprocess_views_view(&$vars) { - $view = $vars['view']; +function views_ui_preprocess_views_view(&$variables) { + $view = $variables['view']; if (!empty($view->views_ui_context) && module_exists('contextual')) { $view->hide_admin_links = TRUE; foreach (array('title', 'header', 'exposed', 'rows', 'pager', 'more', 'footer', 'empty', 'attachment_after', 'attachment_before') as $section) { - if (!empty($vars[$section])) { - $vars[$section] = array( + if (!empty($variables[$section])) { + $variables[$section] = array( '#theme' => 'views_ui_view_preview_section', '#view' => $view, '#section' => $section, - '#content' => is_array($vars[$section]) ? drupal_render($vars[$section]) : $vars[$section], + '#content' => is_array($variables[$section]) ? drupal_render($variables[$section]) : $variables[$section], '#theme_wrappers' => array('views_container'), '#attributes' => array('class' => 'contextual-region'), ); - $vars[$section] = drupal_render($vars[$section]); + $variables[$section] = drupal_render($variables[$section]); } } } @@ -375,52 +403,65 @@ function views_ui_preprocess_views_view(&$vars) { /** * Theme preprocess for theme_views_ui_view_preview_section(). * - * @TODO + * @todo * Perhaps move this to includes/admin.inc or theme/theme.inc + * + * @param array $variables + * Array of key/value pairs passed by reference and used in the theme + * sub-system. */ -function template_preprocess_views_ui_view_preview_section(&$vars) { - switch ($vars['section']) { +function template_preprocess_views_ui_view_preview_section(&$variables) { + switch ($variables['section']) { case 'title': - $vars['title'] = t('Title'); - $links = views_ui_view_preview_section_display_category_links($vars['view'], 'title', $vars['title']); + $variables['title'] = t('Title'); + $links = views_ui_view_preview_section_display_category_links($variables['view'], 'title', $variables['title']); break; + case 'header': - $vars['title'] = t('Header'); - $links = views_ui_view_preview_section_handler_links($vars['view'], $vars['section']); + $variables['title'] = t('Header'); + $links = views_ui_view_preview_section_handler_links($variables['view'], $variables['section']); break; + case 'empty': - $vars['title'] = t('No results behavior'); - $links = views_ui_view_preview_section_handler_links($vars['view'], $vars['section']); + $variables['title'] = t('No results behavior'); + $links = views_ui_view_preview_section_handler_links($variables['view'], $variables['section']); break; + case 'exposed': // @todo Sorts can be exposed too, so we may need a better title. - $vars['title'] = t('Exposed Filters'); - $links = views_ui_view_preview_section_display_category_links($vars['view'], 'exposed_form_options', $vars['title']); + $variables['title'] = t('Exposed Filters'); + $links = views_ui_view_preview_section_display_category_links($variables['view'], 'exposed_form_options', $variables['title']); break; + case 'rows': // @todo The title needs to depend on what is being viewed. - $vars['title'] = t('Content'); - $links = views_ui_view_preview_section_rows_links($vars['view']); + $variables['title'] = t('Content'); + $links = views_ui_view_preview_section_rows_links($variables['view']); break; + case 'pager': - $vars['title'] = t('Pager'); - $links = views_ui_view_preview_section_display_category_links($vars['view'], 'pager_options', $vars['title']); + $variables['title'] = t('Pager'); + $links = views_ui_view_preview_section_display_category_links($variables['view'], 'pager_options', $variables['title']); break; + case 'more': - $vars['title'] = t('More'); - $links = views_ui_view_preview_section_display_category_links($vars['view'], 'use_more', $vars['title']); + $variables['title'] = t('More'); + $links = views_ui_view_preview_section_display_category_links($variables['view'], 'use_more', $variables['title']); break; + case 'footer': - $vars['title'] = t('Footer'); - $links = views_ui_view_preview_section_handler_links($vars['view'], $vars['section']); + $variables['title'] = t('Footer'); + $links = views_ui_view_preview_section_handler_links($variables['view'], $variables['section']); break; + case 'attachment_before': - // @todo: Add links to the attachment configuration page. - $vars['title'] = t('Attachment before'); + // @todo Add links to the attachment configuration page. + $variables['title'] = t('Attachment before'); break; + case 'attachment_after': - // @todo: Add links to the attachment configuration page. - $vars['title'] = t('Attachment after'); + // @todo Add links to the attachment configuration page. + $variables['title'] = t('Attachment after'); break; } @@ -435,29 +476,37 @@ function template_preprocess_views_ui_view_preview_section(&$vars) { 'library' => array(array('contextual', 'contextual-links')), ), ); - $vars['links'] = drupal_render($build); + $variables['links'] = drupal_render($build); } - $vars['theme_hook_suggestions'][] = 'views_ui_view_preview_section__' . $vars['section']; + $variables['theme_hook_suggestions'][] = 'views_ui_view_preview_section__' . $variables['section']; } /** * Returns the HTML for a section of a View being previewed within the Views UI. */ -function theme_views_ui_view_preview_section($vars) { - return '

' . $vars['title'] . '

' - . $vars['links'] - . '
'. $vars['content'] . '
'; +function theme_views_ui_view_preview_section($variables) { + return '

' . $variables['title'] . '

' + . $variables['links'] + . '
'. $variables['content'] . '
'; } /** * Returns contextual links for each handler of a certain section. * - * @TODO + * @todo * Bring in relationships * Refactor this function to use much stuff of views_ui_edit_form_get_bucket. * - * @param $title - * Add a bolded title of this section. + * @param Drupal\views\ViewUI $view + * The view being edited. + * @param ??? $type + * ??? + * @param bool $title + * (optionals) Indicates whether to add a bolded title of this section. + * Defaults to FALSE. + * + * @return array + * An array of links. */ function views_ui_view_preview_section_handler_links(ViewUI $view, $type, $title = FALSE) { $display = $view->display_handler->display; @@ -490,6 +539,17 @@ function views_ui_view_preview_section_handler_links(ViewUI $view, $type, $title /** * Returns a link to editing a certain display setting. + * + * @param Drupal\views\ViewUI $view + * The view being edited. + * @param ??? $type + * ??? + * @param bool $title + * (optionals) Indicates whether to add a bolded title of this section. + * Defaults to FALSE. + * + * @return array + * An array of lndividual link information. */ function views_ui_view_preview_section_display_category_links(ViewUI $view, $type, $title) { $display = $view->display_handler->display; @@ -506,6 +566,12 @@ function views_ui_view_preview_section_display_category_links(ViewUI $view, $typ /** * Returns all contextual links for the main content part of the view. + * + * @param Drupal\views\ViewUI $view + * The view being edited. + * + * @return array + * An array of links information. */ function views_ui_view_preview_section_rows_links(ViewUI $view) { $display = $view->display_handler->display; @@ -520,17 +586,17 @@ function views_ui_view_preview_section_rows_links(ViewUI $view) { } /** - * Fetch metadata on a specific views ui wizard plugin. + * Fetches metadata on a specific views UI wizard plugin. * - * @param $wizard_type + * @param string $wizard_type * Name of a wizard, or name of a base table. * - * @return + * @return array * An array with information about the requested wizard type. */ function views_ui_get_wizard($wizard_type) { $wizard = views_get_plugin_definition('wizard', $wizard_type); - // @todo - handle this via an alter hook instead. + // @todo Handle this via an alter hook instead. if (!$wizard) { // Must be a base table using the default wizard plugin. $base_tables = views_fetch_base_tables(); @@ -544,9 +610,9 @@ function views_ui_get_wizard($wizard_type) { } /** - * Fetch metadata for all content_type plugins. + * Fetches metadata for all content_type plugins. * - * @return + * @return array * An array of arrays with information about all available views wizards. */ function views_ui_get_wizards() { @@ -558,7 +624,7 @@ function views_ui_get_wizards() { $base_tables = views_fetch_base_tables(); $default_wizard = views_ui_views_wizard_defaults(); // Find base tables with no wizard. - // @todo - handle this via an alter hook for plugins? + // @todo Handle this via an alter hook for plugins? foreach ($base_tables as $table => $info) { if (!isset($wizard_tables[$table])) { $wizard = $default_wizard; @@ -571,9 +637,9 @@ function views_ui_get_wizards() { } /** - * Helper function to define the default values for a Views wizard plugin. + * Defines the default values for a Views wizard plugin. * - * @return + * @return array * An array of defaults for a views wizard. */ function views_ui_views_wizard_defaults() { @@ -588,6 +654,15 @@ function views_ui_views_wizard_defaults() { ); } +/** + * ??? + * + * @param array $wizard + * ??? + * + * @return ??? + * ??? + */ function views_ui_get_form_wizard_instance($wizard) { return views_get_plugin('wizard', $wizard['name']); } @@ -629,6 +704,12 @@ function views_ui_contextual_links_view_alter(&$element, $items) { /** * Sets a static variable for controlling whether contextual links are rendered. * + * @param bool|null $set + * ??? + * + * @return bool|null + * ??? + * * @see views_ui_contextual_links_view_alter() */ function views_ui_contextual_links_suppress($set = NULL) { @@ -652,7 +733,7 @@ function views_ui_contextual_links_suppress($set = NULL) { * @see views_ui_contextual_links_suppress_pop() */ function views_ui_contextual_links_suppress_push() { - views_ui_contextual_links_suppress(((int) views_ui_contextual_links_suppress())+1); + views_ui_contextual_links_suppress(((int) views_ui_contextual_links_suppress()) + 1); } /** @@ -661,7 +742,7 @@ function views_ui_contextual_links_suppress_push() { * @see views_ui_contextual_links_suppress_push() */ function views_ui_contextual_links_suppress_pop() { - views_ui_contextual_links_suppress(((int) views_ui_contextual_links_suppress())-1); + views_ui_contextual_links_suppress(((int) views_ui_contextual_links_suppress()) - 1); } /** @@ -681,6 +762,12 @@ function views_ui_contextual_links_suppress_pop() { * literal value as the first argument, because $form_id determines which form * builder function gets called, so must be safe from user tampering. * + * @param string $form_id + * ??? + * + * @return ??? + * ??? + * * @see drupal_get_form() * @see ajax_form_callback() * @see http://drupal.org/node/774876 @@ -722,8 +809,12 @@ function views_ui_ajax_get_form($form_id) { * The javascript patch overwrites the $.ui.dialog.overlay.events object to remove * the mousedown, mouseup and click events from the list of events that are bound * in $.ui.dialog.overlay.create. + * + * @param ??? $libraries + * ??? + * @param ??? $module + * ??? */ - function views_ui_library_alter(&$libraries, $module) { if ($module == 'system' && isset($libraries['jquery.ui.dialog'])) { if (version_compare($libraries['jquery.ui.dialog']['version'], '1.7.2', '>=')) { @@ -733,9 +824,17 @@ function views_ui_library_alter(&$libraries, $module) { } /** - * Truncate strings to a set length and provide a ... if they truncated. + * Truncates a string to a set length and provide a ... if they truncated. * * This is often used in the UI to ensure long strings fit. + * + * @param string $string + * A string potentially to be truncated. + * @param int $length + * The desired length of the truncated string. + * + * @return string + * The truncated string with ellipses added. */ function views_ui_truncate($string, $length) { if (drupal_strlen($string) > $length) { @@ -748,6 +847,12 @@ function views_ui_truncate($string, $length) { /** * Magic load function. Wrapper to load a view. + * + * @param string $name + * Name of the view. + * + * @return ??? + * ??? */ function views_ui_load($name) { return views_get_view($name); -- 1.7.6.msysgit.0