I haven’t written a lot on this blog besides some tutorials for clients that see very little use, so I decided to do some work journaling. It may continue for a long while, it may go on for a few months and stop, or this might be it.
In the end, it doesn’t hurt to try, so here goes nothing.
(It’s obligatory for tech blog posts to use vaguely related pop culture gifs for SEO or whatever.)
Creating Custom WordPress Editor Blocks (AKA Gutenberg Blocks)
In late December, I got a message from one of my old clients in Denver that they needed help for launching a website dealing with funding and planning for retirement.
The “they” was my client who is also a freelancer web developer who has his own client which is a web design agency based in Denver, whose client is an insurance company, which is owned by another company and owns this company as a wholly owned but separate company based in Denver… still with me?
“They” wanted a better-looking website. Lucky for “them”, “we” knew how to do that.
Learning About Blocks
We (my freelance developer client, me, and someone else he hired) were given designs (professionally known as “comps” because every industry needs to keep the outsiders confused) by the designers. We were asked to make it so that someone without much tech experience could build and edit the pages based of the designs. In other words, we weren’t building the website, but building the ability to build the website.
To get started, we needed to pick the right page builder to implement this. We narrowed it down to 3 options: Advanced Custom Fields, Divi Builder, and the newly-implemented WordPress Block Editor.
Each had their pros and cons:
- Advanced Custom Fields would be the fastest to implement, but wouldn’t provide very much flexibility to the end-user. It isn’t a page builder, meaning it’s much easier to control and is a favorite among developers in WordPress, but can provide the same features necessary for a page builder in narrow situations.
- Divi Builder would provide more of what we needed out-of-the-box, but would be harder to modify and implement since it’s proprietary. Many of the elements needed (cover images, stylized header and paragraph text, options for paddings and margins, etc) would already be provided, but it would be hard to modify the output to our specific needs and make things “update-proof”, meaning if the plugin that provides the functionality has an update, it’s possible any modifications we make wouldn’t interact well with the update and break things.
- The WordPress Block Editor, known as the “Gutenberg Editor” pre-release, would be the much more future-proof than any 3rd-party visual editor on the market since it’s baked into WordPress as of early December and is meant to replace the need to install a separate visual editor (meaning that this is probably the beginning of the end for page builders like Divi Builder). However, being a newly released piece of software, it’s prone to bugs that were not caught in development and lack of documentation and support. Plus, none of us had any experience working with the new block editor, besides me, who had just used it experimentally on my travel blog.
In the end, we decided on the WordPress Block Editor. Even though it had its fair share of disadvantages, it was (and still is) the direction that WordPress was going. Also, it wouldn’t hurt to learn something new… well it wouldn’t hurt a lot.
Working with Blocks
We split the work up between creating the blocks themselves, working on backend functions like site analytics, and universal site elements like headers, footers, menus, etc.
I took the task of working with and creating the blocks since I was the most eager to learn it and had the most experience with it, using it experimentally for one or two posts… like that scene in Inglourious Basterds where they’re talking about who knows the most Italian, then Brad Pitt says that he speaks the most Italian (very little), one of the other guys speaks the 2nd-best Italian (basically none), and the last guy speaks the 3rd-best Italian of them (none at all).
Hey look! Another opportunity for pop culture gifs!
I went through the somewhat helpful but also somewhat dry and time-intensive Writing Your First Block Type tutorial on wordpress.org.
Once I got through it, I needed to create what was required for the different block types throughout the site, being design components like:
- Hero images
- Headers (with and without images or pre-approved background & text color combos)
- Subheaders (also with pre-approved colors)
- Stylized buttons
- Icons
- Quotes
The tutorial was helpful for the basics, but the basics weren’t what we needed. Even though these components are all available in some form out-of-the-box with WordPress, there were specific needs that weren’t provided for in the core components, like putting more than just one line of text on hero/cover images, making header text whatever color you want, having specific shading for icon backgrounds (using image blocks), etc.
There is a dearth of documentation on Stack Overflow and similar sites on many different use cases of custom WordPress blocks, so the going was rough in the beginning. Further, WordPress blocks are based on React, which is a JavaScript library that I had no experience with and works much different than the JavaScript that I’ve worked with before.
There were also a fair share of issues that almost halted progress entirely until workarounds were found, like this issue here, which I participated in to get a usable workaround and which is still an open issue as of the writing of this article.
I figured it out little-by-little and, soon enough, I suddenly became comfortable and much quicker in developing custom WordPress blocks.
Eventually I created all the components and all was theoretically good, the keyword there being theoretically.
Block Creation, Phase 2
I created these blocks exactly to what the design said was needed. However, the design wasn’t built with the block editor in mind and what are different components in design end up not working as well for different components in development.
I was violating development process note #5 in this helpful Notes to Myself on Software Engineering.
When you say yes to a request for supporting a new use case, remember that literally adding what the user requested is often not the optimal choice. Users are focused on their own specific use case, and you must counter this with a holistic and principled vision of the whole project. Often, the right answer is to extend an existing feature.
François Chollet on medium.com
Luckily I had the opportunity to follow note #7.
It’s okay not to plan everything in advance. Try things and see how they turn out. Revert incorrect choices early. Make sure you create an environment where that is possible.
François Chollet on medium.com
We got the rare opportunity to see how the software would be used in the wild before finishing the project. The project team built out some of the pages as if they were the client. Many of the necessary designs required different styling options than initially anticipated.
Many revisions were also required for block functionality as testing went on. The way I built it at first required me to individually edit and test every single block which used different-yet-similar code for these functions and the revisions became time-consuming.
At first I tried combining the blocks into one file so they could share functions and variables and so I could edit them once across the board, but then something much simpler came to mind. Why didn’t I combine all these similar components into one block with different stylings instead of needlessly separating them into different blocks? Many of the separate design components worked the same upon functional implementation. My mind was too wrapped up the original requests when I first made the blocks, but once I saw them in action it dawned on me how to make the whole process much easier.
The end result did away with the different blocks for Header Sections, Subheader Sections (originally built with 1-column and 2-column variations), Button Container Sections (for spacing purposes), and Column Container Sections (for spacing and styling purposes).
What replaced them was one block called the “{Undisclosed Company Name} Container”, which was capable of having any background color needed with selectable colors from the official design color palette, gradient backgrounds, or image background, had a few different styling choices based on common margins and paddings (e.g. 72px vertical padding sections vs 72px top-padding w/ 48px bottom-padding).
Also, the original blocks restricted what could be hosted inside as “Inner Blocks” to limit unintended bugs and consequences, but this also limited flexibility and control for the end user. In the “{Undisclosed Company Name} Container” block, we removed the restrictions so the end user would have the ability to host any other block type inside of it like WP core headings, paragraphs, columns, images, buttons – you name it!
The added flexibility made it much easier to move from design to reality and it had a lot less bugs than originally thought.
And finally, we needed to create capabilities for text styling, coloring, and positions not wholly availably in WordPress core blocks. Initially I thought we might have to create these from scratch, but found that core block functions could be extended. That way, instead of reinventing the wheel for common blocks already provided in WordPress, like headings and paragraphs, we extended the functionality of these blocks to meet the needs. This is also relatively update-proof in WordPress, since everything is designed to extend and modify functionality as needed with the framework from the start (that’s where the whole concept of plugins comes from).
Lessons Learned
Of course, it would have been nice to know to build out the website that way from the start, but hindsight is always 20/20 and the first variation of software is almost never truly meets the needs of the client – you would be hard-pressed to find anything with this circumstance that wasn’t complex and/or worthwhile.
This is why UX specialists always tell developers to see people use the software in action – it can be frustrating watching people fail to use what you thought was a perfectly developed piece of technology. You can either instruct every user on how to use your software, or you can admit that attempt #1 maybe wasn’t perfect and take steps to make your software easier to use based on user feedback.
The main takeaway here for me would probably be “test sooner and ask more questions”. Luckily we tested building out the pages partway through the process, so we caught these issues before it was too late instead of scrambling to fix things at the end. Also, I asked plenty of questions whenever I felt it was necessary, but I’ll err on the side of even earlier clarification and testing in the future.
Miscellaneous Updates
This project has been a big part of my work life the last 1.5 months, but it hasn’t been the only thing happening with it.
Working from Argentina
Some of you may know that in early October I moved to Argentina. This is a topic more reserved for my travel blog (there I go promoting myself again), but I’ll say a bit about it here.
I decided since I was working 100% remotely in the US, I might as well do the same thing abroad. My client base hasn’t expanded here, but that’s alright since I’ve had plenty of work with my clients in the US. In fact, it’s been a little easier since I wake up a little later than most people, and Argentina is 4 hours ahead of Denver (3 hours after daylight savings time).
I joined the WordPress community here and went to WordCamp Montevideo last November (Montevideo is just a day’s journey by boat and bus from Buenos Aires). Then in December at the Buenos Aires WordPress meetup, I did a 6-minute mini-presentation on how to create custom post types (in Spanish). The slides available here if you’re curious.
On top of it all, I’ve saved a ton of money on rent and general living costs. This is allowing me to devote more time to side-projects such as…
My First WordPress Plugin
It’s not actually out as of the time of this writing… but it’s 1 bug fix away.
It’s not a complex plugin, but I’ve learned a bit more about the inner workings of WordPress by building it. And in fact, the beta is already live on this site.
If you’re on a real computer and not on your phone, you can see it to your left in the form of the table of contents. There were some plugins in the WordPress plugin repository that did this already, but not entirely in the way that I wanted to do it, so I created my own.
A WordPress user will be able to install it on their site and it will automatically grab the headers from a page or post and makes them clickable links to easily navigate long-form, well-structured text. Try it out if you haven’t.
If it gets used a lot by people, I will be happy to have made a positive impact and may add some new features to it if it makes sense. If not, I am happy to have a good learning experience.
For my next software project, I’m going to try and create something a bit more meaningful for me, perhaps something to do with languages or travel. It’s still in the vague early idea stages… but I’ve got some ideas.