What’s new in Waboot 3

We have tested the 3.0.x branch for a while and now we have merged it to the main branch.
This version includes to major changes:

– Bootstrap has been removed from theme dependecies: now Waboot has a custom built-in grid framework based on flex and BEM. Bootstrap was a very old dependecies of early versions of Waboot, but nowadays it was used solely for the grid, so we decided to switch to a very simple custom one.

– Components have been removed from the main repository. Waboot now features a full-fledged components repository very similiar to the native plugin repository.

The latter is a decisive milestone in Waboot development as many features will be build around this repository, so stay tuned!

Read the full changelog for more informations.

What’s new in WBF 1.1.0 and Waboot 2.3.0

WBF v1.1.0 and Waboot v2.3.0 are a big step towards the official launch of both platforms and features some interesting changes.

For the 1.1.0 milestone, WBF core architecture has been completely revamped. We switched from a singleton pattern to a dependency injection-like structure. This is the first step to make the framework testable in a more efficient way.

The PluginCore class now acts as a service container. We moved the management of all the additional services WBF provides (notice manager, mobile detect, styles compiler and custom updater) to a ServiceManager class that is injected into the core class. This behavior will be further enhanced in future releases.

The Resource class is now gone and all the methods to get the theme work directories have been implemented into the core.

We also removed the obsolete PageBuilder module and some old legacy code about theme customizations.

Along these changes we added two new shiny modules: Update Channels and Plugin Options. The first allows developers to add an update channel switching feature for their custom updaters in the WBF Status page, the latter makes available an API to easily create settings pages for WBF-compatible plugins. See the linked docs for more informations.

Waboot 2.3.0 has some interesting changes too: finally, it feature an auto-installer for WBF; furthermore the Theme class now has a method called add_component_style() that allows to specify a style file that will be merged into a single style file containing all the active components styles added via this method and this will be automatically enqueued by Waboot.

This completes the Components styles management possibilities along the add_inline_style() method (that merges all the active components styles and put them inline into the html).

From the v2.2.0 we also abandoned the templates/wordpress directory and moved all the WordPress standard templates one level up to reduce unnecessary nesting.

See the changelogs for both WBF and Waboot for more informations.

You can download the new version packages here (WBF) and here (Waboot).

We still need some testing for these new releases, so if you happen to find a bug, do not esitate to report it via our github repositories. Thanks.

How detect mobile browsers with WBF

WBF has a built-in mobile detect service (provided by Mobile_Detect class) that you can use via PHP.

You can use the service like so:

	//Code for WBF 1.0.x
	if(WBF()->get_mobile_detect()->isMobile()){
		//...do stuff
	}

	//Code for WBF 1.1.x
	if(WBF()->services()->get_mobile_detect()->isMobile()){
		//...do stuff
	}

The Mobile_Detect class can do much more than that, like detect the type of browser the user is using. You can refer to the class code examples for more information.

How effectively manage WordPress template views (with WBF)

WordPress has a great system for managing templates, partials and to allow the overwriting of specific files in child themes.

When a new request come to WordPress engine, the CMS first try to guess the needed main template file among a specific hierarchy. This work is done in /wp-includes/template-loader.php file; then the filter template_include comes into place to allows developers to customize the default behavior.

Within the main template file (namely single.php, page.php, home.php and such) theme designers can use the famous get_template_part function to include different template partials based on context.

While this method is quick and functional, it lacks of structure; for example, in template partials it is possible to use variables from the outer scope and that can make hard to follow the program workflow.

Many developers within WordPress community have developed their own method to address this issue, with the aim to make WordPress template system more close to an MVC pattern.

Following a MVC pattern is critical for long-term maintainability of your theme and plugin templates. Far too often logic is mixed with presentation in the WordPress ecosystem.

We at WAGA have included an MVC-like template system component in our WBF framework and for the rest of this article, we’ll brief introduce it.

Our system is not a replacement for WordPress get_template_part() but more a tool to help you think of a way to separate logic and presentation in your codebase (we heavely use it when output templates through filters or actions callback, such as add_menu_page() function).

Let’s say you want to output a template that looks like that:

