Upgrading from Perch to Perch Runway

Perch Runway is a powerful, easy to use, content management system (CMS). In particular, I love its content item Collections and the way that it can be used to display related content throughout a site. It's great!

I've converted my CVW Web Design site from Perch to Perch Runway. The process takes a bit of time but is straightforward and I didn't have any major problems. Here's a description of what I did.

Note: I made a back-up and carried out the upgrade on my local development site before copying everything over to the live site.

Starting points

1. If you are considering upgrading to Perch Runway, the first place to start is the upgrade instructions and documentation. You will also need to amend the URL rewrite rules for your server.
2. If you are running the Perch Blog app, you will need to configure this in Runway. I followed the Runway Blog configuration with minor amendments and additions (see below).

Take-off!

I went through the upgrade instructions in Step 1 to the point where I had upgraded Perch but before moving pages into Runway.

As part of the upgrade process, you must set-up Perch Runway rewrite rules. I added the Runway rewrite rules after any existing rewrite rules in my .htaccess file.

At this point, I had a 'halfway house' site. It was running Runway but pages were still files and I wasn't using Runway's front controller architecture to the fullest extent. My existing pages were displayed correctly but I wanted to convert these into Runway pages

Here's the process I used for converting existing pages into Runway pages:

1. Create a master page for each page in /perch/templates/pages. Master pages are created by saving the existing page into the new location. However, these master pages do not need the normal Perch runtime include.
2. Delete the existing page file. Don't delete the page in Perch admin.
3. Configure each new Runway page in Perch admin (in the page options) to use the appropriate master page and with the correct page path.
4. Remove the old rewrite rule for the page from my .htaccess file.
5. Check that the page content is displayed OK.

Perch Forms and Blog add-ons

I decided to convert any pages that use Perch add-ons into Runway pages first. I'm using the Perch Forms app and the Blog app for the News section on my site.

I use the Perch Forms app for a form on my Contact page. There is an associated Thank You page that is displayed after form submissions. I converted my Contact page and the Thank You page into Runway pages and removed the relevant page URL rewrite rules from my .htaccess file.

My site had a /news/ directory containing standard Perch Blog pages like post.php and archive.php. I have a stack of rewrite rules in my .htacess file for the blog/News section and I was a bit wary that these would interfere with Runway URL rewrites. So, I converted all blog pages into Runway pages and created routing as described in the blog configuration documentation (but with news/ as the first part of the route patterns). I also created a route with the pattern news/page/[i:page] for my main News page so that pagination of this page has a clean URL structure.

I created the blog master pages in /perch/templates/pages/blog.

I didn't need to update any links in my templates because the Runway routing in the documentation with my modifications gave me the same URL results as my old rules. I removed the old blog URL rewrite rules in .htaccess. It felt good to remove them. Perhaps that's just me though!

After converting the blog pages to Runway, I deleted the /news/ directory/folder.

Cruising at altitude

I converted my remaining pages to Runway pages so that they used the front controller architecture.

My only problem in this process was a page with 'perch' in the filename. It's called /perch-cms-development (on the site here). After the Runway upgrade, it was giving a 404 page missing error. So, I modified the Runway rewrite rules block in my .htaccess file by changing the first rewrite condition to:

    RewriteCond %{REQUEST_URI} !^/perch/

I've added a trailing slash and this means that the rewrite condition rules won't apply to the /perch/ directory but will apply to my perch page, see this forum post. Problem fixed.

The final page that I converted was the home page, /index.php. After establishing my master page and configuring the page in Runway, it felt a bit strange deleting this page from the server. I've never had a site without an index page before.

At this stage, I made one final change to the Runway rewrite rules block. I was previously using the Runway rules block that applies to upgrades of Perch sites containing existing pages. Now, with all my pages in Runway, this needed amending. I kept my trailing slash addition from above but changed the block to the fresh install example as described on the URL rewrites page.

After this, I checked everything and moved the development site to live version.

Just one more thing... blog post previews

To 'celebrate' my new site, I decided to write a blog post. However, previewing the draft post just gave me a blank page. This was working before the upgrade with a rewrite rule in my .htaccess file but not any more. It wasn't something I thought to check before making the Runway site live. Luckily, after a quick search of the Perch forum, I found this post with a simple solution. In my case, I added a route like this for the post page in Perch admin.

    news/[slug:s]/[preview:preview]

... and add this at the top of the post master page.

    <?php perch_blog_check_preview(); ?>

Blog post preview problem solved!

Overall

The Perch Runway upgrade is straightforward. I had a couple of minor problems but these were quickly fixed.

If you are upgrading from Perch to Perch Runway, I recommend moving the whole site into Runway before making it live. In my opinion, that's better than running a halfway site where some pages still exist as files outside of the Runway front controller.

A side benefit of the Runway upgrade is that the process of creating master pages caused me to rethink the structure of several pages and consolidate these into as few master pages as possible. And, as I did this, it made me review the page content. I rewrote a couple of page sections as a result.

After my upgrade, the site is working great and I'm really pleased I've made the move to Runway! I'll report back on some of Runway's awesome features in a subsequent post.

Discount: Use this referral link and receive a 10% discount on subsequent Perch software licenses after you buy your first copy of Perch or Perch Runway.

Addendum:

If you are a bit unsure about Runway routing, here are the Routes I ended up with

Pattern	Page path
news/page/[i:page]	/news
news/[year:year]	/news/archive
news/[year:year]/[i:month]	/news/archive
news/category/[slug:cat]	/news/archive
news/tag/[slug:tag]	/news/archive
news/author/[slug:author]	/news/archive
news/[blogslug:s]	/news/post
news/[slug:s]/[preview:preview]	/news/post