What turned out to be my last major job before starting at King Arthur was a new website for Second Growth, a local nonprofit dedicated to treatment, recovery, and prevention of substance abuse in adolescents and young adults. Before I came on board with Aquilino Arts my partner had set them up with a lovely Joomla site, but it was hard to update in terms of both content and software. It was time to shift to WordPress, and clean up and reorganize a little at the same time. I was involved in the organization – though we stuck fairly close to the previous structure – and gave feedback and input on the design, but my main job was the technical aspects. I wanted to discuss them here because it is our most sophisticated site to date and it gives a fairly thorough overview of my methods for site construction.

By the way, I have a Pinterest board devoted to plugins we use, which you can take as recommendations.

The front page starts with a mosaic; the left half has a YouTube video and a mini-menu, the right half is split into 3 pieces whose contents can be changed from within the Customizer. The theme is set to use two menus, intended to be the mini-menu and a full menu. The mini-menu includes a link to the full menu; the full menu appears in the footer, which is where the link goes, but if you have JavaScript, it hijacks the link and pops the full menu up in a lightbox (the method is shown almost exactly in my post about AJAX in WordPress).

Below the mosaic and a divider band, there are three more spots whose contents can be set in the Customizer. In every case the options are a page, a specific blog post, or the latest blog post. The footer includes not only the full menu but a 2-up slider of donor logos. The gallery uses Media Library Assistant to allow logos to be selected by categorizing them appropriately on the back end and is set to have two columns and random order. Flickity applies itself after page load and turns each column into a panel of the slider. All gallery/slider and lightbox functionality (which is via Colorbox) is in a custom plugin so it can persist should they change their theme down the road. The choice of Flickity and Colorbox is semi-arbitrary; I’m familiar with both of them and they do what I want. I’ve never written about Colorbox here, but I’ve written fairly extensively about Flickity.

On interior pages the mini-menu appears as the top-of-page menu; the logo gets you back home if you don’t want to use the full menu popup. Certain content is accordion-folded, which is also provided by the custom plugin but is hand-coded. Different pages have different sidebar content via Display Widgets, chosen as the least awkward of the options. Almost all of them have a donate button and contact link; most have a two-column gallery of donor logos; a couple have a still of the home page’s YouTube video that lightboxes up into a watchable video. One has 1-up slider of photos, chosen via Media Library Assistant’s tagging system.

The contact form is from Contact Form 7, because of the option of Selectable Recipient with Pipes, including the ability to use the pre-pipe content by prefixing the label with _raw_. The event calendar is Event Organiser, chosen because it does recurring events and is developer-friendly. I didn’t end up turning off the original CSS, but I found it reassuring that the developer included that option. It provides for per-category colors, which we used to make one-off events stand out from weekly recurring events, and also produces the lists of upcoming events that appear on the home page (set to show only the next instance of any recurring event) and in the sidebar of one of the interior pages.

There are two custom post types aside from contact forms and events, both created and given custom taxonomies using Custom Post Type UI. One is testimonials, which currently only exist in the sidebar of one page (a single random one selected and shown by Flexible Posts Widget with a custom template – and by the way you can get all my custom FPW templates on GitHub). The other is resources. The resources archive and news (blog) archive look similar: they are topped with buttons for each category (or topic, the resource-specific hierarchical taxonomy) and for the whole archive. These buttons are coded into the archive templates. The list of all resources actually excludes one of the categories; resource archives also display alphabetically by title instead of by date and with more allowed per page.

The news archive shows the featured image and an excerpt; the resource archive shows the full content with no image. Featured images aren’t set to automatically show on any of the individual posts or pages; they are used for the front page featured content and news archive only.

The theme is fully responsive, and below a certain width the two-column donor logo galleries are hidden so as not to make the page infinitely long. When at “full size” the right sidebar is positioned and sized via display: table-cell. This caused some problems on Firefox with the pages with the video still in the sidebar, where the sidebar was displaying far wider than it was set to (35%). The fix was to set width: 100% on the still (in addition to the max-width: 100% set on all images in the theme). It was tricky to repair because my browsers have gotten very tenacious about using the old CSS file, regardless of hard refresh or cache clearing, until I change the version number. I’d switched to CSS tables because I was having the same problem in Flexbox, but since then have determined the same fix would have worked for Flexbox.

Using CSS tables or Flexbox was important for getting the main content and sidebar to be the same height, since the leafy divider is actually a small vertically-repeating background image on the sidebar, transparent beyond the leaves on the sidebar side and with solid white background (covering the translucent green background of the sidebar) on the main content side. When the sidebar drops below we switch the image and its positioning and repeat settings.

