Category archive: WordPress 16 posts

F******k Instant Articles: How do they work?

Posted by Jer Clarke on July 21, 2017 · design · WordPress

This is the web version of my WordCamp 2017 talk about Facebook Instant Articles

Here’s the slides embedded from Slideshare.

Key links:


  • You run your own WP site
  • Mobile traffic is key
  • Facebook is a source of traffic for your content
  • You don’t want to use weird awful ad networks
  • Your soul is for sale

What is an iA and what does it do?

instant articles promo image

  • Posts load very fast in Facebook mobile apps
  • Replaces WP theme for posts viewed from Facebook mobile
  • Plugin sends posts to Facebook as raw data when saved
  • Facebook stores post content and renders them for mobile visitors
  • Does not “share” your posts, you do that the normal way with normal URL
  • Only applies to mobile apps, but that is the most common traffic

Okay but what is an AMP again?

  • Alternate version of a URL hosted on your site
  • AMP is a custom „theme“ WP uses on your content to match the AMP standard
  • AMP versions of posts get harvested by Google and stored in their cache
  • Fast AMP cache served to Google mobile visitors
  • Google gives your content special treatment in search (Carousel)

Why NOT use iA?

  • You hand control of your content to Facebook
  • Violates open web principles (walled garden)
  • You are subject to Facebook’s whims
  • Content must be crammed into very limited format
  • Some content not possible in iA
  • Complications integrating with WP plugins
  • Not all ads function
  • Interactivity features must be on Facebook‘s terms

Why use iA?

  • [Promo image]
  • Actually super fast
  • More useable and beautiful than most sites on mobile
  • Only ever uses your URL as the web address of posts (unlike AMP)
  • Analytics integration available
  • No load on your server from traffic wave
  • Advertising integration available
  • Facebook probably gives iA unfair advantage [citation needed]

Steps to set up!

Create a FB page

  • You can figure this out, I believe in you!

Initial plugin setup

  • Install Instant Articles for WP plugin and activate
  • Click „these instructions“ link to iA page activation screen
  • Choose your page, then accept the terms
  • Your page is now „activated“ for iA

Go to your Instant Articles Configuration screen inside Facebook (steps re-used later)

  • In Facebook visit your page
  • Click on Publishing Tools at the top
  • Click on Instant Articles ? Configuration in the sidebar
  • This screen is your real dashboard for iA setup, you will visit it a lot.

Get your facebook „Page ID“ for the plugin settings screen

  • In the Step 1: Set Up Instant Articles section, click on the Connect Your Site:Authorize your site link
  • First, insert your site URL in the Your Registered URLs field.
  • Copy the Page ID from the WordPress Plugin Users section
  • Return to wp-admin and the Facebook Instant Articles Settings screen.
  • Paste the ID you copied into the Facebook Page ID field.
  • Now the iA integration should be working, and you should see the iA metabox whenever you edit a post!

Set up a default Style Template

  • A style template is required to get approved, but can be very simple.
  • Go to your Instant Articles Configuration screen inside Facebook (see above)
  • Find the Tools section (below Initial Setup) and the Styles subsection.
  • Click on the default style to edit it.
  • The only MANDATORY thing is to have a Logo set for the article header (690x132px)
  • Configure the rest by preference, you can change it later anytime
  • Just make sure you have the Logo set up, so that you don’t get errors about it below.

Get 5 posts ready to publish Submit for Review

  • Overarching goal: Get the Submit for Review button in the wp-admin Facebook Instant Articles Settings screen to light up blue so you can push it!
  • We need to have 5 posts that have been submitted to iA by being saved after you have set up the plugin.
  • You can use existing posts, but they have to be re-saved
  • Edit your recently published posts and find the Facebook Instant Articles metabox
  • Move the metabox to just below the post for convenience, at least temporarily
  • Deal with any global errors you see that apply to all posts (see transformation debugging later)
  • Have 5 posts ready with no errors

Submit for Review!

  • Return to iA settings screen in Facebook
  • Find the Submit for Review button
  • Deal with any remaining errors (sorry)
  • Submit!