<h1>Hello <?php echo $name; ?>!</h1>
<p>
	<?php echo $content; ?>
</p>

You first put it in a separate file, for example called hello.php. Then you can use our template system:

$v = new \WBF\components\mvc\HTMLView("path/to/hello.php");
$v->display([
	'name' => 'John Doe',
	'content' => 'You are awesome!'
]);

And that’s it! It is that simple. Your template will be rendered like that:

<h1>Hello John Doe!</h1>
<p>
	You are awesome!
</p>

Let’s us make a more meaningful example: this is how (traditionally and “naively”) you can add an admin page to WordPress and display content in it.

add_action('admin_menu', 'foo_add_admin_page');

function foo_add_admin_page(){
	add_options_page('My Option Page', 'My Option Page', 'my-capability', 'my-option-page', 'foo_display_option_page');
}

function foo_display_option_page(){
	$content = 'This is my option page';
	?>
	<div class='wrap'>
		<h1>My Options</h1>
		<?php echo $content; ?>
	</div>
	<?php
}

You can easily see that while it can works for small functionality, it can be a real pain to maintain when the code grows.

Here it is the WBF approach to the issue (and with a more concise code).

add_action('admin_menu', function(){
	add_options_page('My Option Page', 'My Option Page', 'my-capability', 'my-option-page', function(){
		$title = 'My Options';
		$content = 'This is my option page';

		/*
		 * Here you can do all your logic, data retrieving and elaboration and then pass to the template only the
		 * the results of all operations.
		 */

		$v = new \WBF\components\mvc\HTMLView("path/to/view.php");
		$v->display([
			'title' => $title,
			'content' => $content
		]);
	});
});
    <div class='wrap'>
        <h1><?php echo $title; ?></h1>
        <?php echo $content; ?>
    </div>

As you can see, now logic and presentation are two separated aspect and can be maintained more easily.

Of course, WBF MVC component can do much more and can be even extended to support real template engines. One of its strenghts is that it fully support template overwriting, both in themes and in plugins.

For example:

$v = new \WBF\components\mvc\HTMLView("templates/parts/hello.php");

Will look for hello.php in the following paths:

- your-child-theme/templates/parts/hello.php
- your-parent-theme/templates/parts/hello.php
$v = new \WBF\components\mvc\HTMLView("templates/parts/hello.php","my-plugin");

Will look for hello.php in the following paths:

- your-child-theme/templates/parts/hello.php
- your-parent-theme/templates/parts/hello.php
- my-plugin-directory/templates/parts/hello.php

You can read the official documentation on github.

Getting rid of messy WordPress functions.php files with WBF Theme components

The functions.php is the core of every WordPress theme; developers can use it to customize every WordPress default behavior that has an hook (an action or a filter) attached.

It’s fast and easy to use but WordPress itself does not dictate on how you have to organize it. This is really not a problem if you are an expert: you surely got your method to structure it in way that suits your work methodology. The case is different if you have little to moderate experience with WordPress theming or programming in general, the lack of a fixed structure does not help you and more often then not leads you to decisions that you will regret when you will need to return to the project some time later for some changes.

If you are not so experienced it is relatevely easy to ends up with a very little organized functions.php file, full of copy\paste code or unrelated functions.

There are a numbers of way to organize your hooks and customizations, every famous theme out there has its own method and no one is right or wrong by itself. We at WAGA have developed theme components.

Theme Components represent a structured way to encapsulate theme customizations in isolated contexts that facilitates the code maintenance over extended periods of time. They can also be thought as a sort of snippets repository.

Let’s say, for example, that you have found this code snippet somewhere:

add_action( 'woocommerce_cart_calculate_fees','woocommerce_custom_surcharge' );
/**
 * Adds a % surcharge to cart / checkout in WooCommerce
 * @see: http://wpsnipp.com/index.php/functions-php/add-surcharge-cart-checkout-woocommerce/
 */