Originally the footer used CSS columns, as well as the sidebar when it dropped below but had width enough for multiple widgets, but then I discovered Flickity doesn’t play well with CSS columns. At all. I had crazy spillover outside the Flexbox viewport that I couldn’t figure out how to fix. No more CSS columns; they are now done the old fashioned way with percentage width and floating.

The behind the scenes plugins in the site are WP Smush for image optimization, WP-SpamShield for comment spam elimination, Google Analytics by Yoast, and W3 Total Cache for caching. With such an image-heavy site both image optimization and caching are key elements. I didn’t use WP Fastest Cache because the free version has to be cleared from the hosting account if you haven’t just published a post or page – changing the featured items in the front page won’t do it. W3TC doesn’t detect changes in the front page but you can clear its cache from a button at the top of any of its pages.

The post Touring a New(ish) Site appeared first on rweber.net.

I’ve spent a lot of time recently in the WordPress Customizer for this theme and a client theme, and have found it slow to locate helpful references and tutorials. Part of that was not learning until recently that you can put a single word in quotation marks to keep Google from helpfully trying other word forms and synonyms to get you more results (“custom” and “customize” are far from interchangeable with “Customizer” in this context, so thank you SearchReSearch for the trick), but some of it was a lack of good material.

On with the show…
The fundamental source is the Customizer page in the WordPress Developer Handbook. What it covers it does well, but it is pretty cursory. In some ways I find the old Customizer information in the Codex easier to read.

Other General Tutorials and Examples

WPShout is a reliable source for entry-level tutorials that aren’t shallow, and you may find their Customizer introduction and overview helpful.

Tom McFarlin wrote a tutorial series for WPTuts+ that is well-explained. You can find an index for the WPTuts+ series on his blog.

The WPTuts+ series is a few years old, as is this Theme Foundation Customizer tutorial, which moves a little faster but is a little more comprehensive. However, the basic syntax is largely unchanged.

There’s a general introduction on Noupe that covers some of the same ground, but in a different way and with some different inclusions.

Tom McFarlin has suggestions on organizing your code for maintainability that will already be the case if you are working from Underscores.

Here are two WordPress themes on GitHub that use the Customizer and have authors who know a lot about the Customizer: Hybrid Core by Justin Tadlock; Oenology by Chip Bennett.

Adding Custom Controls

WordPress provides a number of control types: checkbox, radio button, select box, textarea, dropdown of pages, color picker, and media selector. You can add your own on top of these.

If you are adding controls, whether custom or built-in, the input needs sanitation; ThemeShaper has an article on validation and sanitation for the Customizer.

Otto has a good introduction to custom controls that is a little old but still relevant.

WPMU DEV has another intro, including the built-in controls, that might be good for a second explanation.

Justin Tadlock has a tutorial on a control that replaces radio buttons with images but still acts as a radio button control.

I found it easiest to understand custom controls via example. There are lots of collections of premade custom controls on GitHub that you can use and learn from, with a variety of authors: the WordPress Theme Review Team, Paul Underwood, and Frank Bültge for three (but see last week’s post for a caveat). Braad Martin has a control for a color picker with alpha. You can also see custom controls in action in the WP Customize Posts plugin by Weston Ruter.

Contextual Controls and Partial Preview Refresh

Contextual controls are those that appear and disappear based on what you’re previewing or what choices you’ve made in other controls. It and partial refresh are frequently covered in the same articles so I grouped them together. I discuss both in last week’s post, for one.

Otto talks about active_callback for contextual controls in a post about recent changes to the Customizer as of May, 2015.

In a Stack Exchange answer, Weston Ruter discusses the JavaScript alternative to active_callback.

WPShout covers partial refresh and active_callback in their follow-up to the general tutorial.

The Future: More JavaScript, Less PHP

Right now you can avoid JavaScript entirely provided you don’t mind the entire preview refreshing to update and you don’t want to hide and show controls dynamically. Since WordPress is great about back-compatibility, that probably will always be true. However, the future of the Customizer is in JavaScript. [Since the Customizer is pointless without JavaScript even my progressive-enhancement-obsessed soul can’t object.] Here are four links about using JavaScript for everything:

Weston Ruter in Make WordPress Core on how things work and where they’re going, October 2014.

Nick Halsey also in Make WordPress Core on rendering custom controls with JavaScript, in particular; November 2014.

Justin Tadlock has also written about rendering custom controls with JavaScript.

Finally, if you have a lot of options in the Customizer (the wisdom of that may be debatable) and they are injected with JavaScript, you may find your script is noticeably laggy. Here’s an article by Layers on speeding up the Customizer via delayed loading of controls.

I haven’t tried to implement a JavaScript-only Customizer in Amalgamation yet, but it’s on the list.

