Learn how to create a field plug-in - a guided example

This is a supplement to our webinar on developing field plug-ins, aimed at beginners. We also suggest that you see our guide to creating field plug-ins.

If you're interested in creating field plug-ins, this article can lead you through an example. This article is a companion to a recorded  webinar demonstration which we suggest you watch. You'll be able to learn the following:

  • How to customize a baseline field plug-in template.
  • The basics of editing HTML, CSS, JavaScript, and JSON files.
  • How to design a simple field plug-in that adds a currency formatting symbol to a decimal type field.

Resources

You'll need the following files to complete this exercise:

You'll want to unzip the baseline and format-symbol field plug-ins to access the files you'll work with. You'll work using the baseline field plug-in files.

Step 1: Deploy your form with baseline field plug-in

Deploy the form design with the baseline field plug-in as an attachment.

To test the changes you make to your field plug-in, use the field plug-in console, as demonstrated in the webinar. This is faster than packing your files in a zip file and re-attaching it to your form. First, reveal the field plug-in console on the left, and drag it out to the width you prefer. Then, when you make changes to your code using a text editor, paste the updated code into the correct box of the field plug-in console. Click Reload to reload the field with the updated field plug-in code you just pasted in.

You could edit code in the console, but be careful not to close the browser tab as you may lose changes.

If you're not confident about where to paste a section of code, compare to the matched file type inside the format-symbol field plug-in. For example, the code in the scrip.js file should be pasted into the JS box.

Step 2: Add a label to the HTML

This step is covered in the webinar.

Unzip the baseline field plug-in folder, and open each file (or the whole folder) in your text editor. Open the template.html file. This file defines placeholders for everything you expect to see with that field type. Scroll to the bottom, and add a new label placeholder between lines 43 and 44 (in the section defining when the field is not read-only):

<label 
    id="symbol" 
    for="decimal-field"
>$
</label>

At this point you can save your work and test the field plug-in to see the $ sign. However, the placement is not quite right (the $ sign appears on the row above the field). Ideally you want the symbol to be on the same line as the input field. You'll need to modify the CSS to change that (see step 3).

Step 3: Edit the the CSS file

This step is covered in the webinar.

Open the style.css file. This file contains "classes" which are styling rules that can be applied to elements in the HTML.

The $ sign in the HTML appears above the field because the field is too wide. You can change this by modifying the .response class. The width is set to 100% in the baseline field plug-in, but you can lower this number to 80% (or less) to create space for the $ sign label.

