QuickTip: Custom Template Override Files

Connections was built from the ground up for tweaking… I’ve already covered how to create Custom CSS files and Custom Template CSS files. Now, I will go over how to tweak the template card PHP files in an update-safe way. This QuickTip starts very similarly to the other two, so if you have already gone over those, you have a head start… Before I go on, I want to mention that this technique can be used with any Connections templates.

The first thing you need to know is the template slug of the template you are going to tweak. You can find the template slug on the Connections : Templates admin page. The template slug will be shown in the Template Override section of the template description. See the screen capture below. The template slug for cMap would be “cmap” without the quotes.

Connections : Templates - Template Description

Now that you’ve identified the template’s slug, you first need to decide where you want to upload because you have several options on where to upload the file. These options are, in order of priority:

  1. ../wp-content/themes/{child-theme}/connections-templates/{slug}
  2. ../wp-content/themes/{parent-theme}/connections-templates/{slug}
  3. ../wp-content/uploads/connections-templates/{slug}
  4. ../wp-content/plugins/template-folder/

The connections-templates folder will not be in any of these folders. It is not created automatically. This means you must create the folder before uploading the file. The {slug} in the folder paths listed above would be replaced with the template’s slug. After creating the connections-templates, you would create a new folder within it named the template’s slug.

Connections will load the file based on priority; basically, this means; first, it’ll look for the file in the connections-templates/{slug} folder of the active child theme. If it is not found there, then it’ll look for the file in the connections-templates/{slug} folder in the activate parent theme. Finally, it looks for the file in the connections-templates/{slug} folder in the wp-content/uploads folder.

Which folder should you upload it to? Well, that depends. If the tweak theme is specific, I recommend adding it to either the child or parent theme. If it is just a general tweak, I recommend uploading it to the connections-templates/{slug} folder in the wp-content/uploads folder.

You should never edit the files in or save files to the ../wp-content/plugins/connections/templates/{template-folder}/ because those files will be deleted during an update by WordPress, and you will lose any changes you’ve made.

Now that you know the slug of the template you want to tweak and where to upload the files, let’s dig in… Connections will search for two specific files depending on if the directory result list is being shown or the single entry /detail view.

  • When displaying the directory results list, Connections will search for the card.php in the above paths of the template being used and load it. NOTE: All the premium templates come with a card.php file, but most of the free templates do not, so you would have to create one from scratch, which is beyond the scope of this article.
  • When displaying a single entry /detail view, Connections will search for the card-single.php in the above paths of the template being used and load it. NOTE: Not all templates will include this file, so you must create one from scratch or base it on the card.php file. Creating this file from scratch is beyond the scope of this article.

Create a copy of the card.php and/or card-single.php file and upload it to one of the above folders.

Now you can tweak away, and any changes you make will be update-safe!

Bonus Tip:

Connections also supports loading template files based on 15 additional contexts. Simply put, templates can be loaded based on if you are viewing a specific category or specific region or specific entry, and so on. Here’s the rundown of template files that are supported:

  • card-category-{category-slug}.php
  • card-category.php
  • card-country-{country}.php
  • card-country.php
  • card-region-{region}.php
  • card-region.php
  • card-postal-{postal-code}.php
  • card-postal.php
  • card-locality-{locality}.php
  • card-locality.php
  • card-organization-{organization}.php
  • card-organization.php
  • card-department-{deparment}.php
  • card-deparment.php
  • card-{entry-slug}.php
  • card-single.php
  • card.php

This is one of the possibilities you have in customizing your directory…