Add coming soon example code documentation (#48748)

* Add coming soon docs * Update manifest * Add new example and fix writing * Update docs/extension-development/integrating-coming-soon-mode.md Co-authored-by: Adrian Duffell <9312929+adrianduffell@users.noreply.github.com> * Add example for a single page exclusion * Add example for 2-way sync and fix trigger from woocommerce example to use update_option action * Lint * Update docs according to style guide * Better structure for custom exclusions filter * Update manifest --------- Co-authored-by: Adrian Duffell <9312929+adrianduffell@users.noreply.github.com>
2024-06-26 17:07:06 +08:00 · 2024-06-26 17:07:06 +08:00 · d9e837a8ca
parent cacb10065e
commit d9e837a8ca
2 changed files with 148 additions and 2 deletions
--- a/docs/docs-manifest.json
+++ b/docs/docs-manifest.json
@ -309,7 +309,7 @@
          "menu_title": "Integrating admin pages",
          "tags": "how-to",
          "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/extension-development/working-with-woocommerce-admin-pages.md",
-          "hash": "9d01da78347ee7379fe096cce5e3982cd13e46617f90ad78e03af72bc3fb8aba",
+          "hash": "c172fff2814f552e2ab5712edb9e716f75c27946d993a1ade8f2269cc9a8689d",
          "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/extension-development/working-with-woocommerce-admin-pages.md",
          "id": "6f9cc63bc4c614b9e01174069a5ddc4f3d7aa467"
        },
@ -354,6 +354,14 @@
          "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/extension-development/logging.md",
          "id": "c684e2efba45051a4e1f98eb5e6ef6bab194f25c"
        },
+        {
+          "post_title": "Integrating with coming soon mode",
+          "tags": "how-to, coming-soon",
+          "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/extension-development/integrating-coming-soon-mode.md",
+          "hash": "eea34a5e37ceb5448f859d3bb350b6716e4c843a1477bfa5b9a7c369ed837f78",
+          "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/extension-development/integrating-coming-soon-mode.md",
+          "id": "787743efb6ef0ad509b17735eaf58b2a9a08afbc"
+        },
        {
          "post_title": "Creating custom settings for WooCommerce extensions",
          "menu_title": "Creating custom settings",
@ -1359,5 +1367,5 @@
      "categories": []
    }
  ],
-  "hash": "7998790ab69ca3a0f7d480c0dfa0b58916e9c46a04b7e80940cac69f69b50ab4"
+  "hash": "f28ecd23ddeca12c13736f3708c95e0bf8918cca5431abbeb066a9950745bc1e"
 }
