wheels generate helper

wheels generate helper

Generate global helper functions for use throughout the application.

Synopsis

wheels generate helper name=<helperName> [options]

# Can also be used as:
wheels g helper name=<helperName> [options]

CommandBox Parameter Syntax

• Named parameters: param=value (e.g., name=Format, functions="truncate,slugify")
• Flag parameters: --flag equals flag=true (e.g., --force equals force=true)
• Param with value: --param=value equals param=value (e.g., --description="Formatting utilities")

Recommended: Use named parameters with flags: wheels generate helper name=StringUtils --functions="truncate,highlight,slugify"

Description

The wheels generate helper command creates global helper function files that are automatically available throughout your application. Helper functions are useful for view formatting, data transformation, and reusable utility functions. All generated helpers are automatically included in /app/global/functions.cfm and become globally accessible.

Arguments

Argument	Description	Default
name	Helper name (e.g., Format, StringUtils)	Required

Helper Name Validation

• Helper name must be a valid CFML component name
• Cannot contain spaces or special characters
• Will automatically append “Helper” if not present (Format → FormatHelper)
• Must be unique (cannot overwrite existing helper without --force)

Options

Option	Description	Valid Values	Default
functions	Comma-separated list of functions to generate	Valid CFML function names	"helperFunction"
description	it will be placed as comment at the top of helper file	Any descriptive text	""
force	Overwrite existing files and skip validation	true, false	false

Function Name Validation

• Function names must be unique across all helper files
• Must be valid CFML function names
• Cannot duplicate existing global functions
• Validation is skipped when using --force

Examples

Basic helper

wheels generate helper name=Format

Creates:

• /app/helpers/FormatHelper.cfm with default helper function
• Adds include to /app/global/functions.cfm
• /tests/specs/helpers/FormatHelperSpec.cfc test file

Helper with multiple functions

wheels generate helper name=StringUtils --functions="truncate,highlight,slugify"

Creates a helper with three functions: truncate(), highlight(), slugify()

Helper with description

wheels generate helper name=DateHelpers --description="Date formatting and manipulation utilities" --functions="formatDate,timeAgo"

Adds description to the helper file header

Force overwrite existing helper

wheels generate helper name=Format --force

Overwrites existing FormatHelper.cfm without prompting

Complex helper with smart templates

wheels generate helper name=Format --functions="currency,date,truncate"

The generator recognizes common function names and creates appropriate implementations:

• currency → Currency formatting logic
• date → Date formatting logic
• truncate → Text truncation logic

Generated Code Examples

Basic Helper Structure

/**
 * FormatHelper
 */
<cfscript>

  /**
   * Helper function helper function
   * @value.hint The value to process
   * @options.hint Additional options
   * @return Processed value
   */
  public any function helperFunction(
    required any value,
    struct options = {}
  ) {
    // TODO: Implement helperFunction logic
    return arguments.value;
  }

</cfscript>

Helper with Description

/**
 * DateHelper
 * Date formatting and manipulation utilities
 */
<cfscript>

  /**
   * Format date helper function
   * @value.hint The value to process
   * @options.hint Additional options
   * @return Processed value
   */
  public any function formatDate(
    required any value,
    struct options = {}
  ) {
    // Format date with relative time support
    if (!isDate(arguments.value)) {
      return arguments.value;
    }

    local.format = arguments.options.format ?: "medium";

    switch(local.format) {
      case "relative":
        return timeAgoInWords(arguments.value);
      case "short":
        return dateFormat(arguments.value, "m/d/yy");
      case "long":
        return dateFormat(arguments.value, "mmmm d, yyyy");
      default:
        return dateFormat(arguments.value, "mmm d, yyyy");
    }
  }

</cfscript>

Smart Template: Truncate Function

/**
 * Truncate helper function
 * @value.hint The value to process
 * @options.hint Additional options
 * @return Processed value
 */
public any function truncate(
  required any value,
  struct options = {}
) {
  // Truncate text to specified length
  local.length = arguments.options.length ?: 100;
  local.suffix = arguments.options.suffix ?: "...";

  if (len(arguments.value) <= local.length) {
    return arguments.value;
  }

  return left(arguments.value, local.length - len(local.suffix)) & local.suffix;
}

Smart Template: Slugify Function

/**
 * Slugify helper function
 * @value.hint The value to process
 * @options.hint Additional options
 * @return Processed value
 */
public any function slugify(
  required any value,
  struct options = {}
) {
  // Convert text to URL-friendly slug
  local.slug = lCase(trim(arguments.value));

  // Replace spaces with hyphens
  local.slug = reReplace(local.slug, "\s+", "-", "all");

  // Remove non-alphanumeric characters except hyphens
  local.slug = reReplace(local.slug, "[^a-z0-9\-]", "", "all");

  // Remove multiple consecutive hyphens
  local.slug = reReplace(local.slug, "\-+", "-", "all");

  // Trim hyphens from start and end
  local.slug = reReplace(local.slug, "^\-|\-$", "", "all");

  return local.slug;
}

Smart Template: Currency Function

/**
 * Currency helper function
 * @value.hint The value to process
 * @options.hint Additional options
 * @return Processed value
 */
public any function currency(
  required any value,
  struct options = {}
) {
  // Format currency values
  if (!isNumeric(arguments.value)) {
    return arguments.value;
  }

  local.currency = arguments.options.currency ?: "USD";
  local.symbol = arguments.options.symbol ?: "$";

  return local.symbol & numberFormat(arguments.value, "0.00");
}

