Tag: wordpress

Where Did Underline Go?
As of WordPress 4.7, the visual editor no longer has a button for underline. There were a lot of reasons for this, but primary are two:
1. Space is not limitless.
2. Underlining looks like links.
Naturally someone complained that we were breaking style guides:

When referencing a source of information it is correct form to underline the title of the source.

They happen to be wrong. Let me explain.

The Web Is Not Print

We use double spaces to indicate the end of a sentence in printed works. We don’t on the Internet. It took me a long time to get used to that, and if you look back on my older posts, you’d see it all over the place. The point here is that we know you don’t use the same punctuation and style you might use online as you do on paper.

I look to the grandpappy of web, Jakob Nielsen, for some backup here. Your writing style for the web is different from print. A lot different. In Writing Style for Print vs. Web he says:

In linear media — such as print and TV — people expect you to construct their experience for them. Readers are willing to follow the author’s lead.

In non-linear hypertext, the rules reverse. Users want to construct their own experience by piecing together content from multiple sources, emphasizing their desires in the current moment. People arrive at a website with a goal in mind, and they are ruthless in pursuing their own interest and in rejecting whatever the site is trying to push. Banner blindness is only the most extreme manifestation of this selfishness.

But that talks about the way we write and not the design of what it looks like. Web and print design are wildly different too. For newspapers, you have to consider the width of the columns. If you’ve never taken a journalism course, there’s as much about layouts as there is about writing a solid lede.

Good Writing Has Rules

I’m a huge fan of Strunk & White’s The Elements of Style. My wife has a copy and, when we met, she found my grammar to be deplorable and used to wave it at me a lot. Having read it multiple times (yes, I do re-read it) I’ve found my communication skills have been catapulted because of the directions. People ask me why I’m a good speaker and the answer is because I’m a good writer.

One of the lessons from Strunk & White is to use the active voice, for example, which is something Nielsen points out as well. You need to engage your readers. You need to bring them on a journey and make it theirs as much as yours. To do that, you need to understand the rules of the language in which you’re writing.

Content Must Not Confuse By Context

Going back to the heart of the matter, why is it okay that WordPress killed the underline button? It was confusing.

Originally we underlined links because it was easy and being consistent about a display reduced the chances for misunderstandings. Why were they underlined and blue? I actually have no idea. I looked it up but was unable to find a solid answer. My theory was that blue would stand out against the standard grey background as well as the black words so everyone knew what it was for. Similarly, on a monochrome screen, which was very common in the day, an underline would stand out (as it happens, Sir Tim Berners-Lee picked blue totally by happenstance).

Why underline and not bold or italics? My guess is that since underlining is not actually standard practice for writers, it was a safe grab. Otto pointed out that old-old systems always had underlines, but not always italics or bold, so that weighed heavily into the decision as well, clearly.

In a word, it wasn’t confusing. It was consistent.

It’s Actually Italics

Did you double take when I said underlining wasn’t standard practice? Surprise! Let me appeal to Misters Strunk & White on a few matters of form:

Titles. For the titles of literary works, scholarly usage prefers italics with capitalized initials. The usage of editors and publishers varies, some using italics with capitalized initials, others using Roman with capitalized initials and with or without quotation marks. Use italics (indicated in manuscript by underscoring), except in writing for a periodical that follows a different practice. Omit initial A or The from titles when you place the possessive before them.

The Iliad; the Odyssey; As You Like It; To a Skylark; The Newcomes; A Tale of Two Cities;Dickens’s Tale of Two Cities.

Notice the direction to use italics? The talk of a manuscript is in reference to the fact that most people wrote manuscripts by hand or on typewriters that didn’t have italics. I remember having to type a line, and then backspace to add in the underline manually. Have you ever tried to write italics manually? It’s not easy!

The web is not handwritten. Computers in 2016 can handle italics.

And it’s not just Strunk & White. Harvard’s documentation on citation doesn’t recommend underlining at all. The MLA (Modern Language Association) says, as of this year, to use italics for large works like books and magazines, but quotes for short ones in titles. The Chicago Style Guide reads the same.

Use Italics, Not Underline

If you skip the whole post, let me make this simple for you: The title of a source should be italicized.
28 December, 2016
Damn You, Autocorrect!
After the seventh time I shouted “stop autocorrecting cmb2 fields!” at my site, I knew I had to do something.

