A question I get from time to time in the support forums is, “Does Connections support custom fields?” The answer is yes, but no point-and-click interface exists to create them. What does exist is the Custom Fields API. This API allows developers to add custom fields of different types, such as text fields, radio groups, checklist groups, datepicker, slider, and more. In this QuickTip, I’ll walk through how to add a simple text field. Before moving on, the first thing you should do is install the Code Snippets plugin.
Register the Field
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_text_field' );
function cn_register_custom_metabox_and_text_field() {
$atts = array(
'title' => 'Metabox Name', // Change this to a name which applies to your project.
'id' => 'custom_one', // 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', // Change this so it is unique to you project. Each field id MUST be unique.
'type' => 'text', // This is the field type being added.
'size' => 'regular', // This can be changed to one of the following: 'small', 'regular', 'large'
'desc' => 'Text that will display near the field.', // Placement will depend on the field type.
'before' => 'Text that will be displayed before the field.',
'after' => 'Text that will be displayed after the field.',
),
),
);
cnMetaboxAPI::add( $atts );
}
The above code will register a new metabox with a text 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.
If you copy-paste the above code, you must change a few items…
- You should change the function name
cn_register_custom_metabox_and_text_field. Function names should always be unique. If you do not ensure this, you will crash your site. If you do, the Code Snippets plugin has a safe mode that 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
idfromcustom_one. - Lastly, you need to change the field
idfromfield_id
A couple of simple rules should be followed when creating new id names. The names should be in all lowercase, and underscores should be used for spaces.
Lastly, not necessary, but you should change the metabox title and the field name to something applicable to your project.
Display the Custom Field
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 review the latter since that is a bit simpler to implement.
Tip
The custom metabox is automagically compatible with both the Form and Link extensions. The metabox will automatically be immediately available on the Link admin user profile page. You must first turn it on to have the metabox show up in Form. To do this, navigate to the Connections : Settings admin page and click the Form tab. You should see your new custom metabox as an option in the Fieldset section. Add a check to the box, drag it into the position where you wish to display it, and then click the Save Changes button.
Before moving on, you should read how to create custom template override files, as you really should not edit the source 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 will display the field. The custom template override QuickTip gives an example of how to find this file, so to keep this as brief as possible, I will not go over that here.
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:
$text = $entry->getMeta( array( 'key' => 'field_id', // This should match exactly the field id used when registering the custom field. 'single' => TRUE // Do not change this. ) ); if ( ! empty( $text ) ) echo '<p>' . esc_html( $text ) . '</p>';
As you see, there’s not much to add a custom text field.
Export the Field
To have this custom text field exported using the CSV Export Tool, it must be registered. This is done by hooking into the cn_csv_export_fields and cn_csv_export_fields_config filters. The cn_csv_export_fields filter registers the name to be used for the column header in the CSV file, and the cn_csv_export_fields_config filter is the configuration that will be used by the export tool to export the data from the database. Add the following code to your existing code snippet to register the custom text field we just created so it will be exported.
// Register the custom test field CSV Export attributes and processing callback.
add_filter( 'cn_csv_export_fields', 'cn_register_text_field_header' );
add_filter( 'cn_csv_export_fields_config', 'cn_register_text_field_config' );
function cn_register_text_field_header( $fields ) {
// The field_id should match exactly the field id used when registering the custom field.
$fields['field_id'] = 'Header Name';
return $fields;
}
function cn_register_text_field_config( $fields ) {
$fields[] = array(
'field' => 'field_id', // The field_id should match exactly the field id used when registering the custom field.
'type' => 5,
'fields' => '',
'table' => CN_ENTRY_TABLE_META,
'types' => NULL,
);
return $fields;
}
Import the Field
Similarly to exporting the field, the custom field needs to be registered to add support for the CSV Import extension. This can be done with the cncsv_map_import_fields filter and the cncsv_import_fields action. Add the following code to your existing code snippet to register the custom text field we just created so it can be imported.
For CSV Import version 1.4.x and lower.
// Register the custom fields CSV Import mapping options and processing callback.
add_filter( 'cncsv_map_import_fields', 'cncsv_header_name' );
add_action( 'cncsv_import_fields', 'cncsv_process_import', 10, 2 );
function cncsv_header_name( $fields ) {
// The field_id should match exactly the field id used when registering the custom field.
$fields['field_id'] = 'Header Name';
return $fields;
}
function cncsv_process_import( $id, $row ) {
// The field_id should match exactly the field id used when registering the custom field.
$data = isset( $row->field_id ) ? cnFormatting::maybeJSONdecode( stripslashes( $row->field_id ) ) : '';
cnEntry_Action::meta(
'update',
$id,
array(
array(
'key' => 'field_id', // The field_id should match exactly the field id used when registering the custom field.
'value' => $data
),
)
);
}
For CSV Import version 2.1 and higher.
// Register the custom fields CSV Import mapping options and processing callback.
add_filter( 'cncsv_map_import_fields', 'cncsv_header_name' );
add_action( 'cncsv_import_fields', 'cncsv_process_import', 10, 3 );
function cncsv_header_name( $fields ) {
// The field_id should match exactly the field id used when registering the custom field.
$fields['field_id'] = 'Header Name';
return $fields;
}
function cncsv_process_import( $id, $row, $entry ) {
$data = array();
if ( $entry->arrayKeyExists( $row, 'field_id' ) ) {
// The field_id should match exactly the field id used when registering the custom field.
$value = $entry->arrayPull( $row, 'field_id', '' );
$value = cnFormatting::maybeJSONdecode( stripslashes( $value ) );
$data[] = array(
'key' => 'field_id',
'value' => $value,
);
}
if ( 0 < count( $data ) ) {
cnEntry_Action::meta( 'update', $id, $data );
}
}
Related QuickTips: