Voxel Theme Modifier: Format Text and Numbers with Custom Separators

Presenting data in a readable and user-friendly way is crucial. Whether you’re dealing with large numbers or organizing text strings, properly formatted outputs can significantly enhance the user experience.

The “Format with Separator” Voxel Theme Modifier is designed to give you the power to format both numerical and text data using custom separators and grouping options.

Imagine you’re working with financial figures, and you want to display large numbers like 2400000 as 2,400,000 for better readability, or you’re handling text and need to insert a separator every few characters, like turning “HelloWorld” into “Hel-loW-orl-d”. This modifier allows you to define the separator (commas, periods, or even custom characters), and decide exactly how many digits or characters should appear before the separator is applied.

This can be combined with regular Voxel Mods such as Prepend and Append to format numbers and currency just the way you need it.

Example Scenarios:

• Numeric Input:
  Input: 1250000
  Separator: ,
  Grouping: 3
  Decimals: 2
  Decimals Separator: .
  
  Output: 1,250,000.00
  
  
• Numeric Input + Prepend $ + Append USD:
  
  Input: 1250000
  Separator: ,
  Grouping: 3
  Decimal:
  Decimals Separator:
  
  Output: $ 1,250,000 USD
  
• Text Input:
  
  Input: abcdefg
  Separator: –
  Grouping: 2
  Output: ab-cd-ef-g

The Code: Voxel Theme Modifier: Format Text and Numbers with Custom Separators

Add to your functions.php file.

add_filter( 'voxel/dynamic-tags/modifiers', function( $modifiers ) {
    class Format_With_Separator extends \Voxel\Dynamic_Tags\Base_Modifier {

        // Label for the modifier
        public function get_label(): string {
            return 'Format with Separator';
        }

        // Unique key for the modifier
        public function get_key(): string {
            return 'format_with_separator';
        }

        // Define input fields for separator and grouping
        public function get_arguments(): array {
            return [
                'separator' => [
                    'type' => \Voxel\Form_Models\Text_Model::class,
                    'label' => _x( 'Separator (e.g., , or .)', 'modifiers', 'voxel-backend' ),
                    'classes' => 'x-col-12',
                ],
                'grouping' => [
                    'type' => \Voxel\Form_Models\Number_Model::class,
                    'label' => _x( 'Grouping (number of characters e.g. 3)', 'modifiers', 'voxel-backend' ),
                    'classes' => 'x-col-12',
                ],
                'decimals' => [
                    'type' => \Voxel\Form_Models\Number_Model::class,
                    'label' => _x( 'Decimals (for numbers only)', 'modifiers', 'voxel-backend' ),
                    'classes' => 'x-col-12',
                ],
                'decimal_separator' => [
                    'type' => \Voxel\Form_Models\Text_Model::class,
                    'label' => _x( 'Decimal Separator (e.g., . or ,)', 'modifiers', 'voxel-backend' ),
                    'classes' => 'x-col-12',
                ],
            ];
        }

        // Apply the format functionality
        public function apply( $value, $args, $group ) {
            // Get the user-defined options
            $separator = isset($args[0]) ? sanitize_text_field( $args[0] ) : ',';
            $grouping = isset($args[1]) ? absint( $args[1] ) : 3; // Default grouping every 3 characters
            $decimals = isset($args[2]) ? absint( $args[2] ) : 0;
            $decimal_separator = isset($args[3]) ? sanitize_text_field( $args[3] ) : '.';

            // Check if the input is numeric or text
            if ( is_numeric( $value ) ) {
                // If the value is a number, format it using number_format()
                $formatted_value = number_format(
                    (float) $value,
                    $decimals,
                    $decimal_separator,
                    $separator
                );
            } else {
                // If the value is text, insert separators at specified group intervals
                $formatted_value = $this->insert_separator($value, $separator, $grouping);
            }

            // Return the formatted value with HTML escaping to prevent XSS attacks
            return htmlspecialchars( $formatted_value );
        }

        /**
         * Helper function to insert separator into a text string at defined intervals
         */
        private function insert_separator( $text, $separator, $grouping ) {
            // Remove any existing separators to avoid duplication
            $text = str_replace($separator, '', $text);

            // Split the text into an array of characters
            $characters = str_split($text);

            // Insert separators every $grouping characters
            $formatted_array = array_chunk($characters, $grouping);
            $formatted_text = array_map(function($chunk) {
                return implode('', $chunk);
            }, $formatted_array);

            // Join the chunks with the separator
            return implode($separator, $formatted_text);
        }
    }

    // Add the custom modifier to the list of available modifiers
    $modifiers['format_with_separator'] = \Format_With_Separator::class;
    return $modifiers;
} );

To implement this solution, you’ll need to add the code to your WordPress site. You have two options for where to place this code:

• Child Theme’s functions.php File:
  
  If you’re already using a child theme (recommended for customization), simply add the PHP code to your functions.php file. This will ensure your changes are preserved even if the main Voxel theme is updated.
  
• Code Snippets Plugin:
  
  If you prefer not to edit theme files directly, or if you want to manage your custom code more easily, you can use the Code Snippets plugin. This plugin allows you to add custom PHP code without touching your theme files. Just create a new snippet, paste the code, and activate it.

Then apply this Voxel Mod to any number or text element.