Writing Custom Form Fields

Because every game is different, you may want to write a custom FormField to include specific information with your reports. The FormField API provides a quick and easy way to start adding your own custom sections in your reports.

Lets look at how we can create a simple field that adds the text "Hello World!" to a custom section.

First, we'll need to implement the abstract FormField class in our new script:

using EasyFeedback;
	
public class MyFormField : FormField 
{
	public override void FormClosed() 
	{

	}

	public override void FormOpened() 
	{

	}

	public override void FormSubmitted() 
	{

	}
}

In Awake(), FormField finds the FeedbackForm in parent game objects, and adds listeners for FormClosed, FormOpened, and FormSubmitted to their respective callbacks in FeedbackForm.

Note

If you override the Awake method in FormField, be sure to call base.Awake() so that the event listeners are properly registered.

Now, let's add some code to add our custom section to the report:

using EasyFeedback;

public class MyFormField : FormField 
{
	public override void FormClosed() 
	{

	}

	public override void FormOpened() 
	{

	}

	public override void FormSubmitted() 
	{
		// add section if it doesn't exist already
		if(!Form.CurrentReport.HasSection(SectionTitle))
			Form.CurrentReport.AddSection(SectionTitle, SortOrder);
		
		// set section text
		Form.CurrentReport[SectionTitle].SetText("Hello world!");
	}
}

Let's break down what's going on here.

First, we added all of our code to the FormSubmitted() function. This function is called by the FeedbackForm right before the current report is sent off to Trello. It is recommended that you add any last-minute or one-time information to the report in this function.

Let's look now at each line in the function:

// add section if it doesn't exist already
if(!Form.CurrentReport.HasSection(SectionTitle))
	Form.CurrentReport.AddSection(SectionTitle, SortOrder);

Form is a reference to the parent FeedbackForm of this field, and Form.CurrentReport is the current :ref:report for the form. The current report is reset by the FeedbackForm every time it is submitted to Trello. CurrentReport.HasSection(string name) returns whether or not the current report has a section with the given name. SectionTitle is a string that serves as the title of this field's section, and is set in the editor. So, the first line checks if the current report has the section set in the editor.

If the report does not already have the section, we go ahead and add it to the report with CurrentReport.AddSection(string name, int sortOrder). SortOrder is another value set in the editor, and serves as the order of this field's section in the report (lowest first).

// set section text
Form.CurrentReport[SectionTitle].SetText("Hello world!");

Sections on the report are referenced by name via the report's indexer. Here, we're getting the section we just added to the report, and setting its text contents to the string "Hello world!"

Now that we've written our custom field, let's add it to our feedback form!

First, we'll add a new child to the Feedback object for our field, and add the "MyFormField" script to it.

Note

Objects with FormField components must be a child of the Feedback object to work properly. They can be placed at any level in the hierarchy, as long as they are a child of the Feedback object. For example, in the Feedback prefab, FormFields that collect metadata information are organized under the MetadataCollectors object.

In the inspector, you'll see fields for the SectionTitle and SortOrder variables. We'll go ahead and call our section "My Custom Section" and we'll set the sort order to 0 so that it appears at the top of the report.

Let's test our new section! Run your scene, and submit a report. If all went well, our new custom section will appear at the top of the report!