PetPress: a PetPoint plugin for WordPress

PetPress is a plugin for WordPress that enables integration of PetPoint Web services. For shelters that use the PetPoint kennel management services, this is the missing piece which can enable you to include animal listings on your WordPress-based website.

If you are researching options for a website for your animal shelter, please contact us. We can consult with your web developer / agency, or we can do the whole thing for you!

PetPress has been accepted into the WordPress plugin catalog (the first and only plugin of its kind to get the WordPress.org stamp of approval!) and can be downloaded at http://www.wordpress.org/plugins/petpress.

Latest Update

Read about changes in version 1.6.

PetPress in the Wild

Over 20 shelters in the USA and Canada are currently using PetPress. Some use the plugin as it is “out of the box”, and others customize it. Examples:

• Calgary Humane Society – Canada
• Main Line Animal Rescue / PSPCA – PA
• Marshall County Animal Shelter – WV
• Pets on Board – PA
• Routt County Humane Society – CO

Table of Contents

• Requirements – Can I use PetPress?
• Installing PetPress
• Setup and Configuration
• How to use PetPress (the shortcode)
• Troubleshooting
• Tips and hints
• Interactions with other plug-ins
• Future enhancements
• Where to get help

Requirements – Can I use PetPress?

(There are two requirements for an organization to use PetPress:

1) A WordPress website. 

2) Your organization must use the PetPoint shelter management software (www.PetPoint.com). The PetPress plugin calls the PetPoint web services to retrieve all of its animal data. (Note that PetPoint is a separate entity and neither PetPoint nor Airdrie Media provide technical support for the other’s software.)

How to install PetPress

PetPress can be installed like any other WordPress plugin, either by accessing it through the catalog (you can search by name) or by uploading the .zip file. Once you install PetPress, there is a configuration step before you can use it on your site.

Important: Be aware that PetPoint web services have to be enabled for you to use this plugin. To enable web services, you need to make a request to the PetPoint support team (have your group name or shelter ID ready). If web services is not enabled on the PetPoint side, you will get “Access Denied” errors.

Configuring PetPress

 The “settings” screen (under “Settings -> PetPress”) contains the following configuration fields:

• Auth Key: To use the PetPress plugin, you will need to know your PetPoint authorization key. This key can be found in PetPoint under “Admin > Admin Options > Setup > Online Animal Listing Options“. You can also contact PetPoint support for your code.
• List Options -> Specific values for Age / Weight: If checked, the list page will show specific ages and weights rather than generalized size and weights. For example, “2 yr – female – 44 lb” vs “adult – female – medium“.
• List Options -> “Adoption Pending” post-it notes: “Adoption Pending” messages will be displayed only if the animal’s stage in PetPoint begins with the word “Adopted”. If this is checked, and the animal has “adopted” in its stage, there will be a message on the detail page as well.
• List Options -> “In a Foster Home” post-it notes: “In a Foster Home” messages will be displayed only if the animal’s location or sublocation in PetPoint contains the word “foster”. If this is checked, and the animal qualifies, there will be a message on the detail page as well.
• Show Fields: This series of checkboxes allow you to select which fields of PetPoint data should be shown on your WordPress page. Note that if “Site name” is checked then the animal’s site will be shown on all list and detail pages. To show site on only some lists and detail pages, see the shortcode parameter “showsite”. Note, also, that some of the data snet from PetPoint may not be complete, so some longer text fields such as “behavior test result” may be truncated.
• Random Photo: If this box is checked, any time PetPress displays a list of animals, it will choose at random which of the (up to three) photos of the animal to use as the image in the tile. This may help to give some animals a second (or even third) chance to catch the eye of a prospective adopter who re-visits the site. It is not necessary for animals to have more than one photo to use this feature (though if an animal has only one photo, that photo will always be the one shown). Note that “photo 1” is more likely to be shown than the others. If there are two photos, it has a 66% chance of being the image shown, and if there are three photos the chance is 50% (with the other two an equal 25% chance each).
• Pets per page: The number of pets shown on each page in the list. If the “Pets per page” value is higher than the total number of animals to be shown, the pagination controls aren’t shown.
• Accent colors: These are the colors used for the animal’s picture frame on the list pages. To override the defaults, a valid six-character RGB value is required (no color names).

Using PetPress

The syntax for PetPress is as follows (remember the “[” and the “]“):

PETPRESS species=”1″ heading=”Adoptable Dogs”

Note that shortcode parameters (always lower case) are:

• heading – Appears at the top of the list page.
• id – The PetPoint ID of a specific animal. If you provide an “id” parameter, you do not need to also pass a species parameter.
• report – (BETA FEATURE) If set to “found” (ie: report=”found”), the page will list the found animals data (see below).
• showsite – if this is set to true in the shortcode, then the site will be shown for animals in the resulting list and detail pages even if the global “site” checkbox is unchecked. Note that the reverse is not true: you cannot use this parameter to turn the site off situationally when the global checkbox is checked.
• site – the site code for the location for which you want to display animals. If your organization has multiple sites, you can have different pages for each. NOTE: the site ID is numeric and not the same as your organization ID (that usually starts with “US”). If you don’t know what site ID to use, try “0” which will get all animals (of the specified species) from all sites within the organization.
• sort – The sort order for display. Valid arguments are “age”, “name”, and “weight”. The default value is “name”.
• species – If this field is present, the page will list all available animals of that species for the specified site. Valid arguments are: 1 = dogs, 2 = cats, 3 = rabbits, 4 = horses, 5 = small & furry, 6 = pigs, 7 = reptiles, 8 = birds, 9 = barnyard animals, and 1003 = animals that are not dogs or cats.

