Theme Development With Sage (Third Edition) [3 ed.]

Citation preview

Summary Introduction What is Sage? Why Sage? Starting a project Installing the Sage starter theme Theme setup Planning out the theme Customizing templates Blade templates Template files Building template partials Responsive images & post thumbnails Displaying the sidebar Customizing the front-end CSS setup and organization Default CSS and JS Bootstrap Browsersync JavaScript and DOM-based routing 3rd party packages Asset paths in CSS and templates Theme functionality Adding additional files

1 2 3 4 4.1 4.2 4.3 5 5.1 5.2 5.3 5.4 5.5 6 6.1 6.2 6.3 6.4 6.5 6.6 6.7 7 7.1

Namespaces Take advantage of newer PHP features Theme customizations WordPress Customizer Advanced Custom Fields Theme deployment Theme troubleshooting Theme updates and maintenance Resources Wrapping up CHANGELOG

7.2 7.3 8 8.1 8.2 9 10 11 12 13 14

Introduction

Theme Development with Sage Thank you for purchasing a copy of the book. New versions to this book are released as the Sage starter theme goes through major changes. You'll receive lifetime updates and will be notified via email when a new version is released. Please write to [email protected] with any corrections or feedback!

Licensing and cost Unlike the Sage starter theme, this book is not open source. I reserve all commercial and moral rights to the book and supplied code (where not under an existing license). Please buy a copy if you’ve received this book without paying.

About the author Howdy! I'm Ben Word, a web developer & interaction designer who has been creating websites for over 15 years. My goal with our open source projects at Roots is to help developers create awesome websites, and I've always been passionate about web standards and tools that make our jobs more efficient. My first encounter with WordPress was in 2004, and since 2006 I've been using it at my day jobs. I've had the opportunity to work on a WordPress multisite network that receives millions of views per day for the blogs and newspapers part of the Hearst conglomerate, along with running the marketing site for ShoreTel Sky. Originally from Texas, I now live in the west side of Colorado Springs with my two dogs. I love traveling, overlanding, and climbing. I'm new to yoga and slacklining, and hopefully soon mountain biking.

Thank you I'd like to acknowledge and thank: Everyone who has contributed to Roots by helping others on the forum, spreading the word, committing code, opening issues, purchasing our educational materials and plugins, and more. Thank you so much for your support. Craig, who helped evolve Sage into the next version by reworking almost the entire theme. The build process, the file restructuring, the conversion to ES6, and more, are thanks to the work that Craig has done. Scott Walkinshaw, my good friend, for all of the time he's put into Roots and our projects, despite how he never uses WordPress outside of Roots and is naturally a Ruby programmer. Phil Nelson, for the countless contributions to Trellis, and his tremendous level of detail with support on Discourse, GitHub, and all of his work in general. He inspires me with his patience and kindness. Kalen Johnson, for providing countless hours of support and contributions to Roots projects, especially the Blade implementation in Sage 9. Still looking forward to trying one of his beers.

4

Introduction

Tools used to make the book This book was created with GitBook. The source files are in Markdown which allows for painless code example blocks, as well as letting me write with a syntax that I'm familiar with. GitBook with a custom theme Pages edited as Markdown in Atom Git is used for version control Sass is used for styling

There are some GitBook bugs that affect the various formats of this book that I'm working on trying to improve.

Who this book is for This book is not an introduction to WordPress, or themes, and expects that you’ve done theme development before. Things you should understand: Keeping projects under version control with Git Command line basics HTML5, CSS preprocessors, basic JavaScript (with ES6), basic modern PHP WordPress template hierarchy Loops and WP_Query Conditional tags Template parts (get_template_part) Enqueuing scripts and stylesheets

5

What is Sage?

