Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update theme extensibility documentation to include editor widths #6531

Merged
merged 3 commits into from May 2, 2018

Conversation

@jasmussen
Copy link
Contributor

commented May 2, 2018

This updates the extensibility document, and adds a section around loading editor styles. It gives examples for how to change the colors of the editor (which will look good once #6406 gets merged), as well as how to change the width of the editor. The last part fixes #1483.

CC: @maddisondesigns

Update theme extensibility documentation to include editor widths
This updates the extensibility document, and adds a section around loading editor styles. It gives examples for how to change the colors of the editor (which will look good once #6406 gets merged), as well as how to change the width of the editor. The last part fixes #1483.

CC: @maddisondesigns

@jasmussen jasmussen self-assigned this May 2, 2018

@jasmussen jasmussen requested a review from WordPress/gutenberg May 2, 2018

@samikeijonen

This comment has been minimized.

Copy link
Contributor

commented May 2, 2018

Is there anything we can do with these long nesting CSS body.gutenberg-editor-page .edit-post-visual-editor .editor-post-title?

Other than that +1 for updating the docs.

@jasmussen

This comment has been minimized.

Copy link
Contributor Author

commented May 2, 2018

Is there anything we can do with these long nesting CSS body.gutenberg-editor-page .edit-post-visual-editor .editor-post-title?

Long term, yes, the goal is to continue to polish and refactor so that ideally you don't have to write a separate editor stylesheet at all, but we can load the theme stylesheet in directly. This is a north star, but is also somewhat utopian. Nonetheless sort of an umbrella goal is to make it as easy as possible for the theme developer.

We're not there yet, though, and in order for you to be able to style the theme width, you have to add some specificity to the selector so it overrides the base styles.

However I did manage to simplify it a little bit:

/* Main column width */
body.gutenberg-editor-page .editor-post-title,
body.gutenberg-editor-page .editor-default-block-appender,
body.gutenberg-editor-page .editor-block-list__block {
	max-width: 720px;
}

/* Width of "wide" blocks */
body.gutenberg-editor-page .editor-block-list__block[data-align="wide"] {
	max-width: 1080px;
}

/* Width of "full-wide" blocks */
body.gutenberg-editor-page .editor-block-list__block[data-align="full"] {
	max-width: none;
}

Also added the default block appender there, which I'd missed previously.

Further interim improvements can probably come as part of #5360.

@youknowriad
Copy link
Contributor

left a comment

Nice addition

@@ -91,3 +91,69 @@ add_theme_support( 'disable-custom-colors' );
```

This flag will make sure users are only able to choose colors from the `editor-color-palette` the theme provided or from the editor default colors if the theme did not provide one.


This comment has been minimized.

Copy link
@youknowriad

youknowriad May 2, 2018

Contributor

Are the extra spaces between sections necessary? Maybe we should remove them in a effort to be consistent with the rest of the docs

This comment has been minimized.

Copy link
@jasmussen

jasmussen May 2, 2018

Author Contributor

Ack, those are from my markdown editor. I'll clean it up in a normal text editor before I merge. Thanks!

@jasmussen jasmussen merged commit 5689341 into master May 2, 2018

2 checks passed

codecov/project 43.99% (-0.01%) compared to f3f59d2
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@jasmussen jasmussen deleted the add/theme-width-docs branch May 2, 2018

@tofumatt
Copy link
Member

left a comment

I have some copy edit changes here as I think the docs could be clearer, but looks like I missed this one. I'll submit another PR with my tweaks.


### Basic colors

You can style the editor like any other webpage. Here's an example for how to change the background color and the font color. Paste this in your `style-editor.css `file:

This comment has been minimized.

Copy link
@tofumatt

tofumatt May 2, 2018

Member

Nitpick but the style-editor.css section has the space inside the backtick when it should come after.

This comment has been minimized.

Copy link
@tofumatt

tofumatt May 2, 2018

Member

Also the second sentence could be more direct:

 Here's how to change the background color and the font color to blue:

### Add the stylesheet

First thing you need to do is to enqueue the new editor style. Like this:

This comment has been minimized.

Copy link
@tofumatt

tofumatt May 2, 2018

Member

This is missing an article and the next sentence is a fragment. It might read better as:

The first thing to do is enqueue the new editor style:

```
/**
 * Enqueue block editor style
 */
function mytheme_block_editor_styles() {
	wp_enqueue_style( 'mytheme-block-editor-styles', get_theme_file_uri( '/style-editor.css' ), false, '1.0', 'all' );
}
add_action( 'enqueue_block_editor_assets', 'mytheme_block_editor_styles' );
```
add_action( 'enqueue_block_editor_assets', 'mytheme_block_editor_styles' );
```

Now create a new stylesheet, `style-editor.css` and save it in your theme directory.

This comment has been minimized.

Copy link
@tofumatt

tofumatt May 2, 2018

Member

"Now" is a strange word here, this might read better without:

Create a new stylesheet, `style-editor.css`, in your theme directory.
}
```

This will make your editor use blue shades.

This comment has been minimized.

Copy link
@tofumatt

tofumatt May 2, 2018

Member

This could be removed as it adds nothing for anyone who knows CSS already, especially if the above changes were made that reference the colour first.


### Changing the width of the editor

If you'd like to change the main column width of the editor, you can add the following to your `style-editor.css` file:

This comment has been minimized.

Copy link
@tofumatt

tofumatt May 2, 2018

Member

"If you'd like " just clutters up the sentence here so it could be removed; trimming this down to:

To change the main column width of the editor, add the following CSS to `style-editor.css`:

## Editor styles

A theme can provide a stylesheet to the editor itself, to change colors, fonts, and any aspect of the editor.

This comment has been minimized.

Copy link
@tofumatt

tofumatt May 2, 2018

Member

The comma usage here confused me, I think the first one is a semicolon really. How about:

A theme can provide a stylesheet that will style the editor. You can use this to change colors, fonts, and any other visual aspect of the editor.
@paulwilde

This comment has been minimized.

Copy link
Contributor

commented May 2, 2018

It would make sense to just introduce a add_theme_support( 'editor-width', '720px' ); option, where Gutenberg could then simply just use get_theme_support( 'editor-width' ); to determine if the width has been set, then apply inline styles after the main editor style has been enqueued. Then there is no backwards compatibility concerns.

It could be enhanced to support an array of options:

add_theme_support( 'editor-width', [
    'normal' => '720px',
    'wide' => '1080px',
    'full-wide' => 'none',
] );

Likewise with the background/text colours:

add_theme_support( 'editor-color', [
    'background' => '#d3ebf3',
    'text' => '#00005d',
] );
@paulwilde

This comment has been minimized.

Copy link
Contributor

commented May 2, 2018

Having just read the latest update to #6406 I would actually encourage to go with something like I've suggested above. You could then use get_theme_support( 'editor-color' ) to fetch the background colour, and then use PHP to determine if the background colour is dark and then apply is-dark-theme onto the body.

@jasmussen

This comment has been minimized.

Copy link
Contributor Author

commented May 2, 2018

@tofumatt

I'll submit another PR with my tweaks.

👍 👍 thank you.

It would make sense to just introduce a add_theme_support( 'editor-width', '720px' ); option, where Gutenberg could then simply just use get_theme_support( 'editor-width' ); to determine if the width has been set, then apply inline styles after the main editor style has been enqueued. Then there is no backwards compatibility concerns.

Likewise with the background/text colours.

I don't disagree, but I think it's a gray-area. The fact that you can change these things with CSS gives you more freedom to make the editor match your specific theme itself, where explicit PHP functions slightly handcuff you. For example maybe you'd like to have a post title that's much wider than the body text, or perhaps you're not using a flat background color but a gradient or a background image.

That's not a blanket statement that you don't have a point, you absolutely do, and it falls into that whole area that we should definitely make this easier for the themer than it is today, and suggestions like yours could pave the way towards that. I'd probably thumb up a PR, for example.

@paulwilde

This comment has been minimized.

Copy link
Contributor

commented May 2, 2018

I don't disagree, but I think it's a gray-area. The fact that you can change these things with CSS gives you more freedom to make the editor match your specific theme itself, where explicit PHP functions slightly handcuff you. For example maybe you'd like to have a post title that's much wider than the body text, or perhaps you're not using a flat background color but a gradient or a background image.

Adding my suggestion wouldn't handcuff things in anyway though. You can still apply styles like in your documentation example, even with such an add_theme_support in place. This is more of a convenience helper where backwards compatibility is taken care of.

If I build a site with those styles applied, and at some point in the future Gutenberg (or WordPress 5.0+ at that point) adds some new UI which also requires the width being set, the site would require a manual update in order for that width to line up with everything else.

It's very common that sites (especially smaller low budget ones) are one and done for agencies when built (outside of WP & plugin updates), where you cannot dedicate the time/resources to go in and update styles like this for each and every site.

Just playing devils advocate really.

@paulwilde

This comment has been minimized.

Copy link
Contributor

commented May 2, 2018

If my suggestion is something which would be considered though, do let me know and I can whip up a PR when I have time.

@jasmussen

This comment has been minimized.

Copy link
Contributor Author

commented May 2, 2018

If my suggestion is something which would be considered though, do let me know and I can whip up a PR when I have time.

I personally think it does make sense. I'd love for such a PR, feel free to CC me. @youknowriad would you have any concerns with such functions file additions?

@youknowriad

This comment has been minimized.

Copy link
Contributor

commented May 2, 2018

Yes, this looks like a reasonable addition but I have some concerns:

I feel like it can be introduced at anytime and we may want to wait a bit to see what themes do with Gutenberg before committing to an API.

@hvianna

This comment has been minimized.

Copy link

commented May 2, 2018

Forgive me if this is not the best place to ask, but is there any way to detect the current page/post classes in Gutenberg? It would be nice to have the front-end body classes available somewhere in Gutenberg's structure, like we had in the classic editor, so we could adjust the CSS to different page templates.

Edit: added this suggestion to the main issue discussion.

ryanwelcher added a commit to ryanwelcher/gutenberg that referenced this pull request May 4, 2018
Update theme extensibility documentation to include editor widths (Wo…
…rdPress#6531)

* Update theme extensibility documentation to include editor widths

This updates the extensibility document, and adds a section around loading editor styles. It gives examples for how to change the colors of the editor (which will look good once WordPress#6406 gets merged), as well as how to change the width of the editor. The last part fixes WordPress#1483.

CC: @maddisondesigns

* Simplify syntax a bit.

* Trim whitespace
tofumatt added a commit that referenced this pull request May 4, 2018
docs: Copy edits to theme extensibility
Improve theme extensibility docs with copy edits; simplify changes made in #6531.
@tofumatt tofumatt referenced this pull request May 4, 2018
4 of 4 tasks complete
tofumatt added a commit that referenced this pull request May 5, 2018
docs: Copy edits to theme extensibility (#6601)
Improve theme extensibility docs with copy edits; simplify changes made in #6531.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.