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.
Prerequisites
You should have at least a basic understanding of HTML, JavaScript, CSS, and JSON. You should also know how to use field plug-ins. If you have never used field plug-ins before, check out our documentation, as well as our guide to field plug-ins. Also be sure to review the links on the field plug-in resources page.
While not required, we also strongly recommend being familiar with version control, especially Git.
Anatomy of a field plug-in
There are four parts to a field plug-in: the HTML template, the CSS styling, the JavaScript code, and the JSON manifest. When they are complete, they will be compressed into a ZIP file that ends in .fieldplugin.zip. That ZIP file will be your field plug-in to be uploaded to the server. An overview is below, but for full details, check out the field plug-in definition documentation.
HTML template
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.
CSS styling
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).
Javascript code
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.
The main script file must be called script.js, but you can add other JavaScript files as well, which will be defined in the JSON manifest (see below). For example, the ranking-choices field plug-in uses the SortableJS library, as well as its own script.js file.
JSON manifest
Finally, a JSON file will define other details and metadata about your field plug-in. This will include the field plug-in name, the author, version number, extra JavaScript files that will be used, and more. This file must be called manifest.json.
ZIP file
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
When creating a field plug-in, especially your first field plug-in, it is good to start from a base, rather than start from scratch. That way, much of the HTML, JavaScript, and other files are ready for you, even the license file. All you have to do is make adjustments to fit your needs.
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
As you work on your field plug-in, be sure to have the API reference handy for quick reference. It contains details on how to use the different functions and tools available in SurveyCTO field plug-ins. Look over that guide to learn how to reference field properties in your HTML with mustache tags, in JavaScript with the "fieldProperties" object, and the many built-in functions you can use. Also check out the called global JS functions to see which functions you need to define in your field plug-in.
Parameters
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
To use parameters in your field plug-in, it is best to use the getPluginParameter() JavaScript function. The function takes the the key of the parameter as its own parameter, and returns the value of the parameter. For example, in the counter with timer field plug-in, the "duration" parameter defines how much time the timer should start with. Check out its JavaScript file: this line of code is used to retrieve that duration:
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 so they can also be retrieved with bracket and dot notation, like this:
var timeUnit = fieldProperties.PARAMETERS[1].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 JavaScript, you use bracket notation to specify which value you would like. If the array object is called "cropsGrown", then 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
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:
setMetaData(value)
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:
plug-in-metadata(${timer})
To learn more, check out our documentation on using expressions.
More tips
- If your field plug-in should look different depending on the platform (e.g. Android, iOS, or web forms), check to see if the respective CSS classes exist. See this in practice at the top of the baseline-text JavaScript code.
- If to make the field plug-in look as much like standard field plug-ins as possible, use included CSS classes, such as
default-question-text-size.
Testing your field plug-in
You can use the field plug-in console inside the form designer to test your field plug-ins during development. This console allows you to directly edit the HTML, CSS, and main JavaScript files. You can then refresh the field plug-in in the browser to see your changes. Just remember to use the field plug-in's most up-to-date code in the console.
To use the field plug-in console, add a form to the server that includes a field that uses the field plug-in. Make sure the field plug-in is attached to the form. Then, open the form in the test view, and go to the field with the field plug-in. Click the </> on the left, and the field plug-in console will open. Check out the documentation to learn more.
Click this button to open the field plug-in console
| 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. |
Compatibility
Make sure the JavaScript features you are using are compatible with the device(s) that will be used for data collection. Some older versions of Android and iOS will not support newer JavaScript features, such as let declarations. For more detail, check out this PDF.
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.
0 Comments