WordPress 6.9 introduces Notes, a new feature that allows you to leave contextual feedback at the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. level. With notes your team can stay aligned, track changes, and turn feedback into action all in one place. Notes can be resolved, and notes and their replies can be edited or deleted.

Who can use notes?

Because notes can only be created or viewed within the post editor, users must have the edit_post capabilitycapability A capability is permission to perform one or more types of task. Checking if a user has a capability is performed by the current_user_can function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” capability). for that post. By default, this means that:

• Administrators and Editors can view all notes on all posts.
• Authors and Contributors can view all notes for posts that they have authored.
• Subscribers cannot view any notes.

Enabling notes for custom post types

Notes are enabled by default for the post and page built-in post types, but they can be enabled for any custom post typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept.. When you control the register_post_type() call, this is the preferred way to register support for Notes:

register_post_type( 'book', array(
	'label' => 'Books',
	'public' => true,
	'show_in_rest' => true,
	'supports' => array(
		'title',
		'editor' => array( 'notes' => true ),
		'author',
	),
) );

When the custom post type is registered through a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, support for Notes can be added by registering support using the following code snippet:

function custom_add_post_type_support() {
	$supports        = get_all_post_type_supports( 'my-post-type' );
	$editor_supports = array( 'notes' => true );

	// `add_post_type_support()` overwrites feature sub-properties, 
	// so they must be explicitly merged. 
	// See https://core.trac.wordpress.org/ticket/64156.
	if ( 
		is_array( $supports['editor'] ) && 
		isset( $supports['editor'][0] ) && 
		is_array( $supports['editor'][0] ) 
	) {
		$editor_supports = array_merge( $editor_supports, $supports['editor'][0] );
	}
	add_post_type_support( 'my-post-type', 'editor', $editor_supports );
}
add_action( 'init', 'custom_add_post_type_support' );

Since notes is a sub-feature of the editor, the code needs to manually merge the notes setting with other editor attributes. Work is underway in https://core.trac.wordpress.org/ticket/64156 to make this easier. Once this bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. is fixed, adding support will be simplified:

add_post_type_support( 'my-post-type', 'editor', array(
    'notes' => true,
) );

Accessing notes programmatically

Under the hood, Notes are WP_Comments stored in the comments table, and the standard comments APIs can be used to access them by specifying a comment_type of  note. 

For example, this will retrieve all notes for a given post ID:

$notes = get_comments( 
	array(
		'post_id' => $post_id,
		'type'    => 'note',
	)
);

Notes can also be retrieved using the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.:

$request = new WP_REST_Request( 'GET', '/wp/v2/comments' );
$request->set_param( 'post', $post_id );
$request->set_param( 'type', 'note' );
$response = rest_get_server()->dispatch( $request );
if ( ! is_wp_error( $response ) ) {
	$notes = $response->get_data();
	foreach ( $notes as $note ) {
		// Process each note as needed
	}
}

Note status

When a note is added to a block, it:

• Starts in an “Open” state with a comment_status of 0 (aka hold). 
• When resolved, changes to a comment_status of 1 (aka approve).
• When deleted, changes to a status of trash, unless EMPTY_TRASH_DAYS is 0 in which case deleted immediately.

The following snippet will get a list of all unresolved Notes for a given post:

$notes = get_comments( 
	array(
		'post_id' => $post_id,
		'type'    => 'note',
		'status'  => 'hold'
	)
);

Important: Notes must be explicitly requested by specifying either the note or all comment type. Otherwise they are excluded when retrieving comments:

// This only returns comments, 'notes' are automatically excluded.
$comments = get_comments( array ( 'post_id' => $post_id ) );

Notification emails

When another user adds a note to a post, the post_author will receive a notification that a note has been added to the post. Notifications are enabled by default and can be controlled at a site level under Settings->Discussions – Email me whenever > Anyone posts a note. Developers can also use the existing comment filters to control notifications. 

For example, to send notifications for notes on pages but not posts, use this snippet:

function only_notify_page_authors_of_notes( $notify, $comment_id ) {
	if ( 'note' !== get_comment_type( $comment_id ) {
		return $notify;
	}

	if ( 'page' === get_post_type( $comment_post_ID ) {
		return true;
	}

	return false;
}
add_filter( 'notify_post_author', 'only_notify_page_authors_of_notes', 10, 2 );

Miscellaneous

Notes permissions

As previously mentioned, only users who can edit a given post are able to add notes. Because notes are an internal/authorized user feature, the normal restrictions that apply to comment posting do not apply to notes, including the flood protection and duplicate prevention. In addition, the pre_comment_approved filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. is not run for notes.

Linking blocks to notes

Top level notes are linked to blocks with a metadata attribute. . When you add a new note to a block, the note ID is stored in block attributes metadata as noteId. Replies are linked to top level notes as children (with their parent set to the top level note)

To get the note ID from a block based on its clientId, you can use this code:

const attributes = getBlockAttributes( clientId );
const noteId     = attributes.metadata?.noteId;

Important: The reverse is not true – notes do not contain a link back to their associated block. To identify the block(s) associated with a note, search the blocks for the noteId in metadata. You can use this code snippet:

import { store as blockEditorStore } from '@wordpress/block-editor';

const { getBlockAttributes } = useSelect( blockEditorStore );

const { clientIds } = useSelect( ( select ) => {
	const { getClientIdsWithDescendants } = select( blockEditorStore );
	return {
		clientIds: getClientIdsWithDescendants(),
	};
}, [] );

// expectedNoteId is the note we are filtering for.
const blocksWithNote = clientIds.reduce( ( results, clientId ) => {
	const commentId = getBlockAttributes( clientId )?.metadata?.noteId;
	if ( commentId === expectedNoteId ) {
		results[ clientId ] = commentId;
	}
	return results;
}, {} );

Known limitations

• A note can be associated with more than one block. If a block with a note is split or duplicated, the note becomes associated with both blocks. This is primarily due to an underlying limitation in GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ that will be fixed in #29693.
• A notification is sent for each new non-author note which may not be ideal for all users, especially for cases where a high volume of notes are added to a post will in turn generate a high volume of emails to the post author.
• Notes do not work outside post content types, for example in templates.
• All notes are block level, for example this means that they can not reference specific text within a paragraph or text across paragraph blocks.  In-line notes will become available as part of #59445.

What’s next

There are already new features and enhancements planned for Notes in the next release of WordPress (7.0). These features were suggested during the development cycle, but didn’t make it into the 6.9 release.

• Fragment notes – the ability to leave a note on a part of a block or across blocks.
• “@” mentions – mention another user in a post and they will receive a notification.
• Improved notifications – control frequency for notifications, for example receive a daily digest of all new note activity.
• Improved floating layout for wide screens – shift the floating to sit between the editor frame and the sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme..
• Minified mode – notes display as icons with avatars beside blocks that expand when clicked..
• Wider availability across the editor including using notes with templates.
• Real time collaboration with Notes.

You can follow along and contribute to the ongoing effort on the Notes iteration for 7.0 tracking issue.

Have an idea for how to improve Notes? Leave your feedback as a comment below or on the tracking issue linked above.

Props to @jeffpaul, @mamaduka, @wildworks, @annezazu, and @desrosj for review.

#core, #dev-notes, #notes