When you run a website where you enter a lot of people’s names, Autocorrect is a curse more than a blessing. Of course I want it on my post content, but when I get to the field where I enter someone’s name, for crying out loud, some names like Nuñez just don’t meet a spell check. And don’t get me started on my friend’s names or my own. I’ve lost track of the number of times I ended up as “Mike.”

This issue used to only be on phones and tablets. Then Apple introduced autocorrect to their MacOS, which resulted in a lot of tweets followed up by “Damn you, Autocorrect!”

HTML Attributes

If you’ve got a form and you want to tell autocorrect to go away, the code looks like this:
```
<input autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" />
```
For the most part, this will work. You don’t need all of them all of the time, but in my case I was adding names and “Debbie van Houten” was one problem and “Dr. el Farad” was another. I wanted it to just shut up and let me type the name as their parents intended, no matter what. I went whole hog.

But as I mentioned, I use CMB2 and I needed to stop my site from autocorrecting CMB2 fields. It was time for some code.

CMB2 Custom HTML Attributes

This one is so straightforward I was delighted. When you create a new field, you can set arbitrary attributes.
```
// Field: Actor Name
$cmb_characters->add_field( array(
	'name'				=> 'Actor Name',
	'desc'				=> 'Include years (in parens) for multiple actors',
	'id'				=> $prefix . 'actor',
	'type'				=> 'text',
	'repeatable'		=> 'true',
	'attributes'		=> array(
		'autocomplete'		=> 'off',
		'autocorrect'		=> 'off',
		'autocapitalize'	=> 'off',
		'spellcheck'		=> 'false',
	),
) );
```
That was all I needed to do in order to get autocorrect to duck itself. Now I was free to write however weird a name I needed without worrying that autocorrect wanted to call me Mike. Again.

Thanks, autocorrect. Thanks a lot.
23 December, 2016
Security: Do it the WordPress Way
Pretty regularly, people complain that I’m being pedantic and stubborn about security. They argue that their home-grown filters and regular expression checks are more than sufficient for sanitizing and validating data. Invariably I tell them “WordPress has a function for that. Please use it. Don’t create your own.”

Most of the time, this gets a grumbling acquiescence. On the rare occasions it doesn’t I get a pretentious email telling me the developer has been working in tech and computers for 10 to 14 years (10 is most common) and they’ve released code before and they know what they’re talking about.

You know what? You do. Most of the time the code you people come up with looks fine. But after 14 years working for a bank and around 7 of doing WordPress plugin reviews and nearly 5 of working for a web host, I’ve got a different point of view than you do. I have a mountain of experience that is hard to match. This doesn’t mean I’m the smartest person down the pike, don’t get me wrong. But I’ve seen a lot. I’m like that Farmer’s guy.

We know a lot because we’ve seen a lot

With all the things I’ve seen, I’ve developed a very different set of criteria for security beyond just “Is it secure?”

I know the following:
- Someone is always going to be smarter than I am.
- Hackers are incredibly dedicated to being shits.
- Users are incredibly inventive with usage.
- People don’t look before they click.
I ask the following:
- Is this the fastest (most efficient) way to sanity check the data?
- Is it being validated to prevent PEBUaK errors?
- How easy will this be to fix when I find a problem?
- How much damage will this cause if it breaks?
To WordPress or Not to WordPress

When I have a choice of reinventing the wheel or using what WordPress already sanitizes for me, I will always pick WordPress. Every. Single. Time. This is for a very practical reason.
- People don’t upgrade plugins.
- People do upgrade WordPress security releases.
By default everyone using WordPress gets security releases and they get them within 12 hours (more or less). Yes, people can and do disable that, but they’re the minority. When you talk about securing 26% of the Internet, the ability to patch people quickly is paramount. WordPress knows this.

If I’m using the sanitize_name() function from WordPress and not a hand-hewn regular expression, then if there’s a flaw in that function I know it will be patched and the patch pushed and my users made safe. If I make it myself, I have to pray everyone upgrades.

Excellence Uses The Right Tools

Think of it this way. If your plugin becomes a popular plugin and 2% of WordPress users use it, then that’s .5% of all sites on the Internet using your plugin. Which is better for them? Which is safer? Do you rely on the tried and true, tested sanitization via WordPress which will emergency self-update or your own code?

Once you think of it not as “How can I make my code succeed?” but “How can I build trust for 27% of the internet?” it’s clearer.

