Help / Getting Started

You've downloaded and installed Perch so now you can get started editing content. The following steps are all you need to do to begin editing simple content on your pages.

1. Step 1: Add the Perch include to your page
2. Step 2: Add one or more Perch content tags to the page
3. Step 3: Log into the admin and select a template for the new region
4. Step 4: Edit the content for the region

Step 1: Linking Perch into your page

The first thing you must do is link Perch into your page so that it can serve up the content. This is done by adding a simple PHP statement at the top of each page.

<?php include('perch/runtime.php'); ?>

This statement includes a path from the page to the Perch runtime file. Just like a path to an image in HTML, this needs to adjusted depending on where the page lives in your site.

For example, if the page is question was /about/history.php the path would need to be adjusted to move up out of the about folder like so:

<?php include('../perch/runtime.php'); ?>

Step 2: Adding the content tags

Once Perch is linked in, you need to add tags to identify where the editable content should go. A Perch tag is very simple:

<?php perch_content('Main heading'); ?>

These can go anywhere in your page. The value inside the quotes uniquely identifies that piece of content in the page, so you should change this to match the purpose of the content. You should use only letters, numbers, spaces and underscores. All the rest of the configuration is done inside Perch.

A page including Perch with content tags for a heading and main page content

Once you have added one or more tags to a page, refresh the page in your browser (checking that no errors are displayed), and then log into Perch to begin editing content. Unless you changed the install location of Perch you login at /perch - if your domain was http://www.example.com you login at http://www.example.com/perch.

Step 3: Initializing new Content regions

Once logged in you should see a list of pages on your site and the tags they contain. The value under Region is the name you gave the content when adding the tag to your page. The first thing you need to do is to tell Perch what template to use for each of the tags you have added. Until you have done this they will show up as 'NEW' in the list.

The content section of the admin after adding new tags

Click the region name for the content you wish to work with. The next screen will ask you to select a template. Unless you have created some templates of your own the listed templates are the default templates installed with Perch. You can read more about these templates here. In the screenshot below I am selecting to make this content a 'text block'.

The only other thing you need to set when initializing a region, is to decide whether multiple items should be allowed, if so check the checkbox then click submit.

Setting up a region to use a text block template

Step 4: Editing your content

The edit page for the new region with a text block template

After editing your content reload the page on your site (where you added the tags earlier) to see your content display.

The content added with Perch.

If you View Source on this page you can see that the Perch tags have been completely replaced by the content.

The content added with Perch as seen in the document source.

My Content region used a text block and was set to use Textile so it has been correctly wrapped with paragraph tags. The heading I set as text, so it goes into the template just as a string of text. You can specify exactly how each template behaves by editing and creating your own templates.

Working with .html pages

Perch uses PHP to deliver your content, so by default the pages of your site must be .php files. However, if your hosting account allows for .htaccess (web server configuration) files, it's possible to tell the web server to run PHP in other sorts of pages.

To do this, create a new file at the top level of your website and call it htaccess.txt (we'll rename it shortly). Put the following lines into the file:

AddType application/x-httpd-php .php .htm .html

You can add any file extensions you'd like to treat as PHP. (Don't add other server-side scripting languages like .asp unless you know what you're doing!)

Once you've done that, rename you file to .htaccess - that's starting with a dot and no file extension. This is a hidden file, so depending on your software settings, it may then appear to vanish. Most web editing software has a setting to show hidden files.

The files with the extensions you listed should now be run as PHP, enabling Perch to manage your content.