Guide to field plug-ins (how to customize fields)

Avatar
Amrik Cooper
Follow

SurveyCTO supports the extension of the appearance and functionality of basic field types using field plug-ins, significantly expanding the data collection capabilities of the SurveyCTO platform. For a high-level overview of field plug-ins, see our blog post that introduces field plug-ins. For the basics of how to use field plug-ins, see the product documentation. In this guide, we're going to introduce you to field plug-ins and explain how to get started.

1. What do field plug-ins do?

Field plug-ins are an extension of the concept of the field appearance property in SurveyCTO. Changes to the appearance of fields can be radical, effectively offering brand new field types, or as subtle as offering refinements to how recognized field types currently work. Field plug-ins can also help advanced users integrate with web services to trigger actions, receive results, and store them. What hasn't changed is that a field stores data that's input into your form, but everything about the process of generating the value that is stored can change using a field plug-in.

Strategically, think of field plug-ins as a way to adapt your data collection tool to new project requirements. For example, we’ve created a few plug-ins that are used in our computer-assisted telephone interviewing (CATI) starter kit for those looking to transition away from face-to-face data collection.

To understand more clearly, the best thing you can do is to try out a few plug-ins.

2. Where to find plug-ins

The SurveyCTO team maintains a curated catalog of field plug-ins that we consider exceptionally helpful or useful. To find a new plug-in for your form, this should be your first stop:

The SurveyCTO field plug-in catalog

If you're trying to develop your own field plug-ins, SurveyCTO has created several field plug-ins specifically to help you learn. You can find a list of these at the bottom of the developer documentation home page.

In addition to those two curated lists, you can find more field plug-ins by searching GitHub for the “scto-field-plug-in” topic. GitHub is a platform for developers from all over the world to share their work and collaborate with each other. Since anyone can build their own field plug-in and share it on GitHub, you should make sure you trust the developer before using a field plug-in. Click here to search GitHub for the scto-field-plug-in topic.

3. Getting started with a plug-in

Click here to open the presentation in a new tab

Let's say that while reading the field plug-in descriptions in the catalog, you happen upon one that you would like to try. From the catalog, you'll find a direct link to download that field plug-in file, as well as links to any available documentation, guides, and example forms for the plug-in.

You should always first read the plug-in documentation to get an idea of what the plug-in does, what options it supports, and what parameters need to be configured (if any). Most field plug-ins will include an example form, which you can use to test it before integrating it into your own form designs.

To deploy an example form with a field plug-in:

  1. Download the field plug-in .zip file and example form.
  2. Visit the Design tab of the server console, and click on "+" on the left.
  3. Pick the Upload form definition option.
  4. Select the example form in the first +Select file option.
  5. Select the field plug-in .zip file in second +Select file option for media files (just like you would with any CSV or media file).
  6. Click on Upload, and try it out in the Test view, or on SurveyCTO Collect (version 2.70+).

Users of the online form designer looking to use field plug-ins can specify them while configuring or editing a supported field type. Navigate to the field's appearance options and check the box to Use a field plug-in to render this field. You'll see options to either select a field plug-in that's already attached, or to upload a new one.

4. Combining field plug-ins with built in appearance options

Spreadsheet form designers can simply copy the appearance specified in the sample to get started. Whether you're using the online form designer or a spreadsheet form definition, when called for, you'll need to specify the field plug-in parameters as discussed in the field plug-in's documentation (very similar to setting the parameters for an audio audit field).

If the field plug-in supports built-in appearances, you can add those to the beginning of the appearance property, before the reference to the field plug-in, separated by a space (this is just like how you would combine built-in appearance options, like randomized quick). For example, if you would like a field that uses the baseline-select_one field plug-in to have the "quick" appearance, you would use this for the appearance of that field:

quick custom-baseline-select_one

A list of supported appearances will be listed in the README of the field plug-in. Also, for select_one and select_multiple fields, the "randomized" appearance is almost always supported; it is not typically mentioned in the README, since the randomization is established outside of the field plug-in.

For more information, please read the documentation topic on using field plug-ins.

5. Developing your own field plug-ins

Anyone with an understanding of HTML, CSS, and Javascript can experiment with and develop their own field plug-ins. To get started learning how to develop field plug-ins, head over to the developer documentation home page. There, you’ll find instructions, reference materials, and several plug-ins designed specifically to help you learn. You can also learn the basics of field plug-in design in our guide to creating field plug-ins and this guided development exercise.

Even if you lack the experience or time to learn, you might consider hiring a web development professional to design field plug-ins according to the specifications of your project. Whichever way you approach field plug-in development, we have resources to help you get started in the developer documentation including templates.

6. Share your field plug-ins!

Share your work! We encourage you to list field plug-ins in your own public GitHub repo. Please be sure to read our guidelines on sharing your field plug-ins. If you want to help others improve their data collection using your field plug-ins, write to us as support@surveycto.com and let us know about the plug-ins you've created.

7. Feedback on field plug-ins

Feedback is crucial to improving SurveyCTO. Even at the bottom of this article there is a link you can use to provide feedback on this article. We also want your feedback on field plug-ins. We ask that you start a user forum post (you'll need to log in) to provide feedback.

Give your post a good title, and link to the field plug-in in question for clarity. We're happy to discuss fixes and improvements!

8. Field plug-in resources

To learn more about field plug-ins, and learn what is available, check out these additional resources.

Using field plug-ins

Creating 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

Please sign in to leave a comment.