Magento_GiftRegistry

Magento Modules:

• Magento_GiftRegistry
• Magento_GiftRegistryGraphQl

Only Magento_GiftRegistry contains storefront affecting logic/output.

Adobe Commerce Packages

• magento/module-gift-registry
• magento/module-gift-registry-graph-ql

Repository

Note: this repo is only accessible with a Hyvä Enterprise license or as a contributor.

For more details, see: https://www.hyva.io/hyva-enterprise.html.

https://gitlab.hyva.io/hyva-enterprise/commerce/magento2-ee-magento-gift-registry

Overview

For details on this functionality from an admin/customer perspective, see Adobe's documentation.

Features

All points are rated according to priority as P1 (critical), P2 (important), P3 (minor).

• basic - does not break layout/design

Note: this issue is for features related to the main Hyvä Theme only. See #115 for details on Hyvä Checkout compatibility. All checkout features are also supported using the fallback Luma checkout.

Note: All below features assume output only if gift registry is enabled in Stores > Configuration: magento_giftregistry/general/enabled.

Account Area: All Pages

• [P1] Add 'Gift Registry' link to the account area navigation menu that links to the index page (/giftregistry/)

Account Area: Gift Registry Index (/giftregistry/)

Dev Note: please use consistent table markup/approach as per other Enterprise modules (e.g. see B2B grid pages)

• [P1] Output 'Gift Registry' page title
• [P1] Output all existing Gift Registry entities
  • In a table with 'Event' (name), 'Created On' (date) and 'Message' columns (plus actions)
  • Enhancement suggestion: add 'Type', 'Privacy' and 'Event Date' (if set) columns
• [P1] Existing gift registry actions
  • [P1] 'Manage Items' - links to manage items page (/giftregistry/index/items/id/{id}/)
  • [P1] 'Share' - links to share page (/giftregistry/index/share/id/{id}/)
  • [P1] 'Edit' - links to edit page (/giftregistry/index/edit/)
  • [P1] 'Delete' - triggers 'are you sure' confirmation dialog (modal)
• [P2] Pagination and limiter work as expected (need 10+ registries)
• [P1] Output 'Add New' (Gift Registry) button that links to create page (/giftregistry/index/addselect/)

Account Area: Gift Registry Create (/giftregistry/index/addselect/)

• [P3] Ensure 'Gift Registry' account navigation link remains highlighted
• [P1] Output 'Create Gift Registry' page title
• [P1] Output 'Gift Registry Type' (type_id) dropdown select with the following options:
  • 'Birthday', 'Baby Registry', 'Wedding' (defaults unless renamed) or custom type (created/managed in admin panel).
• [P1] Form Validation: 'Gift Registry Type' (type_id) field is required
• [P1] Output 'Next' submit button
• [P1] Form submits successfully (assuming no validation/further errors) and redirects to the add/edit page (/giftregistry/index/edit/)

Account Area: Gift Registry Add/Edit (/giftregistry/index/edit/ / /giftregistry/index/edit/entity_id/{entity_id}/)

• [P3] Ensure 'Gift Registry' account navigation link remains highlighted
• [P1] Output relevant page title dependent upon whether a new or existing gift registry
  • 'Create Gift Registry' or 'Edit Gift Registry'
• [P1] Output the Gift Registry 'Type' selected on the initial page
  • e.g., 'Birthday', 'Baby Registry', 'Wedding' (defaults unless renamed) or custom type (created/managed in admin panel).

Form - Fieldset - General Information - Default Fields

• [P1] Output 'Event' text field
  • Required: Yes
• [P1] Output 'Message' textarea
  • Required: Yes
• [P1] Output 'Privacy Settings' dropdown select
  • Required: Yes
  • Options: 'Private', 'Public'
• [P1] Output 'Status' dropdown select
  • Required: Yes
  • Options: 'Inactive' (default selection), 'Active'

Form - Fieldset - Registrant Information - Default Fields

• [P1] Output 'First Name' field (input type: text, required: yes)
• [P1] Output 'Last Name' field (input type: text, required: yes)
• [P1] Output 'Email' field (input type: email, required: yes)
• [P1] Output 'Add Registrant' button
  • Adds another set of registrant fields
• [P1] Output 'Remove' link
  • Removes adjacent set of registrant fields
  • Only displayed on additional sets of registrant fields (i.e. not the first set)

Form - Fieldset - Shipping Address - Default Fields