Testing your iA posts

    • iA only show on Facebook mobile apps, so testing is tricky
    • Basic: Share a post to Facebook, then view with a mobile app
    • Facebook Page Manager app (ios/Android) lets you preview posts without them being live on FB.
    • Use Page Manager to preview and design your iA while your review is pending
    • Also useful to preview iA without sharing to facebook
    • Getting to Page Manager previews:
      • Open Page Manager
      • Find your page
      • (more)


  • Instant Articles


Development mode

  • Sets your site to submit to Development rather than Production stream
  • Posts only visible in Page Manager app and Publishing Tools on Facebook site.
  • Useful when you are already approved, but want to test publishing with different configurations
  • Using Develpopment mode:
    • Enable Development Mode in wp-admin Instant Articles Settings
    • Change some settings (Style, transformations)
    • Resave an article, which will be submitted to Development rather than updating the Production version that visitors see.
    • Preview the new version in Development section of Page Manager app.
    • Disable  Development Mode in wp-admin Instant Articles Settings
    • Resave a post yet again, now submitting to Production with new settings
    • Check that the new post version is as expected in Page Manager app


  • iA uses a small subset of HTML5 as a strict markup standard
  • Transformations convert your standard HTML into iA markup
  • They can convert to an iA Format, or remove content entirely
  • Many useful WP transformations are built into the plugin

Transforming your problems into solutions

  • Transformations are added in the Custom transformer rules section of wp-admin iA settings
  • Uses JSON format, not very user friendly
  • Can be automated by plugins but not easy
  • Often you just need to remove items added by plugins (sharing tools)
  • Other times your custom styles (.pull-quote) can be converted into matching iA Formats

Debugging transformations

  • Errors for invalid markup will show in the WP post editor
  • Posts with errors just won’t submit, so it’s okay if some posts have un-transformable content
  • Forcing a post with errors to submit will mean the invalid content is just missing.
  • Establish editorial standards about how to solve common transformation errors
  • Some valid HTML combinations must be avoided to use iA consistently

Cover Images

  • Populated by WP Featured Image by default
  • Always show at the very top of posts
  • By rule, cannot be duplicated inside the post
  • Consider disabling Cover Image entirely if you insert your Featured Image in your posts


  • Production/development RSS feed: NO NEVER
  • Always have featured images!
  • Good luck with AMP integration!

Previewing Local/Dev RSS Feeds on Mac OSX

Posted by Jer Clarke on January 27, 2016 · WordPress

This post is filed under “I had an obvious need, I searched for it and found nothing, so here comes a blog post for the next searcher.” If you don’t do local web development or don’t know what that means, please watch this video instead, I promise it’s worth your three minutes and sex seconds.

TL;DR: You can preview local RSS feeds on OSX using ViennaRSS, a simple free app.

The problem: Previewing RSS output from a local development site

Developing locally: I run MAMP as my local server on my Mac to work on WordPress sites. As most developers know, this makes it easy to quickly edit the many PHP/HTML/CSS/JS scripts that make up the site using whatever tools I want, and importantly avoids my edits affecting the production server where my actual sites live. It’s easy to view local sites in any browser using generic URLs like https://localhost/ (most cases) or custom ones like https://dev.gv (which I set up for developing Global Voices).

Modern RSS services can’t fetch local URLs: What’s not easy is previewing the experience of reading your RSS feed, because the way most RSS services work these days makes it impossible. Generally speaking RSS readers function based on services which fetch the RSS for you, then serve you the results. These services can’t see your local feeds  because their servers have no way of accessing your localhost (nor would you want them to).

Why do I want to preview RSS? Whenever I add special formatting into the posts we use on Global Voices (things like expandable boxes, translation quotes, pull-quotes, user lists) I try to ensure that they look good in RSS as well as the homepage, which is not easy considering you lose access to all the JS and CSS the special content normally relies on. This can be a very tricky process, and being able to see the output rendered normally is really valuable (in addition to looking at the raw XML/RSS in Chrome which just shows you the code).

Old fashioned RSS was better at this: In the past RSS readers were much less efficient but also way more simple: You gave them a URL of an RSS feed and they fetched the content. The irony is that in improving the efficiency, reliability and performance of RSS, these newer services accidentally killed our ability to test and preview the content we’re putting out.