The post WordPress Customizer resources appeared first on rweber.net.

After the basics were in place, I started adding to Amalgamation (this site’s theme) to make it customizable for someone who might want, say, different pages featured in the front page’s panels. The correct place to put appearance-affecting settings is now the Customizer, which meant a lot of new learning.

It was not without its swearingdifficulties, and for a while I had a nice little hack in place (labeled as such) but I got a handle on it and thought I’d write a bit about the parts that took me while to figure out or were difficult to find information on. This isn’t intended as a self-contained tutorial; I’ll follow this post up with a post of resources. Edit 3/12: The Customizer resource post is up now.

Customizer PHP

In Amalgamation, this is all in customizer.php.

Underscores is a good start on the Customizer, especially for mimicking JavaScript syntax, but begins quite light on the PHP side. All it does is implement partial refresh for a few of the built-in settings. I wanted to add a bunch of new settings and also remove the irrelevant defaults, which you can see near the beginning of amalgamation_customize_register().

There were two things I remember giving me pause when adding settings (see code on Pastebin):

The first was keeping the pieces straight, including what needed the same name. The setup is a little convoluted; sections and controls are UI entities – they are about what appears and how in the Customizer pane. Settings are data entities – they hold the values you use controls within sections to select. That’s why they don’t exist within sections like controls do, and why the label and description are set within the control definition. They are, however, tightly coupled to controls, which is why they both get the same label as their first parameter.

The other mild slowdown was not knowing how to define a radio button selection, but hopefully my example makes it clear: in the choices array it is ‘setting’s value’ => ‘value’s description’.

WordPress has a page dropdown included, but I wanted to allow posts as well so I needed a custom control. I began by using a post select dropdown from Paul Underwood, but changing the selection didn’t alert the Customizer that a change had been made – the Save button remained grayed out. Since I didn’t need the flexibility of that control I switched to one by Tom Rhodes that has since disappeared from his GitHub. That one worked, and I’ve since determined that the key was in the select element having the attribute data-customize-setting-link="<?php echo $this->id; ?>". When I added that attribute to Paulund’s code, it worked as desired.

Note that the definition of the custom control needs to be accessible from within the function that’s adding the custom control. The easiest way to do that is to define it within the function, whether directly or via an include statement.

Using the settings in your theme is easy: get_theme_mod( 'setting_name' ); returns (rather than echoes) the value.

Customizer JavaScript

This is in two files in Amalgamation: customizer.js and customizer-controls.js; the enqueuings are in customizer.php.

JavaScript is currently optional for the Customizer but developers are encouraged to use it for essentially all the functionality. I did not (though I intend to at least try it out in the future) but I made good use of JavaScript for dynamic display of controls in the sidebar and for partial refresh in the preview so a small change did not require the whole thing to reload.

The first thing to note is that there are two different actions to hook your script enqueue functions into, depending on whether the script affects the sidebar or the preview pane. The preview is in an iframe so it is effectively a completely separate website; scripts that live in one location can’t affect elements in the other.

For dynamic controls, the enqueue command is this (view on Pastebin):

You can code these as you would any other show/hide commands, but I found I needed to enclose them in an extra $(function(){}); to delay execution and prevent them being overridden. The necessary ids for your elements will be generated following a standard pattern and are easy to find in the web inspector.

For preview AJAX, the enqueue command is this (view on Pastebin):

Note that I’m localizing the script also, as in my previous post about AJAX in WordPress. This of course is only necessary if you actually plan to make AJAX calls. Within the script you have to follow the pattern

wp.customize( 'setting_name', function (value) {
    value.bind(function (to) {
        // your css/html change or ajax call
    });
});

If you leave out value.bind it won’t work. From what I understand, “value” here is the fact of the change, and “to” is the result or contents of the change (e.g. the color code, text of the byline, or id of the page you selected from the dropdown). Once you’re inside you can do whatever you want; it’s no different from JavaScript written from scratch to enact a change on the page. In particular AJAX works the same way as in WP at large.

There’s my contribution for now. Stay tuned for the resource post. Edit 3/21: My selection of customizer resources is posted now.

Marionette photo by Jürgen Howaldt (Own work (selbst erstelltes Foto)) [CC BY-SA 3.0 de], via Wikimedia Commons.

The post Learn by doing: the WordPress Customizer appeared first on rweber.net.

The code is on GitHub, and once I get through the basic list I’ll start versioning it so it’s always safe to download and use.

Meanwhile I would love feedback. There’s only so much testing one person can do, especially on the local version. If you notice any brokenness or weirdness or just have an opinion, please let me know!

The post A new and responsive look appeared first on rweber.net.