Server Settings - Mappings

Overview

Mappings in ColdFusion allow you to create logical paths that point to physical directories on your server. This abstraction enables cleaner code organization, easier path management, and better portability across different environments. Understanding how to properly configure and use mappings is essential for building maintainable ColdFusion applications.

The Mappings page allows you to configure ColdFusion mappings, custom tag paths, and archive file mappings. These settings affect how ColdFusion resolves paths when including templates, invoking custom tags, and loading archived components.

ColdFusion Mappings

What Are ColdFusion Mappings?

• Purpose: Create logical path aliases that point to physical directories
• Use Cases: Shared code libraries, component directories, include files
• Benefit: Change physical location without updating code
• Syntax: Logical path starts with forward slash (e.g., /myapp)
• Resolution: ColdFusion resolves logical path to physical directory

Creating a Mapping

• Logical Path: The virtual path name (must start with /)
• Example: /shared, /components, /lib
• Case-sensitive on Linux/Unix, case-insensitive on Windows
• Must be unique within the server
• Directory Path: The physical directory location
• Absolute path recommended (e.g., /var/www/shared)
• Can use drive letters on Windows (e.g., D:\shared)
• Can use UNC paths (\\server\share)
• Inspect Templates: Check templates for changes on each request
• Enabled: Templates are checked and reloaded if modified
• Disabled: Templates cached until server restart (production)

Default ColdFusion Mappings

• /CFIDE: ColdFusion IDE integration and administrator resources
• Required for administrator to function
• Should be secured in production (block external access)
• /cfformprotect: Form protection library (if installed)
• /gateway: Event gateway configuration files
• System Mappings: Cannot be deleted but can be modified

Using Mappings in Code

• Including Templates: <cfinclude template="/shared/utils.cfm">
• Creating Components: createObject("component", "/components/User")
• Extending Components: component extends="/components/Base"
• Custom Tags: <cf_mytag template="/customtags/mytag.cfm">
• Path Notation: Use dot notation for components (/lib/utils.cfc = lib.utils)

Best Practices for Mappings

• Use descriptive names that indicate purpose (/components, /includes, /api)
• Keep mappings consistent across dev, test, and production
• Disable template inspection in production for better performance
• Use mappings to organize shared code and components
• Document all custom mappings in deployment procedures
• Avoid overlapping or conflicting mapping names
• Use absolute paths to prevent ambiguity

Application-Specific Mappings

Configure mappings at the application level in Application.cfc for better portability and isolation.

Example Application.cfc Mapping

Configure mappings dynamically based on the application's location:

component {
  this.name = "MyApplication";

  // Define application-specific mappings
  this.mappings = {
    // Map to application root directory
    "/myapp": getDirectoryFromPath(getCurrentTemplatePath()),

    // Map to components directory
    "/components": expandPath("/myapp/cfc"),

    // Map to includes directory (relative to app root)
    "/includes": expandPath("/myapp/includes"),

    // Map to shared resources (absolute path)
    "/shared": "/var/www/shared"
  };

  function onApplicationStart() {
    // Application initialization
    return true;
  }
}

<cfcomponent>
  <cfset this.name = "MyApplication">

  <!--- Define application-specific mappings --->
  <cfset this.mappings = {}>

  <!--- Map to application root directory --->
  <cfset this.mappings["/myapp"] = getDirectoryFromPath(getCurrentTemplatePath())>

  <!--- Map to components directory --->
  <cfset this.mappings["/components"] = expandPath("/myapp/cfc")>

  <!--- Map to includes directory (relative to app root) --->
  <cfset this.mappings["/includes"] = expandPath("/myapp/includes")>

  <!--- Map to shared resources (absolute path) --->
  <cfset this.mappings["/shared"] = "/var/www/shared">

  <cffunction name="onApplicationStart" returnType="boolean">
    <!--- Application initialization --->
    <cfreturn true>
  </cffunction>
</cfcomponent>

When to Use Application vs Server Mappings

Custom Tag Paths

What Are Custom Tag Paths?

