När Hemingway mötte Gutenberg

Vi går igenom hur man uppdaterar ett befintligt WordPress-tema med stöd för Gutenberg – den nya inläggsredigeraren i WordPress.

Sedan flera år tillbaka har ett av mina fritidsnöjen varit att designa, utveckla och släppa gratisteman för WordPress på WordPress.org:s temabibliotek. Till dato har jag släppt 17 stycken, och vanligtvis har jag åtminstone ett nytt tema på gång som jag plockar upp och pysslar med när andan faller på. Det var genom mina gratis WordPress-teman jag började få frilansuppdrag av webbyråer och, så småningom, ett jobberbjudande av Thord, men det är en annan historia.

Om du rör dig mycket i WordPress-kretsar så har du troligtvis hört talas om Gutenberg – den nya inläggsredigeraren som kommer att släppas med WordPress 5.0. Gutenberg är den största förändringen av hur man redigerar innehåll i WordPress sedan innehållssystemet först släpptes. Istället för den visuella redigeraren, som påminner om vanliga ordredigerare, kommer Gutenberg att introducera en redigeringsmiljö som är baserad på block.

Varje element i innehållet – textparagrafer, bilder, tabeller, inbäddade videoklipp – är ett block, och varje block har unika inställningar som styr hur blockets innehåll ser ut och fungerar. Om man redigerar ett bildblock kan man till exempel ändra bildens placering, storlek och bildtext.

Gutenbergs redigeringsmiljö, stilad för att matcha Hemingway.

För oss utvecklare introducerar Gutenberg även en del huvudvärk – även om man tycker att Gutenberg är ett steg i rätt riktning för WordPress. I mitt fall betyder Gutenberg att jag måste gå tillbaka till alla mina 17 WordPress-teman och uppdatera dem med stöd för den nya redigeraren. Det är en punkt på min att göra-lista som jag har skjutit på länge, men i takt med att Gutenbergs lansering drar sig allt närmare har det blivit dags att ta itu med den.

För någon vecka sedan satte jag bollen i rullning genom att lägga till Gutenberg-stöd i mitt mest populära tema – Hemingway. I det här blogginlägget tänkte jag gå igenom hur jag gick till väga, och även dela med mig av en checklista som WordPress-utvecklare kan utgå från när de lägger till stöd för Gutenberg i sina teman. Det här inlägget är med andra ord skrivet för utvecklare i första hand. Om du inte är en utvecklare, men ändå är nyfiken på vilka förändringar Gutenberg kommer att föra med sig, så kan du se fram emot ett separat inlägg längre fram.

Så lägger du till Gutenberg-stöd

Gutenberg-uppdateringen av Hemingway bestod av tre delar:

  • Uppdateringar av functions.php för att lägga till ny, Gutenberg-specifik funktionalitet
  • Uppdateringar av temats stilmall för att stödja element och klasser introducerade i Gutenberg
  • En editor-stilmall som gör att Gutenbergs utseende matchar temats utseende

Nedan går jag igenom de tre punkterna steg för steg.

Uppdateringar av functions.php

Gutenberg lämnar det till temautvecklare att bestämma huruvida vissa av Gutenbergs funktioner ska finnas tillgängliga i inläggsredigeraren eller inte. Om man vill underlätta för sig själv kan man utelämna dessa, men ska man lägga till stöd för Gutenberg kan man lika gärna göra det ordentligt.

Hemingway lägger till stöd för tre Gutenberg-funktioner i functions.php: Den nya .alignwide-klassen för innehåll, en färgpalett baserad på de färger som är inkluderade i temat, och ett antal förinställda typsnittsstorlekar som användare kan välja när de redigerar innehåll. Koden ser ut som följande:

