From 22b5737a3644d8ee0778306dacbbf66b53081263 Mon Sep 17 00:00:00 2001
From: Adam Silverstein <adam@10up.com>
Date: Mon, 12 Aug 2019 10:28:26 -0600
Subject: [PATCH] =?UTF-8?q?Add=20examples=20for=20the=20lockPostSaving=20a?=
 =?UTF-8?q?nd=20unlockPostSaving=20actio=E2=80=A6=20(#16713)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add examples for the lockPostSaving and unlockPostSaving actions

* build docs
---
 .../developers/data/data-core-editor.md       | 40 ++++++++++++++++++
 packages/editor/src/store/actions.js          | 42 +++++++++++++++++++
 2 files changed, 82 insertions(+)

diff --git a/docs/designers-developers/developers/data/data-core-editor.md b/docs/designers-developers/developers/data/data-core-editor.md
index b38e4ede0bf678..884d2cc3910eb8 100644
--- a/docs/designers-developers/developers/data/data-core-editor.md
+++ b/docs/designers-developers/developers/data/data-core-editor.md
@@ -1094,6 +1094,41 @@ _Related_
 
 Returns an action object used to signal that post saving is locked.
 
+_Usage_
+
+    const { subscribe } = wp.data;
+
+    const initialPostStatus = wp.data.select( 'core/editor' ).getEditedPostAttribute( 'status' );
+
+    // Only allow publishing posts that are set to a future date.
+    if ( 'publish' !== initialPostStatus ) {
+
+    	// Track locking.
+    	let locked = false;
+
+    	// Watch for the publish event.
+    	let unssubscribe = subscribe( () => {
+    		const currentPostStatus = wp.data.select( 'core/editor' ).getEditedPostAttribute( 'status' );
+    		if ( 'publish' !== currentPostStatus ) {
+
+    			// Compare the post date to the current date, lock the post if the date isn't in the future.
+    			const postDate = new Date( wp.data.select( 'core/editor' ).getEditedPostAttribute( 'date' ) );
+    			const currentDate = new Date();
+    			if ( postDate.getTime() <= currentDate.getTime() ) {
+    				if ( ! locked ) {
+    					locked = true;
+    					wp.data.dispatch( 'core/editor' ).lockPostSaving( 'futurelock' );
+    				}
+    			} else {
+    				if ( locked ) {
+    					locked = false;
+    					wp.data.dispatch( 'core/editor' ).unlockPostSaving( 'futurelock' );
+    				}
+    			}
+    		}
+    	} );
+    }
+
 _Parameters_
 
 -   _lockName_ `string`: The lock name.
@@ -1330,6 +1365,11 @@ _Returns_
 
 Returns an action object used to signal that post saving is unlocked.
 
+_Usage_
+
+    // Unlock post saving with the lock key `mylock`:
+    wp.data.dispatch( 'core/editor' ).unlockPostSaving( 'mylock' );
+
 _Parameters_
 
 -   _lockName_ `string`: The lock name.
diff --git a/packages/editor/src/store/actions.js b/packages/editor/src/store/actions.js
index 36190a77b47ade..be98bc2ef8bc67 100644
--- a/packages/editor/src/store/actions.js
+++ b/packages/editor/src/store/actions.js
@@ -875,6 +875,42 @@ export function disablePublishSidebar() {
  *
  * @param  {string} lockName The lock name.
  *
+ * @example
+ * ```
+ * const { subscribe } = wp.data;
+
+ * const initialPostStatus = wp.data.select( 'core/editor' ).getEditedPostAttribute( 'status' );
+ *
+ * // Only allow publishing posts that are set to a future date.
+ * if ( 'publish' !== initialPostStatus ) {
+ *
+ * 	// Track locking.
+ * 	let locked = false;
+ *
+ * 	// Watch for the publish event.
+ * 	let unssubscribe = subscribe( () => {
+ * 		const currentPostStatus = wp.data.select( 'core/editor' ).getEditedPostAttribute( 'status' );
+ * 		if ( 'publish' !== currentPostStatus ) {
+ *
+ * 			// Compare the post date to the current date, lock the post if the date isn't in the future.
+ * 			const postDate = new Date( wp.data.select( 'core/editor' ).getEditedPostAttribute( 'date' ) );
+ * 			const currentDate = new Date();
+ * 			if ( postDate.getTime() <= currentDate.getTime() ) {
+ * 				if ( ! locked ) {
+ * 					locked = true;
+ * 					wp.data.dispatch( 'core/editor' ).lockPostSaving( 'futurelock' );
+ * 				}
+ * 			} else {
+ * 				if ( locked ) {
+ * 					locked = false;
+ * 					wp.data.dispatch( 'core/editor' ).unlockPostSaving( 'futurelock' );
+ * 				}
+ * 			}
+ * 		}
+ * 	} );
+ * }
+ * ```
+ *
  * @return {Object} Action object
  */
 export function lockPostSaving( lockName ) {
@@ -889,6 +925,12 @@ export function lockPostSaving( lockName ) {
  *
  * @param  {string} lockName The lock name.
  *
+ * @example
+ * ```
+ * // Unlock post saving with the lock key `mylock`:
+ * wp.data.dispatch( 'core/editor' ).unlockPostSaving( 'mylock' );
+ * ```
+ *
  * @return {Object} Action object
  */
 export function unlockPostSaving( lockName ) {