Perch documentation

Adding new pages

Enabling editors to create new pages and manage their site is simple in Perch, and you have full control over how much access you give editors to this functionality.

New pages are created using a special kind of template called a master page. They live in perch/templates/pages and instead of being .html fragments these are complete pages including Perch editable regions, that look much like any page of your web site.

When you create a new page you can select which master page to use. You can have as many master pages as you like – it doesn’t matter how different the various sections of your site are.

I am going to create a master page that will enable my editors to add new pages within the about section of the site.

I already have an index.php page inside my about folder, I’ll use this as a basis for my master page. I copy index.php into perch/templates/pages and rename it about.php then I open it in my text editor. I am also opening the default.php template as it has some examples that I can copy.

The first thing you will notice is that the runtime include looks slightly different, this is just so that we don’t need to know the path to this page when adding Perch.

I also add to the title the function

<?php perch_pages_title(); ?>

This will mean that my pages get the title the editor gives them.

Finally, I want the subnavigation to be automatically created. So I use the perch_pages_navigation() function setting the from-path to be the about section.

<?php perch_pages_navigation(array(
  'from-path' => '/about',
  'levels'    => 1
)); 
?>

I will also need to add this same function to the about/index.php page that I copied to create this master page, in order that the navigation will display on the top level page.

Save this template.

Finally we need to make the about section of the site writable by the webserver – this will depend on your hosting configuration but the setting you use for the resources folder in Perch should work.

Now log into Perch admin and select the Master Pages link, here we can set up our master page.

Give it a title that will display in the listing of available pages.

The Copy Region Options setting lets you choose a page in your site where the regions will be copied from. This means that when your editor creates a new page they won’t have to decide what type of content template to use. The regions will already be set up for them and they can just add content. In our case we want to use about/index.php

The next setting lets you choose whether the reference this template (meaning that any changes to the template will be updated on any pages created from it) or copy the template (changes to the template will NOT be reflected on created pages). Generally I want to reference the template so I can keep all pages consistent.

Save the template settings and go back to the main page listing.

I can now add subpages of the about page. They will have the same regions as the about/index.php page that I copied.

If we go back to the site, we can see the new pages appearing in the navigation.

It is worth knowing that creating new pages is not a default Role. Back in admin go to Users and then Roles, look at the settings for the default Editor role in Perch, this does not allow creating new pages and you can change this as you wish.

Also, in Page Options for the about section you can override any defaults and allow or prevent a group of users from adding new pages. Therefore if you have a section – for example a jobs listing and you want people in the HR group to be able to add new pages there only, you could assign them those rights on a section basis.