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.

This is the sixth and final part of my Introduction to WordPress series. The full thing:

1. Logging in and getting around
2. Creating and editing posts and pages
3. More aspects of posts and pages
4. Inserting images into posts and pages
5. Comments and your account
6. Widgets (sidebar content) – you are here

Widgets (sidebar content)

Depending on your theme, various locations of your site will be “widgetized.” The sidebar is the most common location, followed by the footer, but there may be others. The content of those locations consists of a collection of widgets, which are chosen and edited under Appearance → Widgets.

On the left side you’ll find your widget options. Many will come from WordPress itself, shown below, and others may be added by your plugins and even your theme. On the right will be all of your widgetized areas; some may need a click on their title to open the box in which you actually put widgets.

Widgets can be added in two ways: drag the widget into the location you want it (this also works to rearrange widgets within locations), or click on the widget you want and select the location from the list that appears. The second one can be easier if you have a lot of widget options and your locations have scrolled off-screen by the time you get to the widget you want.

Once the widget is in place click its title bar to open up the settings and content editing box. That box also has the option to delete the widget if you’ve changed your mind. Make sure to click save after editing.

More on widgets from iThemes:

Most of the built-in widgets are self-explanatory, but here’s a tip for Text widgets: you can put anything into your sidebar that you could put into a post (except for shortcodes) using a Text widget. They have to be written in HTML, though. The easiest way to put images into your sidebar (and formatted text, if you aren’t comfortable with HTML) is to create a new post, add an image via the “Add Media” button, and with the Text editor tab selected, copy the HTML code WordPress generates for you. Paste that text into the widget and delete the post draft. If you find parts of your content are running together despite being separated by blank lines in the widget, check the box underneath the content that says “Automatically add paragraphs.” That should help.

There’s one last location available in the Widget screen: Inactive Widgets. This is at the bottom of the left side and you can drag widgets here to hold them (with their content and settings) for later.

The post Intro to WP 6: Widgets appeared first on rweber.net.

The fifth part of the Introduction to WordPress series covers two topics: comment management and account-related activities such as changing your password. These are together because there’s less to say about them, not because they go together thematically. The whole series:

1. Logging in and getting around
2. Creating and editing posts and pages
3. More aspects of posts and pages
4. Inserting images into posts and pages
5. Comments and your account – you are here
6. Widgets (sidebar content)

Managing comments

Comments live on their own admin page, but their settings are under Settings → Discussion. There you can choose whether comments are allowed or not by default on new posts (you can change this on a post by post basis), set your desired level of moderation (I like to approve posts by new commenters but then let their comments be approved automatically), paginate comments if you get enough to be necessary, limit the duration post-publication that comments are allowed, forbid use of certain words or phrases, and choose the kind of avatars your site uses – those little graphics by commenters’ names.

For comments themselves you have three options: approve, mark as spam, and trash. You can also reply to comments from the Comments page. Having a spam filter plugin is highly recommended; the two I’ve used most often are Akismet and WP-SpamShield. Hopefully your developed already set one of those up for you.

iThemes has a video about managing comments:

Your account options

Your user profile page is accessible from your name at the right-hand side of the Toolbar, or from Users → Your Profile in the admin sidebar. You can select an admin area color scheme (though on the front end the Toolbar will still be black), hide the Toolbar on the front end to get a better sense of what your site looks like to visitors, and change your account information, including your password. There’s not much to say about this page but it’s important to have a secure password, and to change it whenever there’s any chance it’s been compromised – you get a virus, your site is hacked, you have to make a software update that fixes a big security risk.

The post Intro to WP 5: Comments and Your Account appeared first on rweber.net.

Images are a topic we could spend a lot of time on, but I’m just going to cover the basics. The videos and links included go into more detail on certain topics. As usual, the whole Introduction to WordPress series:

1. Logging in and getting around
2. Creating and editing posts and pages
3. More aspects of posts and pages
4. Inserting images into posts and pages – you are here
5. Comments and your account
6. Widgets (sidebar content)

Inserting images into posts and pages

WordPress has a nice automatic way to manage images. All of the images and other files you’ve ever uploaded into your site via WordPress will be in the Media Library, available to be used again later if you’d like. You can upload them either from Media → Add New or from the Add Media button above the editing box for any post or page; the latter allows you to choose previously uploaded images as well.

Clicking Add Media brings up a large box overlaying your editing screen. After you upload or when you select an image from the library, the right side of the box will give you options for the image and how it appears, shown below. The first four options are Title, Caption, Alt Text, and Description; they stay with the image from use to use (though they can be altered at any time). The alt text is perhaps the most important – it appears within the HTML image tag and appears if the image somehow can’t; it is also used by screen readers and search engines as a description of the image. The rule of thumb is that if the image is wrapped in a link, the alt text should describe the destination of the link. If the image conveys information, the alt tex should repeat that information. If the image is purely decorative, however, feel free to leave the alt text blank.