Either “species” or “id” is always required. Other parameters are optional.

Troubleshooting

Troubleshooting on setup

The most common problem with new setups relates to the enabling of web services by PetPoint. Web services are not turned on by default; you must contact PetPoint support and ask them to enable web services for you. This will probably take 24 hours to perform. Note that the IFRAME approach does not require web services, so do not assume that web services are on just because you have been using the IFRAME.

If you have confirmed that web services are on, check your Auth Key. If your Auth Key is missing or invalid, you should get a warning from the plugin. Also, make sure that your shortcode includes either a species or an individual animal ID. Finally, make sure that the quotation marks in your shortcode are actual “straight quotes” and not “curly quotes”.

Troubleshooting after setup

Although PetPoint web services are generally reliable, they are prone to occasional outages. This may result in empty rosters or the inability to view individual animals (whether or not they appear on the roster). Most outages resolve within a few hours. PetPoint has set up a health monitor page, though it does not always show short outages. If your installation of PetPress has been working fine and suddenly has problems, it is likely an issue on the PetPoint side. The caching routine will not discard old cache data until new data is available, so theoretically the plugin should continue to work through a PetPoint outage.

Troubleshooting data issues

PetPress reports the data sent to it from PetPoint. If your shelter is using PetPoint in a non-standard way, certain display fields in PetPress may not function the way that you want. Also, some longer text fields in PetPoint may be truncated when they are sent to PetPress, and this is unavoidable.

There may be a delay between updating data in PetPoint and seeing the change on your site. Asking PetPoint for data on every click taxes the PetPoint service and results in a slower user experience (because of the extra communication that has to happen). See “understanding caching” below for more information.

Tips and hints

Create links directly to specific animals

“id”, the parameter you can include to show details on a specific animal, and “sort” can also be sent as query string parameters (eg: www.yoursite.com/petpresspage/?id=XXXXXXXXX). By including the querystring “id” parameter, you can create links to specific animals, but be aware that such links will only be useful as long as the animal in question is available for adoption.

Using the “heading” shortcode parameter

You may be wondering why you would want to use the “heading” shortcode parameter rather than simply putting a heading on your webpage above the shortcode. The answer is that the “heading” parameter will be shown above the animal lists and not the animal details, giving you additional flexibility in customizing your list pages.

Understanding caching

For best performance, PetPress refreshes the animal data every thirty minutes in the background. To distribute the load on PetPoint, dogs, cats, and other animals are fetched at different times during this thirty-minute window. In order to see when the refreshes will happen (or to force a refresh) I recommend the WP-Crontrol plugin. Administrators, note that the very first background cache will happen approximately thirty minutes from your activating PetPress. If you begin to view animals before this background task is executed, you may see a short delay in your first page load as the cache is built for the first time. 

Interactions with other plug-ins

SEO tools such as Yoast

PetPress generates specific page titles (eg: “Hambone the Dog (Redbone Coonhound)”) for animal detail pages. These page titles may be overwritten by SEO plugins which generate their own page titles. It is recommended that you do not use SEO plugins on the page(s) that use PetPress if they interfere with this plugin’s title generation. SEO plugins may also overwrite the canonical URLs, making it impossible to create Facebook posts for individual animals.

Page caching plugins

PetPress caches animal data in order to maximize the responsiveness (calls to PetPoint are time consuming). If you are having difficulty with your PetPress pages showing the wrong information (eg: listing animals that are no longer available for adoption) and you are using a third party caching system, try excluding the web pages that use PetPress from the list of pages being cached. 

Future Functionality / Roadmap

The current version of PetPress has been heavily tested and should be particularly reliable. Going forward, reliability will continue to be the top priority, though there will be some additional features added in upcoming revisions.

We are looking for feedback by current users of PetPress to help establish the roadmap. If you are a current or prospective user of this plugin, please contact us and let us know about your experience.

Of course, if you really love it, please leave a review on the WordPress.org site, and consider making a donation to support future enhancements. The animals you’ll be helping thank you!

Where to get more help

Airdrie Media would be more than happy to consult on your PetPoint-integrated website project, whether as the primary agency or as a specialist subcontractor. Contact us to learn more.

As far as changes and enhancements go, these fall into three categories:

• Bug fixes are the top priority. Please report any bugs, and these will move to the top of the to-do list. Note, please, that we do use the developer’s definition of bug, rather than the more general “it doesn’t do what I want it to do” !
• Enhancements are extensions of the plug-in functionality to better integrate PetPoint with WordPress. An enhancement will –at least theoretically– improve the user experience for all PetPress users. Please request whatever enhancements you think would make this a better plug-in. If you really want an enhancement, a donation might be just the thing to move your request higher up in the priority queue.
• Customizations are site or shelter-specific changes to the plug-in to fit your particular needs. This may be important to you if your shelter is not using PetPoint is a completely orthodox way. For a fee, Airdrie Media can create a customized version of the plug-in for you to suit your particular needs. Contact us for a free consultation.