It's all custom fields!

We often get pre-sales queries asking if it is possible to use “custom fields” in Perch.

In some other CMS products, particularly those – like WordPress – that have come from blog roots, custom fields are a way to add additional fields to a post for editors to complete. They give you a way of achieving some sort of structured content in tools that weren’t really designed that way from the outset.

Perch, however, is different. Perch is entirely based around structured content and therefore every template is a collection of “custom fields”. As a quick example, let us assume that we are developing a page for a company website that lists the employees in the company. The CEO is very particular that when the page loads his profile should be front and centre, so to appease him we decided to display the profiles in a carousel and have found a jQuery plugin (Responsive Carousel) that can do this.

Our requirements

To enable content editors to upload staff member details – an image, some bio text, staff member name, job title, email address and phone number
To display these using mark-up that will work with responsive slider
To ensure that everything displays well without JavaScript (because we care about doing things properly)

The slider

Often, the best way to work with a third party plugin is to get the HTML working first and make sure the plugin does what you want. Then you can move to your Perch template.

I’ve downloaded the production version of Responsive Carousel and included it in my page. Then written some HTML displaying a couple of staff members so I can test that Responsive Carousel does what I want and can tweak my CSS for the display.

<ul class="carousel">
  <li>
    <img src="/img/bossman.jpg" alt="Mr. Bossman" />
    <h2>Mr Bossman</h2>
    <div class="job-title">C.E.O.</div>
    <p>I'm the boss. I like to boss people around, like a boss.</p>
    <p>I have lots of qualifications. That's important when you are the boss. I have the certificates framed in my office.</p>
    <div class="contact">
      <div class="email">Email: 
      <a href="mailto:mr.bossman@example.com">mr.bossman@example.com</a></div>
      <div class="tel">Phone: 44 (0) 123 4567</div>
    </div>
  </li>
  <li>
    <img src="/img/catlady.jpg" alt="Jane Smith" />
    <h2>Jane Smith</h2>
    <div class="job-title">Head of cat accessories</div>
    <p>I have a thirty year career in the cat accessories business. Collars, bowls, 
little ears to make your cat look like a mouse. That kind of thing.</p>
    <p>There are currently no qualifications in cat accessorization. This is something I believe should change.</p>
    <div class="contact">
      <div class="email">Email: <a href="mailto:jane.smith@example.com">
     jane.smith@example.com</a></div>
      <div class="tel">Phone: 44 (0) 124 4444</div>
    </div>
  </li>
</ul>

My page now looks like this.

The carousel in place

I’m happy with that, and I have tested how the display will look if the user doesn’t have JavaScript. So that’s two of our objectives met. I now just need to make each employee editable in Perch. To do that I will create a Perch template. I copy out all of the HTML for one slide, plus the opening and closing ul tags and paste that into a new file. Save that file into perch/templates/content/employee.html

<ul class="carousel">
  <li>
    <img src="/img/bossman.jpg" alt="Mr. Bossman" />
    <h2>Mr Bossman</h2>
    <div class="job-title">C.E.O.</div>
    <p>I'm the boss. I like to boss people around, like a boss.</p>
    <p>I have lots of qualifications. That's important when you are the boss. I have the certificates framed in my office.</p>
    <div class="contact">
      <div class="email">Email: <a href="mailto:mr.bossman@example.com">
     mr.bossman@example.com</a></div>
      <div class="tel">Phone: 44 (0) 123 4567</div>
    </div>
  </li> 
</ul>

We now replace the placeholder text with Perch template tags – this will create our “custom fields”. You can find all of the template documentation in the Perch docs.

I am also using the perch:before and perch:after tags to render the opening and closing ul item.

<perch:before>
<ul class="carousel">
</perch:before>
  <li>
    <img src="<perch:content type="image" id="image" label="Image" width="700" />" 
alt="<perch:content type="text" id="alt" label="Description" required="true" 
help="e.g. Photo of MD John Smith with his best wig on" title="true" />" />
    <h2><perch:content id="fullname" type="text" label="Full name" required="true" title="true" /></h2>
    <div class="job-title"><perch:content id="jobtitle" type="text" label="Job title" required="true" /></div>
    <perch:content id="bio" type="textarea" label="Biography" textile="true" editor="markitup" required="true" />
    <div class="contact">
      <div class="email">Email: <a href="mailto:<perch:content id="email" type="email" label="Email" required="true" />">
          <perch:content id="email" type="email" label="Email" required="true" />
      </a></div>
      <div class="tel">Phone: <perch:content id="phone" type="text" label="Phone" required="true" /></div>
    </div>
  </li>
<perch:after>
</ul>
</perch:after>

Back on the page we can delete our test HTML and dummy content. Replace it with a tag to create a Perch Region – don’t forget you will need to have Perch included in this page first.

<?php perch_content('Employees'); ?>

Now reload the page in your browser, the dummy content will disappear and Perch knows we have a new Region. Login into the Perch admin, select your page, click on the new Employees region and choose your employee template. Then in the Region Options select Allow Multiple Items. You can also choose here whether to edit all on one page or in list detail mode, and choose how the items are ordered.

Setting Region Options

You can see that the fields you added to your template are now the fields available to complete in the admin for each employee. It’s easy for a content editor to add new employees to the page. They don’t have to worry about how this content will look at all, they just add a new person.

The edit form

After adding some employees you now have a staff carousel, all managed through Perch.

We make a big deal out of our structured content approach in Perch because we believe that an employee – in this instance – should be stored as an employee and not as a set of custom fields attached to a post. This means that you can make use of the Employees content elsewhere on the site using perch_content_custom, as we know what it is and which fields have been stored and are therefore available.

Photos used in the examples credit: Victor1558 / Foter.com / CC BY