• Purpose: Directories where ColdFusion searches for custom tags
• Custom Tags: Reusable CFML templates invoked with <cf_tagname> syntax
• Search Order: ColdFusion searches paths in order until tag is found
• Default Path: /WEB-INF/customtags directory

Configuring Custom Tag Paths

• Adding Paths: Enter absolute path to directory containing custom tags
• Multiple Paths: Can add multiple directories
• Search Priority: Paths searched in order listed
• First Match: First tag found is used (subsequent matches ignored)
• Subdirectories: Not searched recursively by default

Custom Tag Search Order

• 1. Current directory of calling template
• 2. Directories specified in cfimport taglib attribute
• 3. Custom tag paths defined in administrator (in order)
• 4. /WEB-INF/customtags directory
• Caching: Tags are cached after first use
• Refresh: Clear template cache to reload modified tags

Application-Specific Custom Tag Paths

• Application.cfc Setting: this.customTagPaths
• Syntax: this.customTagPaths = "/path/to/tags";
• Multiple Paths: this.customTagPaths = "/path1,/path2";
• Scope: Applies only to that application
• Priority: Searched before server-level custom tag paths

Best Practices for Custom Tags

• Use cfimport for better organization and namespacing
• Keep custom tags in version control
• Document tag attributes and usage
• Use unique names to avoid conflicts
• Consider using CFC-based custom tags for better OOP support
• Test tags in isolation before deploying

Modern Alternative: CFImport

• Better Approach: <cfimport prefix="mytags" taglib="/customtags">
• Namespacing: <mytags:tagname> prevents naming conflicts
• Clarity: Explicit about where tags come from
• Recommendation: Use cfimport instead of custom tag paths

Archive File Mappings (.CAR Files)

What Are ColdFusion Archive Files?

• Definition: Compiled ColdFusion applications packaged as .car files
• Purpose: Deploy applications without exposing source code
• Contents: Compiled CFM templates, CFCs, and resources
• Creation: Use cfcompile utility or Archive Wizard
• Legacy Feature: Less common in modern development

Configuring Archive Mappings

• Logical Path: Virtual path for the archive
• Archive File: Path to .car file
• Resolution: ColdFusion extracts and serves files from archive
• Use Case: Deploying proprietary code to clients

Advantages of Archive Files

• Protect intellectual property (source code not visible)
• Simpler deployment (single file instead of many)
• Prevent accidental modification of code
• Potentially faster loading (files are pre-compiled)

Disadvantages of Archive Files

• Debugging is more difficult (no source code access)
• Cannot make quick fixes without recompiling
• Less transparent than source code
• Requires additional deployment step (compilation)
• Not widely used in modern CF development

When to Use Archive Files

• Distributing commercial ColdFusion applications
• Protecting proprietary algorithms or business logic
• Deploying to client environments where source protection is required
• Legacy applications that already use archives
• Alternative: Most modern apps use source code with proper access controls

Mapping Resolution and Precedence

Path Resolution Order

• 1. Application-specific mappings (Application.cfc this.mappings)
• 2. Server-level mappings (Administrator settings)
• 3. Relative paths from current template directory
• 4. Web root directory
• First Match: First successful resolution is used

Mapping Conflicts

• Same Logical Path: Application-level overrides server-level
• Case Sensitivity: Linux/Unix is case-sensitive, Windows is not
• Overlap: More specific paths take precedence
• Example: /myapp/lib overrides /myapp
• Best Practice: Avoid conflicting mappings when possible

Path Resolution Issues

• Relative vs Absolute: Relative paths can be ambiguous
• Template Context: Relative paths resolve from current template location
• Include Context: Included templates inherit calling template's context
• Recommendation: Use mappings for clarity and consistency

Performance Impact of Mappings

Template Inspection Setting

• Enabled (Development): ColdFusion checks file modification time on each request
• Automatically reloads changed templates
• Small performance overhead (file system check)
• Convenient for development
• Disabled (Production): Templates cached until server restart
• Better performance (no file checks)
• Requires template cache clear or restart after changes
• Recommended for production

Mapping Overhead

