Twenty Seventeen: Improve user and developer experience with the customizer integration

[celloexpressions]

As the default theme, Twenty Seventeen should showcase what themes can (and should) do with the customizer API. This applies to both users, via instant live previews and contextual controls, and developers, via code that follows core conventions.

Twenty Seventeen should follow all of the recommendations for themes in ​the official customize API documentation. Additionally, every option should be previewable with Selective Refresh and, where feasible, instant postMessage JS-based updates, as these approaches provide faster, more contextual user feedback as they make changes. Controls should be contextual to when they apply. The preview should be as accurate a representation of the front end of the site as possible. The code should be DRY and as simple as possible.

While the initial commit of the theme contains extensive work toward these goals, there are several problems with the current implementation, with #38399 discussing the front page sections handling in particular. This ticket addresses all of the major customize-related issues that don't already have complete patches elsewhere (like #38400). Because many of the issues are inter-related, they'll be addressed together initially, then we can follow up with additional adjustments as needed.

[celloexpressions]

With 38426.diff​. Note that there are a bunch of unnecessary refreshes in the preview at the end due to a core bug with changesets.

[celloexpressions]

First pass, see forthcoming comment.

[celloexpressions]

I forgot to mention in the ticket description, but another criteria is that there should be clear opportunities for plugins and child themes to extend the provided options without reworking the theme's options structure.

38426.diff​ is a first pass based on my initial review. See the screenshot above for the visual changes. Here's a technical summary (roughly in the sequence of the patch, top-to-bottom):

• Rename customizer JS files to customize-preview.js and customize-controls.js to align with the core file naming and make it clearer where each file runs.
• Only show the colorscheme_hue control when there's a custom color scheme.
• Update preview JS handling for revised front page section handling, see below.
• Remove all references to "Theme Customizer" in code comments. ​It hasn't been called that since before 4.0.
• Clarify the purpose of the JS files by updated the code comments in the file headers.
• DRY for the front page section JS.
• DRY for registering front page sections. Unify and simplify the corresponding loops used for front page section output.
• Make the arbitrary number of front page sections filterable, for UI registration and output.
• Add selective refresh for widgets.
• Rename the page layout section to "Layout", so that child themes and plugins can add additional options that are relevantly grouped (see also Twenty Eleven).
• Rename twentyseventeen_sanitize_layout to twentyseventeen_sanitize_page_layout to be clearer about what it sanitizes in case child themes or plugins consider reusing it.
• Rename page_options setting/control to page_layout as that's more reflective of what that option does; and again, helps for potential extensions.
• Make the page layout option contextual to pages and the sidebar being inactive, as the option only applies when there is no sidebar (per its description).
• Remove the generic "Theme Options" panel. Per the official documentation (within a strong), themes should avoid adding panels. There is no need to group multiple sections into a context here, because:
• Condense front page panel controls into a single section. Per the documentation, sections should generally contain multiple controls. The purpose of sections is to group multiple, related controls together. These controls all serve the same purpose, so they should be shown within a single section. This also makes it clearer within the controls pane how the different sections relate to each other.
• Place the "Front Page Sections" section directly after the static front page section, since they're related.
• Integrate with the ability to create pages from a dropdown-pages control in #38164.
• Add selective refresh for front page sections. This allows them to be previewed much more quickly and without losing context. This also brings "shift-click to edit" functionality, and soon visible edit icons via #27403. This required some minor restructuring on the output side but visitors should still see the same results. There is now a template tag for displaying a front page section.
• Locate active_callback functions within customizer.php so that they're easier to find when editing customizer registrations, similarly to sanitize callbacks.
• Remove the fancy borders styling for front page sections in the preview. This prevents users from previewing an accurate representation of the design within the customizer, and seems like something that's intended to be on the frontend as a design element. Visual edit icons should provide a nice alternative.
• Adjust the styling for placeholders for panels that aren't active. Show the placeholders when the front page section is expanded. This shows the placeholder title (which feels more native to the theme design) and an edit icon when appropriate, but hides the placeholders when not explicitly working on the front page sections. This also allows us to simplify the CSS and improve readability there.

I imagine we'll need a bit of back and forth to finalize the various points here, but looking at the changes collectively, the resulting experience is more inline with core recommendations for both users and developers.