My Solution: Use “ViennaRSS” for OSX to Subscribe to your Feed

vienna_logoThere is nothing amazing or revolutionary about this solution, I just wanted to share the outcome of my search. After a few wrong turns and failed attempts, I found ViennaRSS, a straightforward, old-fashioned RSS reader that has been updated enough to work on modern OSX.

In Vienna I was able to add a new feed, give it my local URL (https://dev.gv/feed/) and view the posts to see how they looked.

It doesn’t have any inspect/dev tools to speak of, so don’t expect it to solve all your development problems (view the raw RSS in Chrome to see the HTML), but you can see what most users are likely to see and avoid any major blunders with your new code before it has any effect on your actual RSS readers.

Tips and Troubleshooting

Ticking the Mark updated articles as new setting in Vienna's preferences might make it update more consistently.

Ticking the Mark updated articles as new setting in Vienna’s preferences might make it update more consistently.

  • Remember to disable any caching on your local site, as it will likely serve out-of-date versions of your RSS to Vienna.
  • You can refresh your feed (after making changes to your PHP) by right-clicking your feed in the Vienna sidebar and choosing “Refresh”.
  • “Mark updated articles as new” is an option in Vienna’s Preferences menu that seems to help it refresh more effectively. If the “Refresh” tool doesn’t update the post with your changes, try enabling this setting first.
  • Another way to “force” the refresh of a post is to re-save it in your CMS. I found that Vienna will keep showing me the same version of a WordPress post regardless of refreshing, but re-saving the post, then refreshing Vienna showed me an up-to-date version of my RSS output.

Don’t forget to validate!

The W3 Feed Validator is an extremely useful tool for debugging production RSS issues (by giving it your feed URL), but it can also debug local feeds!  By using the Validate by Direct Input button you can copy your feed’s entire XML code from Chrome and paste it in.

It’s easy to break the “validity” of your RSS when you add things to it, so using the W3 validator is really valuable both for making sure your code is right and to debug any problems you might be having with Vienna or any other RSS reader that can’t handle your RSS.

Slides from my WordCamp Talk: Put A Map On It!

Posted by Jer Clarke on July 5, 2015 · design · GlobalVoices · WordPress

These are the slides for my talk at WordCamp Montreal 2015, about integrating maps and geolocation into your WordPress site with the Geo Mashup plugin. There should be video eventually and I’ll add it here :)

Full talk description

WordPress has built-in support for storing location information on posts, but no real way to make use of it. The Geo Mashup plugin enables deep, powerful geolocation in WordPress, letting you easily add geolocations (coordinates) to almost any content type. It also displays locations on maps you can embed in your theme, posts or widgets, with a dizzying array of options for what to show and how to display it.

This talk will start with the default geolocation system in WordPress and how Geo Mashup integrates with it. We’ll then cover the basics of setup and adding locations on posts, then the different map types and situations where you’d use them. We’ll finish with some dev considerations for displaying maps as elegantly as possible.

NetBeans Color Scheme: Solarized Dark with PHP Tweaks

Posted by Jer Clarke on August 17, 2012 · design · WordPress

Jump to download and installation instructions »

What is Solarized?

solarized logoSolarized is a programming color “palette” designed  by Ethan Schnoonover for use when writing syntax-highlited code. It’s based on color wheel and lightness relationships and it’s all sciencey and stuff, but the essence is that all the colors look good together and have good contrast, so you can use the different colors for different parts of your code (functions, variables, strings etc.) and no matter how you organize it the result should be easy on the eyes. It also has both a “dark” and “light” mode with different background/foreground colors, but most of the colors (red, green, magenta) work the same for both, which is cool.

Here’s a color reference I put together showing the various colors in Solarized Dark along with their RGB and hex codes. It was very useful to have around while working on the NetBeans theme (the Solarized site is strangely lacking a similar reference).

My Solarized Dark theme for NetBeans+PHP

As soon as I heard about Solarized I wanted to try it out with NetBeans, my IDE of choice for PHP/WordPress coding. I’ve spent many an hour tweaking my color schemes in NetBeans (and Smultron, my old text editor before that) and choosing the color relationships was always the hardest part, so having classy choices all laid out for me was very appealing.