Rely on WordPress and not your own code whenever possible. It’s smarter. It’s safer. It has the long-term view to take you from a newbie to a well-known tool. If there’s a security hole in WordPress, everyone will work to fix it, and it will get out to more people than just your users.
21 December, 2016
Custom AMP Design
The basic design of a page using AMP works for news articles. This is by design. It’s meant to be fast to load and fast to display, and that means removing the majority of cruft we shove in sidebars and footers. It means a streamlined website.

That’s a basic page but it works well for what it needs to be. The issue happens when you consider pages that aren’t your typical ‘news’ pages.

Compare the information in a character page. On the left is the normal page and the right is the AMP page.

There’s some work to be done, obviously. Enter Custom Templates.

Calling the Right Template for the Job

The example code works great when you want to universally replace things. I don’t. I want to use a different template per-CPT, so my code is this:
```
/*
 * AMP custom templates
 */
add_filter( 'amp_post_template_file', 'lez_amp_post_template_file', 10, 3 );
function lez_amp_post_template_file( $file, $type, $post ) {

	$post_type=$post->post_type;

	if ( 'post_type_characters' === $post_type || 'post_type_shows' === $post_type ) {
		$file = get_stylesheet_directory() . '/amp-templates/shows-chars.php';
	}
	return $file;
}
```
That was the easy part.

Making Your Template

Now I need to make the template. It’s actually not as obvious as it might be. You can’t just copy the single.php file from the AMP templates folder and go. No, if you want to use it as-is, you will need to set up how to pull the custom templates.

For the quick example, we have the Single Template and with that we have to replace all the calls to load_parts. They look like this:
```
<?php $this->load_parts( array( 'header-bar' ) ); ?>
```
We have to change them because the code for load_parts is relative to the file, and it doesn’t call .php so it’s a bit of a drama to call them. I replaced it with this:
```
<?php include_once( WP_PLUGIN_DIR . '/amp/templates/header-bar.php' ); ?>
```
This is pretty much what I tell plugin developers not to do. Never ever use WP_PLUGIN_DIR unless you absolutely have to. Always use plugins_url() and plugin_dir_path() please and thank you. But since I can’t use a URL in include_once() because it’s https) and I can’t use plugin_dir_path() because it’s relative to the file it’s called from, and this is called from the theme. So yes, here I have to use the one constant I tell you not to use. I’m aware of the irony.

The rest of the template is mostly removing things I can’t filter out. I removed the feature image, I removed the byline (we don’t care who wrote the CPTs, authorship isn’t an issue), and I removed the taxonomies.

Fix The Images

Once the main file is loading properly, it’s time to address the two problems with the images: size and location. There’s, thankfully, some default code that can help with this that didn’t need a template. AMP comes with directions on changing your featured image but the example code had to be tweaked in order to handle multiple post types:
```
add_action( 'pre_amp_render_post', 'lez_amp_add_custom_actions' );
function lez_amp_add_custom_actions() {
	add_filter( 'the_content', 'lez_amp_add_featured_image' );
}

function lez_amp_add_featured_image( $content ) {
	global $post;

	$post_type=$post->post_type;
	$post_id=$post->ID;
	$image_size = 'featured-image';

	if ( $post_type === 'post_type_characters' ) $image_size = 'character-img';
	if ( $post_type === 'post_type_shows' ) $image_size = 'character-img';

	if ( has_post_thumbnail() ) {
		$image = sprintf( '<p class="lezwatch-featured-image">%s</p>', get_the_post_thumbnail( $post_id, $image_size ) );
		$content = $image . $content;
	}
	return $content;
}
```
But. This made double images! Why? Because this is a lie: “The default template does not display the featured image currently.”

It does. This is why I removed the featured image in my template. If I can figure out how not to do that, I’ll be 90% of my way to not needing a custom template at all, because everything else I did in the filter.

Add the Extra Content

Remember function lez_amp_add_featured_image() above? Yeah I threw it out and made an insanely complex. I renamed it function lez_amp_add_content() and the if ( $post_type === 'post_type_characters' ) {} section became huge so that I could output the code the way I wanted.

In the image above, you can see I’ve not only added in a lot more meta content from the post, but I also tweaked the CSS to float the image to the left and resize the SVGs. I went super image light on this, loading the smallest image that would work, and the SVGs are very small sized.

Overall? It should be easier

