Custom Fields

Custom Fields are at the heart of JReviews' structured data functionality for creating and displaying content. There are many types of fields and options for customizating their data-entry in forms and their output via templates.

#Overview

Custom fields offer a lot of functionality for data entry and output display in templates. Continue reading to learn more about the different field types available and how to take advantage of the features available to make them work for you.

If you are looking for more information on how to structure your content, create and setup fields, this is covered in more detail in:

• Planning & Organizing
• Initial setup

More custom field-driven functionality and features can be found in these articles:

• Click2Search
• Customize Layout of Custom Fields
• Custom Field PHP Formatting
• FormBuilder Custom Field
• Fields Module
• Related Listings
• Virtual Categories

#Field Types

• Banner

  Output-only field that doesn't show up in forms. Use the field's description to output a static message, which is the same for all listings, or use the available tags to combine the output of multiple fields.

• Checkbox, Select Multiple

  Uses pre-defined options and allows choosing more than one option. You can set maximum select option limit and the option ordering (A-Z or admin defined).

  Autocomplete UI can be enabled for Select Multiple and allows looking up values with autosuggest. Useful for long lists. After more than one option is selected, the tags can be dragged and dropped into the desired order.

• Code

  Allows storing javascript code, so only admins should be granted write access to this field. Can be used to paste widget code provided by 3rd parties.

• Date

  Shows a calendar widget to select a date.

• Decimal, Integer

  Limits inputs to decimal and integers respectively.

• Email

  Text input requires entering a valid email address.

• FormBuilder

  Learn more about the uses for the FormBuilder Custom Field.

• Select, Radiobutton

  Uses pre-defined options and only allows choosing one option. You can set the option ordering (A-Z or admin defined).

  Autocomplete UI can be enabled for select lists and allows looking up values with autosuggest. Useful for long lists.

• Related Listing

  Learn more about the uses for the Related Listings Custom Field

• Text

  Your standard text input field.

• Textarea

  Your standard textarea input field. You can turn own HTML support and a simple WYSIWYG editor using the field's settings.

• Website

  Text input requires entering a valid website URL.

#Field Relations

There are three different types of custom field relations that can be used in both listing and review forms:

1. Field Option → Field Option
2. Field option → Field
3. Field option → Field group

The relations are established in the target field option, field or field group by specifying the Control Field and Control Value. In other words, we tell the option, field and field group that it will become active and visible only when the control field + value is selected.

There are many different ways to setup relations, from very simple to highly complex. We recommend you try to keep things on the side of simple.

The Initial Setup article has a section on Custom Field Relations that includes more detailed examples and video tutorials.

#Field Option → Field Option

This relation allows changing the available options in a select field when an option is selected in another field (select, checkbox, radiobutton). One example where this type of relation is useful is when working with Country, State and City custom fields.

The relationship is defined in the Controlled By section of the dependent field option using the Control Field and Control Value settings.

For example, to create a Country → State relationship, you would add each State option individually to the State custom field, and for each option set the Control Field and Control Value.

Using the United States to illustrate the setup, when you create the State options the settings would be:

• Control Field: jr_country
• Control Value: united-states

Only one control field can be chosen, but it's possible to select multiple control values in that field, so that if any of the control field values is selected in the control field, the option becomes visible.

Dependent fields need to be placed in a specific order. In the above example, when you view the form, the Country field must be visible above the State field. When a country is selected, the State field displays below it.

#Field Option → Field

This relation allows toggling an entire field, of any type, when a field option is selected in another field (select, checkbox, radiobutton).

The relationship is defined in the Controlled By section of the dependent custom field using the Control Field and Control Value settings.

It can be useful when you need to display certain fields only when an option is selected in another field. For example if you have a Business Category custom field, you can display different fields for each business category depending on the business selected.

Using this approach can allow simplifying the Joomla and WordPress category structure if you are able to use the same listing type for all business listings. This will depend on whether they can share the same rating criteria and settings.

