Tag: javascript

As I’ve mentioned a few times, one of the ways you can adjust settings on a block in Gutenberg is via the sidebar. In fact, this is the default way most people will interact with block settings.

If you make a paragraph today, you can see it like this:

But. I don’t actually like it very much. I appreciate that I have it, and I love that I can get it out of the way. But sometimes I like settings to be a little more contextual.

It’s Easy to Add Sidebar Settings

One of the reasons we all use sidebar settings is that, well, they’re easy. When I built out my listicles plugin, I could use the inspector controls and automagically I have my own settings.

This:

<InspectorControls>
	<PanelBody title={ 'Listicle Settings' }>
		<RangeControl
			label={ 'Items' }
			value={ items }
			onChange={ ( value ) => setAttributes( { items: value } ) }
			min={ 1 }
			max={ MAX_ITEMS }
		/>
		<ToggleControl
			label={ 'Reversed' }
			help={ ( checked ) => checked ? 'Reversed order (10 - 1)' : 'Numerical order (1 - 10)' }
			checked={ props.attributes.reversed }
			onChange={ () => props.setAttributes( { reversed: ! props.attributes.reversed } ) }
		/>
	</PanelBody>
</InspectorControls>

Looks like this:

But like I said, I don’t like it very much. It’s clunky, it’s touchy, if you delete the number and type in a new one it’ll wipe all your data. And worst of all, my partner in crime, Tracy, hates it. If your work partners hate a tool, then it’s serious problem. I’ll put up with annoyances to me, but I’ll learn new code for the team.

Think About What’s Easier

Before I get into the code I used to solve the issue, I want to take a moment to talk about theory and understanding usage.

One of the critiques about Gutenberg is that it’s changing too much too quickly, and it’s not listening to users. The problem with that complaint is it lacks context. I’m big on context because I believe that only with understanding the usage and context can we as a whole make the correct decisions going forward. What changes, when, and why depends entirely on what’s being used, for what, and why.

It’s much more direct to understand this when I look at my little listicles block. You see, we use it for one thing: to make lists with a specific format. And we have few requirements.

• Add and remove items
• Add content of myriad types to each item
• Be able to reverse the item count (1 to 10 or 10 to 1)

That’s really it. Except now I’m adding one more thing:

• An easier, inline, way to add/remove/toggle items.

So I sat and I thought about what would be the easiest to use, and I came up with a simple solution. Three buttons, one to add an item, one to remove, and one to toggle the order. Have those show perpetually at the bottom of the list, and you could easily add and remove as needed.

It’s Actually Easy To Add Buttons

Once I knew what I wanted, I took a page from some work Yoast is doing and sketched my idea to look like this:

In order to do this, I needed to add some code to the bottom of my <dl> code:

<div className='listicles-buttons'>
	<IconButton
		icon='insert'
		onClick={ () => setAttributes( { items: parseInt(`${ items }`)+1 } ) }
		className='editor-inserter__toggle'
	>Add Item</IconButton>

	<IconButton
		icon='dismiss'
		onClick={ () => setAttributes( { items: parseInt(`${ items }`)-1 } ) }
		className='editor-inserter__toggle'
	>Remove Item</IconButton>

	<IconButton
		icon='controls-repeat'
		onClick={ () => setAttributes( { reversed: ! reversed } ) }
		className='editor-inserter__toggle'
	>Toggle Order</IconButton>
</div>

This sits inside the <dl> and just below my <InnerBlocks...> insert. It generates the buttons, which change when you hover by default.

Now it’s not perfect. If you deleted all the items and pressed delete again, it would sure try to delete. I didn’t put in checks to make sure we didn’t go below 0 or above 18 (which is my current limits). But this is the start to make sure we can keep improving and iterating.

While I did write up Spoiler Blocks for Gutenberg one way, I also sat down recently and rewrote it a little cleaner. The primary difference here is how I’m properly using defaults:

The Code

( function( blocks, element, editor, components ) {

	const { registerBlockType } = blocks;
	const { RichText } = editor;
	const { createElement } = element;
	const { InspectorControls } = editor;
	const { SelectControl, ToggleControl } = components;

	registerBlockType( 'library/spoilers', {
		title: __( 'Spoiler Warning' ),
		icon: 'vault',
		category: 'halfelf',
		customClassName: false,
		className: false,
		attributes: {
			content: {
				source: 'children',
				selector: 'div',
				default: 'Warning: This post contains spoilers!'
			}
		},

		save: function( props ) {
			const content = props.attributes.content;
			const container = createElement(
				'div', { className: 'alert alert-danger' },
				React.createElement( RichText.Content, { value: content })
			);
			return container;
		},

		edit: function( props ) {
			const content = props.attributes.content;
			const focus = props.focus;

			function onChangeSpoiler( newContent ) {
				props.setAttributes( { content: newContent } );
			}

			const editSpoiler = createElement(
				RichText,
				{
					tagName: 'div',
					className: props.className,
					onChange: onChangeSpoiler,
					value: content,
					focus: focus,
					onFocus: props.setFocus,
				}
			);

			return createElement(
				'div', { className: 'alert alert-danger' },
				editSpoiler
			);
		},

	});

})(
	window.wp.blocks,
	window.wp.element,
	window.wp.editor,
	window.wp.components,
	window.wp.i18n
);

