Extra button

Warning

Description

Use this field plug-in to add extra buttons to your text, integer, or decimal field. When a button is pressed, and the field value is currently blank, that button's value will be saved as the field value. If the field already has a value when pressing a button (other than the value of the pressed button), a warning message will confirm if you would like to replace what you already have.

You can specify exactly what each button says, and what its value should be (for example, you can specify that when "I don't know" is selected, then the field should have a value of -99). You can use the parameters to specify as many buttons as you would like. The label of the button selected will be stored in the metadata for that field.

The default warning message is:

Warning: This field already has a value. Are you sure you would like to replace it?

However, it can be customized using the parameters.

This field plug-in also inherits functionality from the baseline-text, baseline-integer, and baseline-decimal field plug-ins.

Features

• Add extra buttons to text, integer, and/or decimal field.
• Customize button value and text
• Add as many buttons as needed
• Warning if button pressed when field has a value
• Supports multiple layout configurations, including stacked and dynamically sized buttons
• Fully supports multi-language forms with localized button labels, values, and warning messages

Data format

If a button is not used, then the data will be whatever is in the text box. When a button is used (and confirmed if applicable), then the value of that button (as specified in the parameters) is set as the field value.

You can also retrieve the label of the button selected using the SurveyCTO plug-in-metadata() function.

How to use

Getting started

1. Download the sample form from this repo and upload it to your SurveyCTO server.
2. Download the extrabuttons.fieldplugin.zip file from this repo, and attach it to the sample form on your SurveyCTO server.
3. Adjust the parameter if you would like to use a different unit (see below).

Parameters

Name	Description
button# (required)	See button parameters below to learn more.
value# (required)	See button parameters below to learn more.
warning (optional)	Used to customize the warning message that will appear when the enumerator presses a button when the field already has a value. The value of this parameter will be displayed instead of the default warning message.
yes (optional)	What will be displayed instead of "Yes" in the confirmation.
no (optional)	What will be displayed instead of "No" in the confirmation.
autoadvance (optional)	If this parameter has a value of 1, then when a button is pressed, the field will auto-advance to the next field, similar to the "quick" appearance in select_one fields. If the field already has a value other than the value of the button pressed, then it will first display the warning, and then if "Yes" is pressed, the field will auto-advance.
dynamic (optional)	If set to 1 or yes, the buttons will auto-resize to fit their labels by wrapping text. If not set, the plug-in uses fixed-width buttons and shrinks text to fit.
stacked (optional)	If set to 1 or yes, the buttons will appear stacked vertically. Otherwise, buttons will appear inline horizontally.

Button parameters

For each extra button you would like to add, you will need a label, called "button", and a "value". For the parameter name, take the parameter name, and add the button number. For example, the parameter for the label of the first button will be button1, the parameter for the label of the second button will be button2, and so on. The parameter for the value for the first button will be value1, the parameter for the value of the second button will be value2, and so on. So, if you wanted one button with the label "I don't know" and a value of -99, and another button with a label of "Refused" and a value of -88, you would use this appearance:

custom-extrabuttons(button1="I don't know", value1=-99, button2='Refused', value2=-88)

You can add as many or as few buttons as you'd like.

Be sure to update your constraint so it accepts the button values as values.

Understanding Layout Options (dynamic and stacked)

The dynamic and stacked parameters control how the extra buttons are displayed. Here's how they work individually and together:

• Default (neither dynamic nor stacked set): Buttons appear inline (horizontally) next to each other. They have a fixed width, and if a label is too long for the button, the text size will shrink to fit.
• stacked=1 only: Buttons are arranged vertically, one above the other. They still have a fixed width, and long labels will shrink to fit within that width.
• dynamic=1 only: Buttons appear inline (horizontally). Their width adjusts automatically to fit the length of their labels. If a label is very long, the text will wrap onto multiple lines within the button.
• dynamic=1 and stacked=1: Buttons are arranged vertically. Their width adjusts to fit the available screen space, and the label text will wrap onto multiple lines within the button if it's too long to fit on one line. This combination prevents text from shrinking and ensures readability for longer labels in a vertical layout.

Multi-language support

This field plug-in supports multi-language forms by allowing parameters to be specified for specific languages using a single colon syntax, such as button1:french, value1:spanish, or warning:french. When the form is displayed in a particular language, the plug-in will automatically use the appropriate language-specific parameters if available. If a language-specific version is not provided, it will fall back to the default.

You can localize any of the following: button labels, button values, the warning message, and the confirmation labels (yes and no).

Example

Here is an example of what the appearance of a field using this field plug-in could look like, using dynamic sizing, stacked layout, and multi-language labels:

  custom-extrabuttons(
    warning='This field already has a value. Replace it?',
    yes='Yes',
    no='No',
    button1="I don't know", value1=-99,
    button2="Refused", value2=-88,
    button1:french="Je ne sais pas", value1:french=-99,
    button2:french="Refusé", value2:french=-88,
    button1:spanish="No lo sé", value1:spanish=-99,
    button2:spanish="Rechazado", value2:spanish=-88,
    warning:french="Ce champ a déjà une valeur. Voulez-vous le remplacer ?",
    warning:spanish="Este campo ya tiene un valor. ¿Desea reemplazarlo?",
    yes:french="Oui", no:french="Non",
    yes:spanish="Sí", no:spanish="No",
    dynamic=1,
    stacked=1
  )

In this example, the plug-in will show different button labels and messages depending on the form language (English, French, or Spanish), and the buttons will be stacked vertically and dynamically sized to fit their text.

Default SurveyCTO feature support

Feature / Property	Support
Supported field type(s)	text, integer, decimal
Default values	Yes
Custom constraint message	Yes
Custom required message	Yes
Read only	Yes
media:image	Yes
media:audio	Yes
media:video	Yes
number appearance	Yes
numbers_decimal appearance	Yes
numbers_phone appearance	Yes
show_formatted appearance	Yes

More resources

• Sample form
  You can find a form definition in this repo here: extras/sample-form.

• Developer documentation
  More instructions for developing and using field plug-ins can be found here: https://github.com/surveycto/Field-plug-in-resources