From c0da7026409b501b99466dc0f73f20ab6f213887 Mon Sep 17 00:00:00 2001 From: Joe Parsons <471936+joeparsons@users.noreply.github.com> Date: Fri, 1 Apr 2022 11:02:31 -0700 Subject: [PATCH] Closes #1285: Add documentation to existing migrate plugins. (#1305) Co-authored-by: rmarsh1ua <82287338+rmarsh1ua@users.noreply.github.com> Co-authored-by: Chris Green Co-authored-by: Kevin Cooper --- .../process/ParagraphsCalloutFieldMerge.php | 36 +++++++++++- .../ParagraphsChunksViewDisplayMapping.php | 23 +++++++- .../ParagraphsColumnImageFieldMerge.php | 32 +++++++++++ .../process/ParagraphsExtraInfoFieldMerge.php | 38 ++++++++++++- .../ParagraphsFWMediaRowFieldMerge.php | 30 +++++++++- .../ParagraphsFileDownloadFieldMerge.php | 56 ++++++++++++++++++- .../process/ParagraphsJumbotronFieldMerge.php | 30 +++++++++- .../migrate/process/TextFormatRecognizer.php | 31 +++++++++- .../Plugin/migrate/source/AZFileHandle.php | 1 + 9 files changed, 268 insertions(+), 9 deletions(-) diff --git a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsCalloutFieldMerge.php b/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsCalloutFieldMerge.php index d66557ff6b..e3e76e3415 100644 --- a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsCalloutFieldMerge.php +++ b/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" diff --git a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsChunksViewDisplayMapping.php b/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsChunksViewDisplayMapping.php index 7a40be52f1..20579dcc88 100644 --- a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsChunksViewDisplayMapping.php +++ b/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" diff --git a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsColumnImageFieldMerge.php b/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsColumnImageFieldMerge.php index 44e7b23d64..a11f7a9f58 100644 --- a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsColumnImageFieldMerge.php +++ b/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. ) and place it into a text field that is allowed to use a + * text formatter that is configured to process 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" * ) diff --git a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsExtraInfoFieldMerge.php b/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsExtraInfoFieldMerge.php index 39f785d9f5..841bbb6f2b 100644 --- a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsExtraInfoFieldMerge.php +++ b/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" diff --git a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsFWMediaRowFieldMerge.php b/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsFWMediaRowFieldMerge.php index 4f44c22dd5..9b1e07ba49 100644 --- a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsFWMediaRowFieldMerge.php +++ b/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" diff --git a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsFileDownloadFieldMerge.php b/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsFileDownloadFieldMerge.php index 30c5c1dd2b..4e7b64b669 100644 --- a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsFileDownloadFieldMerge.php +++ b/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. ) 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

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'] = '

' . $field_uaqs_download_name[0]['value'] . '

'; } - // 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); diff --git a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsJumbotronFieldMerge.php b/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsJumbotronFieldMerge.php index d26d216251..cfb41b0055 100644 --- a/modules/custom/az_migration/src/Plugin/migrate/process/ParagraphsJumbotronFieldMerge.php +++ b/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" diff --git a/modules/custom/az_migration/src/Plugin/migrate/process/TextFormatRecognizer.php b/modules/custom/az_migration/src/Plugin/migrate/process/TextFormatRecognizer.php index 869a04001c..739e1ccc75 100644 --- a/modules/custom/az_migration/src/Plugin/migrate/process/TextFormatRecognizer.php +++ b/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" diff --git a/modules/custom/az_migration/src/Plugin/migrate/source/AZFileHandle.php b/modules/custom/az_migration/src/Plugin/migrate/source/AZFileHandle.php index f58abbb0d3..2e4de20d72 100644 --- a/modules/custom/az_migration/src/Plugin/migrate/source/AZFileHandle.php +++ b/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);