Custom Field Output Formatting

Customize one field’s output with the shared Output Format setting, Early Access Blade templates, or Legacy PHP formatting—and migrate existing PHP customizations safely.

#Overview

This article covers formatting the output of one custom field from its Advanced Settings. It does not control how fields and field groups are positioned on a page. For page-level placement, see Customize Layout of Custom Fields.

JReviews provides three approaches:

The Blade and PHP settings can both remain visible in the control panel. The renderer used by the page determines which settings take effect. When the Early Access listing detail page renders a field, legacy PHP output format and Field output template customizations are not executed.

#Choose a Formatting Approach

Start with Output Format when tags and HTML are enough. It works in both rendering systems and requires no migration.

Use Blade template code for short Early Access customizations stored with a field. Use a Field output Blade template file when code is longer or shared by several fields.

Keep PHP output format or a legacy Field output template only for pages that still use the legacy renderer. If you are enabling Early Access, follow the migration guide.

The settings are located under Custom Fields → Edit Field → Advanced Settings.

#Formatting System Reference

Choose the rendering system used by the page you are customizing. Early Access is shown by default.

<span class="field-value">{{ $value }}</span>

templates/jreviews_overrides/resources/views/components/field-output/my-template.blade.php

jreviews_overrides/resources/views/components/field-output/my-template.blade.php

{{ $listing->getFieldTextString($field->name) }}

{{ $comment->getFieldTextString('jr_recommend') }}

{{ $comment->listing->getFieldTextString('jr_neighborhood') }}

<a href="{{ $comment->listing->url }}">
    {{ $comment->listing->title }}
</a>

@if ($comment->isUserComment())
    <span>{{ $comment->owner_name }}</span>
@endif

<time datetime="{{ $listing->created?->toAtomString() }}">
    {{ $listing->created?->format('M j, Y') }}
</time>

{{-- Escaped output --}}
{{ $value }}

{{-- Conditional --}}
@if ($listing->featured)
    <span>Featured</span>
@endif

{{-- Multiple values --}}
@foreach ((array) $listing->getFieldText('jr_amenities') as $amenity)
    <span>{{ $amenity }}</span>
@endforeach

{{-- PHP calculation --}}
@php
    $count = count((array) $listing->getFieldValue('jr_amenities'));
@endphp

<span>{{ $count }} amenities</span>

@php
    $deliveryMethods = (array) $listing->getFieldValue('jr_delivery_methods');
@endphp

@if (in_array('local-delivery', $deliveryMethods, true))
    <span>{{ $listing->getFieldTextString($field->name) }}</span>
@endif

@php
    $parts = array_filter([
        $listing->getFieldValue('jr_address'),
        $listing->getFieldValue('jr_city'),
        $listing->getFieldValue('jr_postcode'),
    ], fn ($part) => $part !== null && $part !== '');
@endphp

@if ($parts)
    <span>{{ implode(', ', $parts) }}</span>
@endif

@php
    $regularPrice = (float) $listing->getFieldValue('jr_regular_price');
    $salePrice = (float) $listing->getFieldValue('jr_sale_price');

    $discountPercentage = $regularPrice > 0
        ? (($regularPrice - $salePrice) / $regularPrice) * 100
        : null;
@endphp

@if ($discountPercentage !== null && $discountPercentage > 0)
    <span class="discount">-{{ number_format($discountPercentage, 2) }}%</span>
@endif

@foreach (($data['items'] ?? $data ?? []) as $item)
    <div class="inventory-item">
        <span>{{ $item['name'] ?? '' }}</span>
        <span>{{ number_format((float) ($item['price'] ?? 0), 2) }}</span>
    </div>
@endforeach

return "<span>Label:</span> <span>{$text}</span>";

?>
<span>Label:</span> <span><?php echo $text; ?></span>

templates/jreviews_overrides/views/themes/{your-theme}/fields_phpformat/my-template.thtml

jreviews_overrides/views/themes/{your-theme}/fields_phpformat/my-template.thtml

$city = $CustomFields->fieldValue('jr_city', $entry);
return $city ?: false;

$methods = (array) $CustomFields->fieldValue('jr_delivery_methods', $entry);
return in_array('local-delivery', $methods, true) ? $output : false;

$parts = array_filter([
    $CustomFields->fieldValue('jr_address', $entry),
    $CustomFields->fieldValue('jr_city', $entry),
    $CustomFields->fieldValue('jr_postcode', $entry),
]);

return $parts ? implode(', ', $parts) : false;

$price = (float) $CustomFields->fieldValue('jr_price', $entry);
$quantity = (float) $CustomFields->fieldValue('jr_quantity', $entry);
$total = $price * $quantity;

return $total > 0 ? number_format($total, 2) : false;

#Blade and Legacy PHP Compared

#Migration Guide

Only fields with custom code in PHP output format or a selected legacy Field output template need migration. Fields that use only Output Format continue working.

When the Early Access listing detail page is enabled, legacy PHP formatting is ignored. The field falls back to its normal Output Format until a Blade override is configured.

#Inventory Before Enabling Early Access

On a staging copy of the site:

1. Open every listing and review field's Advanced Settings.
2. Record fields containing PHP output format code or a selected Field output template.
3. Save a copy of the code and note whether each field belongs to a listing or review.
4. Record the field type and every sibling field, helper, route, or script the code uses.
5. Include examples with blank, single, and multiple values in the test plan.

#Legacy-to-Blade Variable Mapping

Do not mechanically rename $text, $field, $fields, $image, $output, or $params. Their meaning or shape changes and may require redesign.

#Migration Workflow