The Caption is optional but will display with the image in your post or page if it is filled in. The Title and Description are used in the Attachment Page; Attachments, of which images are one kind, are actually in the same class as Posts and Pages, and so each has an individual page devoted to it. For more on the first four options, collectively called metadata, see Morten Rand-Hendriksen’s post Harnessing the Power of WordPress Image Metadata.

After those four options there are three more, which only affect this particular use of the image: Alignment, Link To, and Size. Alignment is the left-right positioning of the image. Left, Center, and Right are fairly self-explanatory; for Left and Right the text will flow into the empty space next to the image, if there is enough of it. None is like Left but without text flowing into the space. Link To is for images that should be clickable. A logo for an event you’re planning could have a Custom Link to the event page; if you’ve gotten into writing good descriptions you could link to the Attachment Page; purely decorative images or those already shown at their largest size could have no link; or you could link directly to the largest size of the image. That last is often required for lightboxing to work.

A word on image sizes: when you upload, WP will generate a bunch of smaller size options for the image, which you can then use in your posts and pages (along with the full-size one). This lets you put images into smaller spaces without forcing visitors to load a file that is way bigger than necessary. You choose which size to insert with the last option in the image insertion window.

If you decide to change the size or link, I find it quickest to delete the inserted image and reinsert it. If you want to change the alignment, it’s quick to go into the Text editor and change among alignnone, alignleft, aligncenter, and alignright.

iThemes has two relevant videos here, the first about inserting images and the second about the Media Library:

And as a final note, remember to make sure you have the rights to use any images you want to put on your site. The easiest way to do that with images you didn’t create yourself is by drawing from a stock of freely licensed photos. The sites I use for that purpose most often are Pixabay and Wikimedia Commons (the former you can use with abandon; the latter generally require attribution), and you can find a huge number of additional options on my Pinterest board Color & Images.

The post Intro to WP 4: Inserting Images appeared first on rweber.net.

Part 3 of Introduction to WordPress discusses additional settings and bits of information associated with posts and pages: excerpts, comments, featured images, and (for posts) categories and tags. The full series:

1. Logging in and getting around
2. Creating and editing posts and pages
3. More aspects of posts and pages – you are here
4. Inserting images into posts and pages
5. Comments and your account
6. Widgets (sidebar content)

More aspects of posts and pages

What about all those other boxes on the page? While title, content, and publication are vital, the rest of the options are important too. What you see will depend a bit on your theme and on whether you are editing a post or a page.

Both posts and pages will have Excerpt and Discussion below the main content box (even if you have to go to Screen Options to get them to appear), shown self-referentially in the screenshot below. Discussion is where you can change whether the post or page allows comments. The relevance of Excerpt will depend on your theme. WordPress generates an automatic excerpt by cutting your content off after a certain number of words; the automatic excerpt strips all formatting and other HTML such as links. You can create a custom Excerpt to be used instead, if the excerpt is used at all. The manual excerpt can include HTML and be longer; you may also wish to create one if the beginning of your actual content is not a good blurb for the content as a whole.

At the bottom of the right column, again true for both posts and pages, there will be a box to set the Featured Image. This is the primary image you want associated with your content; however, whether and how it is displayed is up to your theme. Many themes insert it at the top of the content somehow.

For pages that’s about it. You can read about Page Attributes under the Help tab at the top right of the screen, but they aren’t crucial.

Posts, however, get categorized and tagged. These are both ways to label your content so it can be found more easily and so search engines get the sense of the main ideas of it; more below. Your theme may also support Post Formats, which display the post differently to suit different content.

Categories are intended to be more high-level and non-overlapping – like a table of contents. They can be nested like sections within a chapter, as well. Tags are smaller-scale and can cross category boundaries; they are more like entries in an index, though that is a poorer analogy than the table of contents/category one. The idea is that a given post is in one category but can have multiple tags. You can read more about WordPress categories and tags on Socialbrite.

iThemes has a video about categories and tags:

The post Intro to WP 3: More About Posts and Pages appeared first on rweber.net.

In Part 2 of Introduction to WordPress we start talking about the main activity of most website owners: creating and editing content in the blog and elsewhere. The full series:

1. Logging in and getting around
2. Creating and editing posts and pages – you are here
3. More aspects of posts and pages
4. Inserting images into posts and pages
5. Comments and your account
6. Widgets (sidebar content)

Creating and editing posts and pages