#Field Option → Field Group

This relation allows toggling an entire field group when a field option is selected in a field (select, checkbox, radiobutton).

The relationship is defined in the Controlled By section of the dependent field group using the Control Field and Control Value settings.

This relation has a similar use as the Field Option → Field relation, but allows you to group several fields together in a field group rather than having to create individual field relations.

#Output Format

The output format setting is quite versatile without the need to write any code. In cases where you need to do more, you always have the option of using the PHP Output Format.

There are several pre-defined curly-brace tags you can use in the output format. These include: {listing_id}, {title}, {alias}, {category}, {fieldtext}, {fieldtitle}, {jr_fieldname}.

The default output format is the {fieldtext} tag, and you can use that, together with custom HTML and the above tags to build things like affiliate links, clickable links and buttons, embed a video player, and more.

You can find some examples below:

• Combine Output of Multiple Fields
• Beautify Contact Phone Number
• Change Anchor Text for Website Field
• Affiliate Links
• Embed Media

#Combine Output of Multiple Fields

It's possible to combine the output of multiple fields into one field. This is also a feature of the banner custom field, but it can also be used on other fields that support this.

For example, if you have multiple address fields (e.g. street address, city, state and postal code) it can be a bit verbose to output all of those separately. Instead you can choose one field (e.g. the adddress field) and bring in the output of the others.

<div>{fieldtext}</div>
<div>{jr_city}, {jr_state} {jr_postalcode}</div>

In the above code {fieldtext} will show the output of the current field (e.g. address). When using this feature, it's important to:

• Make all fields required so you don't have hanging commas or too many spaces when some fields are not filled out
• Hide the other fields from view (e.g. listview, detailview), but leave them published

#Beautify Contact Phone Number

If you have a text field for a contact phone number, you can use the output format to add a link so it opens the phone application when clicked on a mobile phone, and also include a phone icon, in this case via an SVG icon:

<a href="tel:{fieldtext}" class="fwd-relative fwd-w-0 fwd-flex-1 fwd-inline-flex fwd-items-center fwd-justify-center fwd-py-4 fwd-text-sm fwd-leading-5 fwd-text-gray-700">
  <svg class="fwd-w-5 fwd-h-5 fwd-text-gray-400" viewBox="0 0 20 20" fill="currentColor">
    <path d="M2 3a1 1 0 011-1h2.153a1 1 0 01.986.836l.74 4.435a1 1 0 01-.54 1.06l-1.548.773a11.037 11.037 0 006.105 6.105l.774-1.548a1 1 0 011.059-.54l4.435.74a1 1 0 01.836.986V17a1 1 0 01-1 1h-2C7.82 18 2 12.18 2 5V3z"></path>
  </svg>
  <span class="fwd-ml-3">{fieldtext}</span>
</a>

The above example uses CSS class names available in JReviews.

#Change Anchor Text for Website Field

To change the website field anchor text to a custom text use this output format:

<a href="{fieldtext}">Visit Website</a>

To show the link as a button

<a href="{fieldtext}" class="jrButton jrBlue">Visit Website</a>

#Affiliate Links

If you are writing product reviews and want to include affiliate links, for example to Amazon.com, it's not necessary to copy the entire URL into the affiliate website field every time. Instead, you can use a text custom field where you enter the product code/number and then use that in the output format to build the complete URL:

<a href="https://www.amazon.com/dp/{fieldtext}?tag=AFFILIATE-ID">
  Buy this product
</a>

You can also add an image as the anchor text:

<a href="https://www.amazon.com/dp/{fieldtext}?tag=AFFILIATE-ID">
	<img src="/path/to/image.jpg" />
</a>

#Embed Media

The same approach can be used to embed any type of media. JReviews already comes an easy way to import and embed videos, but you may have media from other sources that you wish to embed. Using a YouTube example you can use either a website or a text custom field. In this example, we use a text field so all we need to add to the field is the YouTube ID.