Automatic Include in functions.cfm

When you generate a helper, it’s automatically added to /app/global/functions.cfm:

<cfscript>
//=====================================================================
//=     Global Functions
//=====================================================================
include "../helpers/FormatHelper.cfm";
include "../helpers/StringUtilsHelper.cfm";
include "../helpers/DateHelper.cfm";
</cfscript>

Using Helpers in Your Application

In Controllers

component extends="Controller" {

  function index() {
    users = model("User").findAll();

    // Use helper function
    for (user in users) {
      user.displayName = truncate(user.bio, {length: 50});
    }
  }

}

In Views

<cfparam name="post">
<cfoutput>
  <article>
    <h1>#post.title#</h1>
    <p class="meta">
      Posted #formatDate(post.createdAt, {format: "relative"})# by #post.author#
    </p>
    <div class="content">
      #post.content#
    </div>
    <div class="permalink">
      /posts/#slugify(post.title)#
    </div>
  </article>
</cfoutput>

In Models

component extends="Model" {

  function init() {
    beforeSave("generateSlug");
  }

  private function generateSlug() {
    if (!StructKeyExists(this, "slug") || !len(this.slug)) {
      this.slug = slugify(this.title);
    }
  }

}

Smart Template Functions

The generator recognizes common function name patterns and creates appropriate implementations:

Function Name Pattern	Generated Implementation
Contains “truncate”	Text truncation with length and suffix options
Contains “highlight”	Search term highlighting with CSS class
Contains “slugify”	URL-friendly slug generation
Contains “date”	Date formatting with relative time support
Contains “currency” or “money”	Currency formatting with symbol
Contains “format”	Generic formatting based on data type
Other names	Basic template with TODO comment

Function Conflict Detection

The generator validates that function names are unique across all helper files:

Valid: Unique Function Names

# First helper
wheels generate helper name=String --functions="truncate,slugify"

# Second helper (different functions)
wheels generate helper name=Format --functions="currency,date"
# Success: No conflicts

Invalid: Duplicate Function Names

# First helper
wheels generate helper name=String --functions="truncate"

# Second helper (same function)
wheels generate helper name=Text --functions="truncate"
# Error: The following function(s) already exist in helper files: truncate (in StringHelper.cfm)

Override with Force

# Overwrite with force flag (skips validation)
wheels generate helper name=Text --functions="truncate" --force=true
# Success: File created (may cause global function conflicts)

Common Use Cases

Text Formatting Helpers

wheels generate helper name=TextFormat --functions="truncate,excerpt,wordCount,capitalize"

Date/Time Helpers

wheels generate helper name=DateHelpers --functions="formatDate,timeAgo,businessDays"

URL/String Helpers

wheels generate helper name=URLHelpers --functions="slugify,urlEncode,sanitizeFilename"

Number Formatting Helpers

wheels generate helper name=NumberFormat --functions="currency,percentage,fileSize"

Validation Helpers

wheels generate helper name=ValidationHelpers --functions="isEmail,isPhone,isURL"

Best Practices

1. Naming: Use descriptive helper names that indicate purpose (StringUtils, DateHelpers)
2. Function Names: Keep function names concise and action-oriented (truncate, not truncateText)
3. Global Scope: Remember helpers are global - use unique, descriptive names
4. Options Pattern: Use options struct for flexibility instead of many parameters
5. Type Checking: Validate input types before processing
6. Documentation: Use hint attributes to document parameters and return values
7. Testing: Always create and run tests for helper functions
8. Validation: Check for function conflicts before creating helpers

Common Patterns

Options Struct Pattern

public any function formatText(
  required any value,
  struct options = {}
) {
  // Extract options with defaults
  local.maxLength = arguments.options.maxLength ?: 100;
  local.suffix = arguments.options.suffix ?: "...";
  local.preserveWords = arguments.options.preserveWords ?: true;

  // Process with options
  // ...
}

Type-Safe Helpers

public string function formatCurrency(
  required any value,
  struct options = {}
) {
  // Validate input
  if (!isNumeric(arguments.value)) {
    throw(type="InvalidArgument", message="Value must be numeric");
  }

  // Process
  return dollarFormat(arguments.value);
}

Chainable Helpers

public string function sanitize(required string value) {
  return trim(htmlEditFormat(arguments.value));
}

// Usage: displayText = sanitize(userInput)

Testing

The generator automatically creates test files:

/tests/specs/helpers/FormatHelperSpec.cfc

component extends="wheels.Test" {

  function setup() {
    // Global helpers are automatically included
  }

  function test_truncate() {
    // Test truncate function
    local.input = "test value";
    local.result = truncate(local.input);

    assert(isDefined("local.result"), "Function should return a value");
  }

}

Running Tests

wheels test run

Error Handling

Invalid Helper Name

wheels generate helper name="My Helper"
# Error: Invalid helper name: Cannot contain spaces

Function Name Conflict

wheels generate helper name=Utils --functions="truncate"
# Error: The following function(s) already exist in helper files: truncate (in StringHelper.cfm)

File Already Exists

wheels generate helper name=Format
# Error: Helper already exists: FormatHelper.cfm. Use force=true to overwrite.

See Also

• wheels generate controller - Generate controllers
• wheels generate model - Generate models
• wheels generate test - Generate tests
• Template System Guide - Customize generator templates