The good news was that there is already a NetBeans port of the Solarized colors that worked as advertised. The problem was that IMHO it wasn’t particularly well executed. NetBeans has a lot of options in the color scheme settings, but they are also extremely confusing and often flat-out misleading, so I don’t blame the original author for not getting it perfect. He also may not have been looking at PHP code, in which case it makes sense that the PHP-specific color settings weren’t well organized. Lastly there’s a huge element of personal taste, even within the process of implementing a preset color theme like Solarized, so I recognize that the result is really just my personal opinion of what NetBeans+PHP+Solarized should look like.

All that said, here’s a screenshot of my NetBeans Solarized Dark theme:
Screenshot of my solarized dark theme for Netbeans

I like to think it balances the need to have different parts of the code be different colors and the limitations of doing so using the NetBeans color settings. It should work just as well with procedural and object-oriented code.

One feature I added that isn’t in the original Solarized for Netbeans colors is SVN support. I had to invent them, but my theme has appropriate red, green and blue background colors when viewing a SVN DIFF.

Installing my theme in your NetBeans

Since NetBeans has a configuration import/export system you can install these colors really easily.

  1. Download the .zip file linked below (don’t unzip it, NetBeans wants it as .zip).
  2. Open NetBeans and summon the Preferences window (Options on Windows).
  3. Go to the Fonts & Colors Preference tab.
  4. Click Import at the bottom of the window.
  5. Click Browse and find the .zip file, click OK.

Download »

Once you have the theme installed it should show up in the Fonts & Colors preferences as part of the Profile pulldown menu, where it’s identified as Netbeans_Solarized_Dark-jer.

Since I started using this I pretty much never feel the need to use a “light” theme so I haven’t tweaked the Solarized Light colors at all. Sorry if that’s what you would have preferred ;)

Anyway, hope some of you find this useful! I plan to someday get some of my changes added to the official GitHub repo, but wanted to get this out before my Code Faster and Smarter PHP with IDEs Like NetBeans talk tomorrow at WordCamp Montreal.

A Love Poem in PHP

Posted by Jer Clarke on November 7, 2011 · General · WordPress

Wrote this a long time ago but never posted it. Stumbled onto it while cleaning up my email:

	$me = new Lover;

	$me->partner = $you;

	$me->feelings = array('adore','miss','want','love');

	foreach ($feelings as $feeling) {


		if ($you->feeling_mutual($feeling))

Sure, it’s not the most expressive form of writing out there, but like with Haiku I think the limitation and challenge of putting poetry into code form can help push you to create something really fresh and strange without the baggage and cliché feel of regular poetry. I also just love naming variables and methods ;)

Either way, I think my poem is at least more uplifting than this other PHP love poem I found.

It was actually a follow-up to a shorter, twitter-length PHP love poem I wrote around the same time:

	$things_i_dont_miss_about_you = array();

Submit your coded love poems in the comments, bonus points if it could at least theoretically execute in real life (assuming for example things like the existence of a “Lover” class with an express_feeling() method). If you’ve got the time write us an Epic PHP Poem, including all the needed class definitions :P

Another year, another exciting WordCamp Montreal

Posted by Jer Clarke on June 22, 2011 · WordPress

Once again I’m organizing WordCamp Montréal along with a great team of co-organizers. I’m managing the schedule and helping with all the other stuff. We’ve got a lot of great talks lined up as well as some fun summer treats to keep everyone energized and make it a great social event on top of being a place to learn and grow your skills.

I'm going to WordCamp Montreal 2011!

Grab a badge for your blog here.

If you use WordPress and have been meaning to learn more about it you should definitely come. In three years I’ve literally never heard anyone complain that WordCamp is a waste of time, even when they find a million other things to complain about ;)

Tickets are on sale now, so you should register ASAP.


Multilingual content in WordPress, September 2010

Posted by Jer Clarke on September 7, 2010 · General · GlobalVoices · WordPress

Someone emailed me recently to ask about how they should approach the task of setting up a multi-lingual WordPress site (en+fr). My response was long enough that I figured I’d post it here for anyone curious about my thoughts.

