CSS Algorithms

I wouldn’t say the term “CSS algorithm” has widespread usage yet, but I think Lara Schenck might be onto something. She defines it as:

a well-defined declaration or set of declarations that produces a specific styling output

So a CSS algorithm isn’t really a component where there is some parent element and whatever it needs inside, but a CSS algorithm could involve components. A CSS algorithm isn’t just some tricky key/value pair or calculated output — but it could certainly involve those things.

The way I understand it is that they are little mini systems. In a recent post, she describes a situation involving essentially two fixed header bars and needing to deal with them in different situations. In this example, the page can be in different states (e.g. a logged-in state has a position: fixed; bar), and that affects not only the header but the content area as well. Dealing with all that together is a CSS algorithm. It’s probably the way we all work in CSS already, but now have a term to describe it. This particular example involves some CSS custom properties, a state-based class, two selectors, and a media query. Classic front-end developer stuff.

Lara is better at explaining what she means though. You should read her initial blog post, main blog post, collection of examples, and talk on the subject.

She’ll be at PPK’s CSS Day in June (hey, it’s on our conferences list!), and the idea has clearly stirred up some thoughts from him.

Direct Link to ArticlePermalink

The post CSS Algorithms appeared first on CSS-Tricks.

Successful WordPress Freelancing

Andy Adams released a book for aspiring WordPress freelancers. It’s meant to take a lot of the guesswork and the roadblocks that many folks often hit when making the decision to fly solo and rely on WordPress development for a stable source of work and income.

Aside from being included in it (and Andy being an all-around great guy), I want to share the book with y’all because WordPress and freelancing are two topics I care deeply about, particularly because the WordPress platform and community helped me crack into freelancing when I made that decision five years ago.

What I’ve seen over the years is a delta between what is perceived about WordPress freelancing and the actual reality of it. Sure, all you need is a computer, a text editor and a free download of WordPress to get started. That’s the easy part, but there’s much, much more that’s worth considering. Finding clients is hard. Managing those clients is hard. Pricing work is hard. Proposals are hard. Taking time off is hard. These are among the things Andy covers in the book and the advice he provides is something that will benefit anyone breaking into freelance work.

Get the Book

Direct Link to ArticlePermalink

The post Successful WordPress Freelancing appeared first on CSS-Tricks.

WordCamp US 2018

I recently attended and had the chance to speak at WordCamp US 2018 in Nashville. I had a great time. I love conferences that bring people together around a tight theme because it’s very likely you’ll have something to talk about with every person there. Plus, I rather like WordPress and its community. The vibe was very centered around Gutenberg, as it was released in WordPress 5.0 just as the conference started.

Matt’s State of the Word gets into all that:

I took the opportunity to give a brand new talk I’ve been working on I’ve called, “Thinking Like a Front-End Developer”:

There were loads of wonderful people there and loads of wonderful talks. Here’s a playlist!

The post WordCamp US 2018 appeared first on CSS-Tricks.

Gulp for WordPress: Initial Setup

This is the first part of a two-part series on creating a Gulp workflow for WordPress theme development. This first part covers a lot of ground for the initial setup, including Gulp installation and an outline of the tasks we want it to run. If you’re interested in how the tasks are created, then stay tuned for part two.

Earlier this year, I created a course for building premium WordPress themes. During the process, I wanted to use a task runner to concatenate and minify JavaScript and CSS files. I ended up using that task runner to automate a lot of other tasks that made the theme much more efficient and scalable.

The two most popular task runners powered by Node are Gulp and Grunt. I went with Gulp after a good amount of research, it appeared to have an intuitive way to write tasks. It uses Node streams to manipulate files and JavaScript functions to write the tasks, whereas Grunt uses a configuration object to define tasks — which might be fine for some, but is something that made me a little uncomfortable. Also, Gulp is a bit faster that Grunt because of those Node streams and faster is always a good thing to me!

So, we’re going to set Gulp up to do a lot of the heavy lifting for WordPress theme development. We’ll cover the initial setup for now, but then go super in-depth on the tasks themselves in another post.

Article Series:

  1. Initial Setup (This Post)
  2. Creating the Tasks (Coming Tomorrow!)

Initial theme setup

So, how can we use Gulp to power the tasks for a WordPress theme? First off, let’s assume our theme only contains the two files that WordPress requires for any theme: index.php and styles.css. Sure, most themes are likely to include many more files that this, but that’s not important right now.

Secondly, let’s assume that our primary goal is to create tasks that help manage our assets, like minify our CSS and JavaScript files, compile Sass to CSS, and transpile modern JavaScript syntax (e.g. ES6, ES7, etc..) into ES5 in order to support older browsers.

Our theme folder structure will look like this:

├── index.php
├── style.css
└── src/ ├── images/ │ └── cat.jpg ├── js/ │ ├── components/ │ │ └── slider.js │ └── bundle.js └── scss/ ├── components/ │ └── slider.scss └── bundle.scss