[celloexpressions]

#38399 was marked as a duplicate.

[karmatosed]

Looking at this there are a few things that strike me.

• Do we really want to refactor like this to something at this stage that is so large and hasn't been user tested? I'd suggest we shouldn't.
• Front page sections is used as title... are we in this theme now only limiting to front page? I thought the current setup allows us to have not just front page.
• I am very against yet another option for layout. That shouldn't be the case to have to add it in.
• The amount of top level options is overwhelming. I am starting to really feel we're heading towards a 'Paradox of choice' and again without user testing can't be sure. There are valid cases for having sub panels when you have so many top level items. Yes, you shouldn't hide everything, but there's a balance. Having so many things in one top level is overwhelming for most users.

I have strong issues with this approach outside of my comments above, however I would advise us to not change the UI or UX of the current experience now it is in. We can iterate outside in a feature plugin for multi-panel. #37974 shows that and that should continue as a plugin.

[celloexpressions]

Replying to karmatosed:

• Do we really want to refactor like this to something at this stage that is so large and hasn't been user tested? I'd suggest we shouldn't.

Yes, and I'm willing to coordinate user testing here to evaluate the overall customization experience with the theme. The timing is a consequence of circumstances that can't be avoided, as discussed in Slack. We also don't have any public user testing at all here yet.

• Front page sections is used as title... are we in this theme now only limiting to front page? I thought the current setup allows us to have not just front page.

As far as I can tell the theme has it for front-page only. The template part is being called from there, but if it's also somewhere else we can adjust that.

• I am very against yet another option for layout. That shouldn't be the case to have to add it in.

The layout option is existing, it's moved to be easier to find now. The section is also more generic so that child themes and plugins can add additional options if they'd like to without fragmenting the experience with a separate section.

• The amount of top level options is overwhelming. I am starting to really feel we're heading towards a 'Paradox of choice' and again without user testing can't be sure. There are valid cases for having sub panels when you have so many top level items. Yes, you shouldn't hide everything, but there's a balance. Having so many things in one top level is overwhelming for most users.

In most cases there will only be one custom top-level section here. Currently a static front page would have two, although I don't know if the layout option should apply on the front page; if we removed that there's only one or none on any given view in the preview. Please note that panels are explicitly not to be used for the sole purpose of adding hierarchy, which is why we have separate panel and section objects; reference the official documentation linked above. Excessive (and in this case unnecessary) hierarchy can cause equal or worse issues to having to many sections in the first place, but themes should be able to add one or two sections without overwhelming users. If that's an issue we need to look at improving that in core; there were a few ideas floating around when panels were introduced in 4.0 that could be revisited now.

I have strong issues with this approach outside of my comments above, however I would advise us to not change the UI or UX of the current experience now it is in. We can iterate outside in a feature plugin for multi-panel. #37974 shows that and that should continue as a plugin.

The functionality isn't changed much, however the code is simplified to be more appropriate for a default theme. It's still four dropdown-pages controls, and there are some adjustments to the way they're previewed. As far as I can tell you're most concerned about simplifying the sections, but the core philosophies inform us to strive for simplicity. Looking at it objectively there is less UI with this approach and less unnecessary repetition.

