Custom Field PHP Formatting

Overview

Output formatting for custom fields refer to the field output, rather than input presentation in forms. There are two types of customizable output formatting available for fields: Output Format and PHP Based Formatting.

Output Format

Allows using HTML and pre-defined tags to build simple layouts.

PHP Based Formatting

Provides access to raw data for the field and the associated entry (listing or review) so you can create complex logic and mould the output to your specific needs.

To use the PHP Based Formattingfeature, go to any custom field and find the setting under Advanced Options.

There are a couple of different ways to use this feature:

• Template Formatting
• PHP Output Format setting

Template Formatting

With template formatting you can create a custom template with your custom code and add the name of the template in the Template Name setting. Don't include the file extension, just the name.

While this approach requires a bit of extra work to create the template, it's also much easier to work with if your custom code is longer than a few lines. Template formatting also allows sharing a single template with multiple custom fields.

Any template file you create for custom field formatting goes inside your custom theme's fields_phpformat folder in overrides.

Joomla

templates/
`-- jreviews_overrides/
	`-- views/
		`-- themes/
			`-- mysite/
				`-- fields_phpformat/

WordPress

jreviews_overrides/
`-- views/
    `-- themes/
        `-- mysite/
            `-- fields_phpformat/

PHP Output Format Setting

With the PHP Output Format setting you can add write PHP code directly within the field's settings using the PHP editor.

It's important to note that the editor is ready for you to write PHP code without having to add an opening <?php tag. You can pass all your output into a variable and return it, or you can echo your variables.

Both of these are valid within the built-in editor:

Echoed Output

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

When using this option, you need to take into account that there is already an opening php tag, so if you want to add text or HTML code, you need to close it first.

Returned Output

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

Available Variables

The following variables are available within the PHP format scope:

• $value, $text and $image variables are arrays for checkboxes and multiple select custom fields, and strings for all other fields.
• $value and $text are identical for fields without pre-defined options (e.g. text, decimal, integer, etc)
• The CustomFieldsHelper PHP class is available in the PHP format scope by using the $CustomFields object instance.

If you want to inspect the contents of any of the above variables you can use either the prx and dd functions in the code editor:

// Dumps the contents of the variable and stops code execution
dd($params);

// Outputs the contents of the variable and continues
prx($params);

Examples

• Default Output
• Hide Output
• Authentication Conditionals
• Show Ouput if More than One Option Selected
• Custom Images For Select List using Bannner
• Show Output Only When Another Field Option is Selected
• Concatenate Fields
• Hide Output Until Click
• Link to Listing Category
• Link to Other Listings By Same Owner
• Calculate Totals Sales Based on Price and Volume
• Calculate Age Based on Birth Date

Show Default Output

To show the default field output, return the $output array. This is useful when creating conditional logic to show a custom output in some instances, otherwise show the default output.

return $output;

Hide Output

To completely hide the field output, return a boolean false or a empty string.

return false;

Authentication Conditionals

For authentication conditionals, based on the logged in user, we use the auth service.

Hide Output for Guests

$auth = S2Object::make('auth');

return $auth->guest ? false : $output;

Show Log in Message to Guests

$auth = S2Object::make('auth');

return $auth->guest ? "Log in to view this field" : $output;

Show Ouput if More than One Option Selected

For checkbox and multiple select lists

$count = is_array($output) ? count($output) : 1;

return $count > 1 ? $output : false;

Custom Images For Select List using Bannner

The code below goes inside a banner custom field, and we use the output of a jr_city field to check the selected options.

$city = $CustomFields->fieldValue('jr_city',$entry);

switch($city) {
   case 'san-francisco':
      $banner = "sanfrancisco.jpg";
   break;
   case 'new-york':
      $banner = "newyork.jpg";
   break;
   default: // All other cities display the default banner output
       return $output;
   break;
}

$banner = '/media/banners' . $banner;

return "<img src=".$banner." />";

Show Output Only When Another Selected

Checkbox and Multiple Select Lists

In this example, the field output is only shown when the email value is checked in the jr_checkbox field.

$checkboxes = $CustomFields->fieldValue('jr_checkbox',$entry);

return in_array('email',$checkboxes) ? $output : false;

Radiobutton and Single Select List

$selected = $CustomFields->fieldValue('jr_radio',$entry);

return $selected == 'yes' ? $output : false;

Concatenate Fields

Using a banner custom field to concatenate values with commas, or any other specific format, but not all fields are required.

$out = [];
$names = [
  'jr_addressline1',
  'jr_addressline2',
  'jr_town',
  'jr_city',
  'jr_county',
  'jr_postcode'
];
foreach ($names AS $name) 
{
   $out[] = $CustomFields->fieldValue($name, $entry);
}
$out = array_filter($out);
$out = implode(', ', $out);
return $out != '' ? $out : false;

Hide Output Until Click

The code below can be used with a text-based fields or fields with single choice selections (single select, radiobutton).

return '<span class="jrButton" data-value="'.$text.'" onclick="jQuery(this).html(jQuery(this).data(\'value\')).removeClass(\'jrButton\');">Click to reveal info</span>';

Link to Listing Category

$Routes = new RoutesHelper;
return $Routes->category($entry, $entry['Category']);

$Routes = new RoutesHelper;
$url = $Routes->category($entry, array('return_url'=>'true'));
return sprintf('<a href="%s">Custom Text</a>',$url);

Link to Other Listings By Same Owner

$Routes = new RoutesHelper;
return $Routes->myListings($entry['User']['name'], $entry['User']['user_id']);

Calculate Totals Sales Based on Price and Volume

Using a banner custom field.

$price = $CustomFields->fieldValue('jr_price',$entry);
$volume = $CustomFields->fieldValue('jr_volume',$entry);
$total = $price * $volume;
return $total;

If one of the values is zero, you can display the default output of the banner instead, or if you prefer to hide the output, return false instead.

$price = $CustomFields->fieldValue('jr_price',$entry);
$volume = $CustomFields->fieldValue('jr_volume',$entry);
$total = $price * $volume;
return $total > 0 ? $total : $output;

Calculate Age Based on Birth Date

$bday = new DateTime($text);
$today = new DateTime();
$diff = $today->diff($bday);
return $diff->y;