function hemingway_add_gutenberg_features() {

	/* Gutenberg Feature Opt-Ins --------------------------------------- */

	add_theme_support( 'align-wide' );


	/* Gutenberg Palette --------------------------------------- */

	$accent_color = get_theme_mod( 'accent_color' ) ? get_theme_mod( 'accent_color' ) : '#1abc9c';

	add_theme_support( 'editor-color-palette', array(
		array(
			'name' 	=> _x( 'Accent', 'Name of the accent color in the Gutenberg palette', 'hemingway' ),
			'slug' 	=> 'accent',
			'color' => $accent_color,
		),
		array(
			'name' 	=> _x( 'Dark Gray', 'Name of the dark gray color in the Gutenberg palette', 'hemingway' ),
			'slug' 	=> 'dark-gray',
			'color' => '#444',
		),
		array(
			'name' 	=> _x( 'Medium Gray', 'Name of the medium gray color in the Gutenberg palette', 'hemingway' ),
			'slug' 	=> 'medium-gray',
			'color' => '#666',
		),
		array(
			'name' 	=> _x( 'Light Gray', 'Name of the light gray color in the Gutenberg palette', 'hemingway' ),
			'slug' 	=> 'light-gray',
			'color' => '#888',
		),
		array(
			'name' 	=> _x( 'White', 'Name of the white color in the Gutenberg palette', 'hemingway' ),
			'slug' 	=> 'white',
			'color' => '#fff',
		),
	) );


	/* Gutenberg Font Sizes --------------------------------------- */

	add_theme_support( 'editor-font-sizes', array(
		array(
			'name' 		=> _x( 'Small', 'Name of the small font size in Gutenberg', 'hemingway' ),
			'shortName' => _x( 'S', 'Short name of the small font size in the Gutenberg editor.', 'hemingway' ),
			'size' 		=> 16,
			'slug' 		=> 'small'
		),
		array(
			'name' 		=> _x( 'Regular', 'Name of the regular font size in Gutenberg', 'hemingway' ),
			'shortName' => _x( 'M', 'Short name of the regular font size in the Gutenberg editor.', 'hemingway' ),
			'size' 		=> 19,
			'slug' 		=> 'regular'
		),
		array(
			'name' 		=> _x( 'Large', 'Name of the large font size in Gutenberg', 'hemingway' ),
			'shortName' => _x( 'L', 'Short name of the large font size in the Gutenberg editor.', 'hemingway' ),
			'size' 		=> 24,
			'slug' 		=> 'large'
		),
		array(
			'name' 		=> _x( 'Larger', 'Name of the larger font size in Gutenberg', 'hemingway' ),
			'shortName' => _x( 'XL', 'Short name of the larger font size in the Gutenberg editor.', 'hemingway' ),
			'size' 		=> 32,
			'slug' 		=> 'larger'
		)
	) );
	
}
add_action( 'after_setup_theme', 'hemingway_add_gutenberg_features' );

I början av ”Gutenberg Palette”-sektionen kan du se att temat läser in en inställning med namnet accent_color. Hemingway ger användarna möjlighet att välja en egen accentfärg för temat i Anpassaren, och som du ser i koden gör Gutenberg det barmhärtigt enkelt att stödja den färgen i temats palett.

Det andra stycket Gutenberg-kod i Hemingways functions.php lägger till en unik stilmall för Gutenberg, som gör att redigerarens utseende matchar temat. Den koden ser ut som följande:

function hemingway_block_editor_styles() {

	$dependencies = array();

	/**
	 * Translators: If there are characters in your language that are not
	 * supported by the theme fonts, translate this to 'off'. Do not translate
	 * into your own language.
	 */
	$google_fonts = _x( 'on', 'Google Fonts: on or off', 'hemingway' );

	if ( 'off' !== $google_fonts ) {

		// Register Google Fonts
		wp_register_style( 'hemingway-block-editor-styles-font', '//fonts.googleapis.com/css?family=Lato:400,700,400italic,700italic|Raleway:700,400', false, 1.0, 'all' );
		$dependencies[] = 'hemingway-block-editor-styles-font';

	}

	// Enqueue the editor styles
	wp_enqueue_style( 'hemingway-block-editor-styles', get_theme_file_uri( '/hemingway-gutenberg-editor-style.css' ), $dependencies, '1.0', 'all' );
}
add_action( 'enqueue_block_editor_assets', 'hemingway_block_editor_styles' );

