Get or set an output region (primarily for front-end output usage)

This function is an convenience for storing markup that ultimately gets output in a _main.php file (or whatever file $config->appendTemplateFile is set to). It is an alternative to passing variables between included files and provides an interface for setting, appending, prepending and ultimately getting markup (or other strings) for output. It’s designed for use the the “Delayed Output” strategy, though does not necessarily require it.

This function can also be accessed as wireRegion(), and that function is always available regardless of whether the Functions API is enabled or not.

Note: unlike other functions in the Functions API, this function is not related to API variables.

Example

// define a region
region('content', '<p>this is some content</p>');

// prepend some text to region
region('+content', '<h2>Good morning</h2>');

// append some text to region
region('content+', '<p><small>Good night</small></p>');

// output a region
echo region('content');

// get all regions in an array
$regions = region('*');

// clear the 'content' region
region('content', '');

// clear all regions
region('*', '');

Usage

// basic usage
$string = region();

// usage with all arguments
$string = region(string $key = '', $value = null);

Arguments

NameType(s)Description
key (optional)string

Name of region to get or set.

  • Specify "*" to retrieve all defined regions in an array.
  • Prepend a "+" to the region name to have it prepend your given value to any existing value.
  • Append a "+" to the region name to have it append your given value to any existing value.
  • Prepend a "++" to region name to make future calls without "+" automatically prepend.
  • Append a "++" to region name to make future calls without "+" to automatically append.
value (optional)null, string

If setting a region, the text that you want to set.

Return value

string null bool array

Returns string of text when getting a region, NULL if region not set, or TRUE if setting region.


Functions methods and properties

API reference based on ProcessWire core version 3.0.172

Twitter updates

  • ProcessWire 3.0.174 core updates: improvements to the new path/URL hooks and more— More
    12 March 2021
  • ProcessWire 3.0.173 adds several new requested features and this post focuses on one of my favorites: the ability to hook into and handle ProcessWire URLs, independent of pages— More
    5 March 2021
  • This week ProcessWire gained powerful new tools for finding pages and controlling how they are loaded. If you like to maximize performance and efficiency, you’ll like what 3.0.172 brings— More
    5 February 2021

Latest news

  • ProcessWire Weekly #356
    In the 356th issue of ProcessWire Weekly we'll cover the latest core updates (ProcessWire 3.0.173), introduce new third party modules RockCalculator and RockIframe, and take a closer look at a brand new site of the week. Read on!
    Weekly.pw / 6 March 2021
  • ProcessWire 3.0.173 core updates: New URL hooks
    ProcessWire 3.0.173 adds several new requested features and this post focuses on one of my favorites: the ability to hook into and handle ProcessWire URLs, independent of pages.
    Blog / 5 March 2021
  • Subscribe to weekly ProcessWire news

“To Drupal, or to ProcessWire? The million dollar choice. We decided to make an early switch to PW. And in retrospect, ProcessWire was probably the best decision we made. Thanks are due to ProcessWire and the amazing system and set of modules that are in place.” —Unni Krishnan, Founder of PigtailPundits