The only thing we’ve added on top of the two required files is a src directory where our original un-compiled assets will live.

Inside of that src directory, we have an images subdirectory as well as others for our JavaScript and Sass files. And from, there, the JavaScript and Sass subdirectories are organized into components that will be called from their respective bundle file. So, for example, bundle.js will import and include slider.js when our JavaScript tasks run so all our code is concatenated into a single file.

Identifying Gulp tasks

OK, next we want Gulp tasks to a create a new dist directory where all of our compiled, minified and concatenated versions of our assets will be distributed after the tasks have completed. Even though we’re calling this directory dist in this post because it is short for “distribution,” it could really be called anything, as long as Gulp knows what it is called. Regardless, these are the assets that will be distributed to end users. The src folder will only contain the files that we edit directly during development.

Identifying which Gulp tasks are the best fit for a project will depend on the project’s specific needs. Some tasks will be super helpful on some projects but completely irrelevant on others. I’ve identified the following for us to cover in this post. You’ll see that one or two are more useful in a WordPress context (e.g. the POT task) than others. Yet, most of these are broad enough that you’re likely to see them in many projects that use Gulp to process Sass, JavaScript and image assets.

  • Styles Task: This task is responsible for compiling the bundle.scss file in the scss subdirectory to bundle.css in a css directory located in the dist directory. This task will also minify the generated CSS file so that its is it’s smallest possible size when used in production.

We will talk about production vs. development modes during the article. Note that we will not create a task to concatenate CSS files. The bundle.scss file will act as an entry point for all . <code>scss files that we want to include. In other words; any Sass or CSS files you want to include in your project, just import them in the bundle.scss file using @import statements. For instance, in our example folder, we can use @import ./components/slider'; to import the slider.scss file. This way in our task we will have to compile and minify only one file (bundle.css).

  • Scripts Task: Similar to the Styles task, this task will transpile bundle.js from ES6 syntax to ES5, then minify the file for production.

We will only compile bundle.js. Any other JavaScript files we want to include will be done using ES6 import statements. But in order for those import statements to work on all browsers, we will need to use a module bundler. We’re going to use webpack as our bundler. If this is your first time working with it, this primer is a good place to get an overview of what it is and does.

  • Images Task: This task will simply copy images from src/images and send them to dist/images after the files have been compressed to their smallest size.
  • Copy Task: This task will be responsible for copying any other files or folders that are not in /src/images, /src/js or /src/scss and post them to the dist directory.

Remember. the src folder will contain the files that are only used during development and that will not be included in the final theme package. Thus, any assets other than our images, JavaScript and Sass files need to be copied posted to the dist folder. For instance, if we have a /src/fonts folder, we would want to copy the files in there into the dist directory so they get included in the final deliverable.

  • POT Task: As the name suggests, this task will scan all your theme’s PHP files and generate a .pot (i.e. translation) file from gettext calls in the files. This is the most WordPress-centric of all the tasks we’re covering here.
  • Watch Task: This task will literally watch for changes in your files. When a change is made, certain tasks will be triggered and executed, depending on the type of file that changed.

For instance, if we change a JavaScript file, then the Scripts task should do its magic and then it would be ideal if the browser refreshed for us automatically so we can see those changes. Further, If we change a PHP file, then let’s simply refresh the browser since PHP files don’t rely on any other tasks in our project. We’ll be using a Gulp plugin called Browsersync to handle browser refreshes, but we’ll get to that and other plugins a little later.

  • Compress Task: As you might expect, all the plugins that we use to write our tasks will be managed using npm. So, our theme folder will contain another folder, like node_modules, that in turn, contains files like package.json and other configuration files that define our project’s dependencies — and these files and folders are only needed during development. During production, we can take out the necessary files for our theme and leave the unneeded development files behind. That’s what this task will do; it will create a ZIP file that only contains the necessary files to run our theme.

As a bonus step for the compress task, if you are creating a theme that you intend to publish on WordPress.org or maybe on a website like ThemeForest, then you probably already know that all functions in your theme must be prefixed with a unique prefix:

function mythemename_enqueue_assets() { // function body

So, if you are creating a lot of themes. you’ll need to easily reuse functions in different themes but change the prefix to the name of the theme, to prevent conflicts. We can prefix our functions with a placeholder prefix and then replace all instances of that placeholder in the compress task. For instance, we can choose the string _themename as a place holder, and when we compress our theme we will replace all ‘_themename’ strings to the actual theme name:

function _themename_enqueue_assets() { // function body

This can also apply to anywhere we use the theme name for example in the text domain:

<?php _e('some string', '_themename'); ?>
  • Develop Task: This task does nothing new. It runs when as we develop our theme. It cleans the dist folder, runs the Styles, Scripts, Images and Copy tasks in development mode (i.e. without minifying any of the assets), then watches for file changes to refresh the browser for us.
  • Build Task: This task is intended to build our files for production. It will do all the same cleaning and tasks as the Develop task, but in production mode (i.e. minify the assets in the process) and generate a new POT file for translation updates. After it runs, our dist folder should contain the the files that are ready for distribution.
  • Bundle Task: This task will simply run the build task, will making sure that all the files in the dist folder are minified and ready for distribution. Then, it will run the Compress task, which bundles all of the production-ready files and folders into a ZIP file. We want a ZIP file because that is the format WordPress recognizes to extract and install a theme.

Here’s how our file structure looks after our tasks complete:

├── index.php
├── style.css
├── src/
└── dist/ ├── images/ │ └── cat.jpg // after compression ├── js/ │ └── bundle.js // bundled with all imported files (minified in prodcution) └── scss/ └── bundle.scss // bundled with all imported files (minified in production)

Now that we know what tasks we’re going to use on our project and that they do, let’s get into the process for installing Gulp into the project.

Installing Gulp

Before we install Gulp, we should make sure that we have Node and npm installed on our machines. We can do that by running these commands in the command line:

node --version
npm --version

…and, we should get some version number as seen here:

Now, let’s point the command line to the theme folder:

cd path/to/your/theme/folder

…and then run this command to initialize a new npm project:

npm init

This will prompt us with some options. The only important option in our case is the package name option. This is where the name of the theme can be provided — everything else can stay at their default setting. When choosing the theme name, make sure to only use lowercase characters and underscores while avoiding dashes and special characters since this theme name will be used to replace the functions placeholder that we mentioned earlier.

On to installing Gulp! First, we’ve got to install Gulp’s command line interface (gulp-cli) globally so we can use Gulp in the command line.

npm install --global gulp-cli

After that, we run this command in order to install Gulp itself in the theme directory:

npm install –save-dev gulp

The current stable release of Gulp is 3.9.1 at the time of this writing, but version 4.0 is already available in the project repository. The command above uses the @next which installs version 4.0. Removing that will install 3.9.1 (or whatever the current version is) instead.

To make sure everything is installed correctly, we’ll run this command:

gulp --version

Nice! Looks like we’re running version 4.0, which is the latest version at the time of this writing.

Writing Gulp tasks

Gulp tasks are defined in a a file in called gulpfile.js that we’ll need to create and place into the root of our theme.

Gulp is JavaScript at its core, so we can define a quick example task that logs something to the console.

var gulp = require('gulp');
gulp.task('hello', function() { console.log('First Task');

In this example, we’ve defined a new task by calling gulp.task. The first argument for this function is the task’s name (hello) and the second argument is the function we want to run when that name is entered into the command line which, in this case, should print “First Task” into the console.

Let’s do that now.

gulp hello

Here’s what we get:

As you can see, we do indeed get the console.log('First Task') output we want. However, we also get an error saying that our task did not complete. All Gulp tasks require telling Gulp where to end the task, and we do that by calling a function that is passed as the first argument in our task function like so:

var gulp = require('gulp');
gulp.task('hello', function(cb) { console.log('First Task'); cb();

Let’s try running gulp hello again and we should get the same output, but without the error this time.

There are some cases where we won’t have to call the cb() function, such as when a task returns a promise or a node stream. A node stream is what we will use in the tasks in this post, which means we will see it a lot throughout our article.

Here’s an example of a task that returns a promise. In this task, we won’t have to call the cb() function because gulp already knows that the task will end when the promise resolves or returns an error:

gulp.task('promise', function(cb) { return new Promise(function(resolve, reject) { setTimeout(function() { resolve(); }, 300); });

Now try and run ‘gulp promise’ and the task will complete without returning any errors.

Finally, it’s worth mentioning that Gulp accepts a default task that runs by typing gulp alone in the command line. All it takes is using “default” as the task name argument.

gulp.task('default', function(cb) { console.log('Default Task'); cb();

Now, typing gulp by itself in the command line will run the task.

Whew! Now we know the basics of writing Gulp tasks.

There is one more thing we can do to improve things and that’s enabling ES6 syntax in the Gulpfile. This will allow us to use features like destructuring, import statements, and arrow functions, among others.

Using ES6 in the Gulpfile

The first step to use ES6 syntax in the Gulpfile is to rename it from gulpfile.js to gulpfile.babel.js. As you may already know, Babel is the compiler that compiles ES6 to ES5.

So, let’s install Babel and some of its required packages by running:

npm install --save-dev @babel/register @babel/preset-env @babel/core

After that, we have to create a file called .babelrc inside of our theme folder. This file will tell Babel which preset to use to compile our JavaScript. The contents of the .babelrc file will look like this:

{ "presets": ["@babel/preset-env"]

Now we can use ES6 in our Gulpfile! Here’s how that would look if we were to re-write it:

import gulp from 'gulp';
export const hello = (cb) => { console.log('First Task'); cb();
} export const promise = (cb) => { return new Promise((resolve, reject) => { setTimeout(() => { resolve(); }, 300); });
}; export default hello

As you can see, we are importing Gulp using import and not require. In fact, there’s no longer any need to import Gulp at all! I included the import statement anyway to show it can be used instead of require. We’re allowed to skip importing Gulp because we don’t have to call gulp.task — instead, we only need to export a function, and the name of this function will be the name of the task. Further, all that’s needed to define a default function is use export default. And notice those arrow functions, too! Everything is so much more concise.

Let’s move on and start coding the actual tasks.

Development vs. Production

As we covered earlier, we need to create two modes: development and production. The reason we need to delineate between the two is that some details in our tasks will be time and memory-consuming, which only make sense in a production environment. For instance, the styles task needs to minify the CSS. However, the minification can take both time and memory — and if that process runs every single time something changes during development, that is not only unnecessary, but is very inefficient. It’s ideal for tasks to be as fast as possible during development.

We need to set a flag that specifies whether a task should run in one mode or the other. We can use a package called yargs that allows us to define these types of arguments while running a command. So, let’s install it and put it to use:

npm install --save-dev yargs

Now, we can add arguments to our command like so:

gulp hello --prod=true

…and then retrieve these argument in the Gulpfile:

import yargs from 'yargs';
const PRODUCTION = yargs.argv.prod; export const hello = (cb) => { console.log(PRODUCTION); cb();

Notice that the values we define in the command are available inside the yargs.argv object in the Gulpfile and in console.log(PRODUCTION). In our case this will output true, so PRODUCTION will be our flag that decides whether or not a function runs inside the tasks.

We’re all set up!

We covered a lot of ground here, but we now have everything we need to start writing tasks for our WordPress theme development. That just so happens to be the sole focus of the next part of this series, so stay tuned for tomorrow.

The post Gulp for WordPress: Initial Setup appeared first on CSS-Tricks.


(This is a sponsored post.)

I just read a nicely put together story about WooCommerce over on the CodeinWP blog. WooCommerce started life as WooThemes, sort of a “premium themes” business started by just a couple of fellas who had never even met in person. Two years and a few employees later they launch WooCommerce, and 2 years after that it hits a million downloads. A major success story, to be sure, but a collaborative and remote-work based one that wasn’t exactly overnight. Another 2 years and Automattic picks them up and the WooThemes part is spun down.

Now we’re 3-4 years into WooCommerce being an Automattic project and it’s looking at nearly 60 million downloads, 4 million of which are active. A number they are saying is about 30% of all eCommerce on the web. Daaaaang. I’ve used WooCommerce a number of times and it always does a great job for me.

Direct Link to ArticlePermalink

The post WooCommerce appeared first on CSS-Tricks.


Hey! Chris here, with a big thanks to WordPress, for not just their sponsorship here the last few months, but for being a great product for so many sites I’ve worked on over the years. I’ve been a web designer and developer for the better part of two decades, and it’s been a great career for me.

I’m all about learning. The more you know, the more you’re capable of doing and the more doors open for you, so to speak, for getting things done as a web worker. And yet it’s a dance. Just because you know how to do particular things doesn’t mean that you always should. Part of this job is knowing what you should do yourself and what you should outsource or rely on for a trustworthy service.

With that in mind, I think if you can build a site with WordPress.com, you should build your site on WordPress.com. Allow me to ellaborate.

Do I know how to build a functional contact form from absolute scratch? I do! I can design the form, I can build the form with HTML and style it with CSS, I can enhance the form with JavaScript, I can process the form with a backend language and send the data where I need it. It’s a tremendous amount of work, which is fine, because hey, that’s the job sometimes. But it’s rare that I actually do all of that work.

Instead of doing everything from scratch when I need a form on a site I’m building, I often choose a form building service that does most of this work for me and leaves me with just the job of designing the form and telling it where I want the data collected to go. Or I might build the form myself but use some sort of library for processing the data. Or I might use a form framework on the front end but handle the data processing myself. It depends on the project! I want to make sure whatever time I spend working on it is the most valuable it can be &mdash not doing something rote.

Part of the trick is understanding how to evaluate technology and choose things that serve your needs best. You’ll get that with experience. It’s also different for everyone. We all have different needs and different skills, so the technology choices you make will likely be different than what choices I make.

Here’s one choice that I found to be in many people’s best interest: if you don’t have to deal with hosting, security, and upgrading all the underlying software that powers a website…don’t! In other words, as I said, if you can use WordPress.com, do use WordPress.com.

This is an often-quoted fact, but it bears repeating: WordPress powers about a third of the Internet, which is a staggering feature. There are an awful lot of people that are happily running their sites on WordPress and that number wouldn’t be nearly so high if WordPress wasn’t flexible and very usable.

There are some sites that WordPress.com isn’t a good match for. Say you’re going to build the next big Fantasy Football app with real-time scores, charts and graphs on dashboards, and live chat rooms. That’s custom development work probably suited for different technology.

But say you want to have a personal portfolio site with a blog. Can WordPress.com do that? Heck yes, that’s bread and butter stuff. What if you want to sell products? Sure. What if you want to have a showcase for your photography? Absolutely. How about the homepage for a laundromat, restaurant, bakery, or coffeeshop? Check, check, check and check. A website for your conference? A place to publish a book chapter by chapter? A mini-site for your family? A road trip blog? Yes to all.

So, if you can build your site on WordPress.com, then I’m saying that you should because what you’re doing is saving time, saving money, and most importantly, saving a heaping pile of technical debt. You don’t deal with hosting, your site will be fast without you ever having to think about it. You don’t deal with any software upgrades or weird incompatibilities. You just get a reliable system.

The longer I work in design and development, the more weight I put on just how valuable that reliability is and how dangerous technical debt is. I’ve seen too many sites fall off the face of the Earth because the people taking care of them couldn’t deal with the technical debt. Do yourself, your client and, heck, me a favor (seriously, I’ll sleep better) and build your site on WordPress.com.

The post WordPress.com appeared first on CSS-Tricks.

A Basic WooCommerce Setup to Sell T-Shirts

WooCommerce is a powerful eCommerce solution for WordPress sites. If you’re like me, and like working with WordPress and have WordPress-powered sites already, WooCommerce is a no-brainer for helping you sell things online on those sites. But even if you don’t already have a WordPress site, WooCommerce is so good I think it would make sense to spin up a WordPress site so you could use it for your eCommerce solution.

Personally, I’ve used WooCommerce a number of times to sell things. Most recently, I’ve used it to sell T-Shirts (and hats) over on CodePen. We use WordPress already to power our blog, documentation, and podcast. Makes perfect sense to use WordPress for the store as well!

What I think is notable about our WooCommerce installation at CodePen is how painless it was, while doing everything we need it to do. I’d say it was a half-day job with maybe a half-day of maintenance every few months, partially based on us wanting to change something.

The first step is installing the plugin, and immediately you get a Products post type you can use to add new products. We’re selling a T-Shirt, so that looks like this:

Note the variations in use for size. We even track inventory at the size level so our T-Shirt printing company knows when to re-print different sizes.

What is somewhat astounding about WooCommerce is that you might need to do very little else. You could set a price, flip on the basic PayPal integration and enter your email, publish the product, and start taking orders.

Or, you could start customizing things and do as much or as little as you want:

  • You could add as many different payment processors as you like. We like using Stripe for credit card processing at CodePen, but also offer PayPal.
  • You could customize the template of every different page involved, or just use the defaults. At CodePen we have very lightly customized templates for the store homepage and product page.
  • You could get very detailed with calculating shipping costs, or use flat rates. We use a flat rate shipping cost at CodePen almost as marketing: same shipping cost anywhere in the world!
  • You could get into integrations, like connecting it with your MailChimp account for further email marketing or Slack account to notify your team of sales.

If you can dream it, you can do it with WooCommerce.

At CodePen, we work with a company called RealThread that actually prints and ships the T-Shirts.

They work great with WooCommerce of course, and the way we set that up is that we use the ShipStation integration and blast the orders into their account there and they handle all the fulfillment from there. There are all sorts of shipping method plugins though for anything you can think of.

Within WooCommerce, we have a dashboard of all the orders, their status, and even tracking information should we need to look something up.

So essentially:

  1. We use WooCommerce
  2. We use the Stripe plugin to take our credit card payments that way
  3. We use the PayPal plugin to take PayPal payments over Braintree
  4. We use the ShipStation plugin to send orders to that system for our fulfillment company to handle

It was quite easy to set up and works great, and it’s comforting to know that we could do tons more with it if we needed to and support is there to help.

The post A Basic WooCommerce Setup to Sell T-Shirts appeared first on CSS-Tricks.

Learning Gutenberg: Building Our Custom Card Block

We’ve got some base knowledge, we’ve played with some React and now we’ve got our project tools set up. Let’s dive into building our custom block.

Article Series:

  1. Series Introduction
  2. What is Gutenberg, Anyway?
  3. A Primer with create-guten-block
  4. Modern JavaScript Syntax
  5. React 101
  6. Setting up a Custom webpack
  7. A Custom “Card” Block (This Post)

What we’re building

We’re going to build a custom card block that features an image, a title and a summary. It’s a really common design pattern in the web and it also let’s us look at some core Gutenberg components, along with core WordPress elements, such as the Media Library. We’ll also play with some display logic with JSX for the front-end markup.

Our glorious custom card block!

Our glorious custom card block!

We’re going to focus solely on the the previous section. In your active plugin folder, this is located at blocks/src/block/block.js.

If you are working from the file structure created with create-guten-block, you might want to start by deleting everything in block.js and writing your code from scratch along with the tutorial.

Right at the top of this file, add the following:

const { registerBlockType, RichText, MediaUpload, PlainText } = wp.blocks;
const { Button } = wp.components;

We covered destructuring assignments in Part 2, create-guten-block? In case you need reminding, check it out here. The first six of those were relatively straightforward and involved replacing strings or bit of HTML. The seventh item, “Make the paragraph text editable,” is much more complicated to implement and was intended to get you thinking a bit. The time has come though, and we will indeed make some text editable in Gutenberg!

You may also recognize this registerBlockType function from the PHP register_block_type function we used in the last article. While that function registers a block from the server-side of WordPress, this one registers our block into the React ecosystem on the client side. Both are necessary to have a block that uses React, and their registered names, card-block/main must match.

Add the following code, but make sure you put a comma after 'common', so it looks like this: 'common',.

Here’s the code:

attributes: { title: { source: 'text', selector: '.card__title' }, body: { type: 'array', source: 'children', selector: '.card__body' }, imageAlt: { attribute: 'alt', selector: '.card__image' }, imageUrl: { attribute: 'src', selector: '.card__image' }

Here, we are defining the editable attributes of our block and the DOM selector that they are assigned to. This attribute object works in a very similar way to the React state object. It even has a very similar updating method called setAttributes. We’ll get to that later though.

At this point, it’s worth a brief overview of state and attributes because they represent a whole new way of thinking for WordPress developers. I’ll take over for a moment to go over them.

About Attributes and State

It may look like a simple JavaScript object, but that chunk of attributes introduces a whole swath of new concepts to a WordPress theme developer’s brain, not least of which is state. The concept of state has a long history in computer science, and life in general, really. Almost everything has a state. What state is your coffee cup in now? Empty, almost empty? How about your clothing? Are your shoes dirty or new? How about your body? Are you tired or wide awake?

At a high level, state simply refers to the present condition of a thing. In computer science, that thing is a computer program, and that program can be much, much simpler than what we create here on the web. Take a vending machine, for instance. The vending machine has a state that updates each time you put in a coin. When the state of the machine reaches a predefined amount, say $1.25, the machine knows to allow you to make your snack choice.

In Gutenberg, attributes track the present condition of data in a block. Attributes are the closest parallel we can draw to custom fields in Gutenberg, but they exist only in the context of Gutenberg and JavaScript. Let’s take the attribute above for title, for example:

title: { source: 'text', selector: 'card__title'

When Gutenberg fires up, it says, “I need to find some text inside a selector called .card__title, and populate the value for title with whatever I find.”

Attributes in Gutenberg are not directly connected to the database like custom fields are connected to post_meta. The entries source and selector are instructions for Gutenberg to populate the state of each block. When we load up the editor, it follows these instructions and assigns a value to title based on the markup saved in the database between the HTML comments that indicate a block of this type. We don’t see the value of title in the attributes we register, but if I were to access props.attributes.title, I would get whatever text exists in .card__title.

We’ve set up some basics, so let’s dive in to our edit function. This is what’s called when the block is accessed from the Gutenberg editor in visual mode. The user will see the rich interface, rather than the HTML code that it generates. That’s what I’ll cover next.

Add our edit function

Let’s add some code in. Add the following after the closing } of the attributes object. Like before, make sure you add a trailing comma, so it looks like this },.

Add the following code after that:

edit({ attributes, className, setAttributes }) { return ( );

So, we’re using another destructuring assignment to selectively pick our passed parameters to the edit function. The two most important are attributes and setAttributes. The attributes parameter is the same as the attributes block, but it’s the current, reactive state. This means if the setAttributes function updates one of the attributes values, it will automatically update anywhere that references it, which is similar to our React component from Part 3.

There’s a big ol’ return in this function. Can you guess what’s going in it? Yup! We’re going to stick some JSX in there. Add the following within the return parentheses:

<div className="container"> <MediaUpload onSelect={ media => { setAttributes({ imageAlt: media.alt, imageUrl: media.url }); } } type="image" value={ attributes.imageID } render={ ({ open }) => getImageButton(open) } /> <PlainText onChange={ content => setAttributes({ title: content }) } value={ attributes.title } placeholder="Your card title" className="heading" /> <RichText onChange={ content => setAttributes({ body: content }) } value={ attributes.body } multiline="p" placeholder="Your card text" />

OK, there’s a lot going on in here, but it’s all stuff we’ve covered in previous parts of this series. What we’ve got here is a container with three existing Gutenberg components. For each, we are setting the relevant attribute as its value, a relevant placeholder and an onChange/onSelect handler. We’re also passing a custom renderer to the <MediaUpload />, which we’ll cover shortly.

Each onChange handler is a handy little expression that passes the new content that triggered the onChange into the setAttributes function, where we set which attributes object to update. This update then cascades into any reference of that attribute, where the content will update like magic. The <MediaUpload /> element features an onSelect event which is fired when the user selects or uploads an item to the media library.

Speaking of the <MediaUpload /> element, you’ll notice there’s a custom render attribute, which references a getImageButton function. Let’s write that next. Above the return in the edit function add the following:

const getImageButton = (openEvent) => { if(attributes.imageUrl) { return ( <img src={ attributes.imageUrl } onClick={ openEvent } className="image" /> ); } else { return ( <div className="button-container"> <Button onClick={ openEvent } className="button button-large" > Pick an image </Button> </div> ); }

What this function does is detect if there’s an imageUrl in the attributes object. If there is, it’ll render that <img /> tag and let a user click it to select another. If there’s no image, it’ll render a WordPress <Button /> which prompts the user to pick an image. This calls the same openEvent that was passed into the function.

To keep things simple in this tutorial, we’ve bound a click to the <img /> element. You should consider building something fancy that leverages a <button /> for your production-ready blocks, for better accessibility support.

Right, that’s our edit function done. Not much code there, considering what it actually does, which is great!

Add our save function

We’ve got our Gutenberg editor-end of the block written now, which is the hard part. Now all we’ve got to do is tell Gutenberg what we want the block to do with the content. With the same reactive data from attributes, we can render out our front-end markup in real-time, too. That means when someone switches into HTML editing mode on the block, it’ll be up to date. If you edit it in HTML editing mode, the visual mode will also be kept up to date. Super useful.

Let’s dig in then. After our edit function, add a comma, so it looks like }, and then add the following on a new line:

save({ attributes }) { const cardImage = (src, alt) => { if(!src) return null; if(alt) { return ( <img className="card__image" src={ src } alt={ alt } /> ); } // No alt set, so let's hide it from screen readers return ( <img className="card__image" src={ src } alt="" aria-hidden="true" /> ); }; return ( <div className="card"> { cardImage(attributes.imageUrl, attributes.imageAlt) } <div className="card__content"> <h3 className="card__title">{ attributes.title }</h3> <div className="card__body"> { attributes.body } </div> </div> </div> );

Looks pretty similar to the edit function, right? Let’s step through it.

We start of by using a destructuring assignment to pull out the attributes from the passed paramaters, just like the previous edit function.

Then we have another image helper function that firstly detects if there’s an image and returns null if there’s not one. Remember: we return null in JSX if we want it to render nothing. The next thing this helper does is render a slightly varied <img /> tag if there’s alt text or not. For the latter, it hides it from a screen-reader by adding aria-hidden="true" and setting a blank alt attribute.

Lastly, our return spits out a nice .card block with clean, BEM-driven markup that will load on the front-end of our theme.

And that is that for our save function. We’re so close to having a completed block. Just one more step to go!

Add some style

OK, we’ve got this little bit to do and we’re done. The observant amongst you may have noticed some references to className dotted about. These are referencing our editor.scss rules, so let’s add them.

Open up editor.scss, which lives in the same directory as block.js. Add the following:

@import '../common'; .gutenberg { .container { border: 1px solid $gray; padding: 1rem; } .button-container { text-align: center; padding: 22% 0; background: $off-white; border: 1px solid $gray; border-radius: 2px; margin: 0 0 1.2rem 0; } .heading { font-size: 1.5rem; font-weight: 600; } .image { height: 15.7rem; width: 100%; object-fit: cover; }

This is some loose CSS to give our block some card-like style. Notice it’s all nested within a .gutenberg class? This is to battle the specificity of some core styles. Within the editor, there is a <div class="gutenberg" wrapped around the block area of the post editor screen, so we can make sure to only affect those elements with this nesting. You’ll probably also notice that we’re importing another Sass file, so let’s fill that one.

Open common.scss which lives in the src directory, which is the parent of the current block directory that we’re in.

/* * Common SCSS can contain your common variables, helpers and mixins * that are shared between all of your blocks. */ // Colors
$gray: #cccccc;
$off-white: #f1f1f1;

Anyway, guess what? We’ve only gone and built out a custom card block!! Let’s give it a test-drive.

First, check your block is all-good. This is what the complete block.js file should look like:

const { registerBlockType, RichText, MediaUpload, PlainText } = wp.blocks;
const { Button } = wp.components; // Import our CSS files
import './style.scss';
import './editor.scss'; registerBlockType('card-block/main', { title: 'Card', icon: 'heart', category: 'common', attributes: { title: { source: 'text', selector: '.card__title' }, body: { type: 'array', source: 'children', selector: '.card__body' }, imageAlt: { attribute: 'alt', selector: '.card__image' }, imageUrl: { attribute: 'src', selector: '.card__image' } }, edit({ attributes, className, setAttributes }) { const getImageButton = (openEvent) => { if(attributes.imageUrl) { return ( <img src={ attributes.imageUrl } onClick={ openEvent } className="image" /> ); } else { return ( <div className="button-container"> <Button onClick={ openEvent } className="button button-large" > Pick an image </Button> </div> ); } }; return ( <div className="container"> <MediaUpload onSelect={ media => { setAttributes({ imageAlt: media.alt, imageUrl: media.url }); } } type="image" value={ attributes.imageID } render={ ({ open }) => getImageButton(open) } /> <PlainText onChange={ content => setAttributes({ title: content }) } value={ attributes.title } placeholder="Your card title" className="heading" /> <RichText onChange={ content => setAttributes({ body: content }) } value={ attributes.body } multiline="p" placeholder="Your card text" formattingControls={ ['bold', 'italic', 'underline'] } isSelected={ attributes.isSelected } /> </div> ); }, save({ attributes }) { const cardImage = (src, alt) => { if(!src) return null; if(alt) { return ( <img className="card__image" src={ src } alt={ alt } /> ); } // No alt set, so let's hide it from screen readers return ( <img className="card__image" src={ src } alt="" aria-hidden="true" /> ); }; return ( <div className="card"> { cardImage(attributes.imageUrl, attributes.imageAlt) } <div className="card__content"> <h3 className="card__title">{ attributes.title }</h3> <div className="card__body"> { attributes.body } </div> </div> </div> ); }

If you’re happy, let’s fire up webpack. While in your current plugin directory in terminal, run this:

npx webpack --watch

This is slightly different to the previous part in the series because we’ve added the --watch argument. This basically keeps an eye on your js files and re-runs webpack if they change.

Fire up the editor!

Let’s fire up the Gutenberg editor by loading up a post in the WordPress back end. In the Gutenberg editor, click the little plus icon and look in the “blocks” tab and there it is: our awesome new card block!

Go ahead and give it a test drive and add some content in there. Feels good right?

Here’s a quick video of what you should be seeing right now, with your fancy new card block:

And with that, you’re done 🎉

Here’s a thing you might be thinking: Aren’t blocks kind of a replacement for custom fields? Can’t I now create my own content structure directly within WordPress instead of using a plugin like Advanced Custom Fields? Not quite…

Blocks vs. Custom Fields

While Gutenberg does afford us the ability to customize the structure of data entry from the user’s experience, on the back-end it’s no different than the current WYSIWYG editor. Data saved from a block is part of the post_content column in the wp_posts database table—it’s not stored separately in wp_postmeta like custom fields. This means that, at present, we cannot access the data from our card block from another post in the same way we could if we had created custom fields for title, image and content with a standard Advanced Custom Fields setup.

That said, I could see some really interesting plugins surfacing that provide a way to port data from a block to other parts of a website. With the WordPress REST API, the possibilities are just about limitless! In our screencast, Andy and I took a stab at incorporating an API request into our card block and, although things didn’t turn out exactly as planned, the tools are already in place and you can get a taste of what could be possible with Gutenberg in the future. Time will tell!

Wrapping up and next steps

What a journey we’ve been on together! Let’s list out what you’ve learned in this series:

  • You’ve learned some core, modern JavaScript by getting to grips with ES6
  • You’ve learned the basics of JSX
  • You took that new knowledge and built out a React component from scratch
  • You then learned how webpack works and wrote a scalable config file for Gutenberg block development
  • Finally, you built custom Gutenberg card block from scratch

So, where can you go from here? Now that you’ve got some solid base knowledge from this series, you could do some further learning. There’s already fantastic resources for that:

  • Writing Your First Block Type on WordPress.org (Andy: That’s how I learned how blocks work)
  • Gutenberg Courses by Zac Gordon and Joe Casabona
  • Creating a Custom Gutenberg Block by Pete Tasker
  • Anatomy of a Custom Block by Morgan Kay
  • One Thousand and One Ways to Extend Gutenberg Today by Riad Benguella
  • Gutenberg talks on WordPress.tv

Some interesting case studies:

  • Auditing Your WordPress Plugin for Gutenberg
  • Gutenberg on Humanmade.com
  • Modern Tribe’s “Going Gutenberg”

Keep an eye on these resources to stay up to date with the project:

  • Gutenberg News
  • Gutenberg Times

Experimental things happening with Gutenberg:

  • Gutenberg Custom Fields plugin
  • Atomic Blocks plugins and theme

Once Gutenberg becomes part of WordPress core in version 5.0 (release date TBD), you could also publish a useful custom block in the WordPress plugins directory. There’s definitely room for some handy components such as the card block that you’ve just built.

We hope you’ve enjoyed this series, because we’ve certainly enjoyed making it. We really hope this helps you get into Gutenberg and that you build some cool stuff. You should totally send us links of stuff you have built too!

Article Series:

  1. Series Introduction
  2. What is Gutenberg, Anyway?
  3. A Primer with create-guten-block
  4. Modern JavaScript Syntax
  5. React 101
  6. Setting up a Custom webpack
  7. A Custom “Card” Block (This Post)

The post Learning Gutenberg: Building Our Custom Card Block appeared first on CSS-Tricks.