Customize Posts Plugin

This is a feature plugin intended to implement #34923: Introduce basic content authorship in the Customizer.

The goal for this plugin is to be able to expose the editing of posts and pages in the Customizer, allowing you to edit post data and postmeta for any number of posts, and preview the changes before saving them for others to see. This plugin was birthed out of the Widget Customizer feature-as-plugin project which was merged into WordPress Core: as widgets (in 3.9) and nav menus (4.3) can now be managed in the Customizer, so too should posts and pages be editable in the Customizer as well.

Did you know that changing the featured image actually makes the change live even before you save the post? This is very surprising/unexpected behavior. The only way to truly preview a change to a featured image is to use something like Customize Posts.

Likewise, did you know that changing a page template cannot be previewed from the post editor? When you change the selected page template, the change will not show up when you preview the page (see #11049). However, in Customize Posts you can preview changes to the page template just by changing the dropdown selection, and then you can see what your page would look like with the new template after the preview refreshes.

Most other changes to metaboxes containing data that gets saved to custom fields (postmeta) also get written when clicking the Preview button. The Customize Posts plugin provides a framework to edit postmeta in the Customizer with a live preview of the changes. (Fixing this underlying issue of incorrectly persisting postmeta when doing a preview is captured in #20299.)

As much as possible, the previewing of changes in Customize Posts utilizes the selective refresh capabilities introduced in WordPress 4.5. Not only does this mean it is faster to preview changes to posts and postmeta, but it also allows you to shift-click on an element to focus on the corresponding control in the Customizer pane. For example you can shift-click on the post title in the preview to focus on the post title control’s input field, or shift-click on a featured image to focus on the control’s button to open the media library.

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

(This Customize Posts plugin is not to be confused with 10up’s Post Customizer.)

Demo Videos

The following are listed in reverse chronological order. The first, more recent videos, show more polish.

[2016-04-28] New features in 0.5.0.

[2016-03-28] Previewing post from Post Edit screen.

[2016-03-05] Opening a draft post in the Customizer to preview title wrapping.

[2016-03-04] Demo featuring the WP visual rich text editor (TinyMCE), including the insertion of images from the media library. Post content can be edited in the Customizer and previewed in multiple contexts. For example, this allows you to preview how a Read More tag will appear when the post appears on a post list page, and you can navigate to the single post to continue previewing subsequent paragraphs. You can expand the editor into a full-screen mode to focus on writing and then quickly preview the changes on the site by toggling the editor. You can make changes to as many posts as you want, but none of the changes will go live until you hit Save & Publish: everything is previewed so there is no “save and surprise”.

[2016-03-03] Demonstration of integration with Customize Setting Validation (#34893) to gracefully handle failures to save due to post locking and concurrent user editing:

[2016-03-01] Demonstration of hooking into edit post links so that they actually work in the Customizer and expand the section to edit the given post (as opposed to the link doing nothing at all when clicked), as well as shift-clicking on the title and content (needs better discovery UI, see #27403):

1. 

   [0.7.0] Select2 dropdown in a post type's panel allows all posts of that type to be searched, including trashes. Selecting a post here causes its section to be added and expanded, with the preview then navigating to the URL for that post.

2. 

   [0.7.0] Post status control is now accompanied by a post date control. A Move to Trash link also appears with the status control.

3. 

   [0.7.0] Selecting a future date switches status form published to scheduled, and a countdown for when the post will be scheduled is available along with the timezone information.

4. 

   [0.7.0] Clicking the date reset link causes the setting's date to be emptied, with the control's inputs then receiving the current date/time as placeholders which update each minute to correspond to the current date/time.

5. 

   [0.8.0] Integration with dropdown-pages controls. Buttons to add and edit posts appear next to the page on front and page for posts controls.

6. 

   [0.8.0] Edit post button appears in nav menu items that link to a post or page.

7. 

   [0.8.0] Post parent and basic menu order control.

[0.9.1] – [2017-11-13]

Fix saving of postmeta in scheduled changesets. See #375.

[0.9.0] – [2017-11-11]

• Bump minimum required WP version to 4.7; update compatibility for 4.9. See #371.
• Update wrapper around notifications.add for new params accepted in 4.9. See #369.
• Make use of section notifications API in WP 4.9 when available; otherwise polyfill. See #366.
• Fix syncing of post changes made in post preview customizer back to edit post screen. See #361.

See issues and PRs in milestone and full release commit log.

[0.8.7] – [2017-08-03]

• Fixed: Ensure that nested edit shortcuts in Twenty Seventeen front-page panels are positioned properly. See #357.
• Fixed: Prevent post field partials from erroneously selecting nested post placements, prevent edit shortcuts from being duplicated, and ensure partials get created for all posts displayed. See #355, #356.

See issues and PRs in milestone and full release commit log.

[0.8.6] – [2017-06-08]

• Bumped compatibility to WordPress 4.8.
• Added: Show notification when a post is restored from trash. PR #347. Issue #217.
• Added: Allow the customize_action template for a given post type’s panel to be defined via registered post type labels. Issue #343. PR #345.
• Added: Focus on specific field that have conflict. Issue #35. PR #341.
• Updated: Remove sessionStorage and use changeset to save post editor screen data. Issue #338. PR #350.
• Updated: Removed reference to obsolete plugin. Issue #323. PR #342.
• Fixed: Stop continuous ajax requests in select2. PR #351.
• Fixed: Prevent warning when importing starter content including CPT posts. PR #340.
• Fixed: Use auto-draft with late future date instead of customize-draft and clean auto-draft on changeset delete. Issue #329. PR #348.

See issues and PRs in milestone and full release commit log.

Props Weston Ruter (@westonruter), Sayed Taqui (@sayedtaqui), Utkarsh Patel (@PatelUtkarsh), Jeffrey Paul (@jeffpaul), Zlatko Zlatev (@entr).

[0.8.5] – 2017-01-03

• Add syncing of customize post settings to Backbone post models; try this out with the Next Recent Posts Widget. Fixes #331, PR #333.
• Improve logic for determining when to do fallback refresh for post field partials, reducing the number of needless full page refreshes. PR #335.
• Differentiate featured image partials on index templates for separate posts, allowing changes to featured images to be previewed properly on the homepage and archive views. Fixes #297, PR #334.
• Handle edit post links that have child elements; remove need for data-customize-post-id attribute. PR #332.

See issues and PRs in milestone and full release commit log.

[0.8.4] – 2016-12-03

• Ensure auto-draft posts referenced in snapshot/changeset get transitioned to customize-draft, and that customize-draft nav_menus_created_posts get published (PR #326).
• Improve method for skipping attachments so no error in console appears (PR #325, Issue #32).

See issues and PRs in milestone and full release commit log.

[0.8.3] – 2016-11-24

• Prevent extra section params from being passed along to previewUrl (PR #306)
• Fix errors and erroneous selective refresh caused by dirty post settings not being synced into nav menu item settings (PR #307)
• Add compat for WP4.5 where settingConstructor is not defined (PR #308)
• Fix handling of postmeta preview filter when no modifications are in customized state (PR #309)
• Improve compatibility with Customize Changesets (PR #300)
• Recognize and handle dropdown-pages control in WP 4.7-alpha (PR #311)
• Prevent attempting to update original titles for removed nav menu items (placeholders) (PR #312)
• Restore edit_post_link() in WordPress 4.7 (PR #314)
• Disable polyfill for nav menu item loading/searching fix landing in 4.7 (PR #315)
• Eliminate determination of user capability in setting constructor (PR #316)
• Prevent sending back DB-persisted setting values in customize_save_response unless changeset is being published (PR #317)
• Pass missing options param in wrapped isLinkPrewable function (PR #318)
• Improve compat with posts & pages created as stubs in 4.7 (PR #320)

See issues and PRs in milestone and full release commit log.

Props Weston Ruter (@westonruter), Sayed Taqui (@sayedwp), Utkarsh Patel (@PatelUtkarsh).

[0.8.2] – 2016-10-03

• Fixed browser incompatible way of parsing local datetime strings. This is a follow-up on #293, which was not fully fixed in 0.8.1. PR #304.
• Improved fetching of post/postmeta settings so that the customized state is included in the request, and allow for placeholder nav_menu_item settings to be fetched. PR #299.
• Added $setting context to customize_previewed_postmeta_rows filter and add new customize_previewed_postmeta_rows_{$setting->post_meta} filter. PR #299.

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

See issues and PRs in milestone and full release commit log.

[0.8.1] – 2016-09-23

Fixed compatibility with Safari in the wp.customize.Posts.getCurrentTime() method. See #293. Props Piotr Delawski (@delawski).

[0.8.0] – 2016-09-22

Added:

• Add ability to edit and create pages from dropdown-pages controls, such as the controls for page on front and page for posts. Adds startEditPageFlow and startAddPageFlow methods from the Customize Object Selector plugin. See #271 and PRs #272, #284, #285.
• Allow page/post stubs created via nav menus in 4.7-alpha to also be edited like any other page. See #253 and PR #287.
• For nav menu items linking to a post/page, add a edit button that appears in the nav menu item control next to the original link. Clicking edit will expand the section for that post/page, and collapsing the section will return focus to the button in the nav menu item control. See #147 and PR #288.
• Sync post/page changes to available nav menu items and nav menu item controls, ensuring titles are consistent in available item lists and in the nav menu item control’s title, label placeholder, and original link, and in the nav menu item setting’s original_title property. If a nav menu item lacks its own title and inherits from original_title, post/page changes will now trigger nav menu selective refresh updates. See #156 and PR #288, #289.
• Sync pages additions, changes, and removals to all dropdown-pages controls, in particular to the page on front and page for posts controls in the static front page section. See #153. PRs #190, #270, #275, #276.
• Add support post parent control via Customize Object Selector plugin’s control (in v0.3). See #65 and PRs #189, #233.
• Add rudimentary number-based menu order control. See #84 and PR #255, #257.
• Add previewing of title changes for pages listed by wp_list_pages(). PR #256.
• Implement support for all of the WP_Query query vars, including post meta queries, ensuring results have posts’ customized state applied as expected. This is a big improvement to ensure customized posts and postmeta will appear the same before or after saving the customized state. Previously, previewing WP_Query results was very limited and often not accurate. As part of this, get_posts() and any queries made with suppress_filters on will be overridden to force filters to apply. See #246 and PR #248.
• Add support to WP_Customize_Postmeta_Setting for representing non-single postmeta. Such settings are instantiated with a true single arg and they require an array value. The customize_sanitize_{$setting_id} filter will apply to each array item separately, as will the sanitize_meta() call. PR #248.
• Ensure that static front page constructs get registered even without any pages yet created. Add active callback to the static front page section so that it will appear as soon as a published page exists (either via adding a new page from the Pages panel or via a nav menu item page stub in WP 4.7-alpha). See #252 and PR #254.
• Refactor editor control to be reusable for not just post content but also custom fields (postmeta). See PRs #216, #269.
• Ensure that the results of get_pages() has the customized state applied. This enables support for wp_dropdown_pages() (and thus the post parent control). See #241 and PR #250.
• Prevent the same page from being selected as both the page for posts and the page on front. PR #270.
• Improve support for page for posts by hiding page template and content since not displayed. Show notice that the page for posts is being edited. See #228, #277 and PR #278.
• Allow posts component to be filtered out to be disabled like other components (widgets and nav_menus). See #132 with PRs #219 and #258.
• Disable edit-post-links module in customize-direct-manipulation plugin so that edit links in the preview will continue to work in Customize Posts. PR #234.
• Let Customize link in admin bar deep link on the post section when on a singular template. See #105 and PR #236.
• Use non-minified scripts and styles if plugin installed via git (submodule), eliminating the need to add SCRIPT_DEBUG or do a build. PR #249.
• Add all to wp_transition_post_status()``when transitioning fromauto-drafttocustomize-draft`. PR #266.
• Include nav menu items and their postmeta in requests to fetch settings. This is to facilitate custom fields in nav menus items. PRs #263, #268, #274.
• Support constructing Setting objects in JS using a specific settingConstructor if defined for a given setting type when fetching settings. PR #286.

Changed:

• For registered post type attributes, use public instead of show_ui as default show_in_customizer flag. See #264 and PR #265.

Fixed:

• Restrict page template control to just the page post type (as opposed to other post types that support page-attributes). PR #227.
• Ensure that preview urls are used as permalinks for customized posts. PR #245.
• Ensure the page for posts can be previewed as the page for posts (and not a normal page). See #260 and PR #292.
• Fix ability to do translation via translate.wordpress.org. PR #215.
• Ensure wp_insert_post_empty_content filter gets removed after trashing. PR #214.
• Fix theme compat for twentysixteen content rendering by including additional template tags. PR #226.
• Fix display of notifications in date control. See #229 and PR #230.
• Use notification.setting instead of notification.data.setting. PR #238.
• Add syncing of slug (post_name) between edit post screen and customize post preview. PR #239.
• Eliminate post type names in generic strings to ensure ability to translate. See #237 and PR #242.
• Use flexbox for post selection lookup select2 and add button. PR #244.
• Remove underline from time-info-handle in 4.7-alpha. PR #242.
• Make sure post_author is string in PHP but keep int in JS. PR #251.
• Ensure that a post section is expanded when a post editor control is expanded. Issue #259 and PR #280.
• Prevent ESC key from causing the editor to collapse unexpectedly. See #281 and PR #282.
• Ensure that all TinyMCE UIs are hidden when the editor control is collapsed. See #231 and PR #282.

Removed:

• Removed the customize_previewed_posts_for_query filter since now unnecessary and irrelevant after refactor in #248.

See issues and PRs in milestone and full release commit log

Props: Weston Ruter (@westonruter), Sayed Taqui (@sayedwp), Sunny Ratilal (@sunnyratilal), Ryan Kienstra (@kienstra), Eduard Maghakyan (@EduardMaghakyan).

[0.7.0] – 2016-08-06

Added:

• Introduce Select2 dropdown in a post type’s panel for searching for any post to load, even if it is not shown in the preview. Selecting a post adds its section to the Customizer and expands it while also navigating to the post’s URL in the preview. Trashed posts are also listed, and selecting a trashed post will load its post data into the Customizer in its untrashed state (restoring its original status and slug) so that upon save it will be be untrashed. (#196, #199)
• Add control for post date, including synchronization with publish/future status for when date is in future. Control includes timezone information and countdown for when schedule publish will happen. Also includes reset link to leave the date empty so that it will default to the current date/time when it is published. (#56, #202)
• Improve UX for trashing posts, adding a Move to Trash link. (#172, #211)
• Add initial support for meta queries when the Customizer state includes changes to postmeta. (#174, #191, #197, #193)
• Allow post field control labels to be defined in register_post_type() so that the names can be repurposed to be appropriate to the custom post type. (#195)
• Add low-fidelity live JS-applied previews to post title changes while waiting for high-fidelity PHP-applied selective refresh requests to response. (#43)

Fixed:

• Ensure title is focused and selected when creating a new post. (#209, #208, #206)
• Make sure that posts are loaded for any post sections/controls that are autofocused. (#204, #205)
• Speed up performance by registering post/postmeta settings and partials only as they are needed (just in time), introducing a new ensurePosts API call to fetch the settings over Ajax and create the relevant section. (#201)
• Improve test coverage. (#200)
• Fix editor text not persistent issue across all posts and post types. (#129, #198)
• Sort posts in a section reverse-chronologically by date (if non-hierarchical) or else by menu_order if hierarchical. (#124)
• Ensure changes to post status are reflected in return value when calling get_post_status(). (#194)

See full commit log: 0.6.1...0.7.0

Issues in milestone: milestone:0.7.0

Props: Weston Ruter (@westonruter), John Regan (@johnregan3), Sayed Taqui (@sayedwp), Utkarsh Patel (@PatelUtkarsh), Luke Gedeon (@lgedeon), Ahmad Awais (@ahmadawais), Derek Herman (@valendesigns), Piotr Delawski (@delawski)

[0.6.1] – 2016-06-16

• Send values to JS via js_value() and use the settings json method if available.
• Move comments_open and pings_open filters to the WP_Customize_Posts_Preview::add_preview_filters method.
• Fix purgeTrash to ensure trashed post sections do not appear in the Customizer root panel after publishing changes.
• Ensure the modified date is not changed when transitioning to customize-draft.
• Make sure the customize-draft status is always available to Customize Snapshots & wp-admin
• Fix PHP notice generated when a post type is registered without map_meta_cap
• Delete auto-draft and customize-draft status posts when saving the trash post_status
• Use a post type’s edit_posts capability for sections
• Defer embedding a sections contents until expanded
• Implement focusControl support for deferred-embedded post section controls
• Add support for focusing on controls for setting properties when those properties are invalid
• Prevent customized-posts messages sent via selective-refresh from effecting post-navigation state
• Improve feature detection for including customize-controls patched for trac-36521
• Included plugin-support and theme-support PHP files that were inadvertantly omitted from the 0.6.0 build.

See full commit log: 0.6.0...0.6.1

Issues in milestone: milestone:0.6.1

Props: Weston Ruter (@westonruter), Derek Herman (@valendesigns)

0.6.0 – 2016-06-02

Added:

• Add the ability to create new posts and pages in the Customizer. Created posts get auto-draft status in the DB so they will be garbage-collected if the Customizer is never saved. A new view link appears in the post section allowing a newly-created post to be navigated to easily without having to find the created post linked to in the preview. (Issues #48, #50, PR #134)
• Add post status control and preview, with trash status support (Issues #40, #137, PR #152)
• Add support for setting validation in WordPress 4.6-alpha, showing notifications if attempting to save when a post is locked or a conflicting update was previously made. (Issue #142, PR #150)
• Add the ability to vertically resize the post editor (Issue #136, PR #149)
• Add post slug control, wherein changes do not cause the preview to refresh by default since there is nothing to see (Issue #63, PR #148)
• Posts data as saved will now be synced back into the Customizer interface, ensuring that if a post slug gets the infamous -2 added, you’ll see that in the Control. Likewise, if a wp_insert_post_data filter or content_save_pre changes your data in some way, these will be shown in the post’s Customizer controls upon saving.
• Add extendable theme & plugin compatibility classes that can configure partial rendering. All Core themes & Jetpack are currently supported. (Issues #82, #103, PR #123)
• Use plugins_url() for each asset URL so that the plugin can be installed as a submodule without SCRIPT_DEBUG (Issue #133)

Fixed:

• Add all postmeta settings for registered types not just the ones actually referenced (Issues #141, #145)
• Export all registered post types to client, but only register panels if show_in_customizer (PR #130)
• Ensure that control pane expand button is visible when editor is open and the Customizer pane is collapsed (Issue #44, PR #126)
• Improve compatibility with the Customize Snapshots plugin.
• Improve compatibility with the WP REST API plugin.
• Supply a default (no title) placeholder to the post title control for new posts.
• Filter post and page links in the Customizer to return the preview URL.

See full commit log: 0.5.0...0.6.0

Issues in milestone: milestone:0.6

Props: Weston Ruter (@westonruter), Derek Herman (@valendesigns), Philip Ingram (@pingram3541), Daniel Bachhuber (@danielbachhuber), Stuart Shields (@stuartshields)

0.5.0 – 2016-04-27

Added:

• Support for postmeta, including a framework for registering postmeta types. (Issues #1, PR #89)
• Page template control and preview, with sync from Customizer post preview back to post edit screen. (Issue #85, PR #89)
• Featured image control, with sync from Customizer post preview back to post edit screen. Changes to the featured image can now be previewed, where normally this is not possible in WordPress. Improved featured image selection on edit post screen to not update featured image in place, instead waiting until the post is Saved until updating the featured image postmeta. The featured image can be set from the post edit screen and then previewed in the Customizer via the post Preview Changes button: the featured image can be further changed in the Customizer post preview, with changes synced back to the post edit screen when the Customizer post preview is exited. (Issue #57, PR #102)
• Author control and preview, with sync from Customizer post preview back to post edit screen (Issue #62, PRs #89 #92)
• Excerpt control and preview, with sync from Customizer post preview back to post edit screen (Issue #60, PR #91)
• Comment status control and preview, with sync from Customizer post preview back to post edit screen (Issues #61, PR #100)
• Ping status control and preview, with sync from Customizer post preview back to post edit screen (Issue #64, PR #100)
• Improve PHPUnit test coverage to 98%.
• Note: Selective refresh support was specifically tested with Twenty Fifteen and Twenty Sixteen. See #103 for a way for themes to configure how they represent the various post fields in template parts.

Fixed:

• Improve editor styles in mobile and in fullscreen mode. (Issue #45, PR #107)
• Modals, toolbars, and tooltips and are no longer hidden (Issue #80, PRs #81, #101).
• Improve compatibility with Customize Widgets Plus (PR #83). See also https://github.com/xwp/wp-customize-widgets-plus/pull/46 for a fix in the Customizer post preview.
• Export post/postmeta settings during selective refresh requests so that new posts added will appear in the panel, such as when adding the number of posts to show in the Recent Posts widget. (Issue #97, PR #99)
• Improve compatibility with Customize Snapshots (PR #95)

See v0.5 release post on Make XWP.

See full commit log: 0.4.2...0.5.0

Issues in milestone: milestone:0.5

Props: Weston Ruter (@westonruter), Derek Herman (@valendesigns), Luke Carbis (@lukecarbis), Mike Crantea (@mehigh), Stuart Shields (@stuartshields)

0.4.2 – 2016-03-30

Restore stylesheet erroneously deleted during grunt deploy.

0.4.1 [YANKED]

• Restore editability of pages in the Customizer (remove default condition that a post type have publicly_queryable as true).
• Log errors in customize-posts message receiver instead of throwing them.

0.4.0 – 2016-03-29

• Open Customizer to preview and make additional changes when clicking Preview from post edit admin screen (see video).
• Introduce show_in_customizer arg for register_post_type(), and let override condition on show_ui ~~and publicly_queryable~~ being both true.
• Fix modals and inline toolbars in TinyMCE editor displayed in Customizer.
• Fix initialization when TinyMCE does not default to Visual.
• Complete support for Jetpack Infinite Scroll, ensuring posts are listed in Customizer in order of appearance.
• Remove dependency on widgets component being loaded.
• Allow auto-draft posts to be previewed.
• Add Grunt, contributing.

0.3.0 – 2016-03-08

• Complete rewrite of plugin.
• Added: Selective refresh is now used to preview changes to the title and content.
• Added: A TinyMCE editor is now used to edit content, including initial support for Shortcake.
• Added: Each post type has a separate panel. Each post is represented by a section within those panels.
• Added: Edit post links in Customizer preview now open post section.
• Added: Integration with Customize Setting Validation to show show error message when post locking or version conflict happens.
• Removed: Postmeta fields (custom fields, page template, featured image) were removed for rewrite but will be re-introduced.

0.2.4 – 2016-01-06

Remove shim that implemented the customize_save_response filter which was introduced in 4.2. The shim used a slightly different filter name and broke insertion of nav menu items in the Customizer.

0.2.3 – 2015-01-09

Change method for registering scripts/styles to fix conflict w/ Jetpack. PR #26

0.2.2 – 2014-12-12

Add compatibility with WordPress 4.1 now that the Customizer has a proper JS API.

0.2.1 – 2014-09-22

Supply missing selected attribute on post_status dropdown.

0.2.0 – 2014-09-17

Initial release on WordPress.org. Key new features:

• Postmeta can now be added, modified, and deleted—all of actions which are fully previewable.
• Grant customize capability to authors and editors who normally can’t access the Customizer, so they can edit posts there.
• Move the “Customize” admin bar link to the top level, and add one for editors and authors.
• Allow the Page Template and Featured Image to be modified and previewed.