Merge branch 'develop' into fix/screenshots

Author: dkotter

.nvmrc

@@ -1 +1 @@
-16
+18

assets/js/admin-external-connection.js

@@ -324,7 +324,7 @@ function checkConnections() {
 
 				if ( response.data.endpoint_suggestion ) {
 					endpointResult.innerText = `${ __(
-						'Did you mean: ',
+						'Did you mean:',
 						'distributor'
 					) } `;
 
@@ -337,7 +337,7 @@ function checkConnections() {
 					endpointResult.appendChild( suggestion );
 
 					speak(
-						`${ __( 'Did you mean: ', 'distributor' ) } ${
+						`${ __( 'Did you mean:', 'distributor' ) } ${
 							response.data.endpoint_suggestion
 						}`,
 						'polite'

assets/js/admin-pull.js

@@ -4,7 +4,20 @@ import jQuery from 'jquery';
 import { addQueryArgs } from '@wordpress/url';
 import { __ } from '@wordpress/i18n';
 
-const { document } = window;
+const { document, DISTRIBUTOR } = window;
+const { getPullUrl } = DISTRIBUTOR;
+
+/**
+ * Escape special characters in URL components.
+ *
+ * @param {string} str The string to escape.
+ * @return {string} The escaped string.
+ */
+const escapeURLComponent = ( str ) => {
+	return encodeURIComponent( str ).replace( /[!'()*]/g, ( c ) => {
+		return '%' + c.charCodeAt( 0 ).toString( 16 );
+	} );
+};
 
 const chooseConnection = document.getElementById( 'pull_connections' );
 const choosePostType = document.getElementById( 'pull_post_type' );
@@ -16,11 +29,12 @@ const asDraftCheckboxes = document.querySelectorAll( '[name=dt_as_draft]' );
 const pullLinks = document.querySelectorAll( '.distributor_page_pull .pull a' );
 
 jQuery( chooseConnection ).on( 'change', ( event ) => {
-	document.location =
+	const pullUrlId =
 		event.currentTarget.options[
 			event.currentTarget.selectedIndex
-		].getAttribute( 'data-pull-url' );
+		].getAttribute( 'data-pull-url-id' );
 
+	document.location = getPullUrl( pullUrlId );
 	document.body.className += ' ' + 'dt-loading';
 } );
 
@@ -82,12 +96,15 @@ if ( chooseConnection && choosePostType && form ) {
  * @return {string} Distribution URL.
  */
 const getURL = () => {
-	const postType =
-		choosePostType.options[ choosePostType.selectedIndex ].value;
-	const baseURL =
+	const postType = escapeURLComponent(
+		choosePostType.options[ choosePostType.selectedIndex ].value
+	);
+	const pullUrlId = escapeURLComponent(
 		chooseConnection.options[ chooseConnection.selectedIndex ].getAttribute(
-			'data-pull-url'
-		);
+			'data-pull-url-id'
+		)
+	);
+	const baseURL = getPullUrl( pullUrlId );
 	let status = 'new';
 
 	if ( -1 < ` ${ form.className } `.indexOf( ' status-skipped ' ) ) {

assets/js/gutenberg-plugin.js

@@ -151,7 +151,7 @@ const RenderDistributedFrom = () => {
 					) }
 				</span>
 				<span id="distributed-data">
-					{ __( 'Updating the ', 'distributor' ) }
+					{ __( 'Updating the', 'distributor' ) }{ ' ' }
 					<a href={ dtGutenberg.postUrl }>
 						{ __( 'Original Content', 'distributor' ) }
 					</a>
@@ -217,7 +217,7 @@ const RenderDistributedFrom = () => {
 				) }
 			</span>
 			<span id="distributed-data">
-				{ __( 'This post has been unlinked from the ', 'distributor' ) }
+				{ __( 'This post has been unlinked from the', 'distributor' ) }{ ' ' }
 				<a href={ dtGutenberg.postUrl }>
 					{ __( 'Original Content', 'distributor' ) }
 				</a>
@@ -239,12 +239,12 @@ const RenderDistributedFrom = () => {
 					overlayClassName="distributed-modal-overlay"
 				>
 					<span id="distributed-data">
-						{ __( 'Restoring the link to the ', 'distributor' ) }
+						{ __( 'Restoring the link to the', 'distributor' ) }{ ' ' }
 						<a href={ dtGutenberg.postUrl }>
 							{ __( 'Original Content', 'distributor' ) }
-						</a>
+						</a>{ ' ' }
 						{ __(
-							' will start updating this post automatically from the Original, overwriting current content.',
+							'will start updating this post automatically from the Original, overwriting current content.',
 							'distributor'
 						) }
 					</span>

docs/auto-distribution.md

@@ -0,0 +1,69 @@
+You can enable the automatic distribution of posts upon publication by togging on the "auto-distribute" feature.
+
+To enable auto-distribution, you can include this code in your site's feature plugin.
+
+```php
+	add_filter( 'dt_auto_distribution_enabled', '__return_true' );
+```
+
+This code must run prior to or on the `plugins_loaded` hook. If running on the `plugins_loaded` hook, it must do so at priority 19 or lower.
+
+With auto-distribution enabled, the following will occur:
+
+* upon publication, posts and pages will be pushed to all internal and external connections,
+* the default status for pushing posts is `publish`, and,
+* auto distribution is runs via cron jobs to avoid slowing down the publication process for users.
+
+## Filters
+
+The auto-distribution feature comes with a number of filters in additional to the one above.
+
+### Auto-distributed post types
+
+By default only posts and pages are auto-distributed. To enable auto-distribution of custom post
+types requires the `auto_distribute_supported_post_types` filter be used.
+
+To add a custom post type to supported post types would require the code:
+
+```php
+add_filter( 'auto_distribute_supported_post_types', function( $post_types ) {
+	$post_types[] = 'my_cpt';
+	return $post_types;
+} );
+```
+
+### Default post status.
+
+The `dt_auto_distribution_default_status` filter allows you to filter the default post status for
+distribution. To modify the default post status for one post type but not others, you can use the code:
+
+```php
+function ad_demo_modify_page_default_status( $default_status, $post ) {
+	if ( 'page' !== get_post_type() ) {
+		return $default_status;
+	}
+
+	return 'draft';
+}
+add_filter( 'dt_auto_distribution_default_status', 'ad_demo_modify_page_default_status', 10, 2 );
+```
+
+### Whether to auto-distribute a post
+
+The `dt_auto_distribute_post` filter allows you to filter whether an individual post will be
+auto-distributed. The filter accepts a number of arguments providing the context of the post,
+see the [filter's docs](./dt_auto_distribute_post.html) for further information.'
+
+This filter is only run for post types that are supported, see above.
+
+To prevent auto-distribution to a certain connection type:
+
+```php
+function ad_demo_no_external( $should_distribute, $post, $user_id, $connection_type ) {
+	if ( $connection_type === 'external' ) {
+		return false;
+	}
+	return $should_distribute;
+}
+add_filter( 'dt_auto_distribute_post', 'ad_demo_no_external', 10, 4 );
+```

docs/stored-id-handling.md

@@ -40,6 +40,10 @@ This function registers a data piece by providing details about its location and
       - `block_name` (`string`): The block name. **(Required)**
       - `block_attribute` (`string|array`): The attribute(s) containing the data. **(Required)**
 
+  - **`type`** (`string`):
+    Type of data. Accepted values are `'media'`, `'post'`, or `'term'`. If set, the default callbacks will be used.
+    **Note:** If this parameter is used in conjunction with custom callbacks, the custom callbacks will be used instead.
+
   - **`pre_distribute_cb`** (`callable`):
     A callback function that prepares the data on the source site before distribution. It should return extra data that is required for processing on the target site.
 
@@ -56,6 +60,8 @@ Below are several examples demonstrating how to use the `distributor_register_da
 
 In this example, we register an image ID stored in post meta under the key `example_image_id`.
 
+#### With Custom Callback Functions
+
 ```php
 distributor_register_data( 'example_post_meta_data', array(
 	'location'   => 'post_meta',
@@ -105,7 +111,7 @@ distributor_register_data( 'example_post_meta_data', array(
 ) );
 ```
 
-#### Explanation
+**Explanation**
 
 1. **Pre-Distribution Callback (`pre_distribute_cb`):**
    - Retrieves the URL of the image using the stored ID.
@@ -116,10 +122,24 @@ distributor_register_data( 'example_post_meta_data', array(
    - If not found, processes (uploads) the media and updates the relevant post meta with the original source data.
    - Returns the new image ID for the distributed post.
 
+#### Using the `type` Parameter to Utilize the Default Callback
+
+```php
+distributor_register_data( 'example_post_meta_data', array(
+	'location'   => 'post_meta',
+	'attributes' => array(
+		'meta_key' => 'example_image_id',
+	),
+	'type'       => 'media'
+) );
+```
+
 ### 2. Handling Term ID in a Block Attribute
 
 This example demonstrates how to handle a term ID stored in a block attribute.
 
+#### With Custom Callback Functions
+
 ```php
 distributor_register_data(
 	'example_block_data',
@@ -177,10 +197,28 @@ distributor_register_data(
 );
 ```
 
+#### Using the `type` Parameter to Utilize the Default Callback
+
+```php
+distributor_register_data(
+	'example_block_data',
+	array(
+		'location'   => 'post_content',
+		'attributes' => array(
+			'block_name'      => 'example/block-name',
+			'block_attribute' => 'id',
+		),
+		'type'       => 'term'
+	)
+);
+```
+
+
 ### 3. Handling Post ID in a Shortcode Attribute
 
 This example shows how to manage a post ID stored within a shortcode attribute.
 
+#### With Custom Callback Functions
 ```php
 // Distributor data registration for the post ID stored in shortcode attribute.
 distributor_register_data( 'example_post_data', array(
@@ -251,4 +289,17 @@ distributor_register_data( 'example_post_data', array(
 ) );
 ```
 
+#### Using the `type` Parameter to Utilize the Default Callback
+```php
+// Distributor data registration for the post ID stored in shortcode attribute.
+distributor_register_data( 'example_post_data', array(
+	'location'   => 'post_content',
+	'attributes' => array(
+		'shortcode'           => 'extra_shortcode',
+		'shortcode_attribute' => 'example_post_id',
+	),
+	'type'       => 'post'
+) );
+```
+
 If you have any doubts, encounter any different scenarios to handle, or need further assistance, please feel free to report an issue on our [GitHub repository](https://github.com/10up/distributor) and we would be happy to help.

docs/tutorials.json

@@ -14,10 +14,13 @@
 	"snippets": {
 		"title": "Snippets"
 	},
-  "demo-with-playground": {
-    "title": "Demo with Playground"
-  },
-  "stored-id-handling": {
-    "title": "Stored ID Handling"
-  }
+	"demo-with-playground": {
+		"title": "Demo with Playground"
+	},
+	"stored-id-handling": {
+		"title": "Stored ID Handling"
+	},
+	"auto-distribution": {
+		"title": "Enabling Auto Distribution"
+	}
 }