Previous Next

While every SurveyCTO field type has a standard way of appearing, operating, and being configured, the text, integer, decimal, select_one, and select_multiple field types also support field plug-ins. These plug-ins can extend or change the appearance, functionality, and customizability of the standard field types, in order to meet different needs. You can use field plug-ins that other people develop and share, or you can develop your own.

To use a field plug-in, you need to do two things:

1. Attach the field plug-in to your form.
2. Select the field plug-in at the appropriate field(s).

Attaching a field plug-in to a form

Attach the “[name].fieldplugin.zip” file to your form. If you're using the online Form Designer to edit your form, you can attach a field plug-in by opening Form settings and scrolling down to the Attachments section. You may also attach a field plug-in while editing a field's appearance option (see below).

If you're uploading spreadsheet form definitions, you can attach it just like you would do with any other form attachment (like attached .csv files or images).

Selecting a field plug-in at a field

If you're using the online Form Designer, when editing a field, scroll down to the appearance setting in the Other options section. If you select the Use a field plug-in to render this field checkbox, you will see a dropdown list of all the available field plug-ins that are attached to your form and support the current field type. If none are available, you can select the Add new field plug-in option and attach a new one.

If you're manually editing the spreadsheet form definition, you can specify the field plug-in to use in the appearance column of a field. For each field that should use your plug-in, set the field’s appearance to “custom-[plug-in name]”.

Example

Let’s say you have a field plug-in with the filename “myplugin.fieldplugin.zip”. You would enter custom-myplugin in the appearance column for each field that should use it.

What to expect

Please keep in mind, when you use a field plug-in, that plug-in will completely take over the appearance of a field. Make sure you trust the developer before you use their field plug-in and, as always, perform adequate testing before you deploy your form. Some other things to keep in mind:

• A field plug-in may not support your current appearance options. Check the developer's documentation to see what options are supported before you attach it to your form, and test it thoroughly before you start actually collecting data.
• The "Label display behavior" setting (in Collect's Admin Settings) will have no effect on a field plug-in.
• When using SurveyCTO Collect on iOS, the on-screen keyboard may not automatically appear when you arrive on a field that uses a field plug-in. In that case, you will simply need to press once on the actual input field and the on-screen keyboard should appear.

Parameters

Some field plug-ins will accept or even require parameters. Each field plug-in can have slightly different requirements with regard to parameters, so be sure to read the developer's documentation carefully.

If you're using the online Form Designer, adding parameters is easy. Once you've selected a field plug-in in the appearance section, you will see an input box labeled Plug-in parameters. Enter a comma-separated list of parameters according to the requirements of the field plug-in.

Example

Let's say you have a field plug-in that requires min and max parameters; in that case, you could enter "min=0, max=10" in the box. If the same field plug-in accepts an optional parameter for color, you might enter "min=0, max=10, color='blue'".

If you're manually editing the spreadsheet form definition, you can specify parameters when you specify the field plug-in in the appearance column. Add a comma-separated list of parameters after the plug-in name, enclosed by parentheses.

Example

If your field plug-in file is named "slider.fieldplugin.zip" and accepts parameters for min and max, your appearance column could look like this: "custom-slider(min=0, max=10)".

Note: parameters can evaluate expressions and field references. So if you want to define a parameter's value based on the response from a previous field, you could do something like this: "min=0, max=${field}".

To learn more about field plug-ins, including how to add your first field plug-in to your form, and a catalog of all available field plug-ins, check out our Guide to field plug-ins

.

Developing your own field plug-ins

If you're interested in developing your own field plug-ins, please see the developer documentation.

Previous Next