Customizer: Additional CSS highlight, revisions, selection, per-page, pop-out

[folletto]

This ticket is to track the next steps of Additonal CSS after 4.7. See #35395 for the discussion so far.

The MVP of the Additional CSS editor in customizer included the basic UI, navigation and backend work.

There are various next steps that area already included in the design above, and can be done either in a single next release or staggered further as needed. From the latest discussed design, the features we already have ready to build are:

1. Syntax Highlighting
2. Revisions
3. Selection of items on the page (CSS selector)
4. Per-Page CSS as a complement of the current site-wide CSS for better management
5. The ability to pop-out the editor in a separate window for a more comfortable editing experience

Just one special note regarding revisions: we might want to not do CSS revisions, and instead build the more flexible and general revision UI for the customizer as a whole. That's being discussed in #31089.

[folletto]

Customizer CSS design i2

[lukecavanagh]

@folletto

What about global options for CSS?

So plugin CSS specific changes would be global and not be active theme dependant.

[folletto]

What about global options for CSS?
So plugin CSS specific changes would be global and not be active theme dependant.

I'm not convinced about this: CSS is very very strongly DOM and the rest of theme-CSS dependent.

However, I might be biased here. Can you list potential situations where a CSS would translate well across themes so we can evaluate the extent of this feature?

[lukecavanagh]

@folletto

Say for example a user is using the Jetpack subscribe widget on their site.

#subscribe-email input {
 width: 62%;
 padding: 1px 2px;
}
.comment-subscription-form .subscribe-label {
 display: inline !important;
}

So that CSS is just related to plugin front-end changes and it not related to a theme.

[folletto]

I'm not sure, even these seem risky to preserve on a theme change: what if the theme is overriding input fields with flexbox or different widths or margins? What if the inlining breaks entirely the forms?

I think the kind of user that would make use of this UI — which is surely more experienced than others, but also likely not a fully CSS experienced person — might get confused if they enabled a theme straight off and it looks "broken" due to some old lingering CSS they forgot about. That would trigger support emails to the theme author when it's really not the case.

[westonruter]

For CSS syntax highlighting, see #23601.

[westonruter]

I think the revisions should be worked on in another ticket, namely #31089.

