Customize Snapshots

Description

Customize Snapshots save the state of a Customizer session so it can be shared or even published at a future date. A snapshot can be shared with a private URL to both authenticated and non-authenticated users. This means anyone can preview a snapshot’s settings on the front-end without loading the Customizer, and authenticated users can load the snapshot into the Customizer and publish or amend the settings at any time.

Snapshots are an implementation of key aspects of the customizer transactions proposal.

This plugin works well with Customizer Browser History, which ensures that URL in the browser corresponds to the current panel/section/control that is expanded, as well as the current URL and device being previewed.

Requires PHP 5.3+. Development of this plugin is done on GitHub. Pull requests welcome. Please see issues reported there before going to the plugin forum.

Persistent Object Caching

Plugins and themes may currently only use is_customize_preview() to
decide whether or not they can store a value in the object cache. For
example, see Twenty_Eleven_Ephemera_Widget::widget(). However, when
viewing a snapshot on the frontend, the is_customize_preview() method
will return false. Plugins and themes that store values in the object
cache must either skip storing in the object cache when CustomizeSnapshots\is_previewing_settings()
is true, or they should include the CustomizeSnapshots\current_snapshot_uuid() in the cache key.

Example of bypassing object cache when previewing settings inside the Customizer preview or on the frontend via snapshots:

if ( function_exists( 'CustomizeSnapshots\is_previewing_settings' ) ) {
    $bypass_object_cache = CustomizeSnapshots\is_previewing_settings();
} else {
    $bypass_object_cache = is_customize_preview();
}
$contents = null;
if ( ! $bypass_object_cache ) {
    $contents = wp_cache_get( 'something', 'myplugin' );
}
if ( ! $contents ) {
    ob_start();
    myplugin_do_something();
    $contents = ob_get_clean();
    echo $contents;
}
if ( ! $bypass_object_cache ) {
    wp_cache_set( 'something', $contents, 'myplugin', HOUR_IN_SECONDS );
}

Screenshots

  • The “Save & Publish” button is broken up into separate “Save” and “Publish” buttons. The “Save” button creates a snapshot and turns into “Update” to save a new snapshot.
  • For non-administrator users (who lack the new customize_publish capability) the “Publish” button is replaced with a “Submit” button. This takes the snapshot and puts it into a pending status.
  • Saving snapshot causes the snapshot UUID to appear in the URL, allowing it to be bookmarked to easily come back to later. Upon publishing, the UUID will be removed from the URL so a new snapshot can be started made.
  • The Snapshots admin page lists out all of the snapshots in the system. When the excerpt view is turned on, a list of the settings modified in the snapshot can be seen.
  • Viewing a snapshot post in the admin shows all of the modified settings contained within it. A link is provided to open the snapshot in the Customizer to continue making changes.
  • Published snapshots are shown in the admin screen but lack the ability to open in the Customizer, as they are intended to be frozen revisions for when the Customizer was saved.
  • Changes to snapshots are captured in revisions.

Reviews

Read all 1 reviews

Changelog

0.6.0 RC1 – 2017-02-06

See issues and PRs in milestone.

See full commit log: 0.5.2...0.6.0-rc1

Props: Utkarsh Patel (@PatelUtkarsh), Sayed Taqui (@sayedwp), Weston Ruter (@westonruter), Ryan Kienstra (@kienstra), Luke Gedeon (@lgedeon).

0.5.2 – 2016-08-17

  • Fixed: Prevent enqueueing frontend JS in the customizer preview. This was erroneously causing the customize_snapshot_uuid param to get injected into links in the preview. See #80.
  • Fixed: Ensure that Update button gets disabled and reset to Save once changes have been published. See #83.

See full commit log: 0.5.1...0.5.2

Issues in milestone: milestone:0.5.2

Props: Weston Ruter (@westonruter), Utkarsh Patel (@PatelUtkarsh)

0.5.1 – 2016-08-23

  • Added: Pass Customize_Snapshot instance as second param to customize_snapshot_save filter. See #77.
  • Fixed: Restrict user from publishing or scheduling a snapshot unless they can customize_publish. See #74.
  • Fixed: Fix logic for when to show the snapshot publish error admin notice and show underlying error codes when there are validity errors. See #79.

See full commit log: 0.5.0...0.5.1

Issues in milestone: milestone:0.5.1

Props: Utkarsh Patel (@PatelUtkarsh), Luke Gedeon (@lgedeon), Weston Ruter (@westonruter)

0.5.0 – 2016-08-11