--- a/docs/extension-development/integrating-coming-soon-mode.md
+++ b/docs/extension-development/integrating-coming-soon-mode.md
@ -0,0 +1,138 @@
+---
+post_title: Integrating with coming soon mode
+tags: how-to, coming-soon
+---
+
+# Integrating with coming soon mode
+
+This guide provides examples for third-party developers and hosting providers on how to integrate their systems with WooCommerce's coming soon mode. For more details, please read the [developer blog post](https://developer.woocommerce.com/2024/06/18/introducing-coming-soon-mode/).
+
+## Introduction
+
+WooCommerce's coming soon mode allows you to temporarily make your site invisible to the public while you work on it. This guide will show you how to integrate this feature with your system, clear server cache when site visibility settings change, and sync coming soon mode with other plugins.
+
+## Prerequisites
+
+-   Familiarity with PHP and WordPress development.
+
+## Step-by-step instructions
+
+### Clear server cache on site visibility settings change
+
+When the site's visibility settings change, it may be necessary to clear a server cache to apply the changes and re-cache customer-facing pages. The [`update_option`](https://developer.wordpress.org/reference/hooks/update_option/) hook can be used to achieve this.
+
+```php
+add_action( 'update_option_woocommerce_coming_soon', 'clear_server_cache', 10, 3 );
+add_action( 'update_option_woocommerce_store_pages_only', 'clear_server_cache', 10, 3 );
+
+function clear_server_cache( $old_value, $new_value, $option ) {
+    // Implement your logic to clear the server cache.
+    if ( function_exists( 'your_cache_clear_function' ) ) {
+        your_cache_clear_function();
+    }
+}
+```
+
+### Syncing coming soon mode with other plugins
+
+The coming soon mode can be programmatically synced from a plugin or application. Here are some example use cases:
+
+-   Integrating with a maintenance mode plugin.
+-   Integrating with a hosting provider's coming soon mode.
+
+#### Trigger from WooCommerce
+
+You can use the following example to run a code such as setting your plugin's status when coming soon mode option is updated:
+
+```php
+add_action( 'update_option_woocommerce_coming_soon', 'sync_coming_soon_to_other_plugins', 10, 3 );
+
+function sync_coming_soon_to_other_plugins( $old_value, $new_value, $option ) {
+    $is_enabled = $new_value === 'yes';
+
+    // Implement your logic to sync coming soon status.
+    if ( function_exists( 'set_your_plugin_status' ) ) {
+        set_your_plugin_status( $is_enabled );
+    }
+}
+```
+
+#### Trigger from other plugins
+
+You can use the following example to enable or disable WooCommerce coming soon mode from another plugin by directy updating `woocommerce_coming_soon` option:
+
+```php
+function sync_coming_soon_from_other_plugins( $is_enabled ) {
+    // Check user capability.
+    if ( ! current_user_can( 'manage_options' ) ) {
+        wp_die( 'You do not have sufficient permissions to access this page.' );
+    }
+
+    // Set coming soon mode.
+    if ( isset( $is_enabled ) ) {
+        update_option( 'woocommerce_coming_soon', $is_enabled ? 'yes' : 'no' );
+    }
+}
+```
+
+#### 2-way sync with plugins
+
+If 2-way sync is needed, use the following example where `update_option` will not recursively call `sync_coming_soon_from_other_plugins`:
+
+```php
+add_action( 'update_option_woocommerce_coming_soon', 'sync_coming_soon_to_other_plugins', 10, 3 );
+
+function sync_coming_soon_to_other_plugins( $old_value, $new_value, $option ) {
+    $is_enabled = $new_value === 'yes';
+
+    // Implement your logic to sync coming soon status.
+    if ( function_exists( 'set_your_plugin_status' ) ) {
+        set_your_plugin_status( $is_enabled );
+    }
+}
+
+function sync_coming_soon_from_other_plugins( $is_enabled ) {
+    // Check user capability.
+    if ( ! current_user_can( 'manage_options' ) ) {
+        wp_die( 'You do not have sufficient permissions to access this page.' );
+    }
+
+    if ( isset( $is_enabled ) ) {
+        // Temporarily remove the action to prevent a recursive call.
+        remove_action( 'update_option_woocommerce_coming_soon', 'sync_coming_soon_to_other_plugins', 10, 3 );
+
+        // Set coming soon mode.
+        update_option( 'woocommerce_coming_soon', $is_enabled ? 'yes' : 'no' );
+
+        // Re-add the action.
+        add_action( 'update_option_woocommerce_coming_soon', 'sync_coming_soon_to_other_plugins', 10, 3 );
+    }
+}
+```
+
+### Custom exclusions filter
+
+It is possible for developers to add custom exclusions that bypass the coming soon protection. This is useful for exclusions like always bypassing the screen on a specific IP address, or making a specific landing page available.
+
+#### Disabling coming soon in all pages
+
+If there is another feature that behaves similarly to WooCommerce's coming soon mode, it can cause unintended conflicts. The coming soon mode can be disabled by excluding all customer-facing pages. The following is an example:
+
+```php
+add_filter( 'woocommerce_coming_soon_exclude', function() {
+    return true;
+}, 10 );
+```
+
+#### Disabling coming soon except for a specific page
+
+Use the following example to exclude a certain page based on the page's ID. Replace `<page-id>` with your page identifier:
+
+```php
+add_filter( 'woocommerce_coming_soon_exclude', function( $is_excluded ) {
+    if ( get_the_ID() === <page-id> ) {
+        return true;
+    }
+    return $is_excluded;
+}, 10 );
+```