What is Sage? Sage is a WordPress starter theme. Sage was first called Roots and initially released in early 2011. I created Roots when I was working at an agency in Northern Colorado in 2010 and had to pump out several new themes every day. I had experience with WordPress themes before that job, but I had never been in a position where I was regularly creating new themes. Previously I had been a Thesis user, but discovered that I wasn't a fan of using child themes and hooks to make changes. I quickly realized that having a bare bones theme that's ready to start customizing was the way to go. The Roots theme started out by combining Starkers with HTML5 Boilerplate and Blueprint CSS. Starkers was one of the first 'naked' WordPress themes and was created by Elliot Jay Stocks almost 10 years ago. HTML5 Boilerplate, the most popular front-end template, was used in Roots back when it existed as Paul Irish's frontend-pro-template. Blueprint CSS and 960.gs were the most popular front-end frameworks at the time, and Blueprint was my preferred choice since it had a better starting point to work from. On March 28th, 2011, Roots went public. Smashing Magazine tweeting about Roots, then mentioning it in their newsletter and a blog post was directly responsible for a lot of the initial success.

Over the lifetime of the project the theme has undergone lots of changes, improvements, and re-considerations of bestpractices as the team has learned new things while the web moves forward. Going back and looking at the first several major versions of the theme makes me feel embarrassed of a lot of my early decisions, including moving the uploads folder to /media/ and rewriting all theme assets to the web root. Roots was far from perfect, and to this day we still strive to improve it whenever possible.

6

What is Sage?

Some of the bigger milestones include: Roots 3.0.0 (March 2011): First public release Roots 5.0.0 (February 2012): Removed all frameworks except Bootstrap Roots 6.0.0 (September 2012): Added theme wrapper Roots 6.5.0 (August 2013): Introduced a Grunt based front-end workflow Roots 7.0.0 (July 2014): Updated Grunt workflow, moved plugin functionality into Soil Sage 8.0.0 (February 2015): Renamed theme to Sage, switched from Grunt to gulp Sage 9.0.0 (February 2018): Replaced gulp with Webpack, new templates folder organization, Blade as a templating engine, options to use certain CSS frameworks or none Sage is not a theme framework, it is a starter theme. You should rarely need to update it, and typically you shouldn’t create child themes from it. Being a starter theme, Sage is meant to be used as a starting point on a new project. Sage can be implemented on any sort of WordPress installation, independent of our other primary projects (Trellis & Bedrock). Sage combines: Dependency management with Composer and npm Asset management and optimization with Webpack Template inheritance with Laravel's Blade Modern PHP & PSR-2 coding standards An improved project structure The first episode of Roots Radio, Ep 00 — Overview, gives an overview of some of the team members involvement in Roots and an overview of the different Roots projects. In Roots Radio Ep 05 — Sage, Chris Carr, myself, Nick Fox, and Kalen Johnson dig into a bit of the Sage philosophy, what we are doing right now with Sage, and our own theming processes.

7

What is Sage?

What Sage has become Sage has evolved into a full breadth starting point for website development and spawned additional projects to support and enhance it. It has created an entire community of conversation on what web development should be and how it has sometimes lost its way. It has grown into a team of open source developers who are dedicated to making the web better. Roots embraces the open source ethos and believes in peer production. Through our team and community, we have dedicated thousands of person-hours to building and continuously improving our projects since 2011. Over 300 contributors have come together to help make better tools for WordPress under the Roots name.

Who's working on Sage We're still working on and using Sage because we're invested in improving WordPress and the web in general. Many people use WordPress, and we believe there is a way to use it more efficiently. A quote from The Changelog podcast on Modern WordPress with myself and Scott Walkinshaw, which was originally said by Craig:

I think we’re all on the same page when it comes to WordPress. WordPress is a lemon, but the industry likes WordPress, so let’s make lemonade.

Craig (@QWp6t) and myself are the project leads for Sage. Craig joined the Roots team before version 7 in mid 2014. His knowledge in PHP and JavaScript has been an enormous help in making Sage the theme that it is today.

8

Why Sage?