• [P1] Output Select address dropdown select
  • Required: Yes (Luma = No, see bug details below)
  • Options: 'None' + all addresses from address book + 'New Address'
  • Enhancement/bugfix - selecting 'None' causes form submission to error, so force selection of an address (i.e. make it required)
• [P1] Output new address fields (only displayed when 'New Address' selected above)
  • Renders standard address fields based on configuration
  • 'Prefix' and 'Suffix' only display if enabled on storefront
  • 'Phone Number', 'Company' and 'Fax' are always displayed, regardless of config/EAV settings
  • 'Phone Number' is always required, and 'Company' and 'Fax' are always optional, regardless of config/EAV settings
  • User defined 'Customer Custom Attributes' are not supported and never included/output
  • The region field updates or is hidden based on the country and configuration (the same logic as per the default address form)

Note: once saved and edited the select address field will have 'New Address' selected with the previous address details output in the address fields, regardless of whether a new or saved address was used.

Form - Submit

• [P1] Output 'Save' submit button
• [P1] Form submits successfully (assuming no validation/further errors) and returns user to index page (/giftregistry/) where the new registry can be seen in the list

The below is not a feature, but a bugfix for an issue also present in Luma

• [P2] Bugfix: 'Undefined array key' error for region / region_id in \Magento\GiftRegistry\Controller\Index\EditPost::mapAddressInfo()
  • This is caused when the shipping address if for a country that does not have a region ID
  • This occurs regardless of whether the configuration for 'Allow to Choose State if It is Optional for Country' (general/region/display_all) is set to 'Yes' or 'No'.

Dev note: a before plugin on the controller to create the required array keys (with null values) may be a simple way to resolve without having to refactor and replace/take ownership of the entire controller class.

Temporary development fix - in the mapAddressInfo() method replace:

$addressData['address_data']['region'] = [
    'region_id' => $data['address']['region_id'],
    'region' => $data['address']['region']
];

with:

$region = $data['address']['region'] ?? null;
$regionId = $data['address']['region_id'] ?? null;

$addressData['address_data']['region'] = [
    'region_id' => $regionId,
    'region' => $region
];

Form Custom Fields / Fieldsets

Each registry type can have custom fields added to a selection of predefined fieldsets (or 'attribute groups': 'Event Information', 'Gift Registry Details', 'Privacy Settings', 'Registrant Information' and 'Shipping Address').

Fields are configured from the admin panel under 'Stores > Gift Registry'. This checklist outlines each custom field by input type.

• [P2] All attributes are output in the correct order within each fieldset based on their own and adjacent attributes sort order
  • Custom fields are always output after the default fields in their fieldset

Custom (Standard) Field Types

Text

• [P1] Correct attribute code is output in HTML
• [P1] Correct label is output for the current store view
• [P1] Attribute is output in the correct group (fieldset)
• [P1] Attribute is correctly marked as required (or not)

Select

• [P1] Correct attribute code is output in HTML
• [P1] Correct label is output for the current store view
• [P1] Attribute is output in the correct group (fieldset)
• [P1] Attribute is correctly marked as required (or not)
• [P1] Select options are output correctly
  • All options display with correct labels (for the current store view), sort order and the default option is selected (if set)

Date

• [P1] Correct attribute code is output in HTML
• [P1] Correct label is output for the current store view
• [P1] Attribute is output in the correct group (fieldset)
• [P1] Attribute is correctly marked as required (or not)
• [P3] Date format (text output in field) matches configuration (short/medium/long/full)
  • This will not be supported as we will utilize the native browser date picker
• [P1] Date format is stored and output correctly based on locale*
  • *As with other Hyvä products, the locale can be the browser locale, not Magento's

Country

• [P1] Correct attribute code is output in HTML
• [P1] Correct label is output for the current store view
• [P1] Attribute is output in the correct group (fieldset)
• [P1] Attribute is correctly marked as required (or not)
• [P1] Select options are output correctly
  • i.e. all countries included in the directory
• [P1] Region is displayed according to configuration
• [P1] Region is not required if a country that does not have stored regions in the directory is selected and is also hidden if the configuration for 'Allow to Choose State if It is Optional for Country' (general/region/display_all) is set to 'No'.

Static (Registry Specific) Field Types

Event Date

• [P1] Correct attribute code is output in HTML
  • Note: this is always event_date as only 1 of this field type can be added to a registry
• [P1] Correct label is output for the current store view
• [P1] Attribute is output in the correct group (fieldset)
  • Note: this is always 'Event Information' for this field type
• [P1] Attribute is correctly marked as required (or not)
• [P3] Date format (text output in field) matches configuration (short/medium/long/full)
  • This will not be supported as we will utilize the native browser date picker
