QuickTip: Custom Field – Add a Checkbox Group

This is the third post in a series on how to add a checkbox group custom field to Connections. You should review these posts on how to add a custom text field and how to add a checkbox custom field before this one as this post will build upon them. I’m sure you’ll notice much of this is the same as the previous two tutorials, just tweaked to reflect the settings required to render a checkbox group and how to display it.

Before moving on, the first thing you should do is install the Code Snippets plugin. After you install the Code Snippets plugin add a new snippet with the following code:

// Register the metabox and fields.
add_action( 'cn_metabox', 'cn_register_custom_metabox_and_checkboxgroup_field' );
 
function cn_register_custom_metabox_and_checkboxgroup_field() {
 
    $atts = array(
        'title'    => 'Metabox Name', // Change this to a name which applies to your project.
        'id'       => 'custom_three', // Change this so it is unique to you project.
        'context'  => 'normal',
        'priority' => 'core',
        'fields'   => array(
            array(
                'name'       => 'Field Name',     // Change this field name to something which applies to you project.
                'show_label' => TRUE,             // Whether or not to display the 'name'. Changing it to false will suppress the name.
                'id'         => 'field_id_three', // Change this so it is unique to you project. Each field id MUST be unique.
                'type'       => 'checkboxgroup',  // This is the field type being added.
                'options'    => array(
                    'one'   => 'One',
                    'two'   => 'Two',
                    'three' => 'Three',
                    'four'  => 'Four',
                    'five'  => 'Fix',
                    'six'   => 'Six',
                ),
                'default'    => 'three', // This is the default selected option. Leave blank for none.
            ),
        ),
    );
 
    cnMetaboxAPI::add( $atts );
}

The above bit of code will register a new metabox with a checkbox field. This new field will now display when you add/edit your entries. It will also be displayed in the Form extension and on the Link extension admin profile page. A few things to note from the post on how to add a custom text field that are worth repeating:

• You should change the function name cn_register_custom_metabox_and_checkboxgroup_field. Function names should always be unique. If you do not make sure of this, you will crash your site. (If you do crash your site, the Code Snippets plugin has a safe mode which can be enabled so you can fix it. Read the Code Snippets FAQ on how to enable safe mode if you need to.)
• You need to change the metabox id from custom_three.
• Lastly you need to change the field id from field_id_three.
• When creating the new id names. The names should be in all lowercase and underscores should be used for spaces.
• Lastly, but not necessary, you should change the metabox title and the field name to something that is applicable to your project.

That’s all it takes to add a field but there is more to do to display the field. There are two ways in which you can do this. One is to register a content block that outputs the data entered in the custom field. The other is to add a few lines to a template to display it. I’ll go over the latter since that is a bit simpler to implement.

Before moving on, you should go and read how to create custom template override files as you really should not edit the actual template file because any changes to those files will be lost when WordPress updates the plugin. That said, displaying the field in a template requires you to open the template’s card.php file. The exact path to the file will depend on the template you are going to display the field. The custom template override QuickTip give an example on how to find this file. To keep this brief as possible I am not going to go over that here.

Displaying a checkbox group in the template is a bit different because you must iterate thru each option in the checkbox group to determine if it was selected or not before displaying the option. Open the card.php of the template of your choice and add the following code to where you want the custom field data to display:

$group = $entry->getMeta(
    array(
        'key' => 'field_id_three', // This should match exactly the field id used when registering the custom field.
        'single' => TRUE           // Do not change this.
    )
);
 
if ( ! empty( $group ) ) {
 
    echo '<ul>';
 
    foreach ( $group as $option ) {
 
        printf( '<li>%1$s</li>', esc_html( $option ) );
    }
 
    echo '</ul>';
}

Related QuickTips:

• Custom Field – Add a Text Field
• Custom Field – Add a Checkbox
• Tweaking Core Templates
• Custom Template Override Files
• CSV Import Custom Meta Fields