Web Pattern Library:

Personalization Migration Guide

A guide to modifying the existing PDP templates from the full monogram dialog present in tag-60 to the new slide-out personalization panel in tag-61 and newer.

Overview of changes

We've moved to a system where personalization options for the logo, whale, and monogram are all in one PDP and can be previewed and refined before adding the customized product to the bag. Previously, users could add one personalization at a time by opening a logo, whale, or monogram dialog; adding a second personalization or changing its placement (i.e., from sleeve to chest) required opening separate or chained dialogs.

Personalization PDP with new features

New features

Interactive, live preview of personalization overlaid on the product image. A "Customize" slide in the product images carousel displays a lay down product image with selected (or included) customizations previewed in the desired style and placement. This slide is last in the carousel when personalization is optional, first in the carousel when personalizaiton is included (like with sports team logos).

Adding/editing a personalization happens in the panel, which appears as an overlay on small screens, and as a sliding side panel on desktop. In the code, the panel content comes from up to 3 different forms, one for each aviailable personalization.

Users can customize a product in 3 ways. The following links/buttons open the panel with placement, color, and style options for the selected personalization (monogram, whale, or logo):

• "Customize it" text links in the top right corner of the product image.
• "Hotspot" links overlaid on the preview product image in areas that can be customized, for example, the left chest or right sleeve. Each hotspot link opens a small menu with options for adding, editing, or moving a personalization to that spot.
• Personalization buttons under the product's size and color options. They can be in one of 2 states: "add" for optional personalizations (i.e., monogram), and "edit" for personalizations that are automatically included (i.e., MLB logo).

Selected placements are dynamically updated. When personalizations share a placement value (e.g., if both logo and monogram could be on the left chest), adding a personalization to that placement updates the toggle to an "occupied" state (grayed out with a line).

Monograms can be initials or names. Business rules determine when users can enter either intials or name, or toggle between them.

Markup changes

• All markup for the personalization panel is in the page source. AJAX for bringing in different dialogs is no longer in use, nor is chaining dialogs when adding multiple personalizations.
• Attributes in personalization form field markup contain default options/values for that product, which are used to dynamically build the hotspot links (based on placement options), hotspot menu options, and personalization buttons states (add vs edit).
• Monograms use web fonts, not SVGs.

JavaScript files

We've built the new functionality on top of the old so that we could take advantage of existing conventions (like tracking placements). The scripts that control the personalization functions are:

• personalizable-pdp.js - functions for the PDP
• personalize-panel.js - functions for the panel
• personalize.js - original code

Step 1: Add interactive preview slide

The preview slide is just like any other slide in the product carousel, with 2 exceptions: it must be a lay down image of the product, and its navigation thumbnail is always the standard "Customize" icon:

Placement, type, and style values specified in the panel form markup are used to dynamically build and update hotspot links overlaid on the main product image.

Step 2: Add text links to the preview

This links block should be the first child in the pdetail_imgs container, immediately before the snapper carousel.

Note that pricing information is either in the title or individual links depending on whether the personalizations are included or optional.

Step 3: New personalization button markup

Personalize buttons are located under the product's size and style options, and have 2 states: one to add a customization, and one to edit. The personalization JavaScript will take values from the panel form markup and use them to populate and update these buttons with the correct icon and text as the user interacts with the form — all you need to include is the following simple button markup inside the pdetail_personalize container, and only include the button markup needed for that product's possible customizations.

Configure buttons

Each button needs to reference the panel for that customization's form and the type of personalization/link:

• href - reference the relevant panel's ID attribute (as you would for a basic dialog)
• data-personalizable-link - use one of these values: logo, whale, or monogram

Static examples of the personalization buttons are listed on the monogram & logo buttons page.

Remove deprecated button code

Previously, these buttons loaded personalization dialog content using an AJAX request. The data attributes for that functionality may interfere with the new set up, so the following should be removed:

• data-dialog-link
• data-dialog-addclass="personalize-dialog quickview-dialog"

Step 4: Add new panel markup to the PDP template

From the user's point of view, they interact with a seamless form that updates to show the correct personalization fields and data. In the code, this "single" panel is actually made up of several panel dialogs that appear in the same place. Unlike the previous version, this markup must be in the page source and not loaded asynchronosly because values in the panel's form markup are used to build out the interactive preview and personalization buttons.

Panel markup should be included in the source after the pdetail_info element. It includes a personalize_preview element for mobile screens where the panel may obscure the interactive product carousel preview.

Panel dialog markup & variations

Step 5: Customize panel markup

