Build Your First Perch App

In this post we will build a very small Perch app. The app won’t deal with databases, classes, or any advanced PHP stuff. This is more of an introduction to building Perch apps.

What is a Perch app?

Perch has an API that allows developers to build add-ons on top of the Perch platform. There are different types of add-ons. Apps is one type.

An app can be anything. It can be a dashboard widget. It can be an e-commerce application. It can be a collection of functions. The possibilities are endless.

Before we start

It is worth reading the documentation as it explains things, such as the app structure and the naming conventions, in more depth.

Here’s the short version:

What we are building

We are building some sort of “helper” app.

In some projects you may find yourself writing PHP code on a page and then realise you actually need the same code on different pages too. So you either copy it to 5+ different pages making that bit of code not very maintainable, or write it as a function and manage it from one place.

Instead of adding the following to all of our pages:

include('myHelperFunction.php');

We will build an app that makes our functions automatically available to us on all our pages.

Register your app

Create a directory in perch/addons/apps with your app name. Let’s call it prefix_helper. Feel free to replace prefix_ with your name.

Inside the directory, create a file and call it admin.php. Perch will look for this file to register your app.

Use the register_app() function to register your app. The function takes 6 arguments. You can refer to the documentation for more details. The arguments are:

  1. App ID
  2. App Name
  3. Priority (in control panel menu)
  4. Description
  5. Version
  6. Hide/display the app in the control panel menu

In our case:

  1. prefix_helper
  2. Prefix Helper App
  3. 99 (any integer would do - we don’t need it listed in the control panel)
  4. A flexible helper app
  5. 1.0
  6. true (to hide the app from the control panel menu)
$this->register_app('prefix_helper', 'Prefix Helper App', 99, 'A flexible helper app', '1.0', true);

You can also tell Perch what is the minimum version of Perch that your app supports:

$this->require_version('prefix_helper', '3.0');

Your final file:

<?php

$this->register_app('prefix_helper', 'Prefix Helper App', 99, 'A flexible helper app', '1.0', true);
$this->require_version('prefix_helper', '3.0');

Runtime functions

Create a new file in the same directory and call it runtime.php.

Hello World

Let’s add a simple function:

<?php

function prefix_helper_print($string){
    echo $string;
}

Now add prefix_helper to your list of runtime apps in perch/config/apps.php.

Go to any page on your website and print “Hello World”:

prefix_helper_print("Hello World");

Congratulations! You built your first Perch app.

Now what?

Let’s add a useful function to our app.

In a Perch Forum post Dustin asked about his approach of using perch_content_cutsom() to display uncached regions as it suited his development workflow realising he is sacrificing the caching benefits. I suggested he set the production mode and use something like this:

$my_region = perch_content('My Region', true);

if (PERCH_PRODUCTION_MODE === PERCH_DEVELOPMENT) {
    // development environment - output uncached
    perch_content_custom('My Region');
} else {
    // production or staging environment - output cached
    echo $my_region;
}

If you use this technique for all your regions, it takes longer to type than the one liner perch_content(). Here is where the helper app comes in. Let’s make the above as a function:

function prefix_helper_content($region_name) {
    $region = perch_content($region_name, true);

    if (PERCH_PRODUCTION_MODE === PERCH_DEVELOPMENT) {
        perch_content_custom($region_name);
    } else {
        echo $region;
    }
}

Now on your pages you can simply use:

prefix_helper_content('My Region');

Last words

This was a very small app. It is only 2 files and barely does anything. Well sometimes that’s all you need. If you have never built a Perch add-on before, hopefully this small app will encourage you to explore the Perch API.

link

Related articles