Page Builder Areas

###What's an "area"?

A Page Builder "area" is similar in concept to a "widget area" in WordPress. It's simply a place to put stuff. With widgetized areas in WordPress, you drag some widgets into the "area" and some kind of content shows up on the front end. Widgetized areas are great if you want the same content to display on every single page, in the same place on every page. They get a lot more complex if you want different widgetized areas for different pages or different places on the screen. In order to only display a specific widget on an "About" page, for example, you would need some kind of widget visibility-controlling plugin to tell the widget to only display if we were on that specific page. You'd need dozens of these widgets, with very specific rules, anytime you wanted to specify a page or a post type to display that widget on.

Page Builder already sort of solves this by allowing you to create specific saved layouts, and these layouts can be added wherever you want in a theme template file. Page Builder Areas takes this one step further by allowing you to register areas the same way you would register a sidebar. Once areas are registered, those areas appear in the Page Builder meta box on singular edit pages (e.g. New Post and Edit Post screens) and template parts can be added to those areas specifically for that page. Let's take a look at how this works.

###Using Page Builder Areas

First we need to register our areas. This could go into your theme setup function or wherever makes sense.

function mytheme_register_page_builder_areas() {
	register_page_builder_area( 'hero' );
	register_page_builder_area( 'footer' );
}
add_action( 'after_setup_theme', 'mytheme_register_page_builder_areas' );

This will add two new Page Builder areas. They will show up on any post type edit page that currently supports Page Builder (which is to say, any of the post types that are defined in the Page Builder options). These will look like this:

Notice how the Page Builder meta box is now broken into three sections. You have the main Content Area Templates -- that's where the regular Page Builder template parts for this post go -- and you have two new sections for Hero Area Templates and Footer Area Templates. Those two are for the two Page Builder Areas that we just registered. Now the user can define which template parts are loaded into which area, assuming the theme supports those areas.

###Adding theme support for areas

Adding support for areas in your theme is pretty simple and just requires a single Page Builder template tag, wds_page_builder_area. Here's an example:

<?php
/**
 * The template for displaying all pages.
 *
 * This is the template that displays all pages by default.
 * Please note that this is the WordPress construct of pages
 * and that other 'pages' on your WordPress site will use a
 * different template.
 *
 * @package My Cool Theme
 */
get_header(); ?>

	<div class="wrap yo">

		<div class="primary content-area">
			<main id="main" class="site-main" role="main">

				<?php wds_page_builder_area('hero'); ?>

				<?php while ( have_posts() ) : the_post(); ?>

					<?php get_template_part( 'content', 'page' ); ?>

				<?php endwhile; // end of the loop. ?>

				<?php wds_page_builder_area(); ?>

			</main><!-- #main -->
		</div><!-- .primary -->

		<?php get_sidebar(); ?>
		
		<?php wds_page_builder_area('footer'); ?>

	</div><!-- .wrap -->

<?php get_footer(); ?>

The above is from an example page.php. Just above the loop, I'm pulling in my first Page Builder Area, the "hero" area, with the function wds_page_builder_area. After the get_sidebar at the bottom, I'm pulling in the "footer" Page Builder Area.

Page Builder Areas are different from Saved Layouts and individual layouts for single posts but they are similar to both. Their settings are stored differently and independently so there aren't conflicts. In most cases, you'll probably just want to load one or two templates into the Page Builder Areas, but you can add as many as you want or need. Page Builder Areas are not included in -- or affected by -- the Page Builder Layout Hierarchy.

###Static Areas

Sometimes, you will want to define an area statically. What if, for example, you're on a 404 or an archive page? Areas are saved to the single post's meta information -- if you're on a part of the site that does not have a single post ID, it won't have any way to save or retrieve the areas for that page.

For this reason, areas also have a built-in way of registering and loading specific saved areas with predetermined groups of templates. To register the area, you use the same function, but pass an array of template slugs as the second parameter. Using the example above, your function might look like this:

function mytheme_register_page_builder_areas() {
	register_page_builder_area( 'hero' );
	register_page_builder_area( 'footer' );
	register_page_builder_area( 'hero-archive', array( 'featured-post' ) );
	register_page_builder_area( 'footer-archive', array( 'instagram' ) );
}
add_action( 'after_setup_theme', 'mytheme_register_page_builder_areas' );

When the second parameter is passed to register_page_builder_area, Page Builder knows that you are giving this area a specific set of template parts and, therefore, will not display this area on the singular edit pages in the admin. In fact, these areas are entirely hidden from the admin, similar to registering a specific, non-user-editable saved layout.

In the theme template files, however, these areas are called exactly the same.

<?php
/**
 * The template for displaying 404 pages (not found).
 *
 * @package My Cool Theme
 */

get_header(); ?>

	<div class="wrap content-area">

		<main id="main" class="site-main" role="main">
			<section class="error-404 not-found">

				<?php wds_page_builder_area( 'hero-archive' ); ?>

				<header class="page-header">
					<h1 class="page-title"><?php esc_html_e( 'Oops! That page can&rsquo;t be found.', 'my-cool-theme' ); ?></h1>
				</header><!-- .page-header -->

				<div class="page-content">
					<p><?php _e( 'It looks like nothing was found at this location. Maybe try one of the links below or a search?', 'my-cool-theme' ); ?></p>

					<?php get_search_form(); ?>

				</div><!-- .page-content -->
			</section><!-- .error-404 -->

		</main><!-- #main -->

		<?php wds_page_builder_area( 'footer-archive' ); ?>

	</div><!-- .wrap -->

<?php get_footer(); ?>

The code above is for an example 404 page, which we know will not have any kind of ID. Above the content and below, we're using wds_page_builder_area and calling in the specific areas the same way we did before. But since hero-archive and footer-archive had arrays of template slugs passed to them, Page Builder knows to load those specific templates, rather than trying to load the templates from a post ID.

If for some reason that area name doesn't exist -- for example, if it was never registered -- Page Builder will look for a saved layout with the matching name. In this case, wds_page_builder_area becomes a wrapper for wds_page_builder_load_parts. In this way, if you wanted to use Page Builder Areas that were editable by the user, you could call in saved layout names using the wds_page_builder_area function (assuming that there isn't an area saved with the same name).