When the personalization PDP loads and when someone interacts with the personalization form, JavaScript dynamically updates several components on the page, including the interactive preview product image, based on data- attributes and form field values in the markup. The form markup acts like a database that stores default and dynamically updated values, so it's important to make sure that the attributes and values accurately reflect available personalization options and selected states.

Pre-populated customizations

Some products come with customizations included and that cannot be removed, like sports team logos. Included customizations have an initial (default) state that must appear on the interactive preview when the page loads. To display the correct customization preview, set default values in the form field markup. For example, if a whale is included, assign the checked attribute to the default placement and whale style radio input elements. See component pages below for more detail.

Panel components & data configuration

• Placement toggles
  A set of radio button input elements that determine where each customization can go on the product (i.e., front, back, left sleeve, etc). Data attributes on the inputs capture the placement's text label, hotspot coordinates on the interactive preview image, hotspot size, and if it's for a monogram, whether the placement accepts initials, a name, or either. The description that sits under or beside the toggles is dynamically updated when a placement is selected.
• Logo toggles
  A set of radio button input elements for selecting a logo (or whale) style.
• Monogram type toggle
  Monogram customizations can be initials or a name, and each has it's own text input and rules about character max counts. Monogram type is set using the data-allowed attribute on the placement toggle because monogram type can differ by placement; some placements allow for name only, some for initials only, and some can support either.
• Monogram toggles (web fonts)
  A set of radio button input elements for selecting a monogram style (font). A subset is displayed depending on the monogram type allowed for that placement (some fonts are used for either initials or names, not both).
• Customization pricing
  Sets whether there is a flat fee for all customizations or if they're added a la carte (see below). These values are referenced by the hotspot menus and the personalization buttons.
• Customization size
  Similar to pricing, this hidden input value stores the customization size referenced throughout the interface. This input should be located within the personalize form:
  <input type="hidden" data-customization-size value="1/2">

Customization pricing

These fields are included just above the personalization buttons, inside the pdetail_personalize container. They store pricing information that is used to update hotspot menu options and buttons when the page loads and as the user adds/edits their personalization.

When a flat fee is applied for adding any number of customizations, the customization-price-flat value is set to that dollar amount, and the remaining values are set to zero:

<input type="hidden" name="customization-price-flat" value="10">
<input type="hidden" name="customization-price-logo" value="0">
<input type="hidden" name="customization-price-whale" value="0">
<input type="hidden" name="customization-price-monogram" value="0">

When customizations are added a la carte, the customization-price-flat value is set to zero, and the enabled customizations are given a dollar amount:

<input type="hidden" name="customization-price-flat" value="0">
<input type="hidden" name="customization-price-logo" value="0">
<input type="hidden" name="customization-price-whale" value="0">
<input type="hidden" name="customization-price-monogram" value="10">

Step 6: Review "add to bag" form submission

All personalization values for the type, style, and placement are stored in form element values on the page. Note that the name monogram is new and will need to be accounted for in the minicart and bag at checkout.

Step 7: Review editing workflow from cart

Users can edit the personalization of a product from the cart. The cart interface looks similar, but instead of opening a dialog in place (as previously done), the "edit" links return the user to the personalization PDP with all values prefilled. You can see an example of the new editing workflow starting with the bag template.

Step 8: Make CSS block at top of PDP dynamic for swatch images

The personalization tool allows for each customization placement to have a unique or shared background swatch. This is useful for placements that sit on areas of a product that have a different pattern or appearance. There is a style block at the top of the customizable PDP page that lists one or more swatches for the page to use. The first rule sets a common swatch that applies to all areas of the page, including in the right column buttons and radio toggles. After that, you can optionally add placement-specific swatch images to any placements that appear in the page.

/* Custom swatch background: when a color is chosen, this url should be updated so that logo & whale toggles also show the swatch color */
.custom-swatch-background,
[data-personalizable-placement].personalizable_hotspot-populated .personalizable_hotspot_header {
	background-image: url(https://www.vineyardvines.com/dw/image/v2/AAHW_PRD/on/demandware.static/-/Sites-vineyardvines-master/default/dw59805890/images/2017/monogram/Home%20Accessories/976/front.jpg?sw=500&sh=500&sm=cut);
}
/* to override with specific bg images for placements, this attribute format works: */
[data-personalizable-placement="backyoke"].personalizable_hotspot-populated .personalizable_hotspot_header {
	background-image: url(/docs/img/product-samples/plaid-lightblue-variation-1.jpg);
}
[data-personalizable-placement="leftchest"].personalizable_hotspot-populated .personalizable_hotspot_header {
	background-image: url(/docs/img/product-samples/plaid-lightblue-variation-2.jpg);
}