<iframe width="560" height="315"
        src="https://www.youtube.com/embed/{fieldtext}"
        frameborder="0"
        allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
        allowfullscreen>
</iframe>

#Customize Layout of Custom Fields

Create your very own custom field layouts in output views (this doesn't apply for form layouts), using theme customizations.

In most views, the $listing and $review arrays contain the corresponding custom fields.

JReviews renders these fields dynamically, in a pre-defined fashion, using the code snippets shown below which you can find in many of the template files, especially in templates within the listings/ and reviews/ theme folders.

Listings

<?php echo $CustomFields->displayAll($listing,'content');?>

<?php echo $CustomFields->displayAll($listing,'list');?>

Reviews

<?php echo $CustomFields->displayAll($review,'content');?>

<?php echo $CustomFields->displayAll($review,'list');?>

As you can see above, the displayAll method receives the object array $listing or $review and specifies the context content or list.

content refers to a detail page view, whether it's the listing detail page or the review detail page.

Internally displayAll will check the display settings for each field set in the Fields Manager and decide whether it gets included in the current view.

The $CustomFields helper class contains other methods that allow retrieving the information for individual custom fields so you can create your own layout.

#Filter Field Groups

If you need to separate the display of a field group, or several field groups, you can pass a 3rd options parameter to displayAll array to filter the groups. The options parameter accepts both includeGroups and excludeGroups arrays.

The syntax to include one or more groups is:

<?php
echo $CustomFields->displayAll($listing,'content', [
  'includeGroups' => [
    'group-name1',
    'group-name2',
    'group-name3',
  ]
]);
?>

The syntax to exclude one or more groups is:

<?php
echo $CustomFields->displayAll($listing,'content', [
  'excludeGroups' => [
    'group-name1',
    'group-name2',
    'group-name3',
  ]
]);
?>

You can add one or as many group name aliases in the includeGroups and excludeGroups arrays. The group names can be found in the Field Groups manager.

If you are using the above code in a template that already shows custom fields, you should remove the existing code, or replace it, so the fields are not duplicated on the page.

#Show Individual Fields

For the control freak in you, an even more targeted approach to display fields is possible, so you can place them individually in the template.

Field Label

<?php echo $CustomFields->label('jr_fieldname',$listing); ?>

Field Text

This code will output the text of the field value where you place the code in the theme file:

<?php echo $CustomFields->field('jr_fieldname',$listing); ?>

Unformatted Field Text

You can also have a bit more control of the output by using additional parameters when you call the display method: $CustomFields->field($name, &$element, $click2search = true, $outputReformat = true)

The example below calls the brand field and turns off click2search and outputreformat advanced options:

<?php echo $CustomFields->field('jr_fieldname',$listing,false,false); ?>

The above also allows retrieving the text for field options that have associated images.

Field Value

To get the raw data for a custom field, without any formatting or HTML markup:

<?php echo $CustomFields->fieldValue('jr_fieldname',$listing); ?>

Field Value Multiple Options

For multiple select and checkbox fields that can accept multiple options, the fieldValue method returns an array instead of a string so you can't use the above syntax with echo. Instead you can join the values or parse them yourself using any PHP logic you want.

<?php echo implode(', ', $CustomFields->fieldValue('jr_fieldname',$listing)); ?>

#Conditionals Based on Custom Fields

Output something only when a field is not empty

<?php if ($CustomFields->fieldValue('jr_fieldname',$listing)): ?>

  <!-- Conditional output -->

<?php endif;?>

Output something only when the field value matches a specific text

<?php if ($CustomFields->field('jr_fieldname',$listing,false,false) == 'string'):?>

  <!-- Conditional output -->

<?php endif;?>

Output something only when an option is selected in a multiple select or checkbox field

<?php if (in_array('option-value', $CustomFields->fieldValue('jr_fieldname',$listing))): ?>

  <!-- Conditional output -->

<?php endif; ?>

#Custom Field PHP Formatting

Output formatting for custom fields refers 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 mold the output to your specific needs.

To use the PHP Based Formatting feature, 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 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);