The other enhancements to Custom CSS outlined here I think should be among low hanging fruit (in conjunction with #12423).

[westonruter]

The code editor component we pick should to have syntax checking as well so that a user can see when they have an error in their code. With this in place, we could remove the server-side syntax validation that is currently being done incompletely (see #39198, #39728).

[westonruter]

As noted in #12423, there is an inputStyle for CodeMirror that is better for accessibility. Here is a CSS demo forked from @iseulde and @afercia: ​http://codepen.io/westonruter/pen/Graepj

Looks like the main thing missing in this pen is CSS autocomplete.

[melchoyce]

customizer-css-revisions-i3.png​ is an update just including revisions, without any of the other enhancements. I've updated the styles to match my mockups in #21666.

customizer-css-revisions-i4.png​ is a potential second iteration, which specifically shows the additions and subtractions you made in each revision.

Both iterations would still update the preview on the right when you toggle between revisions.

[folletto]

Looks solid, and nicely split into incremental steps :)

One clarification: I'm assuming the text in the i4 (the diff) is going to be "normal" text, not editable which makes things a bit easier. In that case, wouldn't be possible to have the + and the - in the gutter (like line numbers), aligned "outside" the text , instead of being "inside"?

[melchoyce]

Replying to folletto:

One clarification: I'm assuming the text in the i4 (the diff) is going to be "normal" text, not editable which makes things a bit easier.

Yup! Also thinking we could add cursor: not-allowed to reinforce that.

In that case, wouldn't be possible to have the + and the - in the gutter (like line numbers), aligned "outside" the text , instead of being "inside"?

Good idea. 👍

[melchoyce]

Updated mockup with @folletto's feedback

[westonruter]

For development, I think this will look like:

1. Ensure that custom_css posts are exposed via the REST API. It may make sense to have a /customize/custom-css endpoint, along with /customize/custom-css/twentyfifteen for getting the post resource for the twentyfifteen theme and also /customize/custom-css/twentyfifteen/revisions to get the list of revisions for that theme's custom CSS. Some discovery will be needed there for what makes the most sense, and whether or not the REST API should allow access to custom_css posts for non-active themes. See also #39634 and #38900, and questions on ​Custom CSS endpoints.
2. Create a custom customizer section for Custom CSS, instead of re-using the default section type. This custom section would have its UI augmented to show the “See CSS history” link, and when clicked to hide the controls (the textarea) and show the list of revisions (fetched via REST API). This custom section would also override the behavior of the back button to not cause the section to collapse but rather back out of viewing the list of revisions or previewing a revision at a given point. This might warrant also creating a custom control for the textarea input as well; see its ​custom styling and ​behavior.
3. When clicking on a revision, it needs to be previewed. This is a bit tricky, but the CSS from the custom_css post at that revision needs to be pushed into the custom_css setting so that it can be previewed. But a complication here is what if a user then clicks Save & Publish even though they didn't hit the Restore button? In this case, the Restore button would really not be doing anything other than collapsing the revision preview and revision list to then focus back on the textarea; similarly, the Back button would then also have to have the behavior of restoring the previous value for the custom_css setting, as clicking Back instead of Restore indicates the user didn't want to apply the setting change. This seems somewhat backwards, but it seems easier to implement than having a “preview preview”, some kind of preview change to a setting to preview without actually causing it to be written into the changeset.

[jbpaul17]

Punting to 4.8.1 per today's bug scrub.

[westonruter]

👉 Please test the new 0.1.0 release for the “codemirror-wp” feature plugin—being worked on for 4.9. This plugin:

• Extends the Custom HTML widget to add syntax highlighting and checking
• Incorporates CodeMirror to the Additional CSS control in the Customizer
• Adds CodeMirror to the file editors for themes and plugins

See the plugin's GitHub releases page to download a ZIP for easy installation: ​https://github.com/WordPress/codemirror-wp

Report any issues at ​https://github.com/WordPress/codemirror-wp/issues

[westonruter]

@folletto @melchoyce CodeMirror has a full-screen mode which we could leverage for the “pop out” aspect of this ticket.

Demo: ​https://codemirror.net/demo/fullscreen.html

Plugin issue: ​https://github.com/WordPress/better-code-editing/issues/70

Since there is no site/page toggle in Custom CSS, then the full-screen icon would need somewhere else to live.

[folletto]

CodeMirror has a full-screen mode which we could leverage for the “pop out” aspect of this ticket.

Note that the need "popping out" solves is one of the most requested features which is about the sidebar reducing the visibility/width of the site (triggering smaller responsive views) and space available to type. Going full screen would cover entirely the page, surely giving more space to type, but then making the site completely covered.

Thus, I don't consider it a solution for the problem it's trying to solve.
We might it consider as a partial solution, but... I'm not sure about that kind of intermediate take considering some people might still like it and would get disappointed when we change the implementation to a pop-out window.

Since there is no site/page toggle in Custom CSS, then the full-screen icon would need somewhere else to live.

If we're still working toward that i2 design, I'd still place it where it's going to be in the end. Even if it starts being just that icon I would still place it there. Maybe we can start with a visible label, to avoid the icon to hang alone.

If we're not sure if we're headed in that direction, then a good alternative position would be in the bottom "See CSS History" sticky bar, where the "pointer" feature is in i2 (right aligned).

[westonruter]

@folletto By “pop-out”, did you mean a separate browser window or a floating window that floats over the preview but is undocked to the left side?

[folletto]

Separate browser window, as it allows the maximum flexibility.

See the design i2 at the top of this thread for design reference (the rightmost part). :)

[melchoyce]

Replying to folletto:

Separate browser window, as it allows the maximum flexibility.

Yeah, +1 for what @folletto's said.

[westonruter]

In 41376:

Editor: Add CodeMirror-powered code editor with syntax highlighting, linting, and auto-completion.

