Code Snippets

Genesis Responsive Menus

by Leave a Comment

As with any updated release of the Genesis Framework you can always expect changes. One change brought to version 3.0.0 is genesis_register_responsive_menus(). According to the change log this function brings added AMP support with assistance from the WordPress AMP plugin.

Added AMP support if the WordPress AMP plugin is installed and active (https://wordpress.org/plugins/amp/). This includes an AMP-compatible, responsive menu that theme developers can add via genesis_register_responsive_menus(), in place of having to enqueue their own responsive menu scripts.

Genesis Developer Docs

As per the above, the WordPress AMP plugin should be installed and activated for your theme to gain full benefit of the new genesis_register_responsive_menus() function.

Agenda

In this post we will discuss how to prepare the functions.php file and use the new genesis_register_responsive_menus() function which is able to accept an array as a parameter. This array is stored in a configuration file which is read by a separate function named genesis_get_config().

Recommended Reading

The below resources help to familiarize yourself with how all connecting parts of this process work together.

  • Genesis AMP Support
    • Provides information necessary to understand the new genesis_register_responsive_menus() function added to Genesis Framework 3.0.0.
  • ReponsiveMenus.js
    • With the release of Genesis 3.0.0, this is no longer the recommended solution, yet this source contains valuable configuration setting details.

Required Files

To create our new responsive menu we need a minimum of 2 files.

  • functions.php
  • responsive-menus.php

functions.php

The heart of any theme is the functions.php file. In the code snippet below, the two main points of interest are the lines that read wp_enqueue_style( 'dashicons' ) and genesis_register_responsive_menus( genesis_get_config( 'responsive-menus' ) ); respectively.

<?php
/**
* Edwin Velez
*
* Starting point for all WordPress themes.
*
* @package EdwinVelez
* @author Edwin Velez (https://edwinvelez.net)
* @license GPL-2.0-or-later
* @link https://edwinvelez.net
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
// Starts the Genesis Framework engine.
require_once get_template_directory() . '/lib/init.php';
add_action( 'wp_enqueue_scripts', 'ev_enqueue_scripts' );
function ev_enqueue_scripts() {
wp_enqueue_style( 'dashicons' );
}
// Initialize and configure Genesis responsive menus.
genesis_register_responsive_menus( genesis_get_config( 'responsive-menus' ) );
view raw functions.php hosted with ❤ by GitHub

Normally seen on smaller than desktop displays, the hamburger icon is a popular responsive menu feature. To get the hamburger icon on your theme, simply enqueue dashicons which is built in to WordPress. How this works is described later when discussing the responsive-menus.php file.

genesis_get_config()was released in Genesis Framework version 2.8.0. This function reads a configuration file stored in a directory named config. This file returns an array. The array contains configuration information which, according to this example, is stored in a file named responsive-menus.php.

Of course you can pass a array as a parameter directly to genesis_register_responsive_menus() but doing so ignores certain benefits. To learn more about these benefits, be sure to read Load child theme settings from your theme’s config folder.

responsive-menus.php

As explained above,responsive-menus.php returns an array read by genesis_get_config(). The Genesis AMP Support documentation states we are only required to write values that differ from default values. For example, in the code snippet below, .nav-primary is set to a value corresponding to a Genesis theme’s primary menu’s CSS. By passing in .nav-primary as a value, we overwrite the default value of an empty array. If this does not make sense please read the Genesis AMP Support documentation.

<?php
/**
* Genesis Responsive Menus
*
* Responsive menu settings used by Genesis Framework child theme.
*
* @package EdwinVelez
* @author Edwin Velez (https://edwinvelez.net)
* @license GPL-2.0-or-later
* @link https://edwinvelez.net
*/
/*
* See: https://studiopress.github.io/genesis/developer-features/amp/
* See: https://github.com/studiopress/responsive-menus
*/
return array(
'script' => array(
'menuClasses' => array(
'others' => array( '.nav-primary' ),
),
),
'extras' => array(
'media_query_width' => '960px',
),
);
view raw responsive-menus.php hosted with ❤ by GitHub

Note: The code snippet above is a copy and paste taken from the Genesis Sample child theme as stated in the Genesis AMP Support documentation.

Don’t forget! If you are not sure what these parameters mean, you can read more about them on the StudioPress GitHub project page.

Summary

You now have a fully functioning responsive menu. To test it out, simply resize your web browser and notice how the hamburger menu appears and disappears depending on the window size.

In this post we learned how to configure a responsive menu by using the new genesis_register_responsive_menus() function made available beginning with Genesis Framework 3.0.0. We also discussed how genesis_get_config() retrieves an array from a configuration file for use when creating responsive menus.

Build Table of Contents in Sidebar of a Genesis Theme

by Leave a Comment

It is a good practice to use HTML Headings when writing blog posts. Doing so builds structure around your content and helps to make reading a bit easier for your visitor.

To further help your reader, wouldn’t it be nice to have a table of contents section that matches your headings and is displayed alongside your post? Wouldn’t it be even better if the table of contents were dynamically populated as you update existing posts and create new ones?

Before you read further, it is important to know the code below is specific to the Genesis Framework. If your theme is not a child theme of the Genesis Framework you will need to modify this code to fit your specific need.

Post Template Files

WordPress takes advantage of Post Template Files to help change the look and feel of a particular page on your website. There are several template files to choose from. For this example we will concentrate on the single.php file.

The Single.php File

The code below belongs to the single.php file where a JavaScript file is enqueued. This is the file that does much of the heavy lifting for our table of contents to display and work. We will discuss more on this JavaScript File in the next section. In the edwinvelez_do_sidebar() function there is a skeleton, or the beginnings of a <section></section> which also contains an empty <ul></ul>. This is the location and future home of the soon to be populated table of contents.

function edwinvelez_enqueue_scripts() {
wp_enqueue_script( 'toc', get_stylesheet_directory_uri() . '/genesis-build-sidebar-toc.js', array(), '1.0', true );
}
add_action( 'wp_enqueue_scripts', 'edwinvelez_enqueue_scripts' );
/**
* Displays a customized sidebar.
*
* By default only a skeleton of what the table of contents will be is given. The skeleton is populated via JavaScript.
*
* @since 1.2
* @version 1.0
*/
function edwinvelez_do_sidebar() {
?>
<h3 class="sidebar-primary-toc-header">Table of Contents</h3>
<section id="sidebar-primary-toc" class="sidebar-primary-toc">
<ul id="sidebar-primary-toc-headings">
</ul>
</section>
<?php
}
remove_action( 'genesis_sidebar', 'genesis_do_sidebar' );
add_action( 'genesis_sidebar', 'edwinvelez_do_sidebar' );
genesis();
view raw single.php hosted with ❤ by GitHub

An example of this table of contents in action is seen on this very same page you are now reading.

The JavaScript File

The required JavaScript file is enqueued and set to do its job. When loaded, this file scans the page for existing HTML <h1> to <h6> tags and automatically populates the skeleton created in the single.php file. Notice how the $in_footer parameter of the wp_enqueue_script() function is set to true. This is important because we need the page to completely load first before the JavaScript is fired off to run.

'use strict';
// Built-in element ID from the Genesis Framework that contains the content.
let contentContainer = document.getElementById( 'genesis-content' );
// The HTML <section></section> that will contain the table of contents.
let sectionPrimarySidebarToc = document.getElementById( 'sidebar-primary-toc' );
// Available HTML heading tags that could be used in a post.
let containerSelectors = contentContainer.querySelectorAll( 'h1, h2, h3, h4, h5, h6' );
// Loop over all matching selectors found.
for ( let i = 0; i < containerSelectors.length; i++ ) {
buildTableOfContents( containerSelectors[ i ], true );
}
/**
* Builds a Table of Contents based upon an elementList of HTML <h1> to <h6> tags found on a page.
*
* @param headingTitle Existing <h1> to <h6> HTML tags of a page.
* @param addAnchorTag True if <a></a> HTML tags should be applied to the title. Used by internal page linking.
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll
*
* @version 1.0
*/
function buildTableOfContents ( headingTitle, addAnchorTag = false ) {
let sanitizedTitle = hyphenateText( headingTitle.textContent );
let listItem = document.createElement( 'li' );
// The <ul></ul> tag that will eventually contain the Table of Contents.
let containerHeadings = document.getElementById( 'sidebar-primary-toc-headings' );
listItem.setAttribute( 'class', 'sidebar-primary-toc-heading-title' );
// Should the HTML heading be hyperlinked? Needed for internal page linking.
if ( addAnchorTag ) {
let a = document.createElement( 'a' );
// First assign 'id' attribute to the HTML heading.
headingTitle.setAttribute( 'id', sanitizedTitle );
// Build internal page link tag settings.
a.setAttribute( 'href', '#' + sanitizedTitle );
a.textContent = headingTitle.textContent;
// Add hyperlink capabilities to list item.
listItem.appendChild( a );
} else {
// Add text to list out without hyperlink capabilities.
listItem.textContent = headingTitle.textContent;
}
// Add list item to list.
containerHeadings.appendChild( listItem );
}
/**
* Replaces whitespace of the passed in text value with hyphens (-).
*
* @param dirtyText The text to be sanitized.
* @returns {*} Sanitized Text
*
* @version 1.0
*/
function hyphenateText ( dirtyText ) {
return dirtyText.replace( /\s/g, '-' );
}
view raw genesis-build-sidebar-toc.js hosted with ❤ by GitHub

Important Notes

There are at least two important things to keep in mind before you decide to use this code on your Genesis Framework child theme.

Below are two simple changes you may want to make when keeping the above notes in mind.

Restore Your Configured Widgets

When the remove_action() function is called it effectively removes all widgets previously added to the sidebar in the WordPress Dashboard for your theme. What though if you want to keep these widgets? Simply comment out this one line and your widgets are restored.

Change the Position of the Table of Contents

But wait! When the widgets are restored the table of contents is at the very bottom of the widget list. How do you bring it to the top? That is easy!

The add_action() function uses the default $priority value of 10. Change the priority value to a lower number, for example 5, and the position of the table of contents is brought to the top of the widget list.

Creating Page Jumps

The JavaScript Code searches your headings for spaces and replaces them with hyphens to create the table of contents. If you would like to Create a Page Jump when composing your posts, be sure to pay attention to capitalization and complete the same task manually.

To Do List

I would like subheadings to be clearly identified if one is found under a another in order to apply a more visual structure. For example, when a <h2> tag is found under a <h1> there should be an indent, hyphen or leader dots showing it is a subordinate of the previous heading.

Open External Links in New Tab

by Leave a Comment

In part, we write blog posts because we want our readers to benefit from our words. In our writings, it is not uncommon to point to an external source via hyperlink for any number of reasons. When sharing that external link it is very important to ask yourself, what do I want this hyperlink to do? In other words, do you want the user taken away from your site when clicking on the link? Or would you rather have the external hyperlink open in a new browser window or tab?

The WordPress Way

WordPress has built in to give you the option of opening a link in a new tab when composing your blog posts. Simply choose it when using the WordPress Visual Editor. But depending on how many external links you have to share this can become tedious. Could there be a more convenient way?

Let JavaScript Work For You

The WordPress Way works great. But rather than remembering to toggle the option, let JavaScript do it for you in kind of a “set it and forget it” fashion. All it will take is a couple simple and easy steps you are probably already familiar with.

Prepare Your functions.php File

First you need to enqueue the JavaScript file that will do all of the heavy lifting. Generally, this is done within your functions.php file.

<?php
/**
* Open External Links in New Tab
*
* @author Edwin Velez (https://edwinvelez.net)
* @link https://edwinvelez.net/open-external-links-in-new-tab/
*/
function ev_load_my_scripts() {
wp_enqueue_script( 'external_links', get_stylesheet_directory_uri() . '/external_links.js', array( 'jquery' ), '1.0', true );
}
add_action( 'wp_enqueue_scripts', 'ev_load_my_scripts' );
view raw functions.php hosted with ❤ by GitHub

Add Code Snippet to Enqueued File

Now, in the enqueued file defined in the previous step, copy and paste either the JavaScript or jQuery code snippets below. You do not and should not use both code snippets at the same time. You only need to use but one.

Why are there two examples? In short, because some users may have a preference. If you are not sure which to use, it is recommended to select the JavaScipt code snippet. Both options do exactly the same thing but use different methods.

Using JavaScript Code Snippet

The code snippet below uses JavaScript so that any external links on your site are automatically opened in a new tab without you having to toggle the option in the WordPress Visual Editor.

view raw external_links.js hosted with ❤ by GitHub

Using jQuery Code Snippet

Just like the JavaScript Code Snippet above, the same goal is achieved. This time jQuery, which is a JavaScript library, is used instead.

view raw external_links.js hosted with ❤ by GitHub

Summary

Now, when your reader clicks on an external link within your blog post, rather than them being taken away to another site, a new browser tab is opened. Have fun and enjoy!

Set Reading Settings on Theme Activation

by Leave a Comment

Previously I shared a post on how to Set Reading Settings Programmatically. The code below takes it a step further by first creating the required pages, if they do not exist, needed for their respective settings. Thanks to the after_setup_theme() function, the process will run on activation of the theme.

<?php
/**
* Set Reading Settings on Theme Activation
*
* @author Edwin Velez (https://edwinvelez.net)
* @link https://edwinvelez.net/set-reading-settings-on-theme-activation/
*/
function ev_set_reading_settings() {
$author_id = 1;
$page_title_home = 'Home';
$page_title_blog = 'Blog';
// Does the Home page exist?
if ( null == get_page_by_title( $page_title_home, 'page' ) ) {
// Home page does not exist so it must be created.
wp_insert_post(
array(
'post_author' => $author_id,
'post_title' => $page_title_home,
'post_status' => 'publish',
'post_type' => 'page',
)
);
}
// Does the Blog page exist?
if ( null == get_page_by_title( $page_title_blog, 'page' ) ) {
// Blog page does not exist so it must be created.
wp_insert_post(
array(
'post_author' => $author_id,
'post_title' => $page_title_blog,
'post_status' => 'publish',
'post_type' => 'page',
)
);
}
// Set static front page.
update_option( 'page_on_front', get_page_by_title( $page_title_home )->ID );
update_option( 'show_on_front', 'page' );
// Set blog page.
update_option( 'page_for_posts', get_page_by_title( $page_title_blog )->ID );
}
add_action( 'after_switch_theme', 'ev_set_reading_settings' );
view raw functions.php hosted with ❤ by GitHub

Set Reading Settings Programmatically

by Leave a Comment

Home Page and Post Page settings can be changed manually in the Reading Settings page of the WP Admin Dashboard. With the code snippet below, you can set reading settings programmatically.

The two variables, $home_page and $blog_page, should match the title of a Page you create in the WP Dashboard.

<?php
/**
* Set Reading Settings Programmatically
*
* @author Edwin Velez (https://edwinvelez.net)
* @link https://edwinvelez.net/set-reading-settings-programmatically/
*/
// Set static front page.
$home_page = get_page_by_title('Home');
update_option('page_on_front', $home_page->ID);
update_option('show_on_front', 'page');
// Set blog page.
$blog_page = get_page_by_title('Blog');
update_option('page_for_posts', $blog_page->ID);
view raw functions.php hosted with ❤ by GitHub

Compare Two Domain Name Values

by Leave a Comment

The code snippet below compares two domain names. One domain name could point to development environment. The other domain name could be a live site on the Internet where visitors go to see the results of your hard work.

All you need to do is set the variable $live_site_url equal to the value of where your live site is found on the Internet. For example, the variable is set to edwinvelez.net which is points the website you are looking at now which is my live site. My development site lives elsewhere which is not on the Internet for you to find.

With the ability to compare locations based upon the domain name values, I can choose to selectively run code without making changes manually.

<?php
/**
* Compare Two Domain Name Values
*
* @author Edwin Velez (https://edwinvelez.net)
* @link https://edwinvelez.net/compare-two-domain-name-values/
*/
// The domain name or host you want to compare. Can also be a host i.e. http://localhost
$live_site_url = 'https://edwinvelez.net';
$head_pattern = '/(https?:\/\/(w{3}\.)?)?(^w{3}\.)?';
$tail_pattern = '(\:[0-9]+).*|\b\/.*|\b\?.*';
$head_vs_tail_boolean = '|';
$regex_flags = '/m';
$regex_pattern = $head_pattern . $head_vs_tail_boolean . $tail_pattern . $regex_flags;
// Strip everything before and after actual domain name and hostname.
$live_site_url = preg_replace( $regex_pattern, '', strtolower( $live_site_url ) );
$site_url = preg_replace( $regex_pattern, '', strtolower( get_site_url() ) );
$is_live_site = strcmp( $site_url, $live_site_url );
// Is the web browser pointing to the live site?
if ( $is_live_site === 0 ) {
// Insert code here to run if this is your live site.
} else {
// Insert code here to run if this is not your live site.
}
view raw functions.php hosted with ❤ by GitHub