From 371e762470efc1a8c68d5d7273964ba907e66365 Mon Sep 17 00:00:00 2001
From: webchick <drupal@webchick.net>
Date: Mon, 16 Jun 2014 09:31:16 -0700
Subject: [PATCH] Issue #2216533 by jhodgdon: Fill in topic/@defgroup docs for
Entity API overview.
---
.../Drupal/Core/Entity/ContentEntityBase.php | 2 +
.../Core/Entity/ContentEntityInterface.php | 2 +
.../Drupal/Core/Entity/EntityListBuilder.php | 2 +
core/lib/Drupal/Core/Entity/EntityType.php | 2 +
.../Drupal/Core/Entity/EntityViewBuilder.php | 2 +
.../src/ContentTranslationHandler.php | 2 +
core/modules/system/core.api.php | 96 ++++++++++++++-----
7 files changed, 83 insertions(+), 25 deletions(-)
diff --git a/core/lib/Drupal/Core/Entity/ContentEntityBase.php b/core/lib/Drupal/Core/Entity/ContentEntityBase.php
index 9716ccce983d..2ece2b51168c 100644
--- a/core/lib/Drupal/Core/Entity/ContentEntityBase.php
+++ b/core/lib/Drupal/Core/Entity/ContentEntityBase.php
@@ -16,6 +16,8 @@
/**
* Implements Entity Field API specific enhancements to the Entity class.
+ *
+ * @ingroup entity_api
*/
abstract class ContentEntityBase extends Entity implements \IteratorAggregate, ContentEntityInterface {
diff --git a/core/lib/Drupal/Core/Entity/ContentEntityInterface.php b/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
index 654fc5eb77ed..f07936c186d5 100644
--- a/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
@@ -25,6 +25,8 @@
*
* @see \Drupal\Core\TypedData\TypedDataManager
* @see \Drupal\Core\Field\FieldItemListInterface
+ *
+ * @ingroup entity_api
*/
interface ContentEntityInterface extends EntityInterface, RevisionableInterface, TranslatableInterface, ComplexDataInterface {
diff --git a/core/lib/Drupal/Core/Entity/EntityListBuilder.php b/core/lib/Drupal/Core/Entity/EntityListBuilder.php
index ca5025c4f564..16a0849bf406 100644
--- a/core/lib/Drupal/Core/Entity/EntityListBuilder.php
+++ b/core/lib/Drupal/Core/Entity/EntityListBuilder.php
@@ -13,6 +13,8 @@
/**
* Defines a generic implementation to build a listing of entities.
+ *
+ * @ingroup entity_api
*/
class EntityListBuilder extends EntityControllerBase implements EntityListBuilderInterface, EntityControllerInterface {
diff --git a/core/lib/Drupal/Core/Entity/EntityType.php b/core/lib/Drupal/Core/Entity/EntityType.php
index 438266533ca0..ac49238aeaa7 100644
--- a/core/lib/Drupal/Core/Entity/EntityType.php
+++ b/core/lib/Drupal/Core/Entity/EntityType.php
@@ -14,6 +14,8 @@
/**
* Provides an implementation of an entity type and its metadata.
+ *
+ * @ingroup entity_api
*/
class EntityType implements EntityTypeInterface {
diff --git a/core/lib/Drupal/Core/Entity/EntityViewBuilder.php b/core/lib/Drupal/Core/Entity/EntityViewBuilder.php
index 23a4ebfb2139..99a10f420e07 100644
--- a/core/lib/Drupal/Core/Entity/EntityViewBuilder.php
+++ b/core/lib/Drupal/Core/Entity/EntityViewBuilder.php
@@ -22,6 +22,8 @@
/**
* Base class for entity view controllers.
+ *
+ * @ingroup entity_api
*/
class EntityViewBuilder extends EntityControllerBase implements EntityControllerInterface, EntityViewBuilderInterface {
diff --git a/core/modules/content_translation/src/ContentTranslationHandler.php b/core/modules/content_translation/src/ContentTranslationHandler.php
index bd9a9c13467b..500ae4978ef9 100644
--- a/core/modules/content_translation/src/ContentTranslationHandler.php
+++ b/core/modules/content_translation/src/ContentTranslationHandler.php
@@ -14,6 +14,8 @@
/**
* Base class for content translation handlers.
+ *
+ * @ingroup entity_api
*/
class ContentTranslationHandler implements ContentTranslationHandlerInterface {
diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 8c48e376937a..9b0f9ffbe255 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -268,53 +268,100 @@
* @{
* Describes how to define and manipulate content and configuration entities.
*
- * @todo Add an overview here, describing what an entity is, bundles, entity
- * types, etc. at an overview level. And link to more detailed documentation:
- * https://drupal.org/developing/api/entity
- *
- * @section types Types of entities
- * Entities can be used to store content or configuration information. See the
+ * Entities, in Drupal, are objects that are used for persistent storage of
+ * content and configuration information. See the
* @link architecture Drupal's architecture topic @endlink for an overview of
* the different types of information, and the
* @link config_api Configuration API topic @endlink for more about the
- * configuration API. Defining and manipulating content and configuration
- * entities is very similar, and this is described in the sections below.
+ * configuration API.
*
- * @section define Defining an entity type
+ * Each entity is an instance of a particular "entity type". Some content entity
+ * types have sub-types, which are known as "bundles", while for other entity
+ * types, there is only a single bundle. For example, the Node content entity
+ * type, which is used for the main content pages in Drupal, has bundles that
+ * are known as "content types", while the User content type, which is used for
+ * user accounts, has only one bundle.
*
- * @todo This section was written for Config entities. Add information about
- * content entities to each item, and add additional items that are relevant
- * to content entities, making sure to say they are not needed for config
- * entities, such as view page controllers, etc.
+ * The sections below have more information about entities and the Entity API;
+ * for more detailed information, see https://drupal.org/developing/api/entity
*
- * Here are the steps to follow to define a new entity type:
+ * @section define Defining an entity type
+ * Entity types are defined by modules, using Drupal's Plugin API (see the
+ * @link plugins Plugin API topic @endlink for more information about plugins
+ * in general). Here are the steps to follow to define a new entity type:
* - Choose a unique machine name, or ID, for your entity type. This normally
* starts with (or is the same as) your module's machine name. It should be
* as short as possible, and may not exceed 32 characters.
* - Define an interface for your entity's get/set methods, extending either
- * \Drupal\Core\Config\Entity\ConfigEntityInterface or [content entity
- * interface].
+ * \Drupal\Core\Config\Entity\ConfigEntityInterface or
+ * \Drupal\Core\Entity\ContentEntityInterface.
* - Define a class for your entity, implementing your interface and extending
- * either \Drupal\Core\Config\Entity\ConfigEntityBase or [content entity
- * class] , with annotation for \@ConfigEntityType or [content entity
- * annotation] in its documentation block.
+ * either \Drupal\Core\Config\Entity\ConfigEntityBase or
+ * \Drupal\Core\Entity\ContentEntityBase, with annotation for
+ * \@ConfigEntityType or \@ContentEntityType in its documentation block.
* - The 'id' annotation gives the entity type ID, and the 'label' annotation
- * gives the human-readable name of the entity type.
+ * gives the human-readable name of the entity type. If you are defining a
+ * content entity type that uses bundles, the 'bundle_label' annotation gives
+ * the human-readable name to use for a bundle of this entity type (for
+ * example, "Content type" for the Node entity).
* - The annotation will refer to several controller classes, which you will
* also need to define:
* - list_builder: Define a class that extends
- * \Drupal\Core\Config\Entity\ConfigEntityListBuilder or [content entity
- list builder], to provide an administrative overview for your entities.
+ * \Drupal\Core\Config\Entity\ConfigEntityListBuilder (for configuration
+ * entities) or \Drupal\Core\Entity\EntityListBuilder (for content
+ * entities), to provide an administrative overview for your entities.
* - add and edit forms, or default form: Define a class (or two) that
* extend(s) \Drupal\Core\Entity\EntityForm to provide add and edit forms
* for your entities.
* - delete form: Define a class that extends
* \Drupal\Core\Entity\EntityConfirmFormBase to provide a delete
* confirmation form for your entities.
+ * - view_buider: For content entities, define a class that extends
+ * \Drupal\Core\Entity\EntityViewBuilder, to display a single entity.
+ * - translation: For translatable content entities (if the 'translatable'
+ * annotation has value TRUE), define a class that extends
+ * \Drupal\content_translation\ContentTranslationHandler, to translate
+ * the content. Configuration translation is handled automatically by the
+ * Configuration Translation module, without the need of a controller class.
* - access: If your configuration entity has complex permissions, you might
* need an access controller, implementing
* \Drupal\Core\Entity\EntityAccessControllerInterface, but most entities
* can just use the 'admin_permission' annotation instead.
+ * - For content entities, the annotation will refer to a number of database
+ * tables and their fields. These annotation properties, such as 'base_table',
+ * 'data_table', 'entity_keys', etc., are documented on
+ * \Drupal\Core\Entity\EntityType. Your module will also need to set up its
+ * database tables using hook_schema().
+ * - For content entities that are displayed on their own pages, the annotation
+ * will refer to a 'uri_callback' function, which takes an object of the
+ * entity interface you have defined as its parameter, and returns routing
+ * information for the entity page; see node_uri() for an example. You will
+ * also need to add a corresponding route to your module's routing.yml file;
+ * see the node.view route in node.routing.yml for an example, and see the
+ * @link menu Menu and routing @endlink topic for more information about
+ * routing.
+ * - Define routing and links for the various URLs associated with the entity.
+ * These go into the 'links' annotation, with the link type as the key, and
+ * the route machine name (defined in your module's routing.yml file) as the
+ * value. Typical link types are:
+ * - canonical: Default link, either to view (if entities are viewed on their
+ * own pages) or edit the entity.
+ * - delete-form: Confirmation form to delete the entity.
+ * - edit-form: Editing form.
+ * - admin-form: Form for editing bundle or entity type settings.
+ * - Other link types specific to your entity type can also be defined.
+ * - If your content entity has bundles, you will also need to define a second
+ * plugin to handle the bundles. This plugin is itself a configuration entity
+ * type, so follow the steps here to define it. The machine name ('id'
+ * annotation) of this configuration entity class goes into the
+ * 'bundle_entity_type' annotation on the entity type class. For example, for
+ * the Node entity, the bundle class is \Drupal\node\Entity\NodeType, whose
+ * machine name is 'node_type'. This is the annotation value for
+ * 'bundle_entity_type' on the \Drupal\node\Entity\Node class.
+ * - Additional annotations can be seen on entity class examples such as
+ * \Drupal\node\Entity\Node (content) and \Drupal\user\Entity\Role
+ * (configuration). These annotations are documented on
+ * \Drupal\Core\Entity\EntityType.
*
* @section load_query Loading and querying entities
* To load entities, use the entity storage manager, which is a class
@@ -323,6 +370,8 @@
* @code
* $storage = \Drupal::entityManager()->getStorage('your_entity_type');
* @endcode
+ * Here, 'your_entity_type' is the machine name of your entity type ('id'
+ * annotation on the entity class).
*
* To query to find entities to load, use an entity query, which is a class
* implementing \Drupal\Core\Entity\Query\QueryInterface that you can retrieve
@@ -330,9 +379,6 @@
* @code
* $storage = \Drupal::entityQuery('your_entity_type');
* @endcode
- *
- * @todo Add additional relevant classes and interfaces to this topic using
- * ingroup.
* @}
*/
--
GitLab