Introduction
When we built this site, we envisioned the code snippet area to be a reference resource for experienced Formidable developers. However, as this site grows, we are making adjustments for a broader audience. Keep asking your questions. We appreciate it!
If you need help with a code snippet that you found on this site, let us know. Who knows? It could become the subject of the revision required to promote another code snippet to tutorial as this post demonstrates.
If you enjoy this tutorial, please thank Formidable Masterminds Facebook Group member Ana Krček Tvrdeić for asking the question.
To fully grasp the use of this shortcode, or any shortcode for that matter, you first have to understand its basics and the parameters it is designed to receive.
This is a typical WordPress shortcode. We are adding an execution request to provide a handler function to the WordPress Shortcode API. We use the add_shortcode() hook. This execution is found at line 3 in the source.
Shortcode Basics
add_shortcode() takes two parameters, the name you want to use for your shortcode, and the name of your custom handler function. In this snippet, the name of the shortcode is count_entries and the custom handler function is fm_count_entry_records( $atts ) declared at line 4. The parameter $atts is an array that our function receives from the WordPress Shortcode API every time the shortcode is run through some form of user access.
This array of attributes ($atts) is defined in the WordPress Shortcode API. In this snippet, the attributes are the parameters your shortcode can receive because it passes through to your custom function. Using an array like this to communicate with the API is really smart. You can pass as many parameters to your shortcode as your handler function needs to achieve your result.
Formidable Integration
Because our handler function integrates with Formidable, you need to be familiar with Formidable's variety of public functions and hooks. The first place to start though is Formidable's database schema. It's like learning the ABCs.
Formidable uses five tables in your WordPress database. Formidable plugins are their lone users. As developers, we believe this is one of Formidable's strengths. These tables are open to developers that understand Formidable's many development hooks.
Usage
This shortcode is used to count known entry values for a specific field and then display those values in the browser. The shortcode runs a PHP function on the server.
It does not count fields that have no values, nor does it count unknown values that need to be passed as a parameter in real time from an active form entry through Ajax.
Three parameters are defined in our handler function, but you can only send two to execute the shortcode. The first that you send is field_id OR field_key; and the second is the value you want the system to search for in the database.
We access the database and execute the count through built-in WordPress and Formidable functions. Those developers have already done the hard work and by providing public access, they help everyone become better developers themselves.
You can always write your own custom SQL, if you'd like. Especially, if you love debugging and walking through what can sometimes be difficult challenges. And you may end up writing code anyway in case you receive unexpected results when testing built-in functions.
Here are the basic usages:
Usage 1: [count_entries field_id='153' field_value='Class']
Usage 2: [count_entries field_key='codex_type' field_value='Class']
In the first usage, we are passing a field_id and field_value through the shortcode to the handler function. In the second, we pass field_key instead of field_id. These two attributes are essential to Formidable's Core. They exist for multiple Formidable entities. Knowing the difference and when to use one over the other is important. Our recommendation is to get accustomed to referencing keys in your custom code wherever possible.
This pretty much ends the tutorial. The source code is below. We've added comments to clarify a few steps. Use it on your site, pass it around, or modify it for your own purposes.
We haven't tested this in a view, because we only display it on the front end within a post or page. If you try this in a view and it works, please let us know your result in the comments.
Source Code
You do not have to modify the handler function source code to receive a proper count for your search value. All data values are passed to this shortcode as parameters. See basic usages above.
Hi Victor
Thanks for this snippet (Count Entries shortcode); it works perfectly as written if I call it with a specific field value (eg. field_value=’Class’ from your example). What I’m trying to achieve however is to count the number of times (in a text field) that the same text value has been entered in the form, based on calling the shortcode with the relevant field ID so that it counts the number of entries that contain the text value currently in that field.
Something like [count_entries field_id=’153′ field_value='[153]’].
What I’m really trying to achieve is to set a limit on the number of times a specific value can be entered and raise an error when the threshold is reached. I’ve searched through the FF KB and slack community and tried but no luck as yet. Sorry if I’m asking for too much; any tips greatly appreciated.
Cheers Paul
This shortcode was never designed to meet your requirement. It provides a count of existing known values. What you want to do requires a different approach and perhaps Ajax to launch the SQL to return the count to the front end in real time. You didn’t say this, but I’m assuming you want to check the count of a value as it is entered on the front end. Is that correct? If so, that’s a custom job. The SQL would be about the same as that in this shortcode, but passing the value to be counted and returning that count to a field validation requires the Ajax.
We’re happy to discuss this with you if you have a budget and want to start with our Project Application.
Thanks very much for your reply Victor.
Your assumption is correct, I do want to check the count of a value as it is entered on the front end.
I’ll have a go at coding this but will get back to you with a project application if I get stuck.
Cheers
Paul