• [P1] Date format is stored and output correctly based on locale*
  • *As with other Hyvä products, the locale can be the browser locale, not Magento's

Event Country

• [P1] Correct attribute code is output in HTML
  • Note: this is always event_country as only 1 of this field type can be added to a registry
• [P1] Correct label is output for the current store view
• [P1] Attribute is output in the correct group (fieldset)
  • Note: this is always 'Event Information' for this field type
• [P1] Attribute is correctly marked as required (or not)
• [P1] Select options are output correctly
  • i.e. all countries included in the directory
• [P1] Region is displayed according to configuration
• [P1] Region is not required if a country that does not have stored regions in the directory is selected and is also hidden if the configuration for 'Allow to Choose State if It is Optional for Country' (general/region/display_all) is set to 'No'.

Event Location

• [P1] Correct attribute code is output in HTML
  • Note: this is always event_location as only 1 of this field type can be added to a registry
• [P1] Correct label is output for the current store view
• [P1] Attribute is output in the correct group (fieldset)
  • Note: this is always 'Event Information' for this field type
• [P1] Attribute is correctly marked as required (or not)

Role

• [P1] Correct attribute code is output in HTML
  • Note: this is always role as only 1 of this field type can be added to a registry
• [P1] Correct label is output for the current store view
• [P1] Attribute is output in the correct group (fieldset)
  • Note: this is always 'Registrant Information' for this field type
• [P1] Attribute is correctly marked as required (or not)
• [P1] Select options are output correctly
  • All options display with correct labels (for the current store view), sort order and the default option is selected (if set)

Default Custom Fields / Fieldsets

The below are output for completeness and testing. It is appreciated they can be altered in configuration and will not be present on the majority of real-world implementations.

All Default Registry Types

• [P2] 'Country' (input type: event country)
  • Fieldset: Event Information
  • Required: Yes
  • Show Region: Yes

Birthday

• [P2] 'Event Date' field (input type: event date)
  • Fieldset: Event Information
  • Required: Yes
  • Date Format: Short

Baby Registry

• [P2] 'Baby Gender' field (input type: select)
  • Fieldset: Gift Registry Details
  • Required: Yes
  • Options: 'Surprise', 'Boy', 'Girl'
• [P2] 'Role' field (input type: role)
  • Fieldset: Registrant Information
  • Required: Yes
  • Options: 'Mother', 'Father'

Wedding

• [P2] 'Wedding Date' field (input type: event date)
  • Fieldset: Event Information
  • Required: Yes
  • Date Format: Short
• [P2] 'Location' field (input type: event location)
  • Fieldset: Event Information
  • Required: Yes
• [P2] 'Number of Guests' field (input type: text)
  • Fieldset: Event Information
  • Required: Yes
• [P2] 'Role' field (input type: role)
  • Fieldset: Registrant Information
  • Required: Yes
  • Options: 'Bride', 'Groom', 'Partner'

Account Area: Gift Registry Manage Items (/giftregistry/index/items/id/{id}/)

Dev Note: please use consistent table markup/approach as per other Enterprise modules (e.g. see B2B grid pages)

• [P3] Ensure 'Gift Registry' account navigation link remains highlighted
• [P1] Output 'Gift Registry Items' page title
• [P1] Output all products in a table with the following columns/data
  • Product image and name (both link to product page), note (textarea input), added on date, qty input, qty fulfilled amount, delete checkbox
• [P2] Output product options under the name/link (e.g. configurable/bundle/custom options)
• [P1] Output 'Update Gift Registry' submit button
• [P1] Ensure each items notes and qty values update correctly on form submission
• [P1] Ensure items are removed on form submission when delete checkbox is selected

Note: this product list table has no pagination/limiter support

Account Area: Gift Registry Share (/giftregistry/index/share/id/{id}/)

• [P3] Ensure 'Gift Registry' account navigation link remains highlighted
• [P1] Output 'Share Gift Registry' page title
• [P2] Output 'Share '{registry name}' Gift Registry' subtitle
• [P1] Output 'Sender' fieldset
• [P1] Output 'Name' field to 'Sender' fieldset
  • Type: text
  • Required: Yes
• [P1] Output 'Message' field to 'Sender' fieldset
  • Type: textarea
  • Required: Yes
• [P1] Output 'Invitee' fieldset
• [P1] Output 'First Name' field to 'Invitee' fieldset
  • Type: text
  • Required: Yes
• [P1] Output 'Email' field to 'Invitee' fieldset
  • Type: email
  • Required: Yes