.response {
    /* add style rules here to change how the response appears */
    width: 80%; /* adjust this width to resize the input box*/
    margin: .5rem 0;
    padding: .5rem;
    border: 1px solid #047CC2;
    box-sizing: border-box;

You may wish to make the dollar sign stand out more by making it bold. You can do this by adding a new class. You can copy and paste this code into the bottom of your CSS file:

.symbol {
    font-weight: bold;
}

To apply your new class, you will have to update your HTML file as well. Apply the class to your label by making this change to the label with the dollar sign in the HTML file:

<label 
    id="symbol" 
    for="decimal-field"
    class="symbol" 
></label>

Again, you can test these changes using the field plug-in console.

You could also make your currency symbol bold in the HTML itself by enclosing the symbol in bold HTML code (<strong>$</strong>). However, it is best to manage this in CSS.

Step 4: Control the symbol from the JavaScript

This step is covered in the webinar.

You now have a working field plug-in that you can use, but it only displays a $ symbol before text, and not any other character. Field plug-ins are much better when form designers can easily customize them using parameters. For example, what if the form designer would like the text to start with a € instead of a $?. To do this, we first need to edit the HTML to remove the hard coded $ symbol:

<label 
    id="symbol" 
    for="decimal-field"
    class="symbol" 
></label>

Now you will need to modify the script.js file. Open it up, and copy these lines of code and paste them below the "Detect platform" section of code (right above where it says // Find the input element on row 6):

var symbolToUse = getPluginParameter("symbol")
var symbolPlace = document.querySelector("#symbol")
symbolPlace.textContent = symbolToUse

Here, you are defining a variable ("var") that will store the symbol we want to place on screen. The variable's value comes from a field plug-in parameter. If you have questions about these lines of code, take a look at the final JavaScript - but be warned! This link contains spoilers for step 6. Do not do this unless you aren't concerned with learning what is covered in step 6. 

Step 5: Update your form design

This step is covered in the webinar.

Before you see any changes from step 3, you'll need to update your form design to use the parameter you defined. If you look at the decimal field's appearance, you'll see that it says custom-baseline-decimal. That's not the final name for our field plug-in; we'll ignore that for now, and add a parameter by revising to the following:

custom-baseline-decimal(symbol = "$")

The symbol to use is still $, but it is dynamically determined by the parameter. It could also be €, £, or anything else. Test the field plug-in with different currencies by revising the value specified by the parameter.

As an alternative to what you see in the webinar, you can click on the toggle button in the upper-right to swap to the form design view, make changes, and swap back to the test view.

Step 6: Pack your field plug-in

This step is covered in the webinar.

When you are ready, it is time to pack the field plug-in. You can do this at any time (ideally when you begin a field plug-in project). Edit the JSON file to name the field plug-in, update the version number (start from 1.0.0), and provide an author's name.

{
    "name" : "Format symbol",
    "author" : "Dobility",
    "version": "1.0.0",
    "supportedFieldTypes": ["decimal"],
    "hideDefaultRequiredMessage": false,
    "hideDefaultConstraintMessage": false
}

If you're happy with your other changes, zip the HTML, CSS, JavaScript, and JSON files together, and name it in this convention: NAME.fieldplugin.zip (be careful not to add "zip" if your computer already adds this). In the webinar the zipped file is called format-symbol.fieldplugin.zip. Once packed, anyone can use your field plug-in!

Step 7: Add a new parameter for symbol placement

This step wasn't covered in the webinar! This is the solution to the challenge posed in the webinar, so we suggest that you attempt this challenge on your own before following these steps. 

During the webinar, we created the format-symbol field plug-in that allows you to define a symbol that will appear before an input box. This is useful when collecting data that requires a symbol, such as currency.  However, what about symbols that appear on the right, like measures of volume or weight (L, kgs, grams, etc)?

In this step, you will improve the plug-in to be able to take another parameter ("placement") to determine whether the symbol should be on the left or on the right of the input field. 

  1. Add another label to template.html (note the change in the id for the label). This is required so that you can have the symbol before, or after the field.
    <label 
        id="symbol-left" 
        for="decimal-field"
        class="symbol" 
    >
    </label>
    <input 
        type="text" 
        pattern = "[0-9]*" 
        inputmode="decimal"
        value="{{CURRENT_ANSWER}}" 
        id="decimal-field" 
        class="response default-answer-text-size"
        {{#QUESTION_PLACEHOLDER_LABEL}}
          placeholder="{{QUESTION_PLACEHOLDER_LABEL}}"
        {{/QUESTION_PLACEHOLDER_LABEL}}
        {{^QUESTION_PLACEHOLDER_LABEL}}
          placeholder="Your answer here..."
        {{/QUESTION_PLACEHOLDER_LABEL}} 
    />
    <! -- new rows below --> <label id="symbol-right" for="decimal-field" class="symbol" > </label>
  2. Add a class called hide-symbol to style.css. This will hide any HTML element using this class.
    .hide-symbol {
        display: none;
    }
    
  3. Apply this class to the second label in template.html. This will make this second label hidden by default.
    <! -- see new "class..." row below -->
    <label
    id="symbol-right" for="decimal-field" class="symbol hide-symbol" > </label>
  4. Open the script.js file, and after the "symbol" parameter line, add the following new lines. These new lines define variables that store the value of the "placement" parameter, as well as variables for controlling the appearance of the left and right symbol labels. An "if...else" conditional statement toggles the new CSS class from step 2 to make the label (in the HTML file) on the right visible (while hiding the label on the left), or leaving the label on the right hidden (because the hide-symbol class applies).
    var symbol = getPluginParameter("symbol")
    var placement = getPluginParameter("placement") //new row
    var leftLabel = document.querySelector("#symbol-left") //new row
    var rightLabel = document.querySelector("#symbol-right") //new row
    if (placement === "right") { //new row
        rightLabel.textContent = symbol //new row
        rightLabel.classList.remove("hide-symbol") //new row
        leftLabel.classList.add("hide-symbol") //new row
    } else { //new row
        leftLabel.textContent = symbol //new row
    } //new row
    
  5. Edit manifest.json to increase the version number. Here, the "version" has been increased from 1.0.0 to 1.0.1:
    {
        "name" : "Format symbol",
        "author" : "Dobility",
        "version": "1.0.1",
        "supportedFieldTypes": ["decimal"],
        "hideDefaultRequiredMessage": false,
        "hideDefaultConstraintMessage": false
    }
    
  6. Compress the files into a ZIP file called format-symbol.fieldplugin.zip.
  7. Revise your form design so that it reflects the correct name of your field plug-ins, and uses the correct parameters. The syntax would look like this: 
custom-format-symbol(symbol = "$", placement="right")

Please compare your work to the code in the format-symbol field plug-in. The format-symbol field plug-in is exactly the same as the baseline decimal field plug-in, except for the changes discussed here. If you have any questions, you can submit a support request, but field plug-in development help is quite limited (we won't be able to advise much further than this exercise).

Publishing your field plug-in

First, there is no need to publish the format-symbol field plug-in, this is just an exercise, and we have already published it here. However, if you develop something new, we have some suggestions on sharing your field plug-in. We recommend using GitHub as a home for your project, like we do.


Please write to support@surveycto.com if you've developed a field plug-in you would like to share.

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.