Custom Fields API

The Custom Fields API allows developers to programmatically create, manage, and integrate custom fields into ShahiAssist tickets and knowledge base articles.

Overview

Custom fields extend the default form fields, allowing you to collect specific information from users. The API provides methods to define field types, validation rules, and display options.

Basic Usage

Registering Custom Fields

Use the shahiassistcustom_fields filter to add fields:
`php
addfilter(‘shahiassistcustomfields’, function($fields) {
$fields[] = [
‘id’ => ‘product_version’,
‘label’ => ‘Product Version’,
‘type’ => ‘text’,
‘required’ => true,
‘context’ => ‘ticket’, // or ‘kb’
‘help’ => ‘Enter the version number (e.g., 1.2.3)’,
];

return $fields;
});
`

Field Types

Text Field

`php
[
‘id’ => ‘text_field’,
‘label’ => ‘Text Field’,
‘type’ => ‘text’,
‘placeholder’ => ‘Enter text here’,
‘maxlength’ => 100,
]
`

Textarea

`php
[
‘id’ => ‘description’,
‘label’ => ‘Description’,
‘type’ => ‘textarea’,
‘rows’ => 4,
‘placeholder’ => ‘Detailed description’,
]
`

Select Dropdown

`php
[
‘id’ => ‘priority’,
‘label’ => ‘Priority’,
‘type’ => ‘select’,
‘options’ => [
‘low’ => ‘Low’,
‘medium’ => ‘Medium’,
‘high’ => ‘High’,
‘urgent’ => ‘Urgent’,
],
‘default’ => ‘medium’,
]
`

Radio Buttons

`php
[
‘id’ => ‘contact_method’,
‘label’ => ‘Preferred Contact Method’,
‘type’ => ‘radio’,
‘options’ => [
’email’ => ‘Email’,
‘phone’ => ‘Phone’,
‘chat’ => ‘Live Chat’,
],
]
`

Checkboxes

`php
[
‘id’ => ‘features’,
‘label’ => ‘Features Used’,
‘type’ => ‘checkbox’,
‘options’ => [
‘feature_a’ => ‘Feature A’,
‘feature_b’ => ‘Feature B’,
‘feature_c’ => ‘Feature C’,
],
]
`

Date Picker

`php
[
‘id’ => ‘due_date’,
‘label’ => ‘Due Date’,
‘type’ => ‘date’,
‘min’ => date(‘Y-m-d’), // Today’s date
‘max’ => date(‘Y-m-d’, strtotime(‘+1 year’)),
]
`

Number Field

`php
[
‘id’ => ‘quantity’,
‘label’ => ‘Quantity’,
‘type’ => ‘number’,
‘min’ => 1,
‘max’ => 100,
‘step’ => 1,
]
`

Field Configuration Options

Common Options

1. id: Unique identifier (required)
2. label: Display label (required)
3. type: Field type (required)
4. required: Boolean, makes field mandatory
5. help: Help text or tooltip
6. placeholder: Placeholder text
7. default: Default value
8. context: ‘ticket’ or ‘kb’ (default: ‘ticket’)
9. position: Display order (numeric)

Validation Options


10. minlength: Minimum length for text fields
11. maxlength: Maximum length for text fields
12. pattern: Regex pattern for validation
13. custom_validation: Custom validation function

Display Options


14. class: Additional CSS classes
15. style: Inline CSS styles
16. wrapper_class: CSS class for field wrapper
17. showinadmin: Show in admin interface
18. showinfrontend: Show in frontend forms

Advanced Field Types


Conditional Fields


Show fields based on other field values:
`php
[
‘id’ => ‘escalation_reason’,
‘label’ => ‘Escalation Reason’,
‘type’ => ‘textarea’,
‘condition’ => [
‘field’ => ‘priority’,
‘operator’ => ‘equals’,
‘value’ => ‘urgent’,
],
]
`

Dynamic Options


Load options from database or API:
`php
[
‘id’ => ‘assigned_agent’,
‘label’ => ‘Assigned Agent’,
‘type’ => ‘select’,
‘optionscallback’ => ‘getavailable_agents’,
]

function getavailableagents() {
$agents = getusers([‘role’ => ‘supportagent’]);
$options = [];
foreach ($agents as $agent) {
$options[$agent->ID] = $agent->display_name;
}
return $options;
}
`

File Upload Field


`php
[
‘id’ => ‘attachments’,
‘label’ => ‘Attachments’,
‘type’ => ‘file’,
‘multiple’ => true,
‘allowed_types’ => [‘jpg’, ‘png’, ‘pdf’],
‘max_size’ => 5 1024 1024, // 5MB
]
`

Validation and Sanitization


Built-in Validation


ShahiAssist automatically validates fields based on type and options. For custom validation:
`php
addfilter(‘shahiassistvalidatecustomfield’, function($isvalid, $fieldid, $value, $fieldconfig) {
if ($fieldid === ‘customfield’) {
// Custom validation logic
if (empty($value) || strlen($value) < 5) { return new WPError(‘invalidvalue’, ‘Value must be at least 5 characters’);
}
}
return $is_valid;
}, 10, 4);
`

Sanitization


Values are automatically sanitized. For custom sanitization:
`php
addfilter(‘shahiassistsanitizecustomfield’, function($value, $fieldid) {
if ($fieldid === ‘customhtml’) {
return wp_kses($value, [‘strong’ => [], ’em’ => []]);
}
return $value;
}, 10, 2);
`

Displaying Field Values


In Templates


Access field values in custom templates:
`php
$customfields = getpostmeta($postid, ‘shahiassistcustomfields’, true);
if ($custom_fields) {
foreach ($customfields as $fieldid => $value) {
echo ‘

‘;
echo ‘‘ . eschtml(getfieldlabel($fieldid)) . ‘: ‘;
echo esc_html($value);
echo ‘

‘;
}
}
`

In Admin Columns


Add custom fields to admin list tables:
`php
addfilter(‘manageticketpostscolumns’, function($columns) {
$columns[‘priority’] = ‘Priority’;
return $columns;
});

addaction(‘manageticketpostscustomcolumn’, function($column, $postid) {
if ($column === ‘priority’) {
$priority = getpostmeta($postid, ‘shahiassistcustom_fields’, true);
echo esc_html($priority[‘priority’] ?? ‘Not set’);
}
}, 10, 2);
`

Saving and Updating Fields


Programmatic Saving


`php
function savecustomfield($postid, $fieldid, $value) {
$customfields = getpostmeta($postid, ‘shahiassistcustomfields’, true) ?: [];
$customfields[$fieldid] = $value;
updatepostmeta($postid, ‘shahiassistcustomfields’, $customfields);
}
`

AJAX Updates


Handle dynamic field updates:
`php
addaction(‘wpajaxupdatecustom_field’, function() {
$postid = intval($POST[‘post_id’]);
$fieldid = sanitizekey($POST[‘fieldid’]);
$value = sanitizetextfield($_POST[‘value’]);

savecustomfield($postid, $fieldid, $value);

wpsendjson_success();
});
`

Integration with Other Systems


CRM Integration


Sync custom fields with CRM:
`php
addaction(‘shahiassistticketcreated’, function($ticket_id) {
$customfields = getpostmeta($ticketid, ‘shahiassistcustomfields’, true);

// Send to CRM API
wpremotepost(‘https://crm.example.com/api/tickets’, [
‘body’ => [
‘title’ => getthetitle($ticket_id),
‘customfields’ => $customfields,
]
]);
});
`

Email Integration


Include custom fields in notifications:
`php
addfilter(‘shahiassistemailcontent’, function($content, $type) {
if ($type === ‘ticket_created’) {
global $post;
$customfields = getpostmeta($post->ID, ‘shahiassistcustom_fields’, true);

if ($custom_fields) {
$content .= “\n\nCustom Fields:\n”;
foreach ($customfields as $fieldid => $value) {
$content .= ucfirst($field_id) . ‘: ‘ . $value . “\n”;
}
}
}
return $content;
}, 10, 2);
`

Performance Considerations


Caching Field Data


Cache frequently accessed field configurations:
`php
function getcachedcustom_fields() {
$cachekey = ‘shahiassistcustomfields’;
$fields = wpcacheget($cache_key);

if ($fields === false) {
$fields = applyfilters(‘shahiassistcustomfields’, []);
wpcacheset($cachekey, $fields, ”, HOURIN_SECONDS);
}

return $fields;
}
`

Lazy Loading


Load field options only when needed:
`php
addfilter(‘shahiassistcustomfields’, function($fields) {
$fields[] = [
‘id’ => ‘lazy_select’,
‘label’ => ‘Lazy Select’,
‘type’ => ‘select’,
‘options’ => ‘getlazyoptions’, // Function name as string
];
return $fields;
});

function getlazyoptions() {
// Expensive operation here
return [‘option1’ => ‘Option 1’, ‘option2’ => ‘Option 2’];
}
`

Security Best Practices


Input Validation


Always validate user input:
`php
addfilter(‘shahiassistvalidatecustomfield’, function($isvalid, $field_id, $value) {
if ($field_id === ’email’) {
if (!is_email($value)) {
return new WPError(‘invalidemail’, ‘Please enter a valid email address’);
}
}
return $is_valid;
}, 10, 3);
`

Permission Checks


Ensure users can only edit allowed fields:
`php
addfilter(‘shahiassistcaneditcustomfield’, function($canedit, $fieldid, $user_id) {
if ($fieldid === ‘adminonly’ && !currentusercan(‘manage_options’)) {
return false;
}
return $can_edit;
}, 10, 3);
`

XSS Prevention


Sanitize all output:
`php
function displaycustomfield($fieldid, $postid) {
$value = getpostmeta($postid, ‘shahiassistcustomfields’, true)[$fieldid] ?? ”;
echo wp_kses($value, [‘strong’ => [], ’em’ => [], ‘a’ => [‘href’ => []]]);
}
`

Troubleshooting


Fields Not Appearing


19. Check if context matches (‘ticket’ or ‘kb’)
20. Verify field ID is unique
21. Ensure filter is properly hooked

Validation Errors


22. Check field configuration for typos
23. Verify custom validation functions
24. Review PHP error logs

Display Issues


25. Check template overrides
26. Verify CSS classes
27. Test with default theme

Resources


28. WordPress Custom Fields
29. Data Validation
30. ShahiAssist Field Types Reference (in plugin code)