• Code editor is integrated into the Theme/Plugin Editor, Additional CSS in Customizer, and Custom HTML widget. Code editor is not yet integrated into the post editor, and it may not be until accessibility concerns are addressed.
• The CodeMirror component in the Custom HTML widget is integrated in a similar way to TinyMCE being integrated into the Text widget, adopting the same approach for integrating dynamic JavaScript-initialized fields.
• Linting is performed for JS, CSS, HTML, and JSON via JSHint, CSSLint, HTMLHint, and JSONLint respectively. Linting is not yet supported for PHP.
• When user lacks unfiltered_html the capability, the Custom HTML widget will report any Kses-invalid elements and attributes as errors via a custom Kses rule for HTMLHint.
• When linting errors are detected, the user will be prevented from saving the code until the errors are fixed, reducing instances of broken websites.
• The placeholder value is removed from Custom CSS in favor of a fleshed-out section description which now auto-expands when the CSS field is empty. See #39892.
• The CodeMirror library is included as wp.CodeMirror to prevent conflicts with any existing CodeMirror global.
• An wp.codeEditor.initialize() API in JS is provided to convert a textarea into CodeMirror, with a wp_enqueue_code_editor() function in PHP to manage enqueueing the assets and settings needed to edit a given type of code.
• A user preference is added to manage whether or not "syntax highlighting" is enabled. The feature is opt-out, being enabled by default.
• Allowed file extensions in the theme and plugin editors have been updated to include formats which CodeMirror has modes for: conf, css, diff, patch, html, htm, http, js, json, jsx, less, md, php, phtml, php3, php4, php5, php7, phps, scss, sass, sh, bash, sql, svg, xml, yml, yaml, txt.

Props westonruter, georgestephanis, obenland, melchoyce, pixolin, mizejewski, michelleweber, afercia, grahamarmfield, samikeijonen, rianrietveld, iseulde.
See #38707.
Fixes #12423, #39892.

[mrahmadawais]

ADD: Use KBD to show User Keyboard Input Keys

[mrahmadawais]

@westonruter I have added a patch that makes the info in Add CSS section look better by adding kbd elements. It looks like this now.

[westonruter]

Replying to mrahmadawais:

@westonruter I have added a patch that makes the info in Add CSS section look better by adding kbd elements. It looks like this now.

Please follow #41872 for this as the text may get rewritten into a single paragraph. Note also the overlapping kbd elements cause an undesirable darker gray line where they overlap. So the padding would need to be reduced in this element.

[westonruter]

Regarding:

4. Per-Page CSS as a complement of the current site-wide CSS for better management

I wrote a quick plugin which extends the ​Customize Posts plugin to add a “Custom CSS” control for each post/page section added to the Customizer : ​https://github.com/xwp/wp-customize-posts-css

The plugin is just a proof of concept in terms of per-page custom CSS, but mainly serves as a way to test the proposed new code editor customizer control in #41897.

See screenshots: ​https://github.com/xwp/wp-customize-posts-css#screenshots

[folletto]

The plugin is just a proof of concept in terms of per-page custom CSS, but mainly serves as a way to test the proposed new code editor customizer control in

I'm not sure I understand... does this represent a step forward to later implement the Per-Page CSS, is that correct?
So that will come after #41897?

[westonruter]

Bumping priority to high for visibility and alignment with 4.9 goals, and given proximity to beta 1 deadline.

[westonruter]

Replying to folletto:

I'm not sure I understand... does this represent a step forward to later implement the Per-Page CSS, is that correct?
So that will come after #41897?

It's one approach to implementing Per-Page CSS. It's not intended to replace what is designed here, but rather to provide an alternative take on it. In Customize Posts, each post/page gets its own section added dynamically in the Customizer. These sections contain controls for managing each post's title, content, featured image, etc. So it just adds “Custom CSS” as another one of the fields (as a demonstration of the control in #41897). It then ties the CSS to the specific post/page (via meta), and allows those styles to apply on whatever template that post may appear on.

So that actually actually brings up something I've been wondering about in regards to:

Per-Page CSS as a complement of the current site-wide CSS for better management