The biggest issue I have with this is that I wish I could filter more. If I could turn off the featured images and remove the bylines, then I wouldn’t need the custom template at all. At least, not for the characters. The shows? That’s another matter.
19 December, 2016
AMP It Up
We’ve all heard about how Google wants to make mobile pages faster. The Accelerated Mobile Pages (AMP) Project is there to deliver and process a pared down version of a webpage, prioritizing speed. Since speed is important to your SEO, and I’m on a bit of an SEO kick, you bet it was next on my to-do list.

I admit, Joost talked about this at his WordCamp US talk this year, and among my notes was this:

Add AMP – not set it and forget it

This is so, so true.

The AMP Plugin

First its like all things WordPress, you install the plugin AMP by Automattic and activate it. That does the easy work. Of course then you have to customize the hell out of it to make it look right. Still, out of the box the plugin adds a /amp/ so if you go to https://halfelf.org/2016/amp-it-up/amp/ then you’ll see my AMPlified pages. If you’re using Multisite, you may need to re-save your permalinks for the URL to work.

There are some big warnings about this though.

1) No analytics tracking
2) You don’t get to design your AMP page
3) It doesn’t work on the front page or pages or cpts

Don’t worry! We can fix all that!

Analytics

If you’re using Monster Insights for Analytics, supposedly they added in some code to make tracking work, but I was unable to find it in the code or documentation. More than likely it’s in their Pro version. I don’t use that plugin simply because I found it easier to use a 28 line mu-plugin for my network and I don’t need to see my stats all the time. I used the AMP WP recommended method and put it in the same mu-plugin as I have my regular analytics.

Design

This is a little messy. Design is a very complicated word. If you just want to change the colors, you can do this via Appearance > AMP. Whaaaat!? That’s right, it lets you change the header color and font color right there. Super simple. If, though, you want to make your CSS tweaks directly to change that light blue header to navy, perhaps, you can follow the AMP WP directions for CSS additions and have this:
```
add_action( 'amp_post_template_css', 'halfelf_amp_css' );
function halfelf_amp_css( $amp_template ) { 
	?>
	.amp-wp-header {
		background-color: #013659;
	}
    <?php
}
```
I strongly recommend making few changes. Oh, color of course, but don’t go and make a 1 meg CSS file. The point of AMP is to load faster, after all!

There’s a whole second level of design that I’ll get into later. It needs its own post.

AMP your CPTS

Right now you can only do it via code. The AMP WP directions for CPTs state they may come up with a better way, but for now you do this:
```
add_action( 'amp_init', 'my_amp_add_this_cpt' );
function my_amp_add_chars_cpt() {
    add_post_type_support( 'post_type_this', AMP_QUERY_VAR );
}
```
It’s pretty direct, and I added this in the bottom of my existing CPT code.
14 December, 2016
WordCamp LGBT Tribe is Code

Last Friday we had the first ever LGBT+allies party at a WordCamp. It wasn’t really the first time we all got together, but it was the first time we stated to the world that this was what we were doing.

How did it go?

We sold out our 150 tickets. We ran out of shirts. We had an open bar and music and food (real food) and pins and stickers and a million little things. It was loud and a great many more people than I thought would show up did show up. Matt was there too.

Tracy and I kvelled about it. We never expected that. We thought maybe a dozen, or fifty at most, would show up. We thought it would be mostly the queers, filtering in and out. We thought it would be more of a flow.

What we got was a packed house. We had around 200 people who came in, queer and straight, to be there for each other and to support and hug and be there. What we got was a moment where our two tribes were there. Our nerdy WordPress people and our fabulously gay people, together, combined to remind everyone that the best part of us is the us.

Community is what makes WordPress so amazing. I spoke about that on Friday as well, that individually we are not our products, our code, but together we are 27% of the Internet. Individually, we are not just gay, straight, queer, trans, or ace. Together, we are the LGBT+ tribe. Together we are the queers of WordPress. We are a huge slice of WordPress and we are not alone.

I like to joke that WordPress makes queries for a reason, that WordPress is queer. And it really is. The last four years WordPress has gone from quietly supportive into publicly proud.

Thank you, everyone, who sponsored and came to the party last week. You stood up and reminded us that we are not alone. And as much as 2016 sucked, we have each other’s backs.

I don’t know how, but we will have to figure out how to do this next year at Nashville, because this was too amazing to do it as a one-off.

9 December, 2016