function woocommerce_custom_surcharge() {
  global $woocommerce;
        if ( is_admin() && ! defined( 'DOING_AJAX' ) )
                return;
        $percentage = 0.01;
        $surcharge = ( $woocommerce->cart->cart_contents_total + $woocommerce->cart->shipping_total ) * $percentage;
        $woocommerce->cart->add_fee( 'Surcharge', $surcharge, true, '' );
}

You can paste this in your functions.php file and it will works fine, but imagine if you do the same with many more snippets. Eventually you will ends up with a very long file, very problematic to debug. So you can start your own way of hooks management or try out the WBF Theme Components first.

Make sure WBF is installed and activated, then create a new directory in your theme called components. Inside it put a new file under /wcaddons/wcaddons.php.

The file content should look like this:

/**
Component Name: WCAddons
Description: My WooCommerce addons
Category: WooCommerce
Tags: Tag Sample
Version: 1.0
Author: FooBar
Author URI: http://www.foo.bar
*/

if(!class_exists("\\WBF\\modules\\components\\Component")) return;

class WCAddons extends \WBF\modules\components\Component{
    public function setup(){
        parent::setup();
	    add_action( 'woocommerce_cart_calculate_fees',[$this,'woocommerce_custom_surcharge']);
    }
    public function woocommerce_custom_surcharge(){
	    global $woocommerce;
	    if ( is_admin() && ! defined( 'DOING_AJAX' ) )
		    return;
	    $percentage = 0.01;
	    $surcharge = ( $woocommerce->cart->cart_contents_total + $woocommerce->cart->shipping_total ) * $percentage;
	    $woocommerce->cart->add_fee( 'Surcharge', $surcharge, true, '' );
    }
}

With slightly more code, you now have a fully functional component that do just one thing. You can enable \ disable it from the dashboard (/wp-admin/admin.php?page=wbf_components) and customize it even further with some predefined options.

It is easy to see that is more efficient to have many components that groups different functionality and that you can toggle at any moment (for example, in case of bugs or problems) instead of a very long functions.php file or various, scattered, files.

You learn more about WBF Theme Components in the docs.

How easily print WordPress post terms hierarchical (with WBF)

WordPress terms can be ordered hierarchical, but there is no built-in easy way to output them in hierarchical order.

Say, for example, that you have this structure of terms for the “category” taxonomy:

-- Films
 -- Comedy
 -- -- '70
 -- -- '90
 -- -- modern
 -- Historical
 -- Science Fiction

And for a post that belogs to Film, Comedy and modern you want to print categories like so:

Posted in: Films, Comedy, modern.

Functions like wp_get_post_terms() or wp_get_object_terms() doesn’t help us if you expect this result. They, by default, output the terms ordered by name, and get_the_term_list() uses the same default, so the result will be like:

Posted in: Comedy, Films, modern.

Other available order settings (term_id, term_group, term_order) doesn’t produce our desidered output either.

WBF Approach

WBF, on the other hand, has a very quick utility function to do just that (and something more): \WBF\components\utils\Terms::get_post_terms_hierarchical()

The function accepts 5 parameters:

$post_id

(int) (required)

The post ID

$taxonomy

(string) (required)

The taxonomy name

$args

(array) (optional) Default: []

The arguments that will be fetched (internally) to wp_get_post_terms.

$flatten

(bool) (optional) Default: True

If TRUE, the function returns a one-dimensional array of terms; if FALSE terms are nested accordingly to their parent so the function returns a multidimensional array where the first level is composed of top-level terms only.

$convert_to_wp_term

(bool) (optional) Default: False

If TRUE, and $flatten is also TRUE, the resulting array will be an array of WP_Term, otherwise it will be an array of stdClass.

The function automatically fills the array with missing parents (for example, if our post is assigned to Films and modern but not to Comedy) and label these terms with a property called not_assigned with a value of True.

Waboot Approach

Waboot implements this WBF function and make available a get_the_term_list() equivalent called \Waboot\template_tags\get_the_terms_list_hierarchical() that can easily display the desidered ordered list of terms.

The function accepts the same parameters as get_the_term_list()$id, $taxonomy, $before, $sep, and $after, with the addition of $linked parameter.

$linked

(bool) (optional) Default: True

If TRUE, the terms will be linked to their archive page.