For more examples, see the Custom Field PHP Formatting guide.

#FormBuilder Custom Field

The FormBuilder custom field uses a JSON Schema-based system to automatically generate custom forms, and can then process the stored data using the existing custom field output functionality, either through the PHP Output Format, or a custom template for the field.

A couple of the most important features enabled by the FormBuilder are:

• Replicator Inputs

  Inside the FormBuilder custom field, any input or group of inputs can be setup so that with the click of a button a new section is added. This also works with nested sections, so a section within a section can also be replicated. To visualize this, let's use the restaurant menu example. It's possible to setup a form with a main section and dishes inside. The main section (starters, entrees, desserts) can be replicated, and also the dishes within each section.

• Quick Re-order & Delete

  Replicator sections come with quick ordering and delete controls allowing the user to quickly move a section up or down, and to delete an entire section without affecting the remaining sections.

The field includes several examples that can be selected from a drop-down list to get you started:

• Business Hours (array)
• Restaurant Menu (nested arrays)
• Recipe (multiple arrays at the same level)
• Inventory (array)
• Computer Specifications (array)

#Getting Started

To use any one of the included examples follow these steps:

1. Create a new FormBuilder custom field
2. Under Advanced Options, select a Schema
3. Click on Load Schema to preview the form
4. Save the custom field

The template name for each example is automatically pre-filled in the PHP Output Format input below the Schema editor. Learn more about this setting in Custom Field PHP Formatting.

There are also a couple of useful FormBuilder-specific features in the field settings:

• If you change the Schema or use your own Schema, click on Update Form to preview the changes.
• Setting default values in FormBuilder is as simple as filling out and selecting them in Form Preview, then saving the custom field.

#Playground

Take the field for a test drive and see first-hand some of the example forms. Modify them or build your own. We even added some "How to" examples for working with Lists and Arrays.

#Form Schema

Each FormBuilder custom field requires a "recipe" that is used to build the form. This "recipe" is the JSON Schema.

You can use the playground to work on these examples.

Let's consider the Business Hours example. Below we are going to partially build out this example, starting with a single input, converting that to a replicator section, and finally using a list of options for weekdays and assigning that to the day input.

{
    "properties": {
      "day": {
        "title": "Day",
        "type": "string",
        "options": {
            "input_width": "15em"
        }
      }
    }
}

{
    "type": "array",
    "format": "table",
    "items": {
        "title": "Period",
        "properties": {
          "day": {
            "title": "Day",
            "type": "string",
            "options": {
                "input_width": "15em"
            }
          }
        }
    }
}

{
  "type": "array",
  "format": "table",
  "items": {
    "title": "Period",
    "properties": {
      "day": {
        "title": "Day",
        "type": "string",
        "$ref": "#/definitions/weekeday",
        "options": {
          "input_width": "15em"
        }
      }
    }
  },
  "definitions": {
    "weekeday": {
      "type": "string",
      "enumSource": [
        {
          "source": [
            {
              "value": "1",
              "title": "Monday"
            },
            {
              "value": "2",
              "title": "Tuesday"
            }
          ],
          "title": "{{item.title}}",
          "value": "{{item.value}}"
        }
      ]
    }
  }
}

You can see the complete solution for this example, and more, in the FormBuilder Playground.

#Field Output

FormBuilder custom field data is stored as a JSON object. The data format can be seen in the Default Value panel in Advanced Options.

Without any processing you'll see the output of the field appear as a JSON string. It's not possible for JReviews to automatically parse and render the output so it's always necessary to parse the output, first converting it into an array and then accessing the elements in that array. There are two options for doing this.