Why Sage? There's been countless hours of research, development, and support put into Sage by the Roots team and community since 2011. We strive to always use and improve best-practices in the theme, and we're consistent at keeping the theme up to date. Rather than coding an entire theme from scratch, Sage helps you get started, then gets out of the way. Sage is “delete-key friendly” and it's easy to remove any features that you don't need. We do typically recommend that you don't try Sage as your first WordPress theme and instead give it a shot once you've got the basics covered. Underscores (_s) by Automattic is another popular starter theme, but it lacks any sort of front-end workflow and doesn't require a sane minimum-version requirement for PHP. If Underscores is a “1,000 hour head start”, Sage is a 10,000 hour head start. What you'll find in Sage that you won't find in most other WordPress themes: A modern build process Modern PHP and requirements, along with PSR-2 coding standards (the most widely used and accepted coding standards used in the PHP community) rather than WordPress coding standards Better template file organization — no template files exist in the theme root DRY templates with template inheritance

9

Why Sage?

Professionally maintained At the time of writing, the Sage starter theme has over 9,000 stars and is the 15th most popular PHP project on GitHub. We see over 4,000 new Sage projects being created every month based on GitHub and Packagist statistics. Issues are squashed extremely fast, whether on GitHub or on Roots Discourse. The project maintainers communicate daily and we're generally very accepting of feedback and improvements.

Widely used and trusted There are over 50,000 live websites that are based on Sage. Some popular sites and brands using Sage include: Amnesty International USA Bacardi D Magazine Discovery Kids GE Goodwill Hewlett Foundation HotPads Hulu Japan.com JetBlue Jobvite LendingTree Mad Libs Michael and Susan Dell Foundation Morton Salt Pied Piper (HBO) Progresso Quest Diagnostics Redpoint Ventures Sirius Top Hat University of Tennessee UPS US Government (Data.gov & US Embassy) WebMD Whitepages Women Deliver Zillow

Community support Roots and Sage have a big support community behind it. Roots Discourse is a valuable resource with thousands of users and topics. The forum is very active, and topics are usually responded to within 15 hours.

10

Why Sage?

A modern build process The Sage theme has gone through lots of workflow changes over the years. Like almost every other WordPress theme, Sage initially didn't support any sort of build process. The theme has previously used Grunt and then Gulp, but currently uses Webpack. Webpack is responsible for: Compiling assets Sass to CSS with cssnano ES6 to JavaScript that can be run in today's browsers with buble Optimizing images with optipng, gifsicle, pngquant, and svgo By using the Sage build process you will see orders of magnitude of difference in page load time compared to nonoptimized assets:

Sage does a good job at optimizing content efficiency, part of Google's web fundamentals and best practices for modern web development. These performance optimizations include: Eliminating unnecessary downloads Optimizing encoding and transfer size of text-based assets Image optimization

Blade templating engine WordPress lacks a real templating engine (follow WordPress core ticket #33472 by Kalen Johnson from Roots), and Sage has adopted Blade as a templating engine with version 9.

Blade syntax is more elegant, concise, readable, more powerful, and easier to write than just PHP tags. You could even bind PHP data to Vue.js properties using Blade. The most popular PHP framework Laravel has been using blade for a while now, and has been nothing but great. You shouldn’t be against it just because it’s one more thing you have to learn. Functionality-wise, Blade is just amazing IMO. — webber on Roots Discourse

Template inheritance 11

Why Sage?

Outside of WordPress land, most templating engines like Twig and Jade implement the concept of template inheritance. With template inheritance, a base layout template defines blocks containing the common website elements, which are inherited by child templates. It is more flexible than alternative techniques, such as including common page elements (like header and footer files) because each block can be overridden within a child. Template inheritance is good for WordPress specifically because it keeps things DRY. By using the Blade templating engine, we've removed repeated markup from individual templates and put it into a single file. Take a look at page.php in Underscores: