Adding Custom Connections to Beaver Themer

Recently I wanted to add some custom connections to Beaver Themer to simplify some template building, but had some issues understanding the documentation (most likely my fault!). I worked it out and figured I could write up a sample of how I went about it in case it breaks the process down a little more clearly.

Let’s imagine we have some custom meta fields that we’ve added to a post type. Of course we can use the standard Post Custom Field property and manually enter the custom field key, but if we plan on doing this a lot- or handing a site off to a client or designer- we might want to have our custom fields pop-up in a nice list.

Beaver Themer's Standard Post Custom Field Option

Beaver Themer’s Standard Post Custom Field Option

If you’re using Pods to handle your custom meta fields, then this can already be taken care of with the free plugin they have available. But if you’re using something like ACF or CMB2, then you probably want a quicker way to show those meta fields.

In our example, we have a few custom meta fields to determine a location, possibly for a business or member. We want to display these fields- address, city, state, country- in a Beaver Themer layout, but we don’t want to have to type in the custom meta key every time.

Here’s the full code:

Hitting the Action

There’s a few main functions and actions at play here, so let’s break them down:

Our Main Function: demo_add_properties()

This is the main container for most everything. Instead of just directly handling all of our business straight when this php loads, we’re wrapping it in a function so that we can call that function at the right moment. Basically we’ve declared a function that has all of our meaty bits, but we don’t want WordPress to actually do anything with all that code, until…

The Big Action: fl_page_data_add_properties

fl_page_data_add_properties is an action hook provided by Beaver Themer. Beaver Themer is smart, and it knows exactly when it wants everything to happen. It gives us this action hook so that we can let it know we have some code we want it to look at, and it’ll look at it at precisely the right moment.

Since we’ve wrapped everything inside of our custom function demo_add_properties(), we can just just use add_action to make sure our code is loaded up when fl_page_data_add_properties is called. This is executed on line 6.

Beaver Themer Functions

So what are the actual functions we’re going to call here? Well there’s three were going to look at that all modify the field connections to display our custom connections.

New Group Heading: FLPageData::add_group()

First we will add a new group heading to the “Insert Connection” dialog, lines 13 -15. We’ll give it the official name of ‘demo_details_group’ but we can display it as “My Custom Fields” by adding the ‘label’ argument. This is technically optional, but included for your benefit.

New Custom Connection: FLPageData::add_post_property()

Next, we’ll add a new choice under our heading by using this FLPageData::add_post_property() function on lines 20 – 25. First, we’ll give it a name- ‘demo_details’. Then it takes a few arguments to get it up and running. Let’s look at each one.

  • 'label' => 'Address' Determines what the property will be named when we see it pop up.
  • 'group' => 'demo_details_group' Determines what group heading it should go under. Since we create our ‘demo_details_group’ earlier, we’ll use that. If you didn’t want to add a new group, feel free to use ‘general’ or one of the other groups.
  • 'type' => array('string') What type of information are we sending back? It could be an image file or a URL but for our case, its just a string of text.
  • 'getter' => 'demo_connection_getter' Now that we’ve declared this field, we need a getter function that’ll “get” all the correct responses for us, which we’ll explain later.
Our Custom Connection

Our Custom Connection

 

New Settings Field: FLPageData::add_post_property_settings_fields()

Now that we’ve added our custom post property, we’ll register a setting for it so that we can pick exactly what meta field- address, city, state, etc- we want to be displayed. You’ll notice a few things going on here.

First, on line 30, we’ve created a little array of all the meta fields we’re using and saved it as $meta_fields. Before the => is the actual key for the meta field. After the => is our nice pretty label for it.

Next, we call our settings field function. On line 43, we tell it which post property this applies to, our custom property named demo_details.

On line 45, we’re going to name our first (and only) setting key. This will function very similar to the stand Post Custom Field setting, where we tell it the key for the meta field we want. The main difference is what happens when we pass that setting a few arguments:

  • 'type' => 'select' Here we say what kind of input we want it to be. In the standard Post Custom Field, the Key is just a text input, you have to type in the name of the key. Here, we’re making it a Select field, so users can select which key from a drop down list.
  • 'label' => 'Select a Field' Give it a pretty name…
  • 'options' => $meta_fields And here we determine what are the options in our dropdown select. This is where we grab our array from line 30.

And here’s what that settings option looks like when it pops up:

Settings Field - A lot easier than looking up meta field keys.

Settings Field – A lot easier than looking up meta field keys.

Our Helper Function

The last little bit of business is actually displaying the data from those custom fields. For that, we’ll use our helper function demo_connection_getter( $settings, $property ) on lines 58 – 66. There’s three things happening here:

  • global $post; No matter where we use this- in a themer layout, or even in a Posts module looping through some posts- we want to access the current post that’s being displayed.
  • if( '' == $settings->key ) return ''; If there’s no key selected yet, don’t crash! Just return an empty string.
  • return get_post_meta($post->ID, $settings->key, true); But the real meat is to use get_post_meta() to access the current post- $post->ID– and grab the key- $settings->key– of the meta field we’ve chosen in our settings.

And that’s it! Add this to your (child) theme’s functions.php file or better yet, create a quick custom plugin to handle it.

Of course this could be infinitely extended to include more settings, different field types, etc. But this covers the basic gist. What other ways could we connect our custom data to Beaver Themer?

Leave a Comment