#PHP Output Format Setting

For simpler forms requiring less code it's convenient to use the field's PHP output format setting.

First, convert the JSON object into an array that will allow you to access the data or loop through the array. There is no need to use an opening PHP tag inside the PHP editor.

$data = json_decode($data, true);
// The line below allows you to see how the data is stored
prx($data);

#Output Template

To use an output template create the template file (e.g. contacts.thtml) in your custom theme in the fields_phpformat folder and clear the file registry in the JReviews administration.

Then fill out the Template Name setting with the file name (e.g. contacts).

Joomla

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

WordPress

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

First, convert the JSON object into an array that will allow you to access the data or loop through the array.

<?php
$text = json_decode($text, true);
// The line below allows you to see how the data is stored
prx($data);

When creating your own output templates, use the existing examples in the fields_phpformat folder in the default theme as reference.

#Example: Business Hours

#Hide Timezone

If your site is for a specific region only and you don't need the opening hours timezone input in the form Schema you can set a default timezone and hide the select list by modifying the timezone definition like this:

"timezone": {
    "id": "user-timezone",
    "title": "Your timezone",
    "type": "string",
    "$ref": "DEFINITIONS_PATH/timezones.php",
    "default": "Europe/Amsterdam",
    "options": {"hidden": true}
},

Click Update Form, and save the field.

#24h Format

To change the hour schedule to a 24 hour format, copy the template file from the default theme to your custom theme and modify the $twentyfourHourFormat variable to true:

$twentyfourHourFormat = true;

#Known Issues

#Pre-defined Examples Don't Load

If you use Admin Tools in Joomla and cannot load the examples in the FormBuilder settings you may need to adjust your .htaccess settings to allow access to files with the json extension and also allow direct access to the fields_formbuilder folder inside the default theme.

#Field Output Is Just A String

That's what the output looks like without a template. If you are writing your own FormBuilder Schema, you also need to write the output code to process the data as mentioned in the Field Output section above.

#Limitations

Because the entire FormBuilder field data is stored within a single field, this creates some limitations when compared to other types of fields:

• It's not possible to set a FormBuilder field as required
• It's not possible to include other custom fields inside the form
• The field cannot be used for advanced search/filtering nor click2search

#Cannot Create New Fields

If you are creating a lot of custom fields, at some point this may stop working. The reason is an inherent limit in databases for the number of columns in a table. To maximize the number of custom fields, there's a couple of things you can do:

1. Change number of Maximum Characters

2. Change the column data type from VARCHAR to TEXT

#Maximum Characters

Most field types use VARCHAR for the column data type, making it possible to add indexes and improve performance, especially for fields enabled for Click2Search.

When you create a custom field, it will default to a maximum of 255 characters. Most likely some of your custom fields don't need that many characters and reducing the maximum character setting will free-up space for new fields.

Go to the Fields Manager, click on a field, and click the Max. Data Length button to adjust the number of maximum characters. There are two numbers here. One is the current value set for maximum characters. And the other is the actual character length currently in use within this field.

For example, in a City custom field, the longest citiy name option could have 15 characters, while the maximum characters is set to 30, just in case longer values will be necessary later.

The maximum characters value should always be greater or equal to the actual used value. However, for Multiple Select and Checkboxes, the math is different because the required length will depend on the number of options chosen for the field. The storage format for these fields looks like this:

*option-1*option-2*option-3*

All values in a single string wrapped in asterisks. So the maximum characters set needs to account for this and shouldn't be set too low if you expect a field to have any number of options selected/checked.

#Column Data Type

If reducing the number of characters doesn't help, you can try changing the column data type of some of the text, radio, select, multiselect and checkbox custom fields from VARCHAR to TEXT.

This can be done through any database client, the most common one being phpMyAdmin.

Find the #__jreviews_content table and click on the structure tab. Then find the table columns that correspond to the fields you want to modify and choose TEXT for the data type.