Commit 0843922e authored by webchick's avatar webchick

Issue #2216539 by jhodgdon, dawehner: Fill in @defgroup/topic docs for Views overview.

parent 539061c7
......@@ -440,23 +440,6 @@
* @}
*/
/**
* @defgroup views_overview Views overview
* @{
* Overview of the Views module API
*
* @todo write this
*
* Additional documentation paragraphs need to be written, and functions,
* classes, and interfaces need to be added to this topic. Should link to all
* or most of the existing Views topics, and maybe this should be moved into
* a different file? This topic should be an overview so that developers know
* which of the many Views classes and topics are important if they want to
* accomplish tasks that they may have.
* @}
*/
/**
* @defgroup i18n Internationalization
* @{
......
......@@ -9,12 +9,6 @@
use Drupal\Core\Ajax\OpenModalDialogCommand;
use Drupal\Core\Ajax\AjaxResponse;
/**
* @defgroup views_ajax Views AJAX library
* @{
* Handles the server side AJAX interactions of Views.
*/
/**
* Wrapper around drupal_build_form to handle some AJAX stuff automatically.
* This makes some assumptions about the client.
......@@ -67,7 +61,3 @@ function views_ajax_form_wrapper($form_id, &$form_state) {
return (!empty($form_state['title'])) ? array('#title' => $form_state['title'], '#markup' => $output) : $output;
}
/**
* @}
*/
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views access plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\access\AccessPluginBase
*
* @ingroup views_access_plugins
*
* @Annotation
*/
class ViewsAccess extends ViewsPluginAnnotationBase {
......
......@@ -10,9 +10,11 @@
/**
* Defines a Plugin annotation object for views area handlers.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\area\AreaPluginBase
*
* @ingroup views_area_handlers
*
* @Annotation
*/
class ViewsArea extends ViewsHandlerAnnotationBase {
......
......@@ -10,9 +10,11 @@
/**
* Defines a Plugin annotation object for views argument handlers.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\argument\ArgumentPluginBase
*
* @ingroup views_argument_handlers
*
* @Annotation
*/
class ViewsArgument extends ViewsHandlerAnnotationBase {
......
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views argument default plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\argument_default\ArgumentDefaultPluginBase
*
* @ingroup views_argument_default_plugins
*
* @Annotation
*/
class ViewsArgumentDefault extends ViewsPluginAnnotationBase {
......
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views argument default plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\argument_validator\ArgumentValidatorPluginBase
*
* @ingroup views_argument_validate_plugins
*
* @Annotation
*/
class ViewsArgumentValidator extends ViewsPluginAnnotationBase {
......
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views cache plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\cache\CachePluginBase
*
* @ingroup views_cache_plugins
*
* @Annotation
*/
class ViewsCache extends ViewsPluginAnnotationBase {
......
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views display plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\display\DisplayPluginBase
*
* @ingroup views_display_plugins
*
* @Annotation
*/
class ViewsDisplay extends ViewsPluginAnnotationBase {
......
......@@ -10,9 +10,11 @@
/**
* Defines a Plugin annotation object for views display extender plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\display_extender\DisplayExtenderPluginBase
*
* @ingroup views_display_extender_plugins
*
* @Annotation
*/
class ViewsDisplayExtender extends ViewsPluginAnnotationBase {
......
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views exposed form plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase
*
* @ingroup views_exposed_form_plugins
*
* @Annotation
*/
class ViewsExposedForm extends ViewsPluginAnnotationBase {
......
......@@ -10,9 +10,11 @@
/**
* Defines a Plugin annotation object for views field handlers.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\field\FieldPluginBase
*
* @ingroup views_field_handlers
*
* @Annotation
*/
class ViewsField extends ViewsHandlerAnnotationBase {
......
......@@ -10,9 +10,11 @@
/**
* Defines a Plugin annotation object for views filter handlers.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\filter\FilterPluginBase
*
* @ingroup views_filter_handlers
*
* @Annotation
*/
class ViewsFilter extends ViewsHandlerAnnotationBase {
......
......@@ -10,9 +10,11 @@
/**
* Defines a Plugin annotation object for views join plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\join\JoinPluginBase
*
* @ingroup views_join_handlers
*
* @Annotation
*/
class ViewsJoin extends ViewsHandlerAnnotationBase {
......
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views pager plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\pager\PagerPluginBase
*
* @ingroup views_pager_plugins
*
* @Annotation
*/
class ViewsPager extends ViewsPluginAnnotationBase {
......
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views query plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\query\QueryPluginBase
*
* @ingroup views_query_plugins
*
* @Annotation
*/
class ViewsQuery extends ViewsPluginAnnotationBase {
......
......@@ -10,9 +10,11 @@
/**
* Defines a Plugin annotation object for views relationship handlers.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\relationship\RelationshipPluginBase
*
* @ingroup views_relationship_handlers
*
* @Annotation
*/
class ViewsRelationship extends ViewsHandlerAnnotationBase {
......
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views row plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\row\RowPluginBase
*
* @ingroup views_row_plugins
*
* @Annotation
*/
class ViewsRow extends ViewsPluginAnnotationBase {
......
......@@ -10,9 +10,11 @@
/**
* Defines a Plugin annotation object for views sort handlers.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\sort\SortPluginBase
*
* @ingroup views_sort_handlers
*
* @Annotation
*/
class ViewsSort extends ViewsHandlerAnnotationBase {
......
......@@ -12,9 +12,11 @@
/**
* Defines a Plugin annotation object for views style plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\style\StylePluginBase
*
* @ingroup views_style_plugins
*
* @Annotation
*/
class ViewsStyle extends ViewsPluginAnnotationBase {
......
......@@ -12,9 +12,12 @@
/**
* Defines a Plugin annotation object for views wizard plugins.
*
* @Annotation
*
* @see \Drupal\views\Plugin\views\wizard\WizardPluginBase
* @see \Drupal\views\Plugin\views\wizard\WizardInterface
*
* @ingroup views_wizard_plugins
*
* @Annotation
*/
class ViewsWizard extends ViewsPluginAnnotationBase {
......
......@@ -14,6 +14,8 @@
/**
* Plugin type manager for all views plugins.
*
* @ingroup views_plugins
*/
class ViewsPluginManager extends DefaultPluginManager {
......
......@@ -21,6 +21,11 @@
use Drupal\views\Views;
use Drupal\views\ViewsData;
/**
* Base class for Views handler plugins.
*
* @ingroup views_plugins
*/
abstract class HandlerBase extends PluginBase {
/**
......
......@@ -37,6 +37,8 @@
* root directory.
* - module: machine name of the module. It must be present for any plugin that
* wants to register a theme.
*
* @ingroup views_plugins
*/
abstract class PluginBase extends ComponentPluginBase implements ContainerFactoryPluginInterface {
......
......@@ -14,10 +14,17 @@
/**
* @defgroup views_access_plugins Views access plugins
* @{
* The base plugin to handle access to a view.
* Plugins to handle access checking for views.
*
* Therefore it primarily has to implement the access and the alterRouteDefinition
* method.
* Access plugins are responsible for controlling access to the view.
*
* Access plugins extend \Drupal\views\Plugin\views\access\AccessPluginBase,
* implementing the access() and alterRouteDefinition() methods. They must be
* annotated with \Drupal\views\Annotation\ViewsAccess annotation, and they
* must be in namespace directory Plugin\views\access.
*
* @ingroup views_plugins
* @see plugin_api
*/
/**
......
......@@ -2,7 +2,7 @@
/**
* @file
* Definition of Drupal\views\Plugin\views\area\AreaPluginBase.
* Contains \Drupal\views\Plugin\views\area\AreaPluginBase.
*/
namespace Drupal\views\Plugin\views\area;
......@@ -12,16 +12,20 @@
use Drupal\views\Plugin\views\HandlerBase;
/**
* @defgroup views_area_handlers Views area handlers
* @defgroup views_area_handlers Views area handler plugins
* @{
* Handlers to tell Views what can display in header, footer
* and empty text in a view.
* Plugins governing areas of views, such as header, footer, and empty text.
*
* Area handler plugins extend \Drupal\views\Plugin\views\area\AreaHandlerBase.
* They must be annotated with \Drupal\views\Annotation\ViewsArea annotation,
* and they must be in namespace directory Plugin\views\area.
*
* @ingroup views_plugins
* @see plugin_api
*/
/**
* Base class for area handlers.
*
* @ingroup views_area_handlers
* Base class for area handler plugins.
*/
abstract class AreaPluginBase extends HandlerBase {
......
......@@ -17,12 +17,23 @@
/**
* @defgroup views_argument_handlers Views argument handlers
* Handlers to tell Views how to contextually filter queries.
* @{
* Handler plugins for Views contextual filters.
*
* Handler plugins help build the view query object. Views argument handlers
* are for contextual filtering.
*
* Views argument handlers extend
* \Drupal\views\Plugin\views\argument\ArgumentHandlerBase. They must be
* annotated with \Drupal\views\Annotation\ViewsArgument annotation, and they
* must be in namespace directory Plugin\views\argument.
*
* @ingroup views_plugins
* @see plugin_api
*/
/**
* Base class for arguments.
* Base class for argument (contextual filter) handler plugins.
*
* The basic argument works for very simple arguments such as nid and uid
*
......@@ -42,8 +53,6 @@
* and may disappear or change.
* - numeric: If set to TRUE this field is numeric and will use %d instead of
* %s in queries.
*
* @ingroup views_argument_handlers
*/
abstract class ArgumentPluginBase extends HandlerBase {
......
......@@ -2,7 +2,7 @@
/**
* @file
* Definition of Drupal\views\Plugin\views\argument_default\ArgumentDefaultPluginBase.
* Contains \Drupal\views\Plugin\views\argument_default\ArgumentDefaultPluginBase.
*/
namespace Drupal\views\Plugin\views\argument_default;
......@@ -14,7 +14,20 @@
/**
* @defgroup views_argument_default_plugins Views argument default plugins
* @{
* Allow specialized methods of filling in arguments when they aren't provided.
* Plugins for argument defaults in Views.
*
* Argument default plugins provide default values for contextual filters.
* This is useful for blocks and other display types lacking a natural argument
* input. Examples are plugins to extract node and user IDs from the URL.
*
* Argument default plugins extend
* \Drupal\views\Plugin\views\argument_default\ArgumentDefaultPluginBase. They
* must be annotated with \Drupal\Views\Annotation\ViewsArgumentDefault
* annotation, and they must be in namespace directory
* Plugin\views\argument_default.
*
* @ingroup views_plugins
* @see plugin_api
*/
/**
......
......@@ -2,7 +2,7 @@
/**
* @file
* Definition of Drupal\views\Plugin\views\argument_validator\ArgumentValidatorPluginBase.
* Contains \Drupal\views\Plugin\views\argument_validator\ArgumentValidatorPluginBase.
*/
namespace Drupal\views\Plugin\views\argument_validator;
......@@ -14,7 +14,23 @@
/**
* @defgroup views_argument_validate_plugins Views argument validate plugins
* @{
* Allow specialized methods of validating arguments.
* Plugins for validating views contextual filters.
*
* Views argument validator plugins validate contextual filters (arguments) on
* views. They can ensure arguments are valid, and even do transformations on
* the arguments. They can also provide replacement patterns for the view title.
* For example, the 'content' validator verifies verifies that the argument
* value corresponds to a node, loads that node, and provides the node title
* as a replacement pattern for the view title.
*
* Argument validator plugins extend
* \Drupal\views\Plugin\views\argument_validator\ArgumentValidatorPluginBase.
* They must be annotated with
* \Drupal\views\Plugin\Annotation\ViewsArgumentValidator annotation, and they
* must be in namespace directory Plugin\views\argument_validator.
*
* @ingroup views_plugins
* @see plugin_api
*/
/**
......
......@@ -2,7 +2,7 @@
/**
* @file
* Definition of Drupal\views\Plugin\views\cache\CachePluginBase.
* Contains \Drupal\views\Plugin\views\cache\CachePluginBase.
*/
namespace Drupal\views\Plugin\views\cache;
......@@ -14,10 +14,17 @@
/**
* @defgroup views_cache_plugins Views cache plugins
* @{
* The base plugin to handler caching of a view.
* Plugins to handle the storage and loading of Views caches.
*
* Cache plugins can handle both caching of just the database result and
* the rendered output of the view.
* Cache plugins control the storage and loading of caches in Views, for
* both result and render caching.
*
* Cache plugins extend \Drupal\views\Plugin\views\cache\CachePluginBase.
* They must be annotated with \Drupal\views\Annotation\ViewsCache
* annotation, and must be in namespace directory Plugin\views\cache.
*
* @ingroup views_plugins
* @see plugin_api
*/
/**
......
......@@ -2,7 +2,7 @@
/**
* @file
* Contains Drupal\views\Plugin\views\display\DisplayPluginBase.
* Contains \Drupal\views\Plugin\views\display\DisplayPluginBase.
*/
namespace Drupal\views\Plugin\views\display;
......@@ -22,16 +22,26 @@
/**
* @defgroup views_display_plugins Views display plugins
* @{
* Display plugins control how Views interact with the rest of Drupal.
* Plugins to handle the overall display of views.
*
* They can handle creating Views from a Drupal page hook; they can
* handle creating Views from a Drupal block hook. They can also
* handle creating Views from an external module source.
* Display plugins are responsible for controlling where a view is rendered;
* that is, how it is exposed to other parts of Drupal. 'Page' and 'block' are
* the most commonly used display plugins. Each view also has a 'master' (or
* 'default') display that includes information shared between all its
* displays (see \Drupal\views\Plugin\views\display\DefaultDisplay).
*
* Display plugins extend \Drupal\views\Plugin\views\display\DisplayPluginBase.
* They must be annotated with \Drupal\views\Plugin\Annotation\ViewsDisplay
* annotation, and they must be in namespace directory Plugin\views\display.
*
* @ingroup views_plugins
*
* @see plugin_api
* @see views_display_extender_plugins
*/
/**
* The default display plugin handler. Display plugins handle options and
* basic mechanisms for different output methods.
* Base class for views display plugins.
*/
abstract class DisplayPluginBase extends PluginBase {
......
......@@ -2,13 +2,15 @@
/**
* @file
* Definition of Drupal\views\Plugin\views\display_extender\DefaultDisplayExtender.
* Contains \Drupal\views\Plugin\views\display_extender\DefaultDisplayExtender.
*/
namespace Drupal\views\Plugin\views\display_extender;
/**
* @todo
* Default display extender plugin; does nothing.
*
* @ingroup views_display_extender_plugins
*
* @ViewsDisplayExtender(
* id = "default",
......
......@@ -2,7 +2,7 @@
/**
* @file
* Definition of Drupal\views\Plugin\views\display_extender\DisplayExtenderPluginBase.
* Contains \Drupal\views\Plugin\views\display_extender\DisplayExtenderPluginBase.
*/
namespace Drupal\views\Plugin\views\display_extender;
......@@ -11,9 +11,30 @@
use Drupal\views\Plugin\views\PluginBase;
/**
* @todo.
* @defgroup views_display_extender_plugins Views display extender plugins
* @{
* Plugins that offer additional display options across display types.
*
* @ingroup views_display_plugins
* Display extender plugins allow additional options or configuration to be
* added to views across all display types. For example, if you wanted to allow
* site users to add certain metadata to the rendered output of every view
* display regardless of display type, you could provide this option as a
* display extender.
*
* Display extender plugins extend
* \Drupal\views\Plugin\views\display_extender\DisplayExtenderPluginBase.
* They must be annotated with
* \Drupal\views\Plugin\Annotation\ViewsDisplayExtender annotation, and they
* must be in namespace directory Plugin\views\display_extender.
*
* @ingroup views_plugins
*
* @see plugin_api
* @see views_display_plugins
*/
/**
* Base class for Views display extender plugins.
*/
abstract class DisplayExtenderPluginBase extends PluginBase {
......@@ -61,3 +82,7 @@ public function optionsSummary(&$categories, &$options) { }
public function defaultableSections(&$sections, $section = NULL) { }
}
/**
* @}
*/
......@@ -2,7 +2,7 @@
/**
* @file
* Definition of Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase.
* Contains \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase.
*/
namespace Drupal\views\Plugin\views\exposed_form;
......@@ -16,13 +16,21 @@
/**
* @defgroup views_exposed_form_plugins Views exposed form plugins
* @{
* Plugins that handle the validation/submission and rendering of exposed forms.
* Plugins that handle validation, submission, and rendering of exposed forms.
*
* If needed, it is possible to use them to add additional form elements.
* Exposed forms are used for filters, sorts, and pager settings that are
* exposed to site visitors. Exposed form plugins handle the rendering,
* validation, and submission of exposed forms, and may add additional form
* elements.
*
* Exposed form plugins extend
* \Drupal\views\Plugin\views\exposed_form\ExposedFormPluginBase. They must be
* annotated with \Drupal\views\Plugin\Annotation\ViewsExposedForm annotation,
* and they must be in namespace directory Plugin\views\exposed_form.
*/
/**
* The base plugin to handle exposed filter forms.
* Base class for Views exposed filter form plugins.
*/
abstract class ExposedFormPluginBase extends PluginBase {
......
......@@ -2,7 +2,7 @@
/**
* @file
* Definition of Drupal\views\Plugin\views\field\FieldPluginBase.
* Contains \Drupal\views\Plugin\views\field\FieldPluginBase.
*/
namespace Drupal\views\Plugin\views\field;
......@@ -17,24 +17,33 @@
use Drupal\views\ViewExecutable;
/**
* @defgroup views_field_handlers Views field handlers
* @defgroup views_field_handlers Views field handler plugins
* @{
* Handlers to tell Views how to build and display fields.
* Handler plugins for Views fields.
*
* Field handlers handle both querying and display of fields in views.
*
* Field handler plugins extend
* \Drupal\views\Plugin\views\field\FieldHandlerBase. They must be
* annotated with \Drupal\views\Annotation\ViewsField annotation, and they
* must be in namespace directory Plugin\views\field.
*
* The following items can go into a hook_views_data() implementation in a
* field section to affect how the field handler will behave:
* - additional fields: An array of fields that should be added to the query.
* The array is in the form of: