How to create columns with PHP – Developer guide

WP Sheet Editor is a powerful WordPress plugin that allows you to manage your WordPress content in a spreadsheet-like interface. One of its most powerful features is the ability to register custom columns to display and edit any type of data. This comprehensive guide will walk you through all the available column types, parameters, and provide complete examples for each type.

Whether you’re working with custom post meta, taxonomy terms, or complex data relationships, WP Sheet Editor’s column system provides the flexibility to create exactly the interface you need. From simple text fields to complex multi-select dropdowns with AJAX loading, this guide covers everything you need to know.

Column Registration Parameters

Before diving into specific column types, it’s essential to understand all the available parameters for column registration. Each parameter controls different aspects of how the column behaves, appears, and interacts with users.

Core Parameters

Display and Formatting Parameters

Visibility Control Parameters

Feature Control Parameters

Formula Parameters

Callback Parameters

Advanced Parameters

Basic Column Types

Text Column

Text columns are the most basic type, perfect for storing simple text data like names, descriptions, or custom identifiers.

$editor->args['columns']->register_item(
'_custom_text_field',
$post_type,
array(
'data_type'         => 'meta_data',
'column_width'      => 200,
'title'             => 'Text Field',
'supports_formulas' => true,
'value_type'        => 'text',
)
);

Numeric Column

Numeric columns are optimized for numbers and support mathematical formulas and calculations.

$editor->args['columns']->register_item(
'_custom_number_field',
$post_type,
array(
'data_type'         => 'meta_data',
'column_width'      => 100,
'title'             => 'Number Field',
'supports_formulas' => true,
'value_type'        => 'number',
)
);

Interactive Column Types

Checkbox Column

Checkbox columns provide a simple yes/no or true/false interface with customizable checked and unchecked values.

$editor->args['columns']->register_item(
'_custom_checkbox_field',
$post_type,
array(
'data_type'         => 'meta_data',
'column_width'      => 100,
'title'             => 'Checkbox Field',
'supports_formulas' => true,
'formatted'         => array(
'type'              => 'checkbox',
'checkedTemplate'   => 'yes',
'uncheckedTemplate' => 'no',
),
'default_value'     => 'no',
)
);

Single Select Column

Single select columns provide a dropdown interface for choosing one option from a predefined list.

$editor->args['columns']->register_item(
'_custom_select_field',
$post_type,
array(
'data_type'         => 'meta_data',
'column_width'      => 150,
'title'             => 'Select Field',
'supports_formulas' => true,
'formatted'         => array(
'editor'        => 'select',
'selectOptions' => array(
'option1' => 'Option 1',
'option2' => 'Option 2',
'option3' => 'Option 3',
),
),
'default_value'     => 'option1',
)
);

Multi Select Column (Static Options)

Multi select columns allow users to choose multiple options from a predefined list. This version uses static options defined in the column configuration.

$editor->args['columns']->register_item(
'_custom_multiselect_field',
$post_type,
array(
'data_type'             => 'meta_data',
'column_width'          => 200,
'title'                 => 'Multi Select Field',
'supports_formulas'     => true,
'supports_sql_formulas' => false,
'allow_plain_text'      => true,
'list_separation_character' => ',',
'formatted'             => array(
'editor'        => 'wp_chosen',
'selectOptions' => array(
'option1' => 'Option 1',
'option2' => 'Option 2',
'option3' => 'Option 3',
'option4' => 'Option 4',
),
'chosenOptions' => array(
'multiple' => true,
'search_contains' => true,
),
),
)
);

Multi Select Column (AJAX Options)

This version of multi select uses AJAX to load options dynamically, perfect for large datasets like taxonomy terms or user lists. The ajaxParams contains the parameters to be sent in the wp ajax request that your php ajax handler will use to return the values.

$editor->args['columns']->register_item(
'_custom_ajax_multiselect_field',
$post_type,
array(
'data_type'             => 'meta_data',
'column_width'          => 200,
'title'                 => 'AJAX Multi Select',
'supports_formulas'     => true,
'supports_sql_formulas' => false,
'allow_plain_text'      => true,
'list_separation_character' => ',',
'formatted'         => array(
'editor'        => 'wp_chosen',
'selectOptions' => array(),
'chosenOptions' => array(
'multiple'        => true,
'search_contains' => true,
'create_option'   => true,
'skip_no_results' => true,
'persistent_create_option' => true,
'data'            => array(),
'ajaxParams'      => array(
'action'       => 'vgse_get_taxonomy_terms',
'taxonomy_key' => 'category',
),
),
),
)
);

Media and File Column Types

Single File Upload Column

Single file upload columns provide an interface for uploading and managing a single file attachment.

$editor->args['columns']->register_item(
'_custom_file_field',
$post_type,
array(
'data_type'         => 'meta_data',
'column_width'      => 250,
'title'             => 'File Upload',
'supports_formulas' => true,
'type'              => 'boton_gallery',
)
);

Multiple File Upload Column

Multiple file upload columns allow users to upload and manage multiple file attachments in a single field.

$editor->args['columns']->register_item(
'_custom_files_field',
$post_type,
array(
'data_type'         => 'meta_data',
'column_width'      => 300,
'title'             => 'Multiple Files',
'supports_formulas' => true,
'type'              => 'boton_gallery_multiple',
)
);

Rich Content Column Types

TinyMCE Editor Column

TinyMCE editor columns provide a rich text editing interface with full WordPress editor capabilities.

$editor->args['columns']->register_item(
'_custom_content_field',
$post_type,
array(
'data_type'         => 'meta_data',
'column_width'      => 300,
'title'             => 'Content Editor',
'supports_formulas' => true,
'formatted'         => array(
'renderer'          => 'wp_tinymce',
'wpse_template_key' => 'tinymce_cell_template',
),
)
);

Special Purpose Column Types

External Button Column

External button columns create clickable buttons that can trigger custom actions or navigation.

$editor->args['columns']->register_item(
'view_post_custom',
$post_type,
array(
'data_type'          => 'post_data',
'title'              => 'View Custom Post',
'supports_formulas'  => false,
'type'               => 'external_button',
'formatted'          => array(
'renderer' => 'wp_external_button',
'readOnly' => true,
),
'allow_to_save'      => false,
'get_value_callback' => 'get_custom_post_url_for_column',
'allow_to_import'    => false,
)
);

Custom Calculated Field Column

This column type uses a custom callback to calculate values based on other post data or complex logic. Refer to the “custom callbacks” section below for examples related to the parameter get_value_callback and save_value_callback.

$editor->args['columns']->register_item(
'_custom_calculated_field',
$post_type,
array(
'data_type'          => 'meta_data',
'column_width'       => 150,
'title'              => 'Custom Calculated Field',
'supports_formulas'  => true,
'get_value_callback' => 'calculate_custom_field_value',
)
);

Custom Save Processing Column

This column type uses a custom callback to process data before saving, allowing for data transformation or validation.

$editor->args['columns']->register_item(
'_custom_processed_field',
$post_type,
array(
'data_type'             => 'meta_data',
'column_width'          => 200,
'title'                 => 'Processed Field',
'supports_formulas'     => true,
'supports_sql_formulas' => false,
'save_value_callback'   => 'process_custom_field_value',
)
);

Advanced Column Types

Linked Items Column

This advanced column type demonstrates how to handle related data with custom display and database preparation functions.

$editor->args['columns']->register_item(
'_custom_linked_field',
$post_type,
array(
'data_type'                  => 'meta_data',
'column_width'               => 200,
'title'                      => 'Linked Items',
'supports_formulas'          => true,
'supports_sql_formulas'      => false,
'prepare_value_for_display'  => 'prepare_linked_items_for_display',
'prepare_value_for_database' => 'prepare_linked_items_for_database',
'list_separation_character'  => ',',
'formatted'                  => array(
'comment' => array('value' => 'Enter multiple IDs separated by commas'),
),
)
);

Locked Column

Locked columns are read-only and display a lock icon to indicate they cannot be edited by users.

$editor->args['columns']->register_item(
'_locked_field',
$post_type,
array(
'data_type'         => 'meta_data',
'column_width'      => 150,
'title'             => 'Locked Field',
'supports_formulas' => true,
'is_locked'         => true,
'allow_to_save'     => false,
)
);

Role-Restricted Column

This column type demonstrates how to restrict access based on user capabilities, allowing fine-grained permission control.

$editor->args['columns']->register_item(
'_restricted_field',
$post_type,
array(
'data_type'         => 'meta_data',
'column_width'      => 150,
'title'             => 'Restricted Field',
'supports_formulas' => true,
'user_capabilities_can_read' => array('edit_others_posts'),
'user_capabilities_can_edit' => array('manage_options'),
)
);

Callback Functions

Here are the essential callback functions used in the examples above. These demonstrate how to implement custom logic for data retrieval, processing, and transformation.

Get Value Callback

function get_custom_post_url_for_column($post, $cell_key, $cell_args) {
return get_permalink($post->ID);
}

Calculate Value Callback

function calculate_custom_field_value($post, $cell_key, $cell_args) {
// Custom logic to calculate value
$meta_value = get_post_meta($post->ID, '_another_field', true);
return $meta_value ? $meta_value * 2 : 0;
}

Save Value Callback

function process_custom_field_value($post_id, $cell_key, $data_to_save, $post_type, $cell_args, $spreadsheet_columns) {
// Custom logic to process value before saving
return sanitize_text_field($data_to_save);
}

Display Preparation Callback

function prepare_linked_items_for_display($value, $post, $key, $column_settings) {
if (!empty($value) && is_array($value)) {
$values = array_filter($value);
return implode(', ', $values);
}
return '';
}

Database Preparation Callback

function prepare_linked_items_for_database($post_id, $cell_key, $data_to_save, $post_type, $cell_args, $spreadsheet_columns) {
$items = array_map('trim', explode(',', wp_unslash($data_to_save)));
$ids = array();
foreach ($items as $item) {
if (is_numeric($item) && get_post_status($item)) {
$ids[] = (int) $item;
}
}
return $ids;
}

Complete Registration Function

Here’s how to put it all together in a complete registration function:

add_action('vg_sheet_editor/editor/register_columns', 'register_custom_columns');
function register_custom_columns($editor) {
$post_types = $editor->args['enabled_post_types'];
foreach ($post_types as $post_type) {
// Register all your custom columns here
// ... (column registration code from examples above)
}
}

This comprehensive guide provides you with all the tools and knowledge needed to create powerful, custom columns in WP Sheet Editor. Whether you need simple text fields or complex interactive elements, these examples and parameter explanations will help you build exactly what your project requires.