Merge pull request #2810 from WordImpress/issues/2801

feat(email): add email tag meta_*

assets/css/give-admin-rtl.css

@@ -1599,7 +1599,9 @@ table.give-table td.row-title p {
 .form-table td.give-radio-inline fieldset li > label {
   margin: 5px 0 0 !important; }
 
-p.give-field-description, .cmb2-metabox-description {
+p.give-field-description,
+div.give-field-description,
+.cmb2-metabox-description {
   color: #aaaaaa;
   font-style: italic;
   font-size: 13px !important; }

assets/scss/admin/settings.scss

@@ -125,7 +125,9 @@
   margin: 5px 0 0 !important;
 }
 
-p.give-field-description, .cmb2-metabox-description {
+p.give-field-description,
+div.give-field-description,
+.cmb2-metabox-description {
   color: #aaaaaa;
   font-style: italic;
   font-size: 13px !important;

includes/admin/class-admin-settings.php

@@ -860,7 +860,7 @@ public static function get_field_description( $value ) {
 			$value           = ( isset( $value[ $description_key ] ) && ! empty( $value[ $description_key ] ) ) ? $value[ $description_key ] : '';
 
 			if ( ! empty( $value ) ) {
-				$description = '<p class="give-field-description">' . wp_kses_post( $value ) . '</p>';
+				$description = '<div class="give-field-description">' . wp_kses_post( $value ) . '</div>';
 			}
 
 			return $description;

includes/admin/emails/abstract-email-notification.php

@@ -578,13 +578,13 @@ public function get_allowed_email_tags( $formatted = false ) {
 			}
 
 			if ( count( $email_tags ) && $formatted ) : ob_start() ?>
-				<div class="give-email-tags-wrap">
+				<ul class="give-email-tags-wrap">
 					<?php foreach ( $email_tags as $email_tag ) : ?>
-						<span class="give_<?php echo $email_tag['tag']; ?>_tag">
+						<li class="give_<?php echo $email_tag['tag']; ?>_tag">
 							<code>{<?php echo $email_tag['tag']; ?>}</code> - <?php echo $email_tag['description']; ?>
-						</span>
+						</li>
 					<?php endforeach; ?>
-				</div>
+				</ul>
 				<?php
 				$email_tags = ob_get_clean();
 			endif;

includes/admin/emails/class-email-setting-field.php

@@ -232,8 +232,16 @@ public static function get_email_message_field( Give_Email_Notification $email,
 
 		if ( $email_tag_list = $email->get_allowed_email_tags( true ) ) {
 			$desc = sprintf(
-				esc_html__( 'The email that is sent to users after completing a successful donation. HTML is accepted. Available template tags: %s', 'give' ),
-				$email_tag_list
+				'%1$s <br> %2$s: %3$s %4$s',
+				__( 'The email that is sent to users after completing a successful donation. HTML is accepted.', 'give' ),
+				__( 'Available template tags', 'give' ),
+				$email_tag_list,
+				sprintf(
+					'<br><a href="%1$s">%2$s</a> %3$s',
+					esc_url('http://docs.givewp.com/meta-email-tags'),
+					__( 'See our documentation', 'give' ),
+					__( 'for examples of how to use custom meta email tags to output additional donor or donation information in your Give emails.', 'give' )
+				)
 			);
 
 		}

includes/emails/class-give-email-tags.php

@@ -1373,4 +1373,111 @@ function give_get_reset_password_url( $user_id ) {
 	}
 
 	return $reset_password_url;
-}
+}
+
+
+/**
+ * This function helps to render meta data with from dynamic meta data email tag.
+ * Note: meta data email tag must be in given format {meta_*}
+ *
+ * @since 2.0.3
+ * @see https://github.com/WordImpress/Give/issues/2801#issuecomment-365136602
+ *
+ * @param $content
+ * @param $tag_args
+ *
+ * @return mixed
+ */
+function __give_render_metadata_email_tag( $content, $tag_args ) {
+	preg_match_all( "/{meta_([A-z0-9\-\_\ ]+)}/s", $content, $matches );
+
+	if ( ! empty( $matches[0] ) ) {
+		$search = $replace = array();
+		foreach ( $matches[0] as $index => $meta_tag ) {
+			if ( in_array( $meta_tag, $search ) ) {
+				continue;
+			}
+
+			$search[] = $meta_tag;
+
+			$meta_tag     = str_replace( array( '{', 'meta_', '}' ), '', $meta_tag );
+			$meta_tag_arr = array_map( 'trim', explode( ' ', $meta_tag, 2 ) );
+			$meta_tag     = current( $meta_tag_arr );
+
+			$meta_tag  = str_replace( array( '{', 'meta_', '}' ), '', $meta_tag );
+			$type      = current( explode( '_', $meta_tag, 2 ) );
+			$meta_name = preg_replace( "/^{$type}_/", '', $meta_tag );
+
+			switch ( $type ) {
+				case 'donation':
+
+					//Bailout.
+					if ( ! isset( $tag_args['payment_id'] ) ) {
+						$replace[] = '';
+						continue;
+					}
+
+					$meta_data = give_get_meta( absint( $tag_args['payment_id'] ), $meta_name, true, '' );
+
+					if ( ! isset( $meta_tag_arr[1] ) || ! is_array( $meta_data ) ) {
+						$replace[] = $meta_data;
+					} elseif ( in_array( $meta_tag_arr[1], array_keys( $meta_data ) ) ) {
+						$replace[] = $meta_data[ $meta_tag_arr[1] ];
+					}
+
+					break;
+
+				case 'form':
+					$form_id = isset( $tag_args['form_id'] ) ? absint( $tag_args['form_id'] ) : 0;
+
+					// Bailout.
+					if ( ! $form_id && isset( $tag_args['payment_id'] ) ) {
+						$form_id = give_get_payment_form_id( $tag_args['payment_id'] );
+					}
+
+					$meta_data = give_get_meta( $form_id, $meta_name, true, '' );
+					if ( ! isset( $meta_tag_arr[1] ) || ! is_array( $meta_data ) ) {
+						$replace[] = $meta_data;
+					} elseif ( in_array( $meta_tag_arr[1], array_keys( $meta_data ) ) ) {
+						$replace[] = $meta_data[ $meta_tag_arr[1] ];
+					}
+					break;
+
+				case 'donor':
+					$donor_id = isset( $tag_args['donor_id'] ) ? absint( $tag_args['donor_id'] ) : 0;
+
+					// Bailout.
+					if ( ! $donor_id ) {
+						if ( isset( $tag_args['payment_id'] ) ) {
+							$donor_id = give_get_payment_donor_id( $tag_args['payment_id'] );
+						} elseif ( isset( $tag_args['user_id'] ) ) {
+							$donor    = new Give_Donor( $tag_args['user_id'], true );
+							$donor_id = $donor->ID;
+						}
+					}
+
+					$donor     = new Give_Donor( $donor_id );
+					$meta_data = $donor->get_meta( $meta_name );
+					if ( ! isset( $meta_tag_arr[1] ) || ! is_array( $meta_data ) ) {
+						$replace[] = $meta_data;
+					} elseif ( in_array( $meta_tag_arr[1], array_keys(  $meta_data ) ) ) {
+						$replace[] = $meta_data[ $meta_tag_arr[1] ];
+					}
+
+					break;
+
+				default:
+					$replace[] = end( $search );
+			}
+		}
+
+		if ( ! empty( $search ) && ! empty( $replace ) ) {
+			$content = str_replace( $search, $replace, $content );
+		}
+	}
+
+
+	return $content;
+}
+
+add_filter( 'give_email_template_tags', '__give_render_metadata_email_tag', 10, 2 );