Handbook Examples: Language

Another round of examples, shall we? This one will focus on language examples.

I’ll start it off:

Required: load_theme_textdomain()

add_action( 'after_setup_theme', 'my_theme_setup' );
function my_theme_setup(){
    load_theme_textdomain( 'slug-text-domain', get_template_directory() . '/languages' );
}
// if child theme
add_action( 'after_setup_theme', 'my_child_domain', 11 );
function my_child_domain(){
    load_child_theme_textdomain( 'child-text-domain', get_stylesheet_directory() . '/languages'
}

Handbook Examples: Documentation

Any good theme has some documentation. A video tutorial on how to setup some basic options, a specific page on how to use hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. inside of the theme. How to make child themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. https://developer.wordpress.org/themes/advanced-topics/child-themes/. or even a simple how to install the theme. These are examples of documentation. Let’s keep this going by leaving a comment below on some documentation examples.

I’ll start it off:

Action hook

/*
 * Fires before the opening #page tag
 */
function theme_before_page(){
    do_action( 'theme_before_page' );
}

FilterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. hook

/*
 * Returns a specified width for the slider
 * 
 * Usage:
 * add_filter( 'theme_slider_width', 'my_callback' );
 * function my_callback(){
 *     return 755;
 * }
 */
$width = intval( apply_filters( 'theme_slider_width', 600 ) );

Handbook Examples: Functionality and Features

Last week we began with the code section of the handbook. This week let’s get some momentum and tackle: Core functionality and features.

Functionality and Features examples:

Example:
There is no need to use
add_theme_support( 'menus' );
because register_nav_menu() does it behind the scenes.

Example:
Use coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. defined functions when possible
So rather than using your own functions:

function my_custom_cats(){
	$categories = get_the_category();
	$catOut = '';
	$separator = ', ';
	$catOutput = '';
	if($categories){
		foreach($categories as $category) {
			$catOutput .= '<a href="'.get_category_link( $category->term_id ).'" title="' . esc_attr( sprintf( __( "View all posts in %s", 'text-domain' ), $category->name ) ) . '">'.$category->cat_name.'</a>'.$separator;
		}
		$catOut = 'Categories: '.trim($catOutput, $separator);
	}
	return $catOut;
}

Use a core function like the_category()

Handbook Examples: Code Section

Beginning today, we will be discussing examples for the handbook requirements. Ultimately, these examples will end up on the Explanations and Examples page in the handbook.

Each week, we’ll focus on various sections. This week’s section is the Code section. What we need from everyone is to provide examples in the below comments. The admins will round up the examples and add them to the handbook.

Code section examples

I’ll get us started with a couple of examples just to get the ball rolling.

Required: Have a valid DOCTYPE declaration and include language_attributes.

<!DOCTYPE html>
<html <?php language_attributes(); ?>>

Required: No shortcodes are allowed.

The use of the add_shortcode() function is not allowed in themes as shown below:

add_shortcode( 'shortcode_name', 'shortcode_callback_func' );

Handbook refresh.

The first version of the refresh is now up and live under Handbook. The main changes in this first version are:

  • Structure
  • Menu and navigation
  • Requirements and Recommendations

We also now have a new main menu for the team:

  • About
  • Handbook
  • Review
  • TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/.
  • Become a Reviewer

First a few notes about what has happened.

  • No old content is lost. It’s all there just behind. No pages have been deleted.
  • Most old content has been merged into the new structure.
  • A lot of phrasing and words have changed in an attempt to simplify and solidify things.
  • This is very much version one. There will be updates all throughout the next few weeks.
  • Where existing content was brought over links have been updated to developer.wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ from codex as is the plan to as a project move onto that. We need to ‘catch em all’ and make sure we update links.
  • The idea is this becomes a living document. In particular we should review this frequently.

We now have the following main sections:

I’m going to go through the main new sections a little to explain them.

The Team

This section now has the following sub sections:

  • Communication
  • Members

This is where the ‘About’ link goes to.

Get Involved

This is now the section where you can learn about being a reviewer and contribution days:

  • Become a Reviewer
  • Contribution Days: Sub pages on getting started and running a session.
  • Being a Good Theme Citizen. This is a page we talked about at SF and since. It’s going to be something we can build on and help encourage the behaviour we want in theme authors.
  • Mentoring

Review

This is the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. of the handbook now. Explicitly named. The big difference is the simple splitting removing all required into one single document.

  • Review: Lists what a review is, how to do it and what to expect.
  • Required: This now lists every requirement as it stands today. Nothing has been changed that hasn’t been discussed and agreed as a team. Also under this is the theme check pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party to list all it checks (this is a work in progress documentation).
  • Recommended : This will be a section that builds up over time to include all the ‘nice to haves’ we have all talked about. No theme should fail these.
  • Reviewer workflow. For now this has a suggested ticket format and also explanation of queues. This will grow.
  • Accessibility . This document is from the AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) team and needs reformatting along with them.

Resources

This is a single page for now but may grow into sub section. We can fill this up with useful make.blog posts – so they don’t get lost. Also useful articles we come across. We should consider this as a place to really build a good library of useful resources. If you’ve got something you think should be listed there lets hear about it!

Next phase

The next phase is going to focus on the extra pages and fleshing out recommended. Also going over the handbook style guide is important – I’ll be doing that too.

Sections that will get attention are:

  • Handbook landing page itself
  • The Team
  • Get Involved
  • Recommended
  • We also need to work with the Accessibility team and get their new page inline with the changes we’ve done.

For at least a few weeks I’ll be doing weekly maintenance checks on pages to ensure we are on top of things.

Requirements not set in stone yet

There are a few requirements we’re going to be debating over the next few weeks. That’s ok, this exercise was about refactoring the handbook not just requirements. For now, it reflects what stands today.

Any issues?

If you see any issues like spelling mistakes and you can edit those please do – that’s helpful. But, if there is something you would like to see done differently we need to have discussion about this rather than just change. A group of us have worked on this to get it this far. I’m excited about where we can all start to take this now as a larger group. We can also collect issues here and in SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.. I’m around most of the time for questions.