tagged: Coding

Perch shared regions

Perch’s shared regions offer us a fantastic way to eleminate repetition by giving users a single ‘shared’ region to add data to. In Perch, regions are tied to single pages. If for instance we had some contact details or social media links that appear in the header and footer on every single page, then we wouldn’t want to have to add the details for every page. Shared regions mean we can add the data once and are accessible on every page.

Creating a shared region

Progmatically creating a shared region via the perch_content_create is as simple as:

perch_content_create('Contact Details', [
    'template' =>  'contact_deets.html',
    'shared'   =>  true
]);

Setting up the template

You could add this to your global header, or homepage template &mash; right after Perch runtime. It’s worth noting that creating regions via this method can be a really good idea but that will only be created on runtime, so you’d need to visit the page in your browser to trigger the creation initially. Once created, login and you’ll see your newly created shared region now appears at the top of the page listing. Here is an example of what our template we referrenced — contact_deets.html — may look like.

<perch:content id="tel" type="text" label="Telephone Number" />
<perch:content id="email" type="text" label="Email Address" />

Extracting the data

In our example we have placed the perch_content_create in our global header layout, so let’s expand on this to extract the individual pieces of data:

perch_content_create('Contact Details', [
    'template' =>  'contact_deets.html',
    'shared'   =>  true
]);

//fetch the shared region data
$contact_details = perch_content_custom('Contact Details', array(
	'skip-template'=>true,
));

//set each contact detail in a variable
$tel = $contact_details[0]['tel'];
$email = $contact_details[0]['email'];

Now we have the shared region retrieved and the individual entries stored in variables, we can go head and start outputting them where needed within our layout. Let’s fetch the telephone and email and place into our layout:

<div class="contact">
	<ul class="contact__list">		
	    <?php 
	      if (isset($tel)) { echo "<li><span></span> <a href=\"tel:" . $tel . "\">" . $tel . "</a></li>\n"; } 
	      if (isset($email)) { echo "<li><span></span> <a href=\"mailto:" . $email . "\">" . $email . "</a></li>\n"; } 
	    ?>
	</ul>
</div>

Passing the shared content into templates

Sometimes you may want to get these contact details into a template instead, which is easily achieved. First all we need to do is utalise the PerchSystem class. Let’s say we want to pass the telephone and email variables through to one of our templates, we could use:

PerchSystem::set_var('email', $email);
PerchSystem::set_var('telephone', $tel);

It’s worth remembering that this will only work with templates that are parsed at runtime, meaning you need to call in your content using perch_content_custom instead of perch_content.

So our updated layout, may look like:

perch_content_create('Contact Details', [
    'template' =>  'contact_deets.html',
    'shared'   =>  true
]);

//fetch the shared region data
$contact_details = perch_content_custom('Contact Details', array(
	'skip-template'=>true,
));

//set each contact detail in a variable
$tel = $contact_details[0]['tel'];
$email = $contact_details[0]['email'];

//set our perch variables so we can access the data in a different templatea
PerchSystem::set_var('email', $email);
PerchSystem::set_var('telephone', $tel);

This enables us to now access the contact data from within the template of another region by simply referrencing perch_content with the id that corrosponds to the variable we set.

<perch:content id="telephone" />
<perch:content id="email" />