One of the user-friendly aspects of WordPress is that different kinds of content are (mostly) edited in the same way. If you click “Add New” from the Posts dropdown or the Pages dropdown, the screens you get will be quite similar. The main portion of the screen will have a title entry box followed by a content entry box; the right sidebar will begin with a Publish box.

We’ll begin with those three pieces. First, an iThemes video about creating posts:

The title (starred in the screenshot below) will show at the top of the page or post and be part of the name in your browser history when you visit the page or post. Right below it will be the permalink, the address you can use to visit the post or page directly. You can edit the permalink manually with the Edit button next to it, or visit a preview of what you’re writing by clicking the permalink itself (conveniently the preview opens in a new tab).

[Note: this screenshot does not show a permalink editing box because the page shown is set as the home page of the site, so its address must be the main address of the site.]

Below that is the main content box, also starred. It has a lot going on along the top (circled). There will be an Add Media button on the left (possibly others depending on what plugins you have) and your choice of Visual or Text on the right. Below that will be formatting buttons, different for Visual and for Text. The “Add Media” button is how you insert images; more on that later.

Visual is the Microsoft-Word-esque editor: your formatting shows to you. If you make something bold you’ll see it bold. Text is the HTML editor: if you make something bold you’ll see it with HTML “strong” tags around it. Just to note: Visual won’t always show your formatting exactly as it will show on the front end – your theme has to have told it to do so. However, it should be close enough to see what you’re doing unless your theme does very unusual things.

I won’t exhaustively cover the buttons across the top of the main content box; if you hover your mouse pointer over them a little tooltip will pop up and tell you the name of the button. However, a few are worth mentioning: the last two buttons insert a “more…” break, limiting the amount of your post that shows in the blog archive page, and show or hide a second row of buttons. In that second row, the middle two buttons are “paste as text” and “erase formatting.” If you paste formatted test in, for instance from an RTF file or a Word document, WordPress will do its best to replicate the formatting. If you don’t want it, you can click “paste as text” before pasting and get only content, no formatting. If some formatting doesn’t translate correctly or you decide to take formatting in a completely different direction, highlight the text and click “erase formatting” to clear it back to plain old content.

Now, an iThemes video about adding links:

They have one about formatting generally, but it won’t embed, so you’ll have to watch it on Vimeo: WordPress post formatting video from iThemes.

From the Publish box in the upper right (shown below for a draft and in the screenshot above for a published page), in addition to actually publishing the post or page, you can save your post or page as a draft to work on later, edit its privacy settings, preview it, and schedule it to publish at a later time. That last happens by clicking the “Edit” link at the end of the “Publish immediately” line. That will open up a spot to put in a date and time for publication. If you put in a future time you should see the “Publish” button change to “Schedule” after you click OK. Once a post or page is published that button will become “Update.” To get back to a post or page’s editing screen, you can find it in the list of all posts or pages and click the title or the “edit” link that pops up below the title; or while viewing the post/page or a preview thereof, click the edit link that appears in the left half of the Toolbar or at the bottom of the post or page content.

Finally, there is an iThemes video about scheduling posts for later publication:

The post Intro to WP 2: Creating and Editing Posts and Pages appeared first on rweber.net.

Did you have a WordPress site set up for you? Are you now in charge of keeping it up to date? I have a series for you. Over this week and next we’ll cover the basics of using WordPress, including short videos from iThemes. All of the videos plus other information are in my Pinterest board WordPress Tutorials and Tips, and if you are starting a site you may also be interested in my boards So You Want To Get A Website and WordPress Plugins We Use. Pinterest can be a little harder to sift through, so this series puts the videos in order and adds more context and my own tips.

The plan:
1. Logging in and getting around – you are here
2. Creating and editing posts and pages
3. More aspects of posts and pages
4. Inserting images into posts and pages
5. Comments and your account
6. Widgets (sidebar content)

Logging in and getting around

The login page of your site is at your-site-address/wp-login.php, and once you are logged in you’ll be at your-site-address/wp-admin/. That is where all the action happens. In fact, you can use the wp-admin address directly; it will sidetrack you to the login page if you are not logged in.

A little vocabulary: The front end of your site is the part visitors see; the back end is the part that makes the front end happen. You’ll make changes to your site from the admin area. The first page you reach in the WordPress admin area is called the Dashboard (screenshot below), and you’ll sometimes see the entire admin area referred to as such (though properly it is just that one page). At the top of the screen when you are logged in you’ll see the Toolbar, which is basically a menu bar.

One general principle: in the WordPress admin there are a lot of drop-down and pop-out submenus. In every case, clicking the item that has the submenu is the same as clicking the first entry of the submenu. For instance, clicking “Posts” is the same as clicking “All Posts”.