Den lokaliserade strängen som läses in till variabeln $google_fonts gör det möjligt att avaktivera Google Fonts i temat, om det lokaliseras till ett språk som Google Fonts-typsnitten inte har stöd för. Samma sträng används även när temats stilmall läses in.

De här två funktionerna lägger till all Gutenberg-relaterad funktionalitet i Hemingway, vilket betyder att det enda som återstår är att lägga till CSS för Gutenberg i temats stilmall och i hemingway-gutenberg-editor-style.css.

Uppdateringar av temats stilmall

De goda nyheterna för WordPress-utvecklare är att den markup som Gutenberg genererar i mångt och mycket matchar den som den visuella redigeraren har spottat ur sig i alla år. Om du installerar Gutenberg-tillägget, skapar ett testinlägg och visar det i ditt tema så bör det mesta se ut som det ska.

Gutenberg introducerar dock en del nya block och klasser som kan kräva en del uppdateringar i ditt temas stilmall. WordPress inkluderar egen CSS för vissa av dem, men den kan behöva anpassas för att passa in med resten av elementen i ditt tema.

De nya elementen som du kan behöva hålla lite extra koll på är:

Cover images

En ny, fullbred bildtyp med en rubrik placerad ovanpå bilden. I Hemingways fall var WordPress inbyggda Gutenberg-CSS tillräcklig för att det här blocket skulle se ut som det ska utan justeringar.

.alignwide-klassen

Förutsätter att du har specificerat att ditt tema har deklarerat stöd för Gutenbergs alignwide-inställning i functions.php (se rubriken högre upp i inlägget). Den här klassen är avsedd för innehåll som är bredare än innehållsbredden, men inte sträcker sig hela vägen ut till webbläsarens fönster (som .alignfull). .alignwide-klassen kan anges för bland annat bilder och blockcitat.

.alignleft och .alignright

De här klasserna har förstås använts för höger- och vänsterställda bilder i WordPress i alla tider, men Gutenberg låter användare tillämpa dem på nya element – citat, tabeller, och så vidare. Om du bara har stilat bilder med .alignleft/-right, genom att till exempel pricka av .wp-caption.alignleft, så kan du behöva uppdatera din CSS för att det här ska fungera för övriga element.

Temaspecifika färgpaletter och typsnittsstorlekar

add_theme_support()-anropen som jag beskrev för att lägga till färgpaletter och typsnittsstorlekar ovan kräver tillhörande CSS för att ändringarna ska reflekteras på webbplatsen. Om besökare t.ex. anger färgen med sluggen ”accent” som bakgrundsfärg på ett block kommer det blocket att få klassen .has-background-accent, och temat måste ange vilken bakgrundsfärg element med den klassen ska ha i temats stilmall. Helt klart att föredra framför att färgerna anges som style-attribut. Hurr.

En paragraf med anfang i Gutenberg.
Anfang-stil

Anfang (“drop caps” på engelska), är när den inledande bokstaven i en paragraf sträcks ut till flera raders höjd i texten. WordPress inkluderar en standard-stil för anfang som gör att de visas på tre rader, men man kan vilja justera utseendet på anfanget i temat. I Hemingway ändrade jag anfanget till att ta upp två rader och vara fetstilat.

<hr/>-stil

Gutenberg-blocket för en separator, HTML-elementet <hr/>, inkluderar inställningar för hur separatorn ska visas – kort, lång eller prickad (den senare spottar ut tre prickar som ett pseudoelement). Även här har WordPress standardstilar inkluderade, och även här kan du vilja göra vissa justeringar i ditt tema.

Pullquote-stil

Utöver ett vanligt citat-block har Gutenberg även ett block för “pull quotes” – citat som innehåller utdrag från texten. Dessa flyter vanligtvis till höger eller vänster om resten av innehållet på större skärmar. De vänster- och högerställda varianterna av blocket använder .alignleft och .alignright-klasserna.

