How to build your own theme compatibility plugin

The GD core plugin now has a theme compatibility section where you can build any special settings for any theme.
The information below is not required anymore to make your theme compatible, but still contains useful information, so we have not deleted it.

GeoDirectory will integrate nicely into many themes, but there are occasions where things appear to be out of place. This is usually because your theme has declared extra content areas which GD doesn’t recognise, or because your theme’s css rules are overriding those declared by GeoDirectory.

The best way to address these issues is to build a compatibility plugin to modify the behaviour of GeoDirectory and force it to output content into your desired areas.

This isn’t as scary as it sounds, so let’s walk through the process…

Requirements for this project

For this project you will need a text editor to write your code and an FTP program to upload the files to your website. It doesn’t matter which programs you use, but my preferences are Sublime Text and FileZilla

Step 1 – Creating the plugin

All the files you will be creating will be stored in a folder, so let’s create that first. For the purpose of this tutorial i’ve named the folder my-gd-plugin. Now open up your favourite text editor and create a new file within your new folder called mygdplugin.php (you can use your own name, but make sure to save it as a .php file)

Add the following to your new file:

https://gist.github.com/PoshJohn/fe8d902f9e0097e5a3d7

Congratulations – you’ve just created your first plugin! Now let’s make it actually do something…

Step 2 – Adding & Removing Actions

What we will be trying to do here is remove the actions that GeoDirectory uses to output the HTML wrappers of the main content and sidebar areas, and replace them with new ones we create.

GeoDirectory template files are a series of action hooks which run functions. We can change the behaviour of the plugin’s output by “unhooking” functions from their positions, and replacing them with our own functions.

Consider the steps necessary when you make yourself a coffee:

  1. Add coffee powder to cup
  2. Add boiling water to cup
  3. Add milk to cup
  4. Add sugar to cup
  5. Stir.

What if you wanted a black coffee? You would remove action number 3. If you fancied a hot chocolate you would remove action 1 and add a new action in it’s place (1. Add chocolate powder to cup)

This is exactly what we are going to be doing with our plugin.

Depending on the complexity of your theme, there may be many actions you need to look at. For the purposes of this tutorial we will look at the main three elements:

  1. The outer wrapper which contains both the content and sidebar areas
  2. The wrapper which contains the content area
  3. The wrapper which contains the sidebar

Here are the actions we will be replacing.

https://gist.github.com/PoshJohn/37460fa990f836bb768a

So what is happening here? Let’s take the first remove/add example:

We are saying in hook position geodir_wrapper_open remove the function geodir_action_wrapper_open and replace it with a new function called geodir_mytheme_action_wrapper_open

This means that every time a GeoDirectory template gets to that hook position, it will run our function instead of the in-built function. You can give your functions any name you like, as long as you use the same names in the next step.
I typically use the original function name and add the name of my theme into it
e.g. : geodir_action_wrapper_open becomes geodir_mytheme_action_wrapper_open

Step 3 – Adding Our New Functions

At this stage our plugin won’t work because we are telling GeoDirectory to run functions that don’t exist – so let’s start creating them!

Taking the first example again, let’s build the function to replace the output wrapper of the main content/sidebar area.
We told GeoDirectory to run a function called geodir_mytheme_action_wrapper_open, so let’s create that function now.

https://gist.github.com/PoshJohn/f32f2c7f7414f3db05d9

We simply need to continue that process for our remaining functions. Here is the finished plugin which replaces the output wrappers of the 3 main elements:

https://gist.github.com/PoshJohn/e83a32f3cfbcec4b91d4

Step 4 – Styling The Elements

Since you will be creating this plugin to work with a specific theme, it doesn’t really make sense to load a new stylesheet. Styles therefore will be added to your theme’s style.css file as usual. For helpful tips on styling, take a look at this post on customising your style.

Important Things To Note

When we replace a function, it is important to note the structure of the original function. Did you notice the numbers at the end of the actions? The first number is the priority of the action and the second is the number of arguments passed. These should stay the same as the original function in most cases.

For more information on actions & functions, a great place to start is the WordPress Codex:

Conclusion

Congratulations on building your first GeoDirectory compatibility plugin!

There are many other functions that can be overridden, plus filters that can be utilised to modify the output of existing functions.

For working examples of these, you can download one of the existing compatibility plugins.

Hopefully the information provided in this tutorial will enable you to seamlessly integrate GeoDirectory into your theme. If however you are overwhelmed and would rather have someone else create the plugin for you, I am available for a small fee. Please feel free to contact me for a quote.