The Toolbar has some convenient quick links. Your site name, on the left, will take you between the front and back end of the site. Your user name, on the right, drops down a menu that includes “Log Out”. The following is a screenshot of the left half of the Toolbar from a page on the front end of the site.

Admin pages consist of a collection of content boxes called panels. Panels with titles can be collapsed and expanded by clicking on the title bar; there’s a little arrow on the right that changes direction accordingly. Panels as a whole can be shown or hidden from the Screen Options box, which you’ll find at the top right of the page, just under the Toolbar. Not every page has Screen Options, but you’ll always find a Help box in the top right, which will give you page-specific extra information.

Videos from iThemes: first about the WordPress Dashboard, second about the Toolbar.

The post Intro to WP 1: Logging In and Getting Around appeared first on rweber.net.

There are any number of options for email subscriptions to the entirety of your main WordPress blog, including Jetpack. If you want to allow subscriptions to individual blog categories or to custom post types (CPTs), however, the options drop off radically. Here are three possibilities I’ve tracked down.

1. Arigato Pro + Intelligence Module

This is a newsletter plugin that allows email subscriptions via daily or weekly digests (this part requires the Intelligence Module add-on; the whole bundle costs $87 for a lifetime license and a year of support and updates).

Flexibility: You can limit the posts in the digests to specific categories, but it does not do custom post types. [The developers are very responsive, though, and might be amenable to adding CPTs as an option.]

Advantages: There are no limitations on number of subscribers or emails sent (except those imposed by your web host). Your list is local and doesn’t require another online account. You have control over your mailing lists and the design of the emails, which come from your site. If you want to sell subscriptions to certain kind of lists there is a free extension that connects to WooCommerce. If you have multiple lists and lots of people, it is cheaper than most external services (including even the lowest cost plan on MailChimp, below), even if you re-up every year for more support and updates. Your signup form can include checkboxes to allow people to subscribe to multiple categories/lists at once.

Disadvantages: Blog subscriptions are in digest form and sent once a day at most. Setup is fairly complicated. No custom post types at this time.

2. MailChimp

MailChimp is one of the many newsletter services out there, and not the only one to offer RSS to Email (Mad Mimi and AWeber do as well; Constant Contact does not seem to). However, it is the only major player with a free tier: up to 12,000 emails per month spread over up to 2,000 subscribers.

Flexibility: Since WordPress automatically produces individual RSS feeds for not only the main blog but also every taxonomy and post type, this can be used for any type of email subscription.

Advantages: You have control over your mailing lists and the design of the emails, which come from the email address of your choice. If you want to combine with another form of newsletter you can do so in the same account. Your signup form can include checkboxes to allow people to subscribe to multiple categories/CPTs at once (you’d want to have one “list” in MailChimp-speak and “groups” for categories – a “group title” like “Categories to Subscribe To” with “groups” underneath for each category; the nomenclature is a little confusing). A Google search implies MailChimp is the most popular option for RSS to Email and there are tutorials accordingly.

Disadvantages: Your subscriber list is not local and you have an additional online account to deal with. Setup is fairly complicated. If you go over the free tier the price goes up pretty fast.

3. Feedburner

Feedburner is a Google service that’s been around for a long time, and you will read that it ought to be kicking the bucket any day now. Those rumors have been around since 2012, however, and it is still here and even fully integrated with Blogspot.

Flexibility: As with MailChimp, anything with an RSS feed can be used.

Advantages: There are a surprising number of services, styling options, and statistics associated with this free service, and you can look at your subscriber list and download them as CSV. You don’t need to add any plugins to your site, just a form Google provides the code for.

Disadvantages: Email comes from a Google address (though with the blog’s name) and at a delay of nearly 24 hours (regardless of time of posting). Your subscriber list is not local. Multiple category/CPT subscriptions require multiple signups. Google is known for yanking services with little notice.

Where’s the Feed?

A few notes on setting up Feedburner and MailChimp: WordPress feed addresses follow a pattern. In each address below, anything starting with “your” is to be substituted with your specific information; the rest should be left as-is.
Categories:
http://www.your-site.com/category/your-category-slug/feed
Custom post types:
http://www.your-site.com/feed/?post_type=your-cpt-slug
You can even do “per-category” custom post type subscriptions (quoted under the assumption that the “category” would be a custom taxonomy) with
http://www.your-site.com/feed/?post_type=your-cpt-slug&your-custom-taxonomy-slug=your-taxonomy-term-slug
Actually if your taxonomies are specific to post types you could go with just
http://www.your-site.com/feed/?your-custom-taxonomy-slug=your-taxonomy-term-slug
Make sure under Settings → Reading you have “Full Text” or “Summary” selected as desired for articles in the feed.

You can read more about feeds in the WordPress Codex.

The post Flexible Email Subscriptions in WordPress 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.