Stilmall för Gutenberg-redigeraren

Det andra kodblocket under functions.php-rubriken högre upp i inlägget beskriver hur man går till väga för att ange en innehållsredigerare-stilmall (editor style) för Gutenberg. Om du någon gång har skapat en stilmall för den visuella innehållsredigeraren i WordPress så bör det här kännas ganska bekant.

Precis som i den visuella redigeraren innehåller WordPress en basuppsättning av stilar för redigeraren, och du kan komplettera den med CSS i temat som gör att redigeraren matchar temats utseende. Det här är ett utdrag från Hemingways innehållsredigerare-stilmall för Gutenberg:

/*---------------------------------------------------------------------------------
	Gutenberg editor styles for Hemingway
---------------------------------------------------------------------------------*/


/* Structure ---------------------------------------------- */


.edit-post-visual-editor {
	color: #444;
	font-family: 'Lato', sans-serif;
	font-size: 19px;
}

body.gutenberg-editor-page .editor-post-title__block,
body.gutenberg-editor-page .editor-default-block-appender,
body.gutenberg-editor-page .editor-block-list__block {
    max-width: 676px;
}

body.gutenberg-editor-page .editor-block-list__block[data-align="wide"] {
    max-width: 756px;
}

body.gutenberg-editor-page .editor-block-list__block[data-align="full"] {
    max-width: none;
}


/* Typography --------------------------------------------- */


.edit-post-visual-editor a {
	color: #1abc9c;
}

.edit-post-visual-editor p,
.editor-post-title__block .editor-post-title__input {
	font-family: inherit;
	font-size: inherit;
}

.wp-block-heading h1,
.wp-block-heading h2,
.wp-block-heading h3,
.wp-block-heading h4,
.wp-block-heading h5,
.wp-block-heading h6 {
	font-weight: 700;
	line-height: 1.2;
}

.wp-block-heading h4,
.wp-block-heading h5 {
	font-weight: 400;
}

.wp-block-heading h1 { font-size: 2em; }
.wp-block-heading h2 { font-size: 1.75em; }
.wp-block-heading h3 { font-size: 1.5em; }
.wp-block-heading h4 { font-size: 1.25em; }
.wp-block-heading h5 { font-size: 1.1em; }

Gutenberg-checklistan

I och med att jag kommer att behöva upprepa den här processen ytterligare 16 gånger, för resten av mina teman, dokumenterade jag varje steg från uppdateringen av Hemingway i en Gutenberg-checklista. Den checklistan kommer att fungera som utgångspunkt när jag lägger till stöd för Gutenberg i mina övriga teman.

Om du också är i processen med att lägga till stöd för Gutenberg i dina teman så hoppas jag att den kan hjälpa dig en bit på vägen.

# Gutenberg Theme Checklist

## functions.php
- [ ] Add custom colors in functions.php
- [ ] Add the .has-accent-color style to the custom accent color function, if one exists
- [ ] Add support for alignwide
- [ ] Add support for custom font sizes
- [ ] Add Gutenberg editor styles
 
## style.css
- [ ] Cover image styling (+ responsive)
- [ ] .alignfull and .alignwide styling (+ responsive)
- [ ] Generic figure/figcaption styling, if missing
- [ ] Style .alignwide
- [ ] Add styling for custom colors
- [ ] Add styling for custom font sizes (em-based, apply once)
- [ ] Add drop-cap styling
- [ ] Add styling for the <hr/> element, with long and dotted variations
- [ ] Add styling for pullquote

## [theme]-gutenberg-editor-style.css
- [ ] Set body color, font family and base font size
- [ ] Set max-widths of basic blocks, wide, full
- [ ] Match link color, titles, dropcap and blockquote to style.css
- [ ] Add styling for the <hr/> element, with long and dotted variations
- [ ] Add styling for pullquote
- [ ] Match table styling to post-content