Closes #1285: Add documentation to existing migrate plugins. (#1305)

Co-authored-by: rmarsh1ua <82287338+rmarsh1ua@users.noreply.github.com>
Co-authored-by: Chris Green <chrisgreen@arizona.edu>
Co-authored-by: Kevin Cooper <kevincooper@arizona.edu>

modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsCalloutFieldMerge.php

@@ -7,7 +7,41 @@
 use Drupal\migrate\Row;
 
 /**
- * Process plugin to merge field for callout paragraphs.
+ * Process Plugin to handle Callout Paragraphs from QS1.
+ *
+ * Quickstart 1 to Quickstart2 Process plugin to extract specific field values
+ * from the source, (uaqs_callout paragraphs), and transforming those values
+ * by wrapping them in specific arizona-bootstrap markup.
+ *
+ * NOTE: This plugin is only designed to be used with uaqs_callout source
+ * paragraphs and is not generically reusable for other use cases.
+ *
+ * Expects the source value to contain the following fields:
+ *  - title: A Drupal 7 plain text field array.
+ *  - text: A Drupal 7 text area field array.
+ *  - background: A Drupal 7 field array.
+ *  - border: A Drupal 7 field array.
+ *
+ * Available configuration keys
+ * - N/A
+ *
+ * @code
+ * source:
+ *   plugin: az_paragraphs_item
+ *   bundle: uaqs_callout
+ *
+ * destination:
+ *   plugin: 'entity_reference_revisions:paragraph'
+ *   default_bundle: az_text
+ *
+ * process:
+ *   field_az_text_area/value:
+ *     plugin: paragraphs_callout_field_merge
+ *     title: title_field
+ *     text: field_uaqs_summary
+ *     background: field_uaqs_callout_background
+ *     border: field_uaqs_callout_border_color
+ * @endcode
  *
  * @MigrateProcessPlugin(
  *   id = "paragraphs_callout_field_merge"

modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsChunksViewDisplayMapping.php

@@ -7,7 +7,28 @@
 use Drupal\migrate\Row;
 
 /**
- * Process Plugin to map view and display for Chunks View paragraphs.
+ * Process plugin that maps QS1 view & display names QS2 view & display names.
+ *
+ * Used to map view and display names in uaqs_content_chunks_view Quickstart 1
+ * source paragraphs into view and display names suitable for use
+ * in az_view_reference paragraphs in Quickstart 2.
+ *
+ * Expects a source value which is an associative containing the keys
+ * "vname" and "vargs".
+ *
+ * Available configuration keys
+ * - N/A.
+ *
+ * Examples:
+ *
+ * Consider a paragraph item migration, where you want to preserve the view
+ * display mapping.
+ * @code
+ * process:
+ *   field_az_view_reference:
+ *     plugin: paragraphs_chunks_view_display_mapping
+ *     source: field_uaqs_view
+ * @endcode
  *
  * @MigrateProcessPlugin(
  *   id = "paragraphs_chunks_view_display_mapping"

modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsColumnImageFieldMerge.php

@@ -10,6 +10,38 @@
 /**
  * Process Plugin to field merge for Column Image paragraphs.
  *
+ * NOTE: This plugin is only designed to be used with uaqs_column_image source
+ * paragraphs and is not generically reusable for other use cases.
+ *
+ * Available configuration keys
+ * - caption: The field ID for the source image caption.
+ * - credit: The field ID for the source image credit.
+ * - format: The destination filter format for the migrated text.
+ *
+ * Examples:
+ *
+ * Consider a paragraph item migration, where you want to convert a previously
+ * migrated media entity via migration_lookup, to an embedded media entity
+ * (i.e. <drupal-media>) and place it into a text field that is allowed to use a
+ * text formatter that is configured to process <drupal-media> elements.
+ *
+ * @code
+ * process:
+ *  temp_photo:
+ *    plugin: sub_process
+ *    source: field_uaqs_photo
+ *    process:
+ *      - plugin: migration_lookup
+ *        source: fid
+ *        migration:
+ *          - az_media
+ *  field_az_text_area:
+ *     source: '@temp_photo'
+ *     caption: field_uaqs_caption_text
+ *     credit: field_uaqs_image_credit
+ *     format: 'az_standard'
+ * @endcode
+ *
  * @MigrateProcessPlugin(
  *   id = "paragraphs_column_image_field_merge"
  * )

modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsExtraInfoFieldMerge.php

@@ -7,7 +7,43 @@
 use Drupal\migrate\Row;
 
 /**
- * Process Plugin to field merge for Extra Info paragraphs.
+ * Process Plugin to handle Extra Info Paragraphs from QS1.
+ *
+ * Quickstart 1 to Quickstart 2 process plugin to extract specific field values
+ * from the source, (uaqs_extra_info paragraphs), and transforming those values
+ * by wrapping them in specific arizona-bootstrap markup.
+ *
+ * NOTE: This plugin is only designed to be used with uaqs_extra_info source
+ * paragraphs and is not generically reusable for other use cases.
+ *
+ * Expects the source value to contain the following fields:
+ *  - field_uaqs_short_title: An indexed array of associative arrays with a
+ *    `value` key.
+ *  - field_uaqs_body: An indexed array of associative arrays with a
+ *    `value` key.
+ *  - field_uaqs_link: An indexed array of associative arrays with the following keys:
+ *    - url
+ *    - attributes: An associative array with the following keys:
+ *      - class: Link classes.
+ *      - title: Link title.
+ *
+ * Available configuration keys
+ * - N/A
+ *
+ * @code
+ * source:
+ *   plugin: az_paragraphs_item
+ *   bundle: uaqs_extra_info
+ * destination:
+ *   plugin: 'entity_reference_revisions:paragraph'
+ *   default_bundle: az_text
+ * process:
+ *   field_az_text_area/value:
+ *     plugin: paragraphs_extra_info_field_merge
+ *   field_az_text_area/format:
+ *     plugin: default_value
+ *     default_value: az_standard
+ * @endcode
  *
  * @MigrateProcessPlugin(
  *   id = "paragraphs_extra_info_field_merge"

modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsFWMediaRowFieldMerge.php

@@ -7,7 +7,35 @@
 use Drupal\migrate\Row;
 
 /**
- * Process plugin to merge the fields for Full Width Media Row Paragraph.
+ * Process Plugin to handle Full-Width Media Row Paragraphs from QS1.
+ *
+ * Quickstart 1 to Quickstart 2 Process plugin to extract specific field values
+ * from the source, (uaqs_full_width_media_row paragraphs), and transforming those values
+ * by wrapping them in specific arizona-bootstrap markup.
+ *
+ * NOTE: This plugin is only designed to be used with uaqs_full_width_media_row source
+ * paragraphs and is not generically reusable for other use cases.
+ *
+ * Expects the source value to contain the following fields:
+ *  - body: A Drupal 7 text area field array.
+ *  - link: A Drupal 7 multi-value link field array.
+ *
+ * Available configuration keys
+ * - N/A
+ *
+ * @code
+ * source:
+ *   plugin: az_paragraphs_item
+ *   bundle: uaqs_full_width_media_row
+ * destination:
+ *   plugin: 'entity_reference_revisions:paragraph'
+ *   default_bundle: az_text_media
+ * process:
+ * field_az_text_area/value:
+ *   plugin: paragraphs_fw_media_row_field_merge
+ *   body: field_uaqs_summary
+ *   link: field_uaqs_links
+ * @endcode
  *
  * @MigrateProcessPlugin(
  *   id = "paragraphs_fw_media_row_field_merge"

modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsFileDownloadFieldMerge.php

@@ -8,7 +8,57 @@
 use Drupal\media\Entity\Media;
 
 /**
- * Process Plugin to merge the fields for file download paragraphs.
+ * Process plugin for converting uaqs_file_download paragraphs to az_text.
+ *
+ * NOTE: This plugin is only designed to be used with uaqs_file_download source
+ * paragraphs and is not generically reusable for other use cases.
+ *
+ * Transforms uaqs_file_download paragraph file field values (Quickstart 1) into
+ * embedded media markup (i.e. <drupal-media>) for use within the
+ * field_az_text_area field on az_text paragraph entities (Quickstart 2).
+ *
+ * Expects a source value containing an indexed array with 2 elements:
+ * - Destination file ID for field_uaqs_download_file (obtained through
+ * migration lookup)
+ * - Destination file ID for field_uaqs_download_preview (obtained through
+ * migration lookup)
+ *
+ * Also transforms value of the source field_uaqs_download_name (if not empty)
+ * to an <h3> element that is added to the destination field.
+ *
+ * Examples:
+ * @code
+ * process:
+ *   temp_download_file:
+ *     -
+ *       plugin: sub_process
+ *       source: field_uaqs_download_file
+ *       process:
+ *         -
+ *           plugin: migration_lookup
+ *           source: fid
+ *           migration:
+ *             - az_media
+ *
+ *   temp_download_preview:
+ *     -
+ *       plugin: sub_process
+ *       source: field_uaqs_download_preview
+ *       process:
+ *         -
+ *           plugin: migration_lookup
+ *           source: fid
+ *           migration:
+ *             - az_media
+ *   field_az_text_area/value:
+ *     -
+ *       plugin: merge
+ *       source:
+ *         - '@temp_download_file'
+ *         - '@temp_download_preview'
+ *     -
+ *       plugin: paragraphs_file_download_field_merge
+ * @endcode
  *
  * @MigrateProcessPlugin(
  *   id = "paragraphs_file_download_field_merge"
@@ -27,7 +77,7 @@ public function transform($value, MigrateExecutableInterface $migrate_executable
       $value['markup'] = '<h3>' . $field_uaqs_download_name[0]['value'] . '</h3>';
     }
 
-    // Media embeded for field_uaqs_download_file.
+    // Media embedded for field_uaqs_download_file.
     if (isset($value[0]) && count($value[0])) {
       foreach ($value[0] as $mid) {
         $media = Media::load($mid);
@@ -37,7 +87,7 @@ public function transform($value, MigrateExecutableInterface $migrate_executable
       }
     }
 
-    // Media embeded for field_uaqs_download_preview.
+    // Media embedded for field_uaqs_download_preview.
     if (isset($value[1]) && count($value[1])) {
       foreach ($value[1] as $mid) {
         $media = Media::load($mid);

modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsJumbotronFieldMerge.php

@@ -7,7 +7,35 @@
 use Drupal\migrate\Row;
 
 /**
- * Process plugin to merge the fields for Jumbotron Paragraph.
+ * Process plugin for converting uaqs_jumbotron paragraphs to az_text.
+ *
+ * NOTE: This plugin is only designed to be used with uaqs_jumbotron source
+ * paragraphs and is not generically reusable for other use cases.
+ *
+ * Transforms uaqs_jumbotron paragraph field values (Quickstart 1) into
+ * HTML markup for use within the field_az_text_area field on az_text paragraph
+ * entities (Quickstart 2).
+ *
+ * Expects uaqs_jumbotron source fields to exist as source properties:
+ * - field_uaqs_short_title
+ * - field_uaqs_summary
+ * - field_uaqs_links
+ *
+ * Examples:
+ * @code
+ * source:
+ *   plugin: az_paragraphs_item
+ *   bundle: uaqs_jumbotron
+ * destination:
+ *   plugin: 'entity_reference_revisions:paragraph'
+ *   default_bundle: az_text
+ * process:
+ *   field_az_text_area/value:
+ *     plugin: paragraphs_jumbotron_field_merge
+ *   field_az_text_area/format:
+ *     plugin: default_value
+ *     default_value: az_standard
+ * @endcode
  *
  * @MigrateProcessPlugin(
  *   id = "paragraphs_jumbotron_field_merge"

modules/custom/az_migration/src/Plugin/migrate/process/TextFormatRecognizer.php

@@ -9,7 +9,36 @@
 use Drupal\migrate\Row;
 
 /**
- * Process Plugin to recognize text formats and return a given response.
+ * Process plugin to recognize text formats with configurable response values.
+ *
+ * Available configuration keys
+ * - format: The text format to test compatibility with.
+ * - passed: The value to return if the text format compatibility test passed.
+ * - failed: The value to return if the text format compatibility test failed.
+ * - required_module: The name of a required module. (optional)
+ * - module_missing: The value to return if the required module is missing.
+ *   (optional)
+ *
+ * Examples:
+ *
+ * Consider a paragraphs migration, where you want to be able to automatically
+ * use a specific destination paragraph type with a less permissive text format
+ * ('az_text') if the source field value is compatible with it and fallback to a
+ * destination paragraph type with a more permissive text format ('az_html') if
+ * not. This example also checks that the 'az_paragraphs_html' module exists on
+ * the destination and defaults to the 'az_text' paragraph type if the module is
+ * missing.
+ * @code
+ * process:
+ *   destination_bundle:
+ *     plugin: text_format_recognizer
+ *     source: field_uaqs_html
+ *     format: 'az_standard'
+ *     passed: 'az_text'
+ *     failed: 'az_html'
+ *     required_module: 'az_paragraphs_html'
+ *     module_missing: 'az_text'
+ * @endcode
  *
  * @MigrateProcessPlugin(
  *   id = "text_format_recognizer"

modules/custom/az_migration/src/Plugin/migrate/source/AZFileHandle.php

@@ -72,6 +72,7 @@ public function prepareRow(Row $row) {
     $path = str_replace(['public:/', 'private:/', 'temporary:/'],
     [$this->publicPath, $this->privatePath, $this->temporaryPath],
     $row->getSourceProperty('uri'));
+    // Set the filepath for the source files.
     $row->setSourceProperty('filepath', $path);
 
     return parent::prepareRow($row);