What is the CSS linked with when you provide per-page CSS? Is it a “Page” page we're talking about or just some URL? Like would it allow a user to provide custom styling to a category archive page? If I supply styling for a category then does it get applied to page 2 and page 3 of the category's posts? In other words, are the customizations tied to the specific _URL_ or the “queried object”? This leads directly into one of the big challenges that @melchoyce and I have been thinking about for the future of the Customizer: how can users be informed when a change is local to the current “page” or global to all areas of the site?

[folletto]

So it just adds “Custom CSS” as another one of the fields

Ok, now I understand. I'm not sure of the plan for Customize Posts tho, so I can't at this time evaluate which could be better. From what I understand, if Customize Posts lands, it would make sense to explore that direction in more depth.

What is the CSS linked with when you provide per-page CSS?

These are all good question that need to be sorted out. We need to figure out what's the best pattern to follow.

For example, a "high level" approach that we could use for testing would be to reuse the same set of classes specified by get_body_class(). This however might get TOO granular and have unintended side effects, yet, it's where I'd probably start prototyping as it already exists.

Another approach could be to define a criteria that seems working well in most of the scenarios, striking a balance between all the various pages above: posts get tied to post ID, while categories apply to any category page.

Another approach would be to limit this strictly to Pages, Posts and Custom Post Types, which will provide a narrow scope that might be more feasible for a v1, and would also avoid any ambiguity.

Do you have a preference here?

This leads directly into one of the big challenges that @melchoyce and I have been thinking about for the future of the Customizer: how can users be informed when a change is local to the current “page” or global to all areas of the site?

Yes, this is a broader question, that I'd still try to avoid in the work done in this component specifically. The reason is that it's an issue at a higher order in the architecture, and should be addressed there instead of a per-feature UI. Once we have a higher-level pattern, we can review all the UIs to follow that pattern.

The reason I'm saying this is that I could imagine that, with Gutenberg in sight, the difference is dealt in the same way at a block level, either by having "global blocks" (instances that are flagged as such) or "templates" (layout schemes that can be reused across multiple screens). Or... maybe not.

It's a very important discussion to have tho. Is there another existing issue where it's better to discuss it?

[melchoyce]

Replying to folletto:

This leads directly into one of the big challenges that @melchoyce and I have been thinking about for the future of the Customizer: how can users be informed when a change is local to the current “page” or global to all areas of the site?

Yes, this is a broader question, that I'd still try to avoid in the work done in this component specifically. The reason is that it's an issue at a higher order in the architecture, and should be addressed there instead of a per-feature UI. Once we have a higher-level pattern, we can review all the UIs to follow that pattern.

The reason I'm saying this is that I could imagine that, with Gutenberg in sight, the difference is dealt in the same way at a block level, either by having "global blocks" (instances that are flagged as such) or "templates" (layout schemes that can be reused across multiple screens). Or... maybe not.

I agree — I think our work informing global vs. local in Gutenberg will help us make a better decision here. Cool exploration, and let's keep it in mind for customization post-Gutenberg.

[westonruter]

In 41558:

Customize: Introduce extensible code editor Customizer control for CodeMirror.

• Adds WP_Customize_Code_Editor_Control and wp.customize.CodeEditorControl().
• Control respects user preference for syntax highlighting, showing a textarea when user opts out.
• Code editor control takes the ad hoc code for Additional CSS and makes it reusable and extensible, for Additional CSS in core and plugins to use (such as Jetpack).
• Replace settings arg in wp_enqueue_code_editor() with separate args for codemirror, csslint, jshint, and htmlhint.
• Prefix codemirror script and style handles with wp- to prevent collisions, as also the object is exported as wp.CodeMirror in JS.
• Reduce indent size in Customizer code editor instances and Custom HTML widget to use tab size of 2 instead of 4 to save on space.

See #12423, #38707, #35395.
Fixes #41897.

[westonruter]

The syntax highlighting aspect has landed with #12423. Note the “per-post” aspect has been yanked from consideration for the near future, as it depends on solving the local vs. global issue. So the remaining issues to be considered in the near term are: selector discovery, revisions, and popping the editor out into a new window. Let's work on these issues in a feature plugin outside of core and propose in future release.

[celloexpressions]

#50205 was marked as a duplicate.