FormBuilder Custom Field

Build custom functional data-entry interfaces and outputs in just a few steps. The FormBuilder custom field comes with several ready-to-go examples including hours of operation, recipes, and restaurant menus.

Overview

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, lets 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. However, creating custom schemas and output templates is not included as part of JReviews support.

Development & Support
Customizations are not included with support. We provide this information to make it easier for developers to extend the functionality. From time to time we may have some availability for custom work. Get in touch to see if there's an opportunity to work together.

Getting Started

The included examples listed below each come with its a JSON Schema and custom output template.

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

To use any one of them 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're 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.

Visit the Playground

Form Schema

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

You can use the playground to work on this 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.

1 Creating Day Input

Let's start with a single day input defined under properties and include a day object with: title, type, and options.

The options key is optional and allows modifying the output like changing the width, height, visibility, etc.

The day key will be used as the input name and can be used in the output template to access the stored value for the selected day.

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

2 Add Replicator Functionality

To add replicator functionality we need a section denoted as items which can hold one or more inputs, and apply the array type to that section.

To control the button text for the replicator functionality, we use the items.title property, in this case set to Period.

The format property allows modifying the way the inputs are rendered, in this case as a table with a single heading above the corresponding inputs, instead of duplicating the label for each input.

The field should now show button that everytime it's clicked adds a new period section with the day input.

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

3 Add Weekday Options

The final step for this example is to replace the day text input with a list of options.

We define the list of options separately under the definitions.weekday property. The example only includes a couple of days for illustration purposes. The same approach can be used for hours, and allows re-using the definiton for open and close times.

Now assign the weekday definion to the day input using the $ref attribute.


{
  "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 is 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 requering less code it's convenient 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

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 modying 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.

Business Hours: 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;

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 adv. search/filtering nor click2search

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.