Added:

  • Allow snapshot posts to be published from the admin, and thus also scheduled for publication. Customizer settings get saved when a snapshot post transitions to the publish status. If any of the settings are unrecognized or invalid, none of the settings are saved and the status gets kicked back to pending with error messages explaining the problem(s). Published snapshots are considered “locked” and the UI for updating them is hidden, aside from trash. (#15, #62, #59)
  • Add UI for scheduling for scheduling a snapshot when inside the Customizer. When a future date is selected, the “Save” button becomes “Schedule”. (#68)
  • Add link in Customizer to access edit post screen. (#59)
  • Add initial read-only REST API endpoints for snapshots. (#63, #59)
  • Ensure that setting validations are handled in snapshot requests. If any settings are invalid, the snapshot save will be rejected, invoking the same behavior as when attempting to publish invalid settings. (#59, #54, #31)
  • Add link in Customizer to view the snapshot applied to the frontend, adding the customize_snapshot_uuid query param to the current URL being previewed and optioning a new window. (#57)
  • Add link in snapshot edit post screen to view snapshot applied to the frontend. (#49, #52)
  • Add link in Customizer to access the snapshot’s edit post admin screen, allowing the snapshot’s state to be inspected. (#48, #51)
  • Inject the customize_snapshot_uuid param into all links when viewing a snapshot on the frontend. This allows the frontend to be browsed as normally with the snapshot context retained. In this mode, the admin bar shows links for returning to the Customizer, for inspecting the snapshot in the admin, and for existing the snapshot preview. If a user happened to navigate to a URL without the snapshot UUID param, then the admin bar will prompt for restoring the snapshot session. (#47, #70)
  • Inject the current Customizer state into Ajax requests. When viewing a snapshot on the frontend this is done by inserting the customize_snapshot_uuid param into the request via jQuery.ajaxPrefilter. When in the Customizer preview, the Ajax requests are also intercepted by jQuery.ajaxPrefilter: if they are GET they get converted to POST with X-HTTP-Method-Override header added, and the customized data is amended to the request. Requests to the WP REST API, Admin Ajax, and custom endpoints should all have the Customizer state reflected in the responses. (#65, #70)
  • Also, inject the current Customizer state into form submissions. When viewing a snapshot on the frontend this is done by inserting a customize_snapshot_uuid hidden form input. When in the Customizer preview, forms with a GET method get intercepted and the form data gets serialized and added to the action and then navigated to like a normal link. Forms with POST will continue to no-op when submitted in the Customizer (and their submit buttons will have not-allowed cursor). This fixes a long-standing Trac ticket #20714 “Theme customizer: Impossible to preview a search results page”. (#72)

Fixed:

  • Changes to nav menus, nav menu items, and nav menu locations can now be saved to snapshots, previewed on the frontend, and published like other settings in a snapshot. (#2, #55, #56)
  • Refactor codebase, including new Post_Type class. (#59)
  • Use customize_refresh_nonces filter to export snapshot nonce. (#59)
  • Eliminate generate_snapshot_uuid request by returning new UUID in saving response. (#59)
  • Clear up distinction between previewing vs saving values in a snapshot. Remove the can_preview method: only users who have the setting’s capability can write to the snapshot, so everyone should be able to freely preview what has been stored there. (#26, #59)
  • Ensuring that snapshots UI isn’t loaded if a theme switch is happening; prevent Save & Activate button from going missing. (#28, #59)
  • Ensure that get_permalink() returns the frontend URL for the site with the customize_snapshot_uuid param added.

Removed:

  • The scope parameter has been removed, as has storing non-dirty settings in a snapshot. (#59)

See full commit log: 0.4.0...0.5.0

Issues in milestone: milestone:0.5.0

Props: Weston Ruter (@westonruter), Utkarsh Patel (@PatelUtkarsh), Derek Herman (@valendesigns), Miina Sikk (@miina), Sayed Taqui (@sayedwp)

0.4.0 – 2016-06-11

Added:

  • Improved UX by removing save/update dialogs, changing the Snapshot button text to “Save” & “Update” for a more streamlined experience by removing the “full” snapshot option. (Issues #13, #42, PR #30)
  • Snapshot UUID is dynamically added to the Customizer URL when a snapshot is first saved and it is stripped from the URL once the settings are published (and the snapshot is published), at which point the snapshot is “frozen”. (Issue #37, PR #40).
  • Update button can now be shift-clicked to open the snapshot on the frontend in a new window.
  • Eliminate the storage of non-dirty settings in a Snapshot, which deprecates the scope feature (Issue #42)
  • Support listing snapshots in the admin and inspecting their contents WP Admin UI, with shortcuts to open snapshot in Customizer, viewing the list of settings contained in a snapshot from the excerpt in post list view (Issue #45, PRs #38, #46).
  • Introduce pending snapshots for users who are not administrators (who lack the customize_publish capability) to be able to make snapshots and save them, and then submit them for review once ready (PR #38).
  • Added revisions for snapshots so that changes to a snapshot made before the time it is published can be tracked.
  • New banner image and icon (Issue #24, PR #27).
  • Bumped minimum WordPress version to 4.5.

Fixed:

  • Store content in post_content instead of post_content_filtered (Issue #25, PRs #36, #43). This breaks backwards compatibility with existing snapshots.
  • Replace customize-snapshots JS dependency from customize-widgets to customize-controls (PR #14).
  • Ensure that widget actions and filters are added when previewing snapshots from the front-end (Issue #34, PR #33).
  • Use wp_slash() instead of add_magic_quotes() when loading the snapshot post vars (PR #23).
  • Update dev-lib.

See full commit log: 0.3.1...0.4.0
Issues/PRs in release: milestone:0.4.0
Props: Weston Ruter (@westonruter), Derek Herman (@valendesigns), Luke Carbis (@lukecarbis)

0.3.1

  • Fix additional WordPress VIP issues.
  • Update dev-lib.
  • Update Coveralls.

0.3.0

  • Initialize Snapshots before Widget Posts so that $wp_customize will be set on the front-end.
  • Fix WordPress VIP PHPCS issues.
  • Update dev-lib.
  • Remove unused button markup in dialog.

0.2.1

  • Fix AYS confirmation if the snapshot state is saved.
  • Register dynamic settings to ensure that snapshot settings are recognized in the post values.
  • Slash input for wp_insert_post() to prevent loss of slashes.

0.2

  • Added the customize_publish capability.
  • Separate “Save” & “Publish” buttons.

0.1.1

  • Fix widget preview.

0.1

  • Initial release.

Contributors & Developers

This is open source software. The following people have contributed to this plugin.

Browse the code