A significant part of the changes is to add the UX benefits of selective refresh (which will also bring visual edit icons, see #27403), and another part of it is to make it possible to preview these areas in the way they'll be displayed on the front end (removing the borders and contextually showing placeholders). This is one of the areas where we have options on the specifics and could do something in the middle if desired.

Another general comment here - there was originally conern about consolidating the panel-registration code to loop through the four identical options because of the complexity it would add to the theme. However, digging thorugh the way this is implemented, there was actually much more complexity with the front page feature in the templates and the customizer implementation. 38426.diff​ tries to find a middle ground there in terms of balancing developer and user experience, and supporting selective refresh is a great way to do both.

[davidakennedy]

Replying to celloexpressions:

Thanks for all the ideas and work here! Twenty Seventeen wouldn't be the same without your contributions!

38426.diff​ is a first pass based on my initial review. See the screenshot above for the visual changes. Here's a technical summary (roughly in the sequence of the patch, top-to-bottom):

• Rename customizer JS files to customize-preview.js and customize-controls.js to align with the core file naming and make it clearer where each file runs.

Makes sense.

• Only show the colorscheme_hue control when there's a custom color scheme.

Also makes sense.

• Update preview JS handling for revised front page section handling, see below.

See below for my comments on this.

• Remove all references to "Theme Customizer" in code comments.​It hasn't been called that since before 4.0.

Thanks!

• Clarify the purpose of the JS files by updated the code comments in the file headers.

Awesome.

• DRY for the front page section JS.
• DRY for registering front page sections. Unify and simplify the corresponding loops used for front page section output.

The DRY approach is great, as are the comments explaining what's happening.

• Make the arbitrary number of front page sections filterable, for UI registration and output.

I really like this addition, and it should help child themes.

• Add selective refresh for widgets.

This has already been committed, so the next patch can remove this.

• Rename the page layout section to "Layout", so that child themes and plugins can add additional options that are relevantly grouped (see also Twenty Eleven).
• Rename twentyseventeen_sanitize_layout to twentyseventeen_sanitize_page_layout to be clearer about what it sanitizes in case child themes or plugins consider reusing it.

Makes sense.

• Rename page_options setting/control to page_layout as that's more reflective of what that option does; and again, helps for potential extensions.

Makes sense.

• Make the page layout option contextual to pages and the sidebar being inactive, as the option only applies when there is no sidebar (per its description).

Awesome!

• Remove the generic "Theme Options" panel. Per the official documentation (within a strong), themes should avoid adding panels. There is no need to group multiple sections into a context here, because:
• Condense front page panel controls into a single section. Per the documentation, sections should generally contain multiple controls. The purpose of sections is to group multiple, related controls together. These controls all serve the same purpose, so they should be shown within a single section. This also makes it clearer within the controls pane how the different sections relate to each other.
• Place the "Front Page Sections" section directly after the static front page section, since they're related.

This part seems problematic – the change in location of the layout control and front page sections. It's what I've meant by not waiting to make huge UI changes. I agree with you that the sections themselves should not be separate panels – especially since the Customizer documentation advises against it.

However, moving everything to the top level creates problems in my mind.

1. The options have a potential to become muddled if more Core options are added in the future.
2. A user has no way of knowing they're specific to the theme. I don't think Twenty Eleven is a good example here because, if I remember correctly, its Customizer options were added after the fact and tried to mimic its options page. Grouping the options under Theme Options makes sense and bundling the sections with page layout, combined with the active callbacks should make sure only the relevant options show.

• Integrate with the ability to create pages from a dropdown-pages control in #38164.

This makes sense to do only if that ticket gets in. Otherwise, let's wait.

• Add selective refresh for front page sections. This allows them to be previewed much more quickly and without losing context. This also brings "shift-click to edit" functionality, and soon visible edit icons via #27403. This required some minor restructuring on the output side but visitors should still see the same results. There is now a template tag for displaying a front page section.

Makes sense – and something that should definitely be added.

• Locate active_callback functions within customizer.php so that they're easier to find when editing customizer registrations, similarly to sanitize callbacks.

I like this. Makes total sense.

• Remove the fancy borders styling for front page sections in the preview. This prevents users from previewing an accurate representation of the design within the customizer, and seems like something that's intended to be on the frontend as a design element. Visual edit icons should provide a nice alternative.
• Adjust the styling for placeholders for panels that aren't active. Show the placeholders when the front page section is expanded. This shows the placeholder title (which feels more native to the theme design) and an edit icon when appropriate, but hides the placeholders when not explicitly working on the front page sections. This also allows us to simplify the CSS and improve readability there.

I don't mind iterating on the design of the placeholders. However, this change goes too far in the other direction for me. It looks exactly like content to me. Content that might be displayed on the front end. Part of the reason of the bold border colors was to provide an idea of "this is temporary" to users. We could probably remove the borders after a page is selected and base it on a timer – so users see it, but then know it won't show up on the front end. Can we split out these changes to another ticket? That way, it doesn't hold up any improvements here.

I imagine we'll need a bit of back and forth to finalize the various points here, but looking at the changes collectively, the resulting experience is more inline with core recommendations for both users and developers.

Definitely. I'm all for collaboration, as nothing amazing ever gets done without it. Let’s both remain open to new ideas, perspectives, and experiences here.

Thanks again!

[davidakennedy]

Improvements for the panel styles in the Customizer can be moved to #38408.

[celloexpressions]

Thanks for going through each change with comments! See my responses below.

Replying to davidakennedy:

Replying to celloexpressions:

• Remove the generic "Theme Options" panel. Per the official documentation (within a strong), themes should avoid adding panels. There is no need to group multiple sections into a context here, because:
• Condense front page panel controls into a single section. Per the documentation, sections should generally contain multiple controls. The purpose of sections is to group multiple, related controls together. These controls all serve the same purpose, so they should be shown within a single section. This also makes it clearer within the controls pane how the different sections relate to each other.
• Place the "Front Page Sections" section directly after the static front page section, since they're related.

This part seems problematic – the change in location of the layout control and front page sections. It's what I've meant by not waiting to make huge UI changes. I agree with you that the sections themselves should not be separate panels – especially since the Customizer documentation advises against it.

However, moving everything to the top level creates problems in my mind.

1. The options have a potential to become muddled if more Core options are added in the future.
2. A user has no way of knowing they're specific to the theme. I don't think Twenty Eleven is a good example here because, if I remember correctly, its Customizer options were added after the fact and tried to mimic its options page. Grouping the options under Theme Options makes sense and bundling the sections with page layout, combined with the active callbacks should make sure only the relevant options show.

I understand these points and they are issues, but they're actually much broader than this theme. The first thing to note is that in most cases this change will still leave only one top-level element added by the theme (and in many views there will be no top-level elements). I'd also propose not applying the layout option to the front page since it's a bit confusing in addition to the custom sections, which would mean there's only ever one at a time.

In terms of separating theme-specific options from theme-agnostic options, the customizer traditionally intermixes these. Custom logo, header, background, and often color options are all theme-specific but not nested in anything indicating that they're theme-specific. All of the past core user testing for the customizer tends to be done with themes following the de-facto standard - sections labeled by their purpose (colors, layout, featured content, etc.). Because all of the core options follow this approach, grouping by purpose as opposed to source, the default theme should do the same.

There is potential to re-think how it works in core, potentially even moving to a strategy where everything is grouped into panels, and all theme options need to be in the same place (including things that use add_theme_support). It's worth going back through the history here - #27406, #27591, #28979, #29172 (for order), #29173, #29197, #31336. Panels were originally a subclass of the section object, but later became distinct object (all in 4.0). I'll note as part of that that sections and panels had completely different "opening" actions at the time panels were introduced, and because the objects are entirely separate objects, there is potential to revisit distinct UIs for these when the customizer UI is reimagined in the future. The previous UI reinforced the notion that panels are distinct contexts whereas sections are UI containers for organizing controls; the current UI causes that to become more confused. As it is, custom sections and panels can use different UIs anyway, with the themes panel and sections being a good example in core. Bottom line, the current best practice and core behavior is to use sections describing their contents specifically; Twenty Seventeen should respond accordingly, but know that core will likely restruture things in the future.

As a brief aside to that point, there's a pretty good chance that the entire thing that we currently know as the "customizer" will be completely re-imagined in terms of UI and UX as a front-end-native live-preview framework that facilitates managing a majority of a site (including content), in the next year or so. It would likely continue to use the customize API and inherit all of the theme and plugin integrations there, but it's especially important that themes avoid making decisions related to the specific way the different core customize UI objects are displayed since they're subject to significantly change over time.

• Integrate with the ability to create pages from a dropdown-pages control in #38164.

This makes sense to do only if that ticket gets in. Otherwise, let's wait.

Fortunately, this is a one-line change with no impact if the core change doesn't happen. However, I'm pretty confident the core change is ready to go.

• Remove the fancy borders styling for front page sections in the preview. This prevents users from previewing an accurate representation of the design within the customizer, and seems like something that's intended to be on the frontend as a design element. Visual edit icons should provide a nice alternative.
• Adjust the styling for placeholders for panels that aren't active. Show the placeholders when the front page section is expanded. This shows the placeholder title (which feels more native to the theme design) and an edit icon when appropriate, but hides the placeholders when not explicitly working on the front page sections. This also allows us to simplify the CSS and improve readability there.

I don't mind iterating on the design of the placeholders. However, this change goes too far in the other direction for me. It looks exactly like content to me. Content that might be displayed on the front end. Part of the reason of the bold border colors was to provide an idea of "this is temporary" to users. We could probably remove the borders after a page is selected and base it on a timer – so users see it, but then know it won't show up on the front end. Can we split out these changes to another ticket? That way, it doesn't hold up any improvements here.

Another idea I got as I was iterating on the approach was to only show the borders when the front page section is open, similarly to how the placeholders are only shown with the front page section (as part of the placeholder). What about adding that back in, then iterating on the colors/style (per @karmatosed) on #38399? The current approach still reads like a design element to me, not something that's only shown when you're customizing it. But only showing it when you're working on the UI might be a nice intermediate approach. My biggest issue with the borders, and the reason they're removed in the initial pass, is that the implementation in :before prevents users from interacting with the contents of the panel within the preview; in a default theme that's concerning as it may cause new users to think they can't interact with the preview and navigate their site within the customizer.

Also, I don't think the borders were showing before something was selected in a given section, but that may have been a bug. Either way, we should continue iterating on the placeholders. Some changes (especially with the JS) are coupled directly with the other changes here but I'd expect further iterations on the other ticket. Another idea I had was to add a link to add front page sections within the static front page section, but I left it out for now for simplicity.

[davidakennedy]

Replying to celloexpressions:

Thanks for the thoughtful response and the continued contributions to Twenty Seventeen. I hear everything you're saying, and every time I work with theme customization, I see room for improvement too. But as we're close to beta, I want to focus in on what needs to and can be done for 4.7. And some of these larger issues are out of scope for the theme to handle.

The reality is there are a number of outstanding tickets for the theme, and this is something we need to get pinned down and patched before beta. Let's draw out what we can bring in, rather than focus what we need to have improve in core, then spin a patch from that.

Like:

• The code-specific improvements you made are awesome.
• Iterating on the border design would also be great.

I know that doesn't cover everything but let's start making plans for 4.8 now. Let's make some tickets, and look to how we can make themes better for all. #37974 is a good one to keep pressure on.

[celloexpressions]

Refresh for directory structure change, restore panel borders when editing sections, integrate with [38906].

[celloexpressions]

Replying to davidakennedy:

Replying to celloexpressions:

Thanks for the thoughtful response and the continued contributions to Twenty Seventeen. I hear everything you're saying, and every time I work with theme customization, I see room for improvement too. But as we're close to beta, I want to focus in on what needs to and can be done for 4.7. And some of these larger issues are out of scope for the theme to handle.

The reality is there are a number of outstanding tickets for the theme, and this is something we need to get pinned down and patched before beta. Let's draw out what we can bring in, rather than focus what we need to have improve in core, then spin a patch from that.

Agreed. That's why we need to stick to the existing core conventions and written best practices with Twenty Seventeen for now. We don't have time to go down the rabbit hole of grouping options that are theme-specific, or reducing the number of core top-level sections, in the theme. And really, themes shouldn't need to worry about this; these should be addressed on the core side in a future release. For Twenty Seventeen, both theme-added sections are contextual, so when they are visible it'll almost always be one at a time. If you have a sidebar you'll never see the layout section unless child themes or plugins add additional options to it.

In past user testing, I've noticed that users tend to click around to the different sections to see what the options do. If that behavior holds, the front page sections should still be discoverable, and showing the borders when the section is open would continue to provide that UX benefit of showing where each section is. If that doesn't work we may be able to leverage the preview/edit toggle concept added with #27403, but let's try it, user test it, and iterate as needed during beta.

38426.2.diff​:

• Refresh 38426.diff​ for the directory structure change.
• Update for [38906], allowing pages to be created directly to be used as front page sections. It's a bit repetitive, so we could do something like only showing them on the last option, but for new sites/users this will be incredibly useful.
• Restore the panel borders, but only shown them when editing the front page sections (along with the placeholders for empty panels). This also makes the panel placeholders look like placeholders again. I tried adding back the needed CSS based on the updated structure with selective refresh, but if it's missing pieces we still need let's add those back in. This part of the patch is fairly involved and I think there were some things leftover from other themes, so I'm not entirely sure what the expected/current behavior should be when the other changes are taken into account. The patch feels close.
• Ensure that front page panels borders don't prevent panel contents from being interacted with, by setting a negative z-index. Likely also fixes a conflict in styling with #27403.

I'm planning on running and recording some user tests for Twenty Seventeen and the customizer on Thursday, and by then we'll probably also have visible edit icons (#27403), which will really turn the whole experience upside down. So let's see how it goes with 38426.2.diff​. Let me know if you have any specific objections to this revised patch; probably the most important part for me is correcting the section structure (naming can be iterated on) and removing the unnecessary panel, followed by selective refresh support for the front page panels.

[celloexpressions]

Related: ​https://make.wordpress.org/core/2016/10/18/twenty-seventeen-merge-proposal-for-4-7/#comment-31470.

Simplifying the organization of the controls to follow for conventions and adding selective refresh will be big improvements to the "clunky" and "slow" feeling noted by @matt. Those also set us up well for the longer-term changes I noted there in my reply.

[davidakennedy]

Replying to celloexpressions:

Thanks again for your thoughts here. As I've said a few times in this ticket, and in post conversations on the GitHub repository for the theme, I'm against bringing these options to the top-level of the Customizer. In most everything else I've been very open to change and iteration.

The best practice issues you mention reference documentation. Documentation, like the whole of WordPress, is subject to change. It shouldn't be something that becomes an inflexible.

The organization of the theme's panels will remain as it is now unless we have significant user feedback during beta to prompt a change.

Twenty Seventeen is trying to do something that users want and themers do every day with WordPress. Build a complex home page. Most default themes haven't attempted this because there have been many answers, and no support from WordPress core. Twenty Seventeen's answer isn't the best. But I hope it will spur a conversation that will lead to improvements in core and beyond to help users build and customize the sites they want easier. Moving the options to the top-level of the Customizer won't get us any closer on that. Right now, you and I are wasting time on the wrong conversation. Tickets like #37974 start the conversation from a better place to impact more users.

[celloexpressions]

Merge the two theme sections into generic "theme options", tweak visual edit shortcuts.

[celloexpressions]

38426.3.diff​ merges the theme sections together into a generic "theme options" section. We should user test this against the option of putting the front page controls in the static front page section.

I also made a couple tweaks to ensure that the new visible edit shortcuts don't have any issues. Should be ready for a commit. Note that the file renames need to be done in SVN by the committer, then the revisions to the JS files can follow that up.

[davidakennedy]

Just to close the loop, this was talked about in the #core-themes Slack channel, and a path agreed upon here: ​https://wordpress.slack.com/archives/core-themes/p1477515821003986

[davidakennedy]

In 38986:

Twenty Seventeen: Improve user and developer experience with the customizer integration

• Rename customizer JS files to customize-preview.js and customize-controls.js to align with the core file naming and make it clearer where each file runs.
• Only show the colorscheme_hue control when there's a custom color scheme.
• Update preview JS handling for revised front page section handling, see below.
• Remove all references to "Theme Customizer" in code comments. It hasn't been called that since before 4.0.
• Clarify the purpose of the JS files by updated the code comments in the file headers.
• Improve code readability.
• Make the arbitrary number of front page sections filterable, for UI registration and output.
• Rename twentyseventeen_sanitize_layout to twentyseventeen_sanitize_page_layout to be clearer about what it sanitizes in case child themes or plugins consider reusing it.
• Rename page_options setting/control to page_layout as that's more reflective of what that option does; and again, helps for potential extensions.
• Make the page layout option contextual to pages and the sidebar being inactive, as the option only applies when there is no sidebar (per its description).
• Condense options into a single section.
• Add selective refresh for front page sections.
• Locate active_callback functions within customizer.php so that they're easier to find when editing customizer registrations, similarly to sanitize callbacks.
• Adjust the styling for placeholders for panels that aren't active.
• Ensure that the new visible edit shortcuts don't have any issues.

Props celloexpressions.

Fixes #38426.