We’re looking to update our WordPress website with a multi-language setup […] Would you recommend that we use a multi-lingual plugin, such as WPML, or just create two different wordpress sites?  I’d rather do the former, since once setup it demands much less updating.  I’ve heard in the past that this is very difficult to do, but now with WP 3.0, I’m thinking it must be much easier.  I’d much appreciate your opinion.

Multi-lingual in 3.0

The advent of 3.0 has changed many things but not the frustrating lack of support for multilingualism in WP. The same issues exist now as did in the 2.x days. The main relevant change in 3.0 is that WPMU, a seperate project which let you have multiple sites in one installation, is now part of the main WordPress code. The feature is now referred to as “Multi-site” or “Network” and is fairly easy to activate. This means if you decide to use separate sites it is a bit simpler to have both sites running off the same WP install and sharing themes/plugins. Just set up your main site as and the French one as

Plugins can be abandoned

While its true that two sites requires more tedious repetitive work during updates it less likely to involve insane compatibility work that could arise from the plugin acting up or becomming unsupported. Users of the previously-standard Gengo plugin all got fucked around version 2.5 (don’t feel like looking up the exact version) when the plugin stopped working and none of them could update their sites, leaving them susceptible to hackers. An unpatched version of WP is often vulnerable to attack and a site that depends on a plugin that stops working can’t be patched. is probably your best bet for a plugin

WPML seems like it has serious and dedicated professional developers, and has a LOT of features that are very useful, so its a decent bet that as a translation system it will continue working for a long time. Especially if you don’t have a ton of content it is a pretty good choice (because you can always copy/paste the content into a second site some day if the plugin stops working). Using it will require some heavy modifications to your theme if you want the language chooser etc. to actually make sense. My experience with WPML has lead me to believe that the devs aren’t particularly great UI designers compared to their programming skills.

Multiple sites keeps your posts database clean and logical

I personally like the two-site approach because it keeps your content and databases clean as a tradeoff for the deeper linkage between translations you could otherwise get from a plugin. It’s extra hassle to edit the content on both sites all the time but IMHO the bigger hassle is actually translating and keeping content fully synchronized which is nearly impossible regardless of your translation infrastructure.

On Global Voices we have a custom solution we call Lingua

I don’t have any real experience with WPML or qTranslate (the other big name in WP translation) because on Global Voices (the site I run) I’ve coded a custom translation plugin that we call Lingua. It uses separate sites but keeps a database that links translations across the sites (see for an example of the output). IMHO this is the best model for running translations because if the plugin stops working all you lose is the links to other versions. Each translation site can continue to work independently without knowledge of the others, so you can work on the update issues seperately while still being secure. Unfortunately the plugin isn’t even close to being public-friendly, but I’m hoping the model gets used someday. I added it to the list of potential plugin types on the Codex page about multilingual WordPress.

Maybe one day it will be easy

Good luck to anyone trying to build multi-lingual WordPress sites. It’s a nightmare but none of the other CMS options are actually much easier, and all the other benefits of  WP make it hard to turn down. Here’s hoping that one day the core development team is willing to pick up the problem and commit to a standardized solution (vote for built-in multilingualism on the WordPress “Ideas forum”).

EDIT (Sep 11, 2010): I should also mention the Worldwide Lexicon project and their WWL translation plugin for WordPress. It has an intense approach that combines machine translation with human editing to make your site quickly translated and let you improve it incrementally as time goes on. I haven’t used their plugin myself because older dev versions I tried were very buggy and hard to understand. If you’re just starting now the new versions are worth a try and may be a good solution if the combination of machine and human translation is desirable to you.

WordPress Admin Header Redesign: Light or Dark?

Posted by Jer Clarke on March 27, 2010 · design · WordPress

WARNING: Intense discussion of the open-source design of the WordPress website software lies ahead. I will literally discuss shades of grey. People uninterested in WordPress and its future should probably learn more about snuggies instead.

I updated my WordPress SVN Trunk installation today and noticed a huge change to the admin screens that had just been committed. The header and footer of the admin section had been switched from basically black to a very light grey color. This change was committed as a work in progress, so people would see it and work towards a final solution.

