This article draws significantly upon the field plug-in developer documentation. If you are already an experienced developer, you may wish to skip this article. However, if you are relatively new to software development, this article may help.
Field plug-ins are an excellent way to extend the capabilities of SurveyCTO. We have an extensive catalog of field plug-ins, but you may need something more specialized. Luckily, one of the best parts about field plug-ins is that you can make your own, and share them with the rest of the SurveyCTO community.
Even with no prior experience in programming, it is possible to learn how to build basic field plug-ins in a relatively short amount of time. If you have some experience with data analysis software that involves scripting like Stata or R, you'll have a distinct advantage, as these software packages already involve programming concepts. Even as a SurveyCTO form designer, you'll be familiar with concepts like variables (or "fields") and functions, which are also concepts in field plug-in design.
While not required, we also strongly recommend being familiar with version control, especially Git.
Anatomy of a field plug-in
Here is where you will define the basic structure of the field plug-in, and how it will be laid out. You will use HTML to state where the label, hint, text box, images, and whatever else your field plug-in will have. This file must be called template.html.
Here you will define the style and looks of your field plug-in. The main stylesheet file must be called style.css, but you can add other CSS files as well, which will be defined in the JSON manifest (see below).
Here is where you will define the behavior of your field plug-in. Here you will retrieve field plug-in parameter values, set the answer/value of the field, and other behavior of your form.
Once your files are ready, you can compress them into a ZIP file. Make sure the ZIP file ends in .fieldplugin.zip. This ZIP file will be your field plug-in.
Starting a field plug-in
Look through the field plug-in catalog, and choose a field plug-in you would like to build off of. Then, open that field plug-in's repository on GitHub. For example, if you would like to create a modified version of the standard text field, go to the repository for the baseline-text field plug-in.
Once you have chosen the field plug-in you would like to build off of, either fork the field plug-in, or download the field plug-in files. You can then start making your own changes and adjustments.
Working with Git version control
Git is version control software that allows you to to keep track of the changes made to source code, called "commits". That way, it is easy to keep track of what changes have been made, and easily undo changes if a commit turns out to be a mistake.
GitHub is a popular software repository hosting service. It is where we keep all of our field plug-ins, and you should too. That way, other SurveyCTO users can take advantage of the amazing tools you will build. Check out this page for more information about Git and GitHub.
|Using version control is not strictly necessary for developing field plug-ins, and you can instead just download the files and edit them. However, we recommend learning the process of software development while learning how to build field plug-ins, which includes version control. This will help in the long run.|
Working on your field plug-in
Field plug-ins usually take parameters. This is a great way to customize a field plug-in so that you don't have to create and use a different field plug-in for slightly different fields.
However, whenever possible, you should use features that are already a part of SurveyCTO. For example, the ranking-choices field plug-in uses choice list choices for its choices instead of them being defined as parameters.
Retrieve parameter value: getPluginParameter() function
var timeUnit = getPluginParameter('time-unit')
This is also why it is important to give your parameters meaningful key names.
Retrieve parameter value: From an array of objects
Parameters are also stored in an array in the fieldProperties object, so they
var timeUnit = fieldProperties.PARAMETERS.value
However, this is not recommended, because it means the parameters will have to be in a specific order. For example, the extra buttons field plug-in needs to be flexible enough not only to accept any number of buttons, but also be able to customize the warning labels. Since there will be an unknown number of extra buttons, and several parameters that are optional, so it is much easier for the form designer if the parameter order does not matter. Otherwise, it will not be known if those optional parameters are other buttons or not.
If you are a beginner, retrieving data from an array (kind of a list of variables) is somewhat like using the selected-at() SurveyCTO function to retrieve data from a space-separated list or a select_multiple field. For example, with a SurveyCTO select_multiple field called "crops_grown", you would use
In field plug-ins, each parameter in the array is an object. Going into how objects work is beyond the scope of this article, but to retrieve the value of the parameter, add
Metadata is a great way to keep track of information that should not be saved as the answer, but should still be tracked for the field plug-in in case the enumerator returns to that field. For example, in the field plug-in counter-with-timer, the counter value and the time remaining are stored in the metadata. That way, if the enumerator starts the timer, but then leaves the field before saving the answer, then they can continue the counter and timer where they left off.
To store the metadata, use the setMetaData() function, like this:
To retrieve the metadata, use the getMetaData() function, like this:
var metadata = getMetaData()
You can also retrieve metadata from another field. Simply use the plug-in-metadata() SurveyCTO function in a SurveyCTO expression. For example, to retrieve the field plug-in metadata from the field called "timer", you can use this expression:
To learn more, check out our documentation on using expressions.
Note: The plug-in-metadata() function was added to SurveyCTO 2.70.3, which is currently only available as an early release version. To use this function and other newer features, check out our support article on the SurveyCTO Collect for Android early release.
- If to make the field plug-in look as much like standard field plug-ins as possible, use included CSS classes, such as
Testing your field plug-in
Testing in a web browser
When you are ready, you can start uploading the field plug-in to your server. Every time a new version is uploaded, make sure you increase the version number in the manifest. For example, if version 1.0.0 has been uploaded already, increase the version number to 1.0.1 before uploading. Otherwise, you will have to remove the field plug-in, save (sometimes even save-and-deploy), and then re-add the field plug-in before saving again.
|Note: SurveyCTO support will not help you troubleshoot the actual code of the field plug-in, but we are happy to help with any questions you might have on how the API works, and we can also offer tips and general guidance. You can also post to the SurveyCTO forums to ask for help from fellow users.|
Sharing your field plug-in
Have you created a field plug-in that could be of great help to other SurveyCTO users? Let us know! We may even add it to our field plug-in catalog.
Make sure your field plug-in repository has a readme document, a sample form, and other ways to make sure SurveyCTO users can quickly and easily learn and use your field plug-in. To learn more, check out our support article on best practices for sharing field plug-ins.
Do you have thoughts on this support article? We'd love to hear them! Feel free to fill out this feedback form.