Revisions

MediaPress Revisions replaces the core WordPress revision experience with a more intuitive visual comparison between different revisions of a post.

The following view modes are included:

• Blocks - compare the rendered block content of a post
• Metadata - compare post title, excerpt and all revisions-enabled post-meta
• Code - compare the source code of a post

What is a revision?

In WordPress, a revision is created whenever a post is updated, but only in specific circumstances. If certain metadata is updated, or if a post is updated via code using a means other than wp_update_post then a revision might not be created.

A revision will contain the following data by default:

• Post title
• Post excerpt
• Post content
• Post meta (if registered using revisions_enabled flag)

This plugin will also enable the post thumbnail (featured media) to be revisioned by default, if a post type supports it.

Note

Taxonomy terms, post attributes including post status, and post meta without the revisions_enabled flag set are not copied to or restored from revisions.

Ensuring plugin compatibility

If a post-meta is updated directly via code, this might not create a revision. The recommended way to update meta if you expect a revision to be created is to use wp_update_post with a meta_input argument. This also allows you to update multiple meta values at once, whilst creating a single revision, rather than producing multiple revisions related to each meta change.

Additionally, when viewing and restoring a revision, only post-meta that is revisions_enabled will be visible, and only this meta will be restored when the revision is restored.

Diffing

Diffing is the process of comparing two revisions to one another and retrieving a list of differences that we can use to visually indicate what has changed for a user.

The diffing process for blocks is twofold. First, we compare the block list and attributes to understand whether a block is different between the two versions we are comparing. If we detect a difference, we will highlight the entire block to visually indicate it has changed.

We then compare the block attributes to understand more deeply what has changed. Currently, we are only interested in RichText attributes, since these are likely to be rendered visually within the block and will allow us to inject additional visual indicators to highlight specific differences.

For all other attributes the ‘metadata’ or ‘code’ views are useful to see additional context relating to exactly what has changed within a specific revision.

Restoring

In core, when restoring a revision you will lose context of any subsequent revisions that were made after the revision you restored from.

For this reason, when we ‘restore’ a revision, we perform an update to the post. Rather than reverting the post to a previous state, this creates a new revision with the content that has been restored and maintains the revision history of the post.

Custom block support

This plugin aims to support all block types out of the box, but there are some limitations to be aware of.

For example, if a block is used purely to render some post-meta, the block code might not provide any indication that it is different between two versions when comparing blocks. This is because the block technically hasn’t changed - it’s markup and attributes remain the same. In this case, you would use the ‘metadata’ view to see the meta difference.

In other cases, if a block attribute has changed and it’s not a RichText attribute, then the overall block would be highlighted, to understand more about the difference between the two versions of the block and exactly what has changed, you can toggle to the ‘code’ view to inspect the block markup and the changed attribute will be highlighted there.

This means all types of custom blocks can be diffed in the same way, without requiring special treatment.

Additional Configuration

Revisions must be activated via the “MediaPress” settings page. No further configuration is required.

Filters/Actions

PHP

Filters

mediapress_revisions_supported_post_types

Defines the post types on which the revisions functionality will be enabled.

Default Value

[ 'post', 'page' ]

Parameters

Name	Type	Description
post_types	array	Array of post type slugs

Usage

add_filter( 'mediapress_revisions_supported_post_types', 'my_plugin_add_revisions_support' );
function my_plugin_add_revisions_support( array $post_types ): array {
  $post_types[] = 'my_custom_post_type';
  return $post_types;
}

mediapress_revisions_editor_settings

Allows the customization of revisions block editor settings.

Can be used to inject additional CSS into the block editor within the revisions view, or adjust any of the other settings as needed.

Parameters

Name	Type	Description
editor_settings	array	The settings to apply to the block editor instance
post	WP_Post	The current post we’re viewing revisions for

Usage

add_filter( 'mediapress_revisions_editor_settings', 'add_revision_styling', 10, 2 );
function add_revision_styling( array $editor_settings, WP_Post $post ): array {
  if ( 'post' !== $post->post_type ) {
    return $editor_settings;
  }

  $editor_settings['styles'][] = [
    'css' => 'insert custom CSS rules here',
  ];
  return $editor_settings;
}