1. Decide whether the code belongs in inline Blade template code or a reusable file.
2. Replace legacy field reads with methods on $listing or $comment.
3. Replace array access with model properties and methods.
4. Choose stored values (getFieldValue) or display labels (getFieldText) intentionally.
5. Add guards for missing data, invalid numbers, division by zero, and multiple-value arrays.
6. Escape output with {{ }} unless trusted HTML is explicitly required.
7. Flag legacy routes, helper classes, JavaScript, $output, and $params for manual redesign.
8. Enable Early Access on staging, add the Blade code, and test all recorded scenarios.

#Migration Example: Sibling-Field Calculation

Legacy PHP

$regularPrice = $CustomFields->fieldValue('jr_regular_price', $entry);
$salePrice = $CustomFields->fieldValue('jr_sale_price', $entry);
$discount = (($regularPrice - $salePrice) / $regularPrice) * 100;

return '<span class="discount">-'.number_format($discount, 2).'%</span>';

Early Access Blade

@php
    $regularPrice = (float) $listing->getFieldValue('jr_regular_price');
    $salePrice = (float) $listing->getFieldValue('jr_sale_price');

    $discount = $regularPrice > 0
        ? (($regularPrice - $salePrice) / $regularPrice) * 100
        : null;
@endphp

@if ($discount !== null && $discount > 0)
    <span class="discount">-{{ number_format($discount, 2) }}%</span>
@endif

#Migration Example: FormBuilder JSON

Legacy PHP

$items = json_decode($text, true);

foreach ($items as $item) {
    echo '<div>'.htmlspecialchars($item['name']).'</div>';
}

Early Access Blade

@foreach (($data['items'] ?? $data ?? []) as $item)
    <div>{{ $item['name'] ?? '' }}</div>
@endforeach

#AI-Assisted Migration

AI can produce a useful first draft, but it cannot infer field ownership, field types, stored values, or the intent of an undocumented helper. Give it those details and review every unsupported dependency it identifies.

Copy this prompt and add the requested information and legacy code:

Convert the JReviews legacy custom-field PHP formatting below to Early Access Blade.

Context I will provide:
1. Is this a listing field or a review/comment field?
2. What is the current field name and field type?
3. For every sibling field used: field name, field type, and whether the code needs its stored value or display label.
4. Is the result going into inline "Blade template code" or a reusable .blade.php file?

JReviews Blade runtime rules:
- $listing and $comment are models, never legacy arrays.
- Use $listing->getFieldValue('jr_name') or $comment->getFieldValue('jr_name') for stored values.
- Use getFieldText(), getFieldTextString(), or getFieldOptionImage() only when their display result matches the legacy intent.
- A review field can read a listing field through $comment->listing.
- $field is a Field model, not the legacy field array.
- $data contains JSON-decoded data when the stored value is valid JSON; otherwise it is the normalized value.
- $route is 'listing.detail' or null, not a route object.
- There is no direct injected equivalent for legacy $output, $params, $fields, or $image. Flag each use for manual redesign unless a verified model method solves the exact requirement.
- Do not assume $text maps directly to $data. Decide whether it represented a stored value or a display label.
- A genuinely blank writable field is rejected before the Blade template runs, so the template cannot create a placeholder for that case.

Verified model attributes and relationships:
- Listing: $listing->id, title, alias, url, summary, description, featured, views, owner_id, owner_name, owner_email, created, updated, and category_title.
- Comment/review: $comment->id, title, comments (the body), rating, url, comment_type, listing_id, owner_id, owner_name, owner_email, created, and updated.
- Relationships: $comment->listing->title, $comment->listing->url, $listing->user, $listing->listing_type, $comment->user, and $comment->listing_type.
- Dates are date objects or null. Guard them, for example: $listing->created?->format('M j, Y').
- Useful model checks include $listing->isPublished(), $listing->isPending(), $comment->isPublished(), $comment->isUserComment(), and $comment->isEditorComment().
- Use only attributes or methods listed here or elsewhere in the supplied documentation. If the legacy code needs another property, mark it "needs model/API verification" instead of inventing a replacement.

Conversion requirements:
- Use object access and the documented model methods; never use legacy array syntax.
- Escape output with {{ }} by default. Use {!! !!} only for deliberately trusted HTML and explain why.
- Guard nulls, invalid numeric data, multiple-value arrays, and division by zero.
- Preserve the behavior, but improve misleading variable names when the calculation reveals their real meaning.
- Flag legacy helper classes, route builders, inline scripts, click-to-search behavior, and unsupported variables instead of inventing replacements.
- If any unsupported dependency remains, say that the conversion is incomplete.

Return:
1. The converted Blade code.
2. A mapping of every legacy variable/helper to its replacement or "manual redesign required."
3. Assumptions and unresolved items.
4. Test cases covering blank, normal, invalid, and multiple values where relevant, plus listing and review context where relevant.

Field context:
[DESCRIBE FIELD OWNERSHIP, TYPES, AND SIBLING FIELDS]

Legacy PHP code:
[PASTE CODE HERE]

#Verify an AI Conversion

Before using converted code on production, confirm:

• [ ] No legacy array access remains on $listing, $comment, or $field.
• [ ] Every field read intentionally uses a stored value or display label.
• [ ] $output, $params, $fields, $image, route helpers, and scripts were redesigned or explicitly removed.
• [ ] Arithmetic handles blank, non-numeric, zero, and negative values appropriately.
• [ ] Multiple-value fields are treated as arrays.
• [ ] Dynamic output is escaped unless trusted HTML is required.
• [ ] Listing and review fields use the correct model.
• [ ] The result was tested on staging with Early Access enabled.

#Related Documentation

• Custom Fields — create fields and configure their shared Output Format.
• Customize Layout of Custom Fields — position fields and groups in page templates.
• Discover Data Available in Templates — inspect the broader variables available to page templates.
• Early Access Features — enable the rewritten listing detail page and review its migration checklist.