Commit 5ffb1d3c authored by alexpott's avatar alexpott

Issue #2216535 by jhodgdon, Berdir: Replace Node overview topic and Node API...

Issue #2216535 by jhodgdon, Berdir: Replace Node overview topic and Node API topic with Entity Hooks topic.
parent 028920c1
......@@ -35,6 +35,8 @@
* 'article'. Entity IDs may contain dots/periods. The entire remaining string
* after the config_prefix in a config name forms the entity ID. Additional or
* custom suffixes are not possible.
*
* @ingroup entity_api
*/
class ConfigEntityStorage extends EntityStorageBase implements ConfigEntityStorageInterface, ImportableEntityStorageInterface {
......
......@@ -34,6 +34,8 @@
* the defined base fields. Entity types can override
* ContentEntityDatabaseStorage::getSchema() to customize the generated
* schema; e.g., to add additional indexes.
*
* @ingroup entity_api
*/
class ContentEntityDatabaseStorage extends ContentEntityStorageBase implements SqlEntityStorageInterface {
......@@ -350,15 +352,7 @@ protected function doLoadMultiple(array $ids = NULL) {
}
/**
* Maps from storage records to entity objects.
*
* This will attach fields, if the entity is fieldable. It calls
* hook_entity_load() for modules which need to add data to all entities.
* It also calls hook_TYPE_load() on the loaded entities. For example
* hook_node_load() or hook_user_load(). If your hook_TYPE_load()
* expects special parameters apart from the queried entities, you can set
* $this->hookLoadArguments prior to calling the method.
* See Drupal\node\NodeStorage::attachLoad() for an example.
* Maps from storage records to entity objects, and attaches fields.
*
* @param array $records
* Associative array of query results, keyed on the entity ID.
......
......@@ -17,6 +17,8 @@
* Most simple, SQL-based entity controllers will do better by extending
* Drupal\Core\Entity\ContentEntityDatabaseStorage instead of implementing this
* interface directly.
*
* @ingroup entity_api
*/
interface EntityStorageInterface {
......
......@@ -12,6 +12,8 @@
/**
* Defines a common interface for entity view controller classes.
*
* @ingroup entity_api
*/
interface EntityViewBuilderInterface {
......
......@@ -85,6 +85,8 @@
* The block plugin instance.
*
* @see hook_block_view_BASE_BLOCK_ID_alter()
* @see entity_crud
*
* @ingroup block_api
*/
function hook_block_view_alter(array &$build, \Drupal\block\BlockPluginInterface $block) {
......@@ -113,6 +115,8 @@ function hook_block_view_alter(array &$build, \Drupal\block\BlockPluginInterface
* The block plugin instance.
*
* @see hook_block_view_alter()
* @see entity_crud
*
* @ingroup block_api
*/
function hook_block_view_BASE_BLOCK_ID_alter(array &$build, \Drupal\block\BlockPluginInterface $block) {
......
......@@ -298,7 +298,7 @@ function template_preprocess_block(&$variables) {
}
/**
* Implements hook_user_role_delete().
* Implements hook_ENTITY_TYPE_delete() for user_role entities.
*
* Removes deleted role from blocks that use it.
*/
......@@ -315,7 +315,7 @@ function block_user_role_delete($role) {
}
/**
* Implements hook_menu_delete().
* Implements hook_ENTITY_TYPE_delete() for menu entities.
*/
function block_menu_delete(Menu $menu) {
if (!$menu->isSyncing()) {
......
......@@ -234,7 +234,7 @@ function book_form_update($form, $form_state) {
}
/**
* Implements hook_node_load().
* Implements hook_ENTITY_TYPE_load() for node entities.
*/
function book_node_load($nodes) {
/** @var \Drupal\book\BookManagerInterface $book_manager */
......@@ -248,7 +248,7 @@ function book_node_load($nodes) {
}
/**
* Implements hook_node_view().
* Implements hook_ENTITY_TYPE_view() for node entities.
*/
function book_node_view(array &$build, EntityInterface $node, EntityViewDisplayInterface $display, $view_mode) {
if ($view_mode == 'full') {
......@@ -268,7 +268,7 @@ function book_node_view(array &$build, EntityInterface $node, EntityViewDisplayI
}
/**
* Implements hook_node_presave().
* Implements hook_ENTITY_TYPE_presave() for node entities.
*/
function book_node_presave(EntityInterface $node) {
// Make sure a new node gets a new menu link.
......@@ -278,7 +278,7 @@ function book_node_presave(EntityInterface $node) {
}
/**
* Implements hook_node_insert().
* Implements hook_ENTITY_TYPE_insert() for node entities.
*/
function book_node_insert(EntityInterface $node) {
/** @var \Drupal\book\BookManagerInterface $book_manager */
......@@ -287,7 +287,7 @@ function book_node_insert(EntityInterface $node) {
}
/**
* Implements hook_node_update().
* Implements hook_ENTITY_TYPE_update() for node entities.
*/
function book_node_update(EntityInterface $node) {
/** @var \Drupal\book\BookManagerInterface $book_manager */
......@@ -296,7 +296,7 @@ function book_node_update(EntityInterface $node) {
}
/**
* Implements hook_node_predelete().
* Implements hook_ENTITY_TYPE_predelete() for node entities.
*/
function book_node_predelete(EntityInterface $node) {
if (!empty($node->book['bid'])) {
......@@ -555,7 +555,7 @@ function book_type_is_allowed($type) {
}
/**
* Implements hook_node_type_update().
* Implements hook_ENTITY_TYPE_update() for node_type entities.
*
* Updates book.settings configuration object if the machine-readable name of a
* node type is changed.
......
......@@ -13,172 +13,6 @@
* @{
*/
/**
* Act on a comment being inserted or updated.
*
* This hook is invoked from $comment->save() before the comment is saved to the
* database.
*
* @param \Drupal\comment\Comment $comment
* The comment object.
*/
function hook_comment_presave(Drupal\comment\Comment $comment) {
// Remove leading & trailing spaces from the comment subject.
$comment->setSubject(trim($comment->getSubject()));
}
/**
* Respond to creation of a new comment.
*
* @param \Drupal\comment\Comment $comment
* The comment object.
*/
function hook_comment_insert(Drupal\comment\Comment $comment) {
// Reindex the node when comments are added.
if ($comment->getCommentedEntityTypeId() == 'node') {
node_reindex_node_search($comment->getCommentedEntityId());
}
}
/**
* Respond to updates to a comment.
*
* @param \Drupal\comment\Comment $comment
* The comment object.
*/
function hook_comment_update(Drupal\comment\Comment $comment) {
// Reindex the node when comments are updated.
if ($comment->getCommentedEntityTypeId() == 'node') {
node_reindex_node_search($comment->getCommentedEntityId());
}
}
/**
* Act on a newly created comment.
*
* This hook runs after a new comment object has just been instantiated. It can
* be used to set initial values, e.g. to provide defaults.
*
* @param \Drupal\comment\Entity\Comment $comment
* The comment object.
*/
function hook_comment_create(\Drupal\comment\Entity\Comment $comment) {
if (!isset($comment->foo)) {
$comment->foo = 'some_initial_value';
}
}
/**
* Act on comments being loaded from the database.
*
* @param array $comments
* An array of comment objects indexed by cid.
*/
function hook_comment_load(Drupal\comment\Comment $comments) {
$result = db_query('SELECT cid, foo FROM {mytable} WHERE cid IN (:cids)', array(':cids' => array_keys($comments)));
foreach ($result as $record) {
$comments[$record->cid]->foo = $record->foo;
}
}
/**
* Act on a comment that is being assembled before rendering.
*
* @param array &$build
* A renderable array representing the comment content.
* @param \Drupal\comment\Entity\Comment $comment $comment
* Passes in the comment the action is being performed on.
* @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display
* The entity view display holding the display options configured for the
* comment components.
* @param $view_mode
* View mode, e.g. 'full', 'teaser'...
* @param $langcode
* The language code used for rendering.
*
* @see hook_entity_view()
*/
function hook_comment_view(array &$build, \Drupal\comment\Entity\Comment $comment, \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display, $view_mode, $langcode) {
// Only do the extra work if the component is configured to be displayed.
// This assumes a 'mymodule_addition' extra field has been defined for the
// node type in hook_entity_extra_field_info().
if ($display->getComponent('mymodule_addition')) {
$build['mymodule_addition'] = array(
'#markup' => mymodule_addition($comment),
'#theme' => 'mymodule_my_additional_field',
);
}
}
/**
* Alter the results of comment_view().
*
* This hook is called after the content has been assembled in a structured
* array and may be used for doing processing which requires that the complete
* comment content structure has been built.
*
* If the module wishes to act on the rendered HTML of the comment rather than
* the structured content array, it may use this hook to add a #post_render
* callback. Alternatively, it could also implement hook_preprocess_HOOK() for
* comment.html.twig. See drupal_render() documentation for details.
*
* @param array &$build
* A renderable array representing the comment.
* @param \Drupal\comment\Entity\Comment $comment
* The comment being rendered.
* @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display
* The entity view display holding the display options configured for the
* comment components.
*
* @see comment_view()
* @see hook_entity_view_alter()
*/
function hook_comment_view_alter(array &$build, \Drupal\comment\Entity\Comment $comment, \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display) {
// Check for the existence of a field added by another module.
if ($build['#view_mode'] == 'full' && isset($build['an_additional_field'])) {
// Change its weight.
$build['an_additional_field']['#weight'] = -10;
}
// Add a #post_render callback to act on the rendered HTML of the comment.
$build['#post_render'][] = 'my_module_comment_post_render';
}
/**
* Act before comment deletion.
*
* This hook is invoked from entity_delete_multiple() before field values are
* deleted and before the comment is actually removed from the database.
*
* @param \Drupal\comment\Comment $comment
* The comment object for the comment that is about to be deleted.
*
* @see hook_comment_delete()
* @see entity_delete_multiple()
*/
function hook_comment_predelete(Drupal\comment\Comment $comment) {
// Delete a record associated with the comment in a custom table.
db_delete('example_comment_table')
->condition('cid', $comment->id())
->execute();
}
/**
* Respond to comment deletion.
*
* This hook is invoked from entity_delete_multiple() after field values are
* deleted and after the comment has been removed from the database.
*
* @param \Drupal\comment\Comment $comment
* The comment object for the comment that has been deleted.
*
* @see hook_comment_predelete()
* @see entity_delete_multiple()
*/
function hook_comment_delete(Drupal\comment\Comment $comment) {
drupal_set_message(t('Comment: @subject has been deleted', array('@subject' => $comment->getSubject())));
}
/**
* Alter the links of a comment.
*
......
......@@ -434,7 +434,7 @@ function comment_node_links_alter(array &$node_links, NodeInterface $node, array
}
/**
* Implements hook_node_view_alter().
* Implements hook_ENTITY_TYPE_view_alter() for node entities.
*/
function comment_node_view_alter(array &$build, EntityInterface $node, EntityViewDisplayInterface $display) {
if (\Drupal::moduleHandler()->moduleExists('history')) {
......@@ -639,7 +639,7 @@ function comment_view_multiple($comments, $view_mode = 'full', $langcode = NULL)
}
/**
* Implements hook_form_FORM_ID_alter().
* Implements hook_form_FORM_ID_alter() for field_ui_field_overview_form.
*/
function comment_form_field_ui_field_overview_form_alter(&$form, $form_state) {
$request = \Drupal::request();
......@@ -886,7 +886,7 @@ function comment_user_cancel($edit, $account, $method) {
}
/**
* Implements hook_user_predelete().
* Implements hook_ENTITY_TYPE_predelete() for user entities.
*/
function comment_user_predelete($account) {
$entity_query = \Drupal::entityQuery('comment');
......
......@@ -253,6 +253,8 @@ function hook_field_info_max_weight($entity_type, $bundle, $context, $context_mo
* The field as it will be post-update.
* @param \Drupal\field\FieldConfigInterface $prior_field
* The field as it is pre-update.
*
* @see entity_crud
*/
function hook_field_config_update_forbid(\Drupal\field\FieldConfigInterface $field, \Drupal\field\FieldConfigInterface $prior_field) {
// A 'list' field stores integer keys mapped to display values. If
......
......@@ -5,43 +5,10 @@
* Hooks for file module.
*/
/**
* Act on a newly created file.
*
* This hook runs after a new file object has just been instantiated. It can be
* used to set initial values, e.g. to provide defaults.
*
* @param \Drupal\file\Entity\File $file
* The file object.
* @addtogroup hooks
* @{
*/
function hook_file_create(\Drupal\file\Entity\File $file) {
if (!isset($file->foo)) {
$file->foo = 'some_initial_value';
}
}
/**
* Load additional information into file entities.
*
* file_load_multiple() calls this hook to allow modules to load
* additional information into each file.
*
* @param $files
* An array of file entities, indexed by fid.
*
* @see file_load_multiple()
* @see file_load()
*/
function hook_file_load($files) {
// Add the upload specific data into the file entity.
$result = db_query('SELECT * FROM {upload} u WHERE u.fid IN (:fids)', array(':fids' => array_keys($files)))->fetchAll(PDO::FETCH_ASSOC);
foreach ($result as $record) {
foreach ($record as $key => $value) {
$files[$record['target_id']]->$key = $value;
}
}
}
/**
* Check that files meet a given criteria.
......@@ -70,58 +37,6 @@ function hook_file_validate(Drupal\file\FileInterface $file) {
return $errors;
}
/**
* Act on a file being inserted or updated.
*
* This hook is called when a file has been added to the database. The hook
* doesn't distinguish between files created as a result of a copy or those
* created by an upload.
*
* @param \Drupal\file\FileInterface $file
* The file entity that is about to be created or updated.
*/
function hook_file_presave(Drupal\file\FileInterface $file) {
// Change the owner of the file.
$file->uid->value = 1;
}
/**
* Respond to a file being added.
*
* This hook is called after a file has been added to the database. The hook
* doesn't distinguish between files created as a result of a copy or those
* created by an upload.
*
* @param \Drupal\file\FileInterface $file
* The file that has been added.
*/
function hook_file_insert(Drupal\file\FileInterface $file) {
// Add a message to the log, if the file is a jpg
$validate = file_validate_extensions($file, 'jpg');
if (empty($validate)) {
\Drupal::logger('file')->notice('A jpg has been added.');
}
}
/**
* Respond to a file being updated.
*
* This hook is called when an existing file is saved.
*
* @param \Drupal\file\FileInterface $file
* The file that has just been updated.
*/
function hook_file_update(Drupal\file\FileInterface $file) {
// Make sure that the file name starts with the owner's user name.
if (strpos($file->getFilename(), $file->getOwner()->name) !== 0) {
$old_filename = $file->getFilename();
$file->setFilename($file->getOwner()->name . '_' . $file->getFilename());
$file->save();
\Drupal::logger('file')->notice('%source has been renamed to %destination', array('%source' => $old_filename, '%destination' => $file->getFilename()));
}
}
/**
* Respond to a file that has been copied.
*
......@@ -162,41 +77,6 @@ function hook_file_move(Drupal\file\FileInterface $file, Drupal\file\FileInterfa
}
}
/**
* Act prior to file deletion.
*
* This hook is invoked when deleting a file before the file is removed from the
* filesystem and before its records are removed from the database.
*
* @param \Drupal\file\FileInterface $file
* The file that is about to be deleted.
*
* @see hook_file_delete()
* @see \Drupal\file\FileStorage::delete()
* @see upload_file_delete()
*/
function hook_file_predelete(Drupal\file\FileInterface $file) {
// Delete all information associated with the file.
db_delete('upload')->condition('fid', $file->id())->execute();
}
/**
* Respond to file deletion.
*
* This hook is invoked after the file has been removed from
* the filesystem and after its records have been removed from the database.
*
* @param \Drupal\file\FileInterface $file
* The file that has just been deleted.
*
* @see hook_file_predelete()
* @see \Drupal\file\FileStorage::delete()
*/
function hook_file_delete(Drupal\file\FileInterface $file) {
// Delete all information associated with the file.
db_delete('upload')->condition('fid', $file->id())->execute();
}
/**
* Control download access to files.
*
......@@ -251,3 +131,7 @@ function hook_file_download_access_alter(&$grants, $context) {
$grants = array('node' => $grants['node']);
}
}
/**
* @} End of "addtogroup hooks".
*/
......@@ -87,7 +87,7 @@ function file_element_info() {
* @deprecated in Drupal 8.x, will be removed before Drupal 9.0.
* Use \Drupal\file\Entity\File::loadMultiple().
*
* @see hook_file_load()
* @see hook_ENTITY_TYPE_load()
* @see file_load()
* @see entity_load()
* @see \Drupal\Core\Entity\Query\EntityQueryInterface
......@@ -113,7 +113,7 @@ function file_load_multiple(array $fids = NULL, $reset = FALSE) {
* @deprecated in Drupal 8.x, will be removed before Drupal 9.0.
* Use \Drupal\file\Entity\File::load().
*
* @see hook_file_load()
* @see hook_ENTITY_TYPE_load()
* @see file_load_multiple()
*/
function file_load($fid, $reset = FALSE) {
......@@ -1002,7 +1002,7 @@ function file_progress_implementation() {
}
/**
* Implements hook_file_predelete().
* Implements hook_ENTITY_TYPE_predelete() for file entities.
*/
function file_file_predelete(File $file) {
// TODO: Remove references to a file that is in-use.
......
......@@ -150,7 +150,7 @@ function file_test_set_return($op, $value) {
}
/**
* Implements hook_file_load().
* Implements hook_ENTITY_TYPE_load() for file entities.
*/
function file_test_file_load($files) {
foreach ($files as $file) {
......@@ -178,14 +178,14 @@ function file_test_file_download($uri) {
}
/**
* Implements hook_file_insert().
* Implements hook_ENTITY_TYPE_insert() for file entities.
*/
function file_test_file_insert(File $file) {
_file_test_log_call('insert', array($file->id()));
}
/**
* Implements hook_file_update().
* Implements hook_ENTITY_TYPE_update() for file entities.
*/
function file_test_file_update(File $file) {
_file_test_log_call('update', array($file->id()));
......@@ -206,7 +206,7 @@ function file_test_file_move(File $file, File $source) {
}
/**
* Implements hook_file_predelete().
* Implements hook_ENTITY_TYPE_predelete() for file entities.
*/
function file_test_file_predelete(File $file) {
_file_test_log_call('delete', array($file->id()));
......
......@@ -233,7 +233,7 @@ function forum_node_validate(EntityInterface $node, $form, &$form_state) {
}
/**
* Implements hook_node_presave().
* Implements hook_ENTITY_TYPE_presave() for node entities.
*
* Assigns the forum taxonomy when adding a topic from within a forum.
*/
......@@ -256,7 +256,7 @@ function forum_node_presave(EntityInterface $node) {
}
/**
* Implements hook_node_update().
* Implements hook_ENTITY_TYPE_update() for node entities.
*/
function forum_node_update(EntityInterface $node) {
if (\Drupal::service('forum_manager')->checkNodeType($node)) {
......@@ -298,7 +298,7 @@ function forum_node_update(EntityInterface $node) {
}
/**
* Implements hook_node_insert().
* Implements hook_ENTITY_TYPE_insert() for node entities.
*/
function forum_node_insert(EntityInterface $node) {
if (\Drupal::service('forum_manager')->checkNodeType($node)) {
......@@ -316,7 +316,7 @@ function forum_node_insert(EntityInterface $node) {
}
/**
* Implements hook_node_predelete().
* Implements hook_ENTITY_TYPE_predelete() for node entities.
*/
function forum_node_predelete(EntityInterface $node) {
if (\Drupal::service('forum_manager')->checkNodeType($node)) {
......@@ -328,7 +328,7 @@ function forum_node_predelete(EntityInterface $node) {
}
/**
* Implements hook_node_load().
* Implements hook_ENTITY_TYPE_load() for node entities.
*/
function forum_node_load($nodes) {
$node_vids = array();
......@@ -358,7 +358,7 @@ function forum_permission() {
}
/**
* Implements hook_comment_update().
* Implements hook_ENTITY_TYPE_update() for comment entities.
*/
function forum_comment_update(CommentInterface $comment) {
if ($comment->getCommentedEntityTypeId() == 'node') {
......@@ -367,7 +367,7 @@ function forum_comment_update(CommentInterface $comment) {
}
/**
* Implements hook_comment_insert().
* Implements hook_ENTITY_TYPE_insert() for comment entities.
*/
function forum_comment_insert(CommentInterface $comment) {
if ($comment->getCommentedEntityTypeId() == 'node') {
......@@ -376,7 +376,7 @@ function forum_comment_insert(CommentInterface $comment) {
}
/**
* Implements hook_comment_delete().
* Implements hook_ENTITY_TYPE_delete() for comment entities.
*/
function forum_comment_delete(CommentInterface $comment) {
if ($comment->getCommentedEntityTypeId() == 'node') {
......
......@@ -130,7 +130,7 @@ function history_cron() {
}
/**
* Implements hook_node_view_alter().
* Implements hook_ENTITY_TYPE_view_alter() for node entities.
*/
function history_node_view_alter(array &$build, EntityInterface $node, EntityViewDisplayInterface $display) {
// Update the history table, stating that this user viewed this node.
......@@ -148,7 +148,7 @@ function history_node_view_alter(array &$build, EntityInterface $node, EntityVie
}
/**
* Implements hook_node_delete().
* Implements hook_ENTITY_TYPE_delete() for node entities.
*/
function history_node_delete(EntityInterface $node) {
db_delete('history')
......@@ -170,7 +170,7 @@ function history_user_cancel($edit, $account, $method) {
}
/**
* Implements hook_user_delete().
* Implements hook_ENTITY_TYPE_delete() for user entities.
*/
function history_user_delete($account) {
db_delete('history')
......
......@@ -228,7 +228,7 @@ function image_file_move(File $file, File $source) {
}
/**
* Implements hook_file_predelete().
* Implements hook_ENTITY_TYPE_predelete() for file entities.
*/
function image_file_predelete(File $file) {
// Delete any image derivatives of this image.
......
......@@ -347,7 +347,7 @@ function language_get_default_configuration_settings_key($entity_type, $bundle)
}
/**
* Implements hook_node_type_update().
* Implements hook_ENTITY_TYPE_update() for node_type entities.
*/
function language_node_type_update(NodeTypeInterface $type) {
if ($type->original->id() != $type->id()) {
......
......@@ -17,7 +17,7 @@
* translated; i.e., after the user access to the link's target page has
* been checked. It is only invoked if $menu_link['options']['alter'] has been
* set to a non-empty value (e.g. TRUE). This flag should be set using
* hook_menu_link_presave().
* hook_ENTITY_TYPE_presave() for entity 'menu_link'.
*
* Implementations of this hook are able to alter any property of the menu link.
* For example, this hook may be used to add a page-specific query string to all
......@@ -37,129 +37,6 @@ function hook_translated_menu_link_alter(\Drupal\menu_link\Entity\MenuLink &$men
}
}
/**
* Alter menu links when loaded and before they are rendered.
*
* This hook is only invoked if $menu_link->options['alter'] has been set to a
* non-empty value (e.g., TRUE). This flag should be set using
* hook_menu_link_presave().
* @ todo The paragraph above is lying! This hasn't been (re)implemented yet.
*
* Implementations of this hook are able to alter any property of the menu link.
* For example, this hook may be used to add a page-specific query string to all
* menu links, or hide a certain link by setting:
* @code
* 'hidden' => 1,
* @endcode
*
* @param array $menu_links
* An array of menu link entities.
*
* @see hook_menu_link_presave()
*/
function hook_menu_link_load($menu_links) {
foreach ($menu_links as $menu_link) {
if ($menu_link->href == 'devel/cache/clear') {
$menu_link->options['query'] = drupal_get_destination();
}
}
}
/**
* Alter the data of a menu link entity before it is created or updated.
*
* @param \Drupal\menu_link\Entity\MenuLink $menu_link
* A menu link entity.