Fig 1. Old admin header color on top, current SVN version below.

Old WordPress header color and temporary new on in SVN

Overall I support this change and think it looks better, but the exact shade of grey in the background didn’t match the gradients in similar UI elements (the dashboard sections and screen options buttons) so I worked out a different light-grey graphic to use as a background that would match. Here is a screenshot of how it should look if this light grey is used in the final WP 3.0 release, I think it is pretty solid and shouldn’t make anyone cry.

Fig 2. WP-Admin with darker but still light-grey heading and footer. Pretty okay.

Screenshot of wp admin with light grey header and footer
Click to view full size

I remembered a conversation on the WP UI dev blog where another middle-grey option was proposed but didn’t get a lot of attention. I really liked the darker grey version in JohnONolan‘s original mockup so I worked out a full page screenshot using the darker shade of grey that I thought worked better and added them to the trac ticket about the header change.

Here’s the one I think would work the best, dark grey to match the active heading in the sidebar (in this case the “Dashboard” section heading).

Fig 3. Nice dark WordPress Admin screen, how it should be.

Screenshot of my proposed WP admin colorsClick to view full size

Here is one giant image with both of them so you can compare. Instead of images like this I like to open two versions in seperate tabs in my browser than jump back and forth to decide which I prefer.

Fig 4. Side-by-Side comparison of light and dark grey proposals for admin header and footer.

Side by side comparison of light and dark optionsClick to view full size.

I’m hoping the dark one can get implemented because it has a lot of nice features that the lighter version lacks:

  • It is not a big change from the old version, so people will be inherently less upset about it.
  • It brackets the whole UI nicely and preserves the high-contrast from the old design.
  • It avoids a page where 90% of the chrome matches each other pefectly. I think the dark grey is important to keeping the look neat, and having only one element in the page with that color (the active sidebar heading) make it look unbalanced.

Feedback welcome, what do you think? If you want to support/flame me the trac ticket about it is probably the best place, so that your input affects the final decision.

Montreal WordPress Developer Meetup this thursday

Posted by Jer Clarke on September 22, 2009 · General · WordPress

So yeah, as the title of the last post (which has slowly become ludicrously out of date) implies, WordCamp Montreal was in fact pretty awesome. If you’re a visual kind of person check out the photos.

wordpres-montreal-community-logo-square-400Now a few months have passed since then and its time to move on. Move on to something other than WordPress events? No. Move on to smaller, more regular, less stressful WordPress events (and hopefully some posts here on my blog about other topics, we can still dream).

We’re going to use the Montreal WordPress Community group on facebook to organize evening meetups about once a month (join the group to get invited automatically). Patrick and the members of Station C have generously offered to let us use their coworking space for our get-togethers. This is great cause its sexy and well stocked with tools, but sad cause its not that big. Hopefully we can keep a healthy level of attendance without exploding.

The first meeting will be this thursday, when we’ll have a presentation and discussion about programming tools and how they can speed you up followed by a discussion of GPL and what it means for paid themes, plugins etc. I also told people to bring drinks and food, so it should be a cool party as well. You can read more about it and RSVP on the facebook event listing.

WordCamp Montreal will be awesome

Posted by Jer Clarke on June 11, 2009 · WordPress

I'm Speaking at WordCamp Montreal - Jul 11-12I’ve been spending a lot of time lately getting shit ready for WordCamp Montreal, Montreal’s instance of the user-generated WordPress conference that has already happened in cities literally across the entire planet (I’ve been to New York, San Francisco and Toronto in the past).

Today the tickets went on sale (25-30$) which is a huge relief. There’s still lots of work to do organizing the speakers/schedule, sponsors and all the other details, but we’re on our way to a really useful and fun event if I have anything to say about it.

I’ll be doing a talk about whatever is missing from the lineup of speakers who come forward, which reminds me: Would you like to become a speaker? We’re still looking for WP experts to share their wisdom and experience and hopefully some laughs, so get in touch if you think that might be you. Oh yeah, if you’ve got a pile of money and have been hoping for some visibility maybe you’d like to sponsor WordCamp Montreal? It’s the perfect way to make yourself known to an incredibly useful new subsection of the north american technocracy!