• [P1] Output 'Add Invitee' button
  • Removes new 'First Name/Email' field group row underneath last existing group
• [P2] Output 'Remove' link alongside each 'First Name/Email' field group row
  • Removes adjacent field group row
  • Does not display against first field group row
• [P1] Output 'Share Gift Registry' submit button
• [P1] Form submits successfully (assuming no validation/further errors), triggers email to listed invitees and returns user to index page (/giftregistry/)

Account Area: Order View (/sales/order/view/order_id/{id}/)

The below is not a feature, but a bugfix for an issue also present in Luma

• [P2] Bugfix: fatal error when shipping address is gift registry recipients address
  • Because the address output is replaced with 'Ship to Recipient Address' an error is thrown as this is an instance of \Magento\Framework\Phrase\ and not a string, which is what Magento\Framework\Filter\FilterManager::template() expects (it expects an address template)

Dev note: an after plugin on \Magento\Customer\Block\Address\Renderer\DefaultRenderer::getFormatArray() to cast the return value as a string (if it is an instance \Magento\Framework\Phrase) would likely resolve the issue, but needs further consideration and testing.

Gift Registry Info (/giftregistry/view/index/id/{hash}/)

• [P1] Output 'Share Gift Registry' page title
• [P1] Output all default and 'listed' attributes
  • 'static type' attributes should only display if 'Is Listed' is set to 'Yes' for the attribute in the registry type configuration in the admin panel
  • If there are multiple registrants they should be output comma separated (same applies for 'role' where applicable)
• [P1] Output 'Gift Registry Items' heading
• [P1] Output all products in a table with the following columns/data
  • Product image and name (both link to product page), requested (qty), fulfilled (qty), remaining (qty), unit price (inc. sale/regular price where relevant), qty input
• [P1] Output 'Add to cart' submit button
• [P1] Ensure the correct products and qty's are added to cart on form submission, along with the user being redirected to the cart part (/checkout/cart/)
  • Qty added should not exceed the qty requested. This should be adjusted on submission and outlined in a global message once redirected to the cart page.

Note: this product list table has no pagination/limiter support

Cart Page (/checkout/cart/)

Add Cart Items to Gift Registry Form

The below is only applicable for logged in customers that have one or move active gift registries.

• [P1] Output a list of the current customers' active Gift Registries
  • As a dropdown (select)
  • Field should be required
• [P1] Output 'Add All To Gift Registry' submit button
• [P1] Form submits successfully (assuming no validation/further errors) and adds all* current cart items to the selected registry with the correct qty
  • *excluding virtual, digital (downloadable) and gift card products

Mark Items In Cart Added From Gift Registry

• [P1] Output 'Gift Registry: {registry_name}' text and link on applicable line items in the cart
  • The registry_name is the name of Gift Registry and links to the info page (/giftregistry/view/index/id/{hash}/)

Checkout Review Page (/checkout/onepage/review/)

Mark Items In Order Added From Gift Registry

• [P1] Output 'Gift Registry: {registry_name}' text and link on applicable line items in the order
  • The registry_name is the name of Gift Registry and links to the info page (/giftregistry/view/index/id/{hash}/)

Wishlist (/wishlist/)

Add Wishlist Item to Gift Registry Form

For each product in the wishlist:

• [P1] Output an 'Add to Gift Registry' toggle that opens with a list of the current customers' active Gift Registries

• [P2] Toggle should only be added for allowed product types (not virtual, digital (downloadable) or gift cards)

• [P1] Selecting a Gift Registry from the list adds the product to that registry and redirects to the customer to the 'Gift Registry Manage Items' page (/giftregistry/index/items/id/{id}/)

• [P2] If the product has required options that are not set the customer is redirected to the product page to select them (/catalog/product/view/id/{id}/?options=giftregistry&entity={gift_registry_id})

• [P2] Output Tasks TBC (add to gift registry dropdown select)

Product Page - Options Select (/catalog/product/view/id/{id}/)

Note: these modifications only apply when a product in the wish list does not have all the required options and they need selecting before it can be added to the chosen gift registry. This mode can also be triggered via appending ?options=giftregistry&entity={gift_registry_id} to the URL of a product page, where gift_registry_id is the ID of the gift registry the product should be added to.

• [P2] The 'Add to Cart' button is replaced with 'Add to Gift Registry'
• [P2] Standard 'add to cart' form validation should continue to work (e.g. selecting required options)
• [P2] Form submits successfully (assuming no validation/further errors), adding the product to the correct gift registry with the selected options/qty and redirects the user to 'Gift Registry Manage Items' page (/giftregistry/index/items/id/{id}/)