• Resolution Cost: Mapping resolution is very fast
• Caching: Resolved paths are cached
• Impact: Minimal performance impact in practice
• Benefit: Performance cost is negligible compared to benefits

Network Paths

• UNC Paths: Mappings to network shares (\\server\share)
• Performance: Significantly slower than local paths
• Latency: Network latency affects every file access
• Reliability: Network issues can cause failures
• Recommendation: Avoid network paths if possible
• Alternative: Copy files to local disk during deployment

Best Practices for Performance

• Disable template inspection in production
• Use local paths instead of network paths
• Keep mapping structures simple
• Monitor file system performance
• Use SSD storage for better I/O performance

Organizing Code with Mappings

Common Mapping Patterns

• /components: Application CFCs and business logic
• /model: Model layer components (MVC pattern)
• /services: Service layer components
• /utils: Utility functions and helpers
• /includes: Commonly included templates
• /api: API endpoints and handlers
• /lib: Third-party libraries and frameworks

Framework Mappings

• FW/1: /framework, /controllers, /views, /layouts
• ColdBox: /coldbox, /models, /handlers, /modules
• Fusebox: /fusebox, /circuits
• Best Practice: Follow framework conventions

Multi-Application Server Organization

• Shared Mappings: /shared for code used by all apps
• Application Mappings: /app1, /app2 for application-specific code
• Common Libraries: /lib for shared utilities
• Isolation: Use application-specific mappings when possible

Recommended Directory Structure

• Physical Layout:
• /var/www/myapp/ (webroot)
• /var/www/myapp/cfc/ (components)
• /var/www/myapp/includes/ (includes)
• /var/www/shared/ (shared across apps)
• Logical Mappings:
• /myapp → /var/www/myapp
• /components → /var/www/myapp/cfc
• /shared → /var/www/shared

Common Issues and Solutions

Mapping Not Found Errors

• Symptom: "Could not find mapping for path" error
• Causes:
• Mapping not defined in administrator or Application.cfc
• Typo in mapping name
• Case sensitivity on Linux/Unix
• Solutions:
• Verify mapping exists in administrator
• Check spelling and case
• Ensure "Enable Per App Settings" is enabled

File Not Found Despite Valid Mapping

• Symptom: Mapping resolves but file not found
• Causes:
• Physical path is incorrect
• File doesn't exist at physical location
• Permissions prevent access
• Case sensitivity on Linux/Unix
• Solutions:
• Verify physical directory path
• Check file exists in physical location
• Verify ColdFusion has read permissions
• Check file name case matches exactly

Templates Not Reloading

• Symptom: Changes to templates not reflected
• Causes:
• Template inspection disabled
• Template cache not cleared
• Browser caching
• Solutions:
• Enable template inspection for development
• Clear template cache in administrator
• Clear browser cache
• Use query string to bust cache (?v=123)

Mapping Conflicts Between Applications

• Symptom: One application's mapping affects another
• Cause: Server-level mappings are global
• Solutions:
• Use application-specific mappings in Application.cfc
• Use unique mapping names per application
• Ensure "Enable Per App Settings" is enabled

Performance Issues with Mappings

• Symptom: Slow template loading
• Causes:
• Network paths (UNC) instead of local
• Template inspection enabled in production
• Slow file system (HDD, network storage)
• Solutions:
• Use local paths only
• Disable template inspection in production
• Use SSD storage
• Monitor disk I/O

Security Considerations

Mapping Security Best Practices

• Never map to sensitive directories (system folders, password files)
• Restrict /CFIDE access to localhost or admin IPs only
• Use proper file system permissions on mapped directories
• Avoid mapping to directories above webroot when possible
• Document all mappings for security audits
• Regularly review and remove unused mappings

Web Server Configuration

• /CFIDE Protection: Block external access via web server rules
• Apache Example: <Location /CFIDE> Deny from all </Location>
• IIS: Use IP restrictions or authentication
• Nginx: Deny access in location block

File System Permissions

• ColdFusion service account needs read access to mapped directories
• Limit write access to only necessary directories
• Use principle of least privilege
• Regularly audit permissions

Related Resources