How to test field plug-ins

This support article is a supplement to our documentation on testing field plug-ins. For related articles, check out further reading below.

If you make a change to a field plug-in, and you want to test that change, it can be time-consuming to have to re-create the field plug-in file and re-upload it to your form every time. Luckily the SurveyCTO test view has a tool you can use to quickly apply and test the changes you have made, called the field plug-in console. This tool can provide helpful insight into your field plug-in, and also make testing changes much easier.

How to open

First, open the form using the test view, which we describe in section 1 of our support article on how to troubleshoot forms using the form inspector.

When you get to a field with a field plug-in, you may notice a new panel on the left with this button:

Click that button, and it will open the field plug-in console.

Modules

Field plug-in info

Exactly what it sounds like, this is general information about the field plug-in, including the name and version defined in the manifest.json file. If you click SHOW MORE, you can view other information as well.

Current values

If your field plug-in uses metadata, click the Refresh button to view the current metadata value (you can learn more about field plug-in metadata in the API on field properties).

Code modules

The bottom three boxes store the code for the three main field plug-in files: HTML for the template.html file, CSS for the style.css file, and JS for the script.js file. These boxes contain all of the code (i.e. content) for those files. If you click into the blue boxes, you may notice that you can edit the code from there. This is where you will paste in your updated code so you can test it.

When you make a change to a field plug-in file in your text editor, and you would like to see how it looks in the form, follow these steps:

Copy all of the text in the file.
In the field plug-in test view, click into the blue box for the code you just copied.
Select all of the text, and then replace it by pasting in the text you had copied from the text editor (you can also delete all of the text already there, then paste in the text you had copied). The old code should be gone, replaced by the new code (though the new code will likely be similar).
Repeat steps 1-3 for each file you edited.
Click the blue Reload button to reload the field plug-in with the latest code you just pasted in.

Check out this video for an example:

Once you are satisfied with your changes, you can save a new version of the field plug-in file, and upload it to the form so it can be used with the deployed form version.

Other notes

Deploying changes

Changing the code in the field plug-in console will not change it for the deployed form. So, once you are ready, create a new version of the field plug-in file, and re-upload it to the form. Be sure to increase the version number in the manifest.json file before creating the new field plug-in file.

Other fields in form using that field plug-in

If you change the code for the field plug-in in one field in the test view, it will change the field plug-in for all fields that use it. That way, you don't have to paste in the new changes for every field.

Reverting changes

If you don't like the changes you made, and you would like to go back to the version before you pasted in the new code, click Revert. Your changes will still be saved, and you can click Load edited version to reload the saved version of the field plug-in.

Returning to test view

Your changes are saved even when you exit the test view. When you re-open the online form designer, there will be a box that says Edited version available. To continue working with the code you pasted in before (instead of uploading in a new field plug-in file), simply click the Load edited version link. To get rid of the saved version, click Discard edited version.

If you open the test view, and it has the box to the right instead, it means the field has already loaded with the edited version of the field plug-in.

Additional field plug-in files

If you have additional CSS or JavaScript files attached to your form, you cannot edit them from the field plug-in console. While testing, you may want to temporarily move the code to the main files so you can test them more quickly and easily.