Add examples for the lockPostSaving and unlockPostSaving actio… (#16713)

* Add examples for the lockPostSaving and unlockPostSaving actions * build docs
WordPress · Aug 29, 2019 · 22b5737 · 22b5737
1 parent ca455e9
commit 22b5737
Show file tree

Hide file tree

Showing 2 changed files with 82 additions and 0 deletions.
diff --git 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
@@ -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 ) {