# Email Signature Template - Structured Address Fields

## Overview
Updated email signature templates to support structured address fields, giving users better control over address formatting in email signatures.

## Implementation Date
November 27, 2025

## New Placeholders Available

### Structured Address Fields (NEW)
- `{company_address_line1}` - Street address, P.O. box
- `{company_address_line2}` - Suite, unit, building, floor, etc.
- `{company_city}` - City name
- `{company_state}` - State or province
- `{company_zip}` - ZIP or postal code
- `{company_country}` - Country

### Legacy Address Field (Still Available)
- `{company_address}` - Full address combined (backwards compatible)

### Other Company Placeholders
- `{company_name}` - Company name
- `{company_email}` - Company email
- `{company_phone}` - Company phone
- `{company_website}` - Company website
- `{company_logo}` - Company logo image

### User Placeholders
- `{user_name}` - Full name
- `{user_email}` - Email address
- `{user_phone}` - Phone number
- `{position_title}` - Job title

## Usage Examples

### Example 1: Simple Structured Address
```html
<div style="font-size: 12px; color: #666;">
    {company_name}<br>
    {company_address_line1}<br>
    {company_city}, {company_state} {company_zip}<br>
    {company_phone} | {company_website}
</div>
```

### Example 2: Full Structured Address
```html
<div style="font-size: 11px; color: #333;">
    <strong>{company_name}</strong><br>
    {company_address_line1}<br>
    {company_address_line2}<br>
    {company_city}, {company_state} {company_zip}<br>
    {company_country}<br>
    <br>
    Phone: {company_phone}<br>
    Email: {company_email}<br>
    Web: {company_website}
</div>
```

### Example 3: Using Legacy Combined Address
```html
<div style="font-size: 12px;">
    {company_name}<br>
    {company_address}<br>
    {company_phone}
</div>
```

### Example 4: Conditional Address Line 2
Since Address Line 2 is optional, you can include it but it will be empty if not set:
```html
{company_address_line1}<br>
{company_address_line2}<!-- Will be blank if not set -->
{company_city}, {company_state} {company_zip}
```

## Files Modified

1. `/views/settings/email-templates/edit.php`
   - Lines 52-58: Updated placeholder list to include structured fields
   - Lines 112-123: Added structured fields to preview JavaScript

2. `/models/EmailSignatureTemplate.php`
   - Lines 231-241: Added structured address fields to render() method

3. `/models/SystemSettings.php` (from previous update)
   - Lines 214-220: Included structured fields in getCompanyInfo()

4. `/controllers/SettingsController.php` (from previous update)
   - Lines 122-137: Saves structured address fields

## Benefits

### Better Formatting Control
✅ **Multi-line addresses** - Each component on its own line
✅ **Flexible layouts** - Mix and match fields as needed
✅ **International support** - Adapt format by country
✅ **Clean appearance** - No extra commas or spaces when fields are empty

### Examples of Improved Formatting

**Before (Legacy):**
```
Company Name
123 Main St Suite 100, City, State 12345
(may have awkward spacing)
```

**After (Structured):**
```
Company Name
123 Main St
Suite 100
City, State 12345
```

### Migration Path

**Option 1: Keep using legacy field**
- Continue using `{company_address}`
- No changes needed to existing templates

**Option 2: Upgrade to structured fields**
- Edit your template
- Replace `{company_address}` with individual fields
- Better control over layout

## Preview Function

The preview function in the template editor now includes sample data for all structured fields:
- Address Line 1: "123 Main Street"
- Address Line 2: "Suite 100"
- City: "City"
- State: "State"
- ZIP: "12345"
- Country: "United States"

Click the "Preview" tab to see how your template looks with the new fields.

## Technical Details

### Data Flow
1. Admin updates company info at `/settings/company`
2. Structured fields saved to `system_settings` table
3. Legacy `company_address` auto-generated from structured fields
4. Templates access fields via `SystemSettings::getCompanyInfo()`
5. `EmailSignatureTemplate::render()` replaces placeholders
6. Final HTML includes actual company address data

### Backwards Compatibility
- All existing templates continue to work
- `{company_address}` still functions
- New fields available but not required
- Gradual migration supported

## Best Practices

### 1. Use Structured Fields for New Templates
When creating new signature templates, use structured fields for better control:
```html
{company_address_line1}<br>
{company_city}, {company_state} {company_zip}
```

### 2. Handle Empty Fields Gracefully
Since Address Line 2 is optional, format it to handle empty values:
```html
{company_address_line1}<br>
{company_address_line2}
{company_city}, {company_state} {company_zip}
```

### 3. International Addresses
For international companies, adjust order based on country standards:
```html
{company_address_line1}<br>
{company_zip} {company_city}<br>
{company_country}
```

### 4. Consistent Spacing
Use `<br>` tags for line breaks instead of relying on spaces:
```html
<!-- Good -->
{company_city}, {company_state} {company_zip}<br>

<!-- Avoid -->
{company_city}, {company_state} {company_zip}
```

## Testing

To test the new fields:
1. Go to `/settings/company`
2. Fill in all address fields
3. Save
4. Go to `/settings/email/templates/1/edit`
5. Click "Preview" tab
6. Verify all address fields appear correctly

---
**Status:** ✅ Implemented and Active