Learning more and more about Gutenberg, and javascript, I’ve been able to iterate on the existing code and keep improving.

Making a straight forward block to insert content in Gutenberg is (relatively) easy. I hate using the word ‘easy’ here, because in order to do it you will need to master a whole new world of coding, but all things considered, yes. It is easy. In fact, Gary (aka Pento) wrote a sample plugin that will let you convert a shortcode to a Gutenberg Block.

I myself have written a mildly complicated Spoiler Block (there’s a new version of it I will share soon). But then the day happened that my cohort in lesbian TV crime, Tracy, expressed annoyance at how Gutenberg destroyed her listicle.

What is a Listicle?

Have you seen those posts that show you the top ten ways to LifeHack your used egg cartons? Those are listicles. They’re lists (list) articles (icle). Makes sense, right? Listicles have a pretty basic format as well, there will be a header with some sort of numerical mark, then content with images etc. This repeats for the number of times you have an article.

Most people make them by hand by manually editing the numbers in their header. That’s all well and good until you want to craft better formatting and have a listicle look somehow ‘different’ from the rest of your content. Maybe you want them to have a special background color, or a different design for the header. 

If we were doing this in the old, simple, HTML way, it would look like this:

<dl class="listicle">
    <dt>The Title</dt>
    <dd>The Content</dd>
</dl>

Of course that doesn’t make anything look like a list until you put in some CSS magic:

.listicle {
  counter-reset: listicle-counter;
}

.listicle dt:before { 
    content: counter(listicle-counter);
    counter-increment: listicle-counter;
    margin-right: 6px;
}

What this does is create a CSS counter and increment it every time you use <dt> creating an auto incrementing list.

No HTML for Gutenberg

Now, if you know the HTML, you can still do this in Gutenberg in HTML by using the HTML block.

But if you don’t know HTML, then this is a bloody nightmare to handle. And part of the reason why I’m very pro-Gutenberg is that it’s 2018, and expecting people to know all the myriad magical steps of HTML, in order to create a webpage, feels passé. No, it feels restrictive. We can’t expect websites to advance and become more than just pages if we don’t give them the tools.

Complex Design

Unlike the relatively simple javascript I used to make my Spoiler Box block, to do this requires the use of a feature called ‘Inner Blocks‘ which is effectively putting a block inside a block. 

My original idea was to have a multiple nested block with the following:

1. Listicle Block that calls a template of a list item
2. ListItem block that calls a title and description
3. ListDT block that calls the title
4. ListDD block that allows you to add whatever more inner blocks you want

It sounds incredibly complicated, and sadly the perfect version was so difficult I actually started with a pared down version.

1. Listicle block that sets up a template of title and description

The problem here is that I end up having a separate dl for each block. I can work around it with some CSS magic, but it’s not perfect. So I knuckled down and actually wrote the code that does exactly what I want. Whew.

Some Code

… Actually I’m going to do something I hate and that’s link to an external directory.

I’ve build out Listicles for Gutenberg for you to peruse and fork and enjoy. Or even use if you want, becuase it does work. But it’s big. No, it’s huge for an in-post example. And to explain everything line by line wouldn’t help.

If you go to the repository, the Gutenberg source code is located in /src/ – that’s where most (if not all) of your work will happen.

• blocks.js – A list of all the separate JS files included
• /block/listicle.js – The main listicle file
• /block/listitem.js – Individual list items (this is only usable inside the Listicles block)
• /block/listdt.js – The list title
• /block/listdd.js – The list content (this allows you to add as many sub blocks as you can)

And yes, not only does it auto increment as you move the slider (or bump the counter), you can flip it into reverse mode:

The real trick of it all was the copious use of templates.

It’s all Complicated

Besides the fact that the blocks aren’t quite  where I want them to be, I also have to use a block builder to convert that javascript into my real files. I chose the Create Guten Block builder, instead of building out my own NPM build script.

That too illustrates some of the concerns people have, and rightly so, about blocks being incredibly more complicated than they need to be. And yet, having gone through the exercise myself, I think that it’s perhaps not going to be that much of a drama.

For those of use who generally just make new shortcodes, the world won’t change too much. Gutenberg supports inline shortcodes, after all, which is the majority of what people need from it. We want to be able to make our own embed blocks, which again isn’t terrible, and when someone gets to the complicated point of needing something advanced like a listicle, well eventually there will be a plugin that will handle this better than a shortcode.

Or you could just use that HTML block.