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’m going to go over how to tweak the template card PHP files in an update safe way. This QuickTip starts off very similar to the other two so if you have already gone over those you have a head start… Before I go on I just 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 your 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, the first thing you need to do is 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/theme/{child-theme}/connections-templates/{slug}
  2. ../wp-content/theme/{parent-theme}/connections-templates/{slug}
  3. ../wp-content/connections-templates/{slug}
  4. ../wp-content/plugins/template-folder/

The connections-templates folder will not actually be in any of these folders. It is not created automatically. This means you need to create the folder before you can upload 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 as 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 look for the file in the connections-templates/{slug} folder in the wp-content folder.

Which folder should you upload it to? Well that depends. If the tweak theme specific tweak, then I recommend adding it to either the child or parent theme. If it is just a general tweak, then I recommend uploading it to the connections-templates/{slug} folder in the wp-content 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, so you will lose any changes you’ve made to those files.

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 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 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 QuickTip.
  • 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 would have to create one from scratch or base it the card.php file. Creating this file from scratch is beyond the scope of this QuickTip.

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

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

Bonus Tip:

Connections also supports loadingtemplate files based on 15 additional contexts. Simply put, templates can loaded based on if you 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-deparment-{deparment}.php
  • card-deparment.php
  • card-{entry-slug}.php
  • card-single.php
  • card.php

This of the possibilities you have in customizing your directory…