Bundle Products

In addition to the above, bundle products also have one additional modification:

• [P2] The 'Customize and Add to Cart' button text is replaced with 'Customize and Add to Gift Registry'

Gift Registry Search (/giftregistry/search/)

• [P2] Output 'Gift Registry Search' page title
• [P2] Output 'Search Options' heading

Search By Name/Type

• [P2] Output 'Gift Registry Type' dropdown select and comment text
  • Required: No
  • Options: '-- All --', 'Birthday', 'Baby Registry', 'Wedding' (defaults unless renamed) or custom type (created/managed in admin panel).
  • Only displays types where 'Is Listed' is set to 'Yes' in admin configuration
• [P2] If a 'Gift Registry Type' selection is made, load and output fields for each of the registry types attributes
  • Only display static type attributes that have 'Is Searchable' set to 'Yes' in admin configuration
• [P2] Output 'First Name' text field
  • Required: Yes
• [P2] Output 'Last Name' text field
  • Required: Yes
• [P2] Output 'Search' submit button
• [P2] Form submits successfully (assuming no validation/further errors) and directs to results page (/giftregistry/search/results/)

Search By Email

• [P2] Output 'Registrant Email' email field
  • Required: Yes
• [P2] Output 'Search' submit button
• [P2] Form submits successfully (assuming no validation/further errors) and directs to results page (/giftregistry/search/results/)

Search By ID

Note: in this instance, ID refers to the hash value for the registry, not the entity ID.

• [P2] Output 'Gift Registry ID' text field
  • Required: Yes
• [P2] Output 'Search' submit button
• [P2] Form submits successfully (assuming no validation/further errors) and directs to results page (/giftregistry/search/results/)

Gift Registry Search Results (/giftregistry/search/results/)

• [P2] Output the same page title and sections/fields as the search page above
• [P2] Prefill the values of the fields filled from the search page
• [P2] Output 'Search Results' heading below

If results are found

• [P2] Output the search results in a table with the following data
  • Name (user), Location*, Event (name), Type, Event Date*
• [P2] Output actions column for each row with 'View' link that directs to the registries info page (/giftregistry/view/index/id/{hash}/)
• [P3] Pagination and limiter work as expected (need 10+ results)

If no results are found

• [P2] Output an error message 'Your search returned no results.'

Gift Registry Search Widget

As with all widgets, it can be placed (almost) anywhere on site and can be created/managed from 'Content > Widgets' or inserted into an WYSIWYG editor (e.g. in a CMS Page/Block)

• [P3] Output 'Gift Registry Search' heading

If more than one search type (name/email/ID) has been configured for the widget

• [P3] Output 'Search By' dropdown select
  • Required: 'Yes'
  • (potential) options: 'Registrant Name Search', 'Registrant Email Search', 'Gift Registry ID Search'
• [P3] Only output options that have been selected
  • This can be multiple option selections in the widget configuration, or the 'All Forms' option
• [P3] Once a selection is made, display the relevant fields for the search type chosen (see fields for each type below)

If only one search type (name/email/ID) has been configured for the widget

• [P3] Output the fields for the single search type (see fields for each type below)

Search By Name/Type

• [P3] Output 'First Name' text field
  • Required: Yes
• [P3] Output 'Last Name' text field
  • Required: Yes
• [P3] Output 'Gift Registry Type' dropdown select
  • Required: No
  • Options: '-- All --', 'Birthday', 'Baby Registry', 'Wedding' (defaults unless renamed) or custom type (created/managed in admin panel).
  • Only displays types where 'Is Listed' is set to 'Yes' in admin configuration
  • Unlike the main search page, type specific fields are not loaded when making a selection
• [P3] Output 'Search' submit button
• [P3] Form submits successfully (assuming no validation/further errors) and directs to results page (/giftregistry/search/results/)

Search By Email

• [P3] Output 'Registrant Email' email field
  • Required: Yes
• [P3] Output 'Search' submit button
• [P3] Form submits successfully (assuming no validation/further errors) and directs to results page (/giftregistry/search/results/)

Search By ID

Note: in this instance, ID refers to the hash value for the registry, not the entity ID.

• [P3] Output 'Gift Registry ID' text field
  • Required: Yes
• [P3] Output 'Search' submit button
• [P3] Form submits successfully (assuming no validation/further errors) and directs to results page (/giftregistry/search/results/)

Contributors

Voting

Use 👍 to cast your vote.