Introducing Experimental Form Templates

[renato (Renato Atilio)]

Hello, Discourse Meta Community!

We are excited to introduce a new experimental feature, form templates. With it, you can enforce a structured form with data validation as part of the topic creation flow.

Enabling the feature

The feature is hidden behind a site-wide experimental flag. To enable it, just turn on the experimental_form_templates site setting under Admin ▸ Settings.

Managing the templates

The form templates can be created, edited, and deleted at Admin ▸ Customize ▸ Templates (/admin/customize/form-templates/).

There, you’ll see a table with a list of the templates that exist on the forum. You can edit, delete, and preview any existing template or you can create new ones. The table also shows the categories that each template is currently active in.

Templates are defined in a YAML structure. You can type this up manually, or make use of the “Add” buttons at the top, which will append a piece of example YAML code to the end, defining a certain input type.

Here’s a complete YAML example, with all field types:

- type: input
  id: name
  attributes:
    label: "Full name"
    placeholder: "eg. John Smith"
    description: "What is your full name?"
  validations:
    required: true
    minimum: 2
    maximum: 100
- type: textarea
  id: introduction
  attributes:
    label: "Introduction"
    placeholder: "A short introduction"
    description: "Write a short introdution about yourself"
  validations:
    required: true
    minimum: 10
    maximum: 500
- type: dropdown
  id: fav-animal
  attributes:
    label: "Favorite animal"
    description: "Select your favorite animal"
    none_label: "Select an option"
  choices:
    - "Dog"
    - "Cat"
    - "Other"
  validations:
    required: true
- type: multi-select
  id: comm-channel
  attributes:
    label: "Communication channels:"
    description: "Select your preferred communication channels:"
    none_label: "Select an option"
  choices:
    - "Email"
    - "Phone"
    - "Messenger"
- type: upload
  id: cat-photo
  attributes:
    label: "Cat photo"
    description: "Send a photo of your cat (or any cat)"
    file_types: ".jpg, .png"
    allow_multiple: false
- type: checkbox
  id: accept-terms
  attributes:
    label: "I have read and I agree to the terms"
    description: "You need to accept terms to continue"
  validations:
    required: true

Validations

For each field, you can add validation options that must be passed before being able to create the form. For a list of available validations, click the Validations button above the code editor. This will show you the syntax for each validation option and describe its intended usage.

Validation options

Key	Type	Description
required	boolean	Requires the field to be completed to submit the form
minimum	integer	For text fields, specifies the minimum number of characters allowed
maximum	integer	For text fields, specifies the maximum number of characters allowed
pattern	regex string	For text fields, a regular expression specifying the allowed input
type	string	For input fields, you can specify the type of input that should be expected (text|email|date|number|url|tel|color)

Applying a template to a category

Once you’ve created a form template, you’ll want to apply it to a category. To do this, head to the settings of the category you would like to apply the template to.

Select the Template menu, and then on the right, use the switch to turn on form templates. Once it has been enabled, you can use the dropdown to add one/more templates to a category.

Filling out the form

Once a template has been applied to a category, the template’s form will now appear automatically when you create a topic and select the category that has the template. If the category has more than one template assigned to it, you’ll also see a picker to switch between available templates.

When filling out the form, it will abide by any validations specified in the form template definition, and only after it’s valid you can hit Create Topic and it will generate the topic content from all the input fields.

Finally, after submitting, the topic content is composed of all the filled fields:

Pre-filling form values

You can also pre-fill form values by calling /new-topic with params matching the field IDs defined on the form template. For example, for the template previously used as an example:

/new-topic?name=John%20Smith&favorite-animal=Cat

Roadmap

• Store the JSON output in the topic data when a topic is created
• Toggle to still be able to select and use the freeform composer on categories with form templates

How you can help us

We’d love to hear your feedback on this new feature. If you’re an admin and would like to try it out on your forum, you can turn on the experimental_form_templates setting and start using them right away!

Please share your experiences, report any bugs, or provide any suggestions on this announcement topic.

Thank you for helping us make Discourse better!

[packman (Chris McMahon)]

This looks very useful and I’ll definitely be enabling it to experiment.

One thing I’d find useful is the ability to link a template field to a user custom field. For example, in a support category the first couple of questions usually asked by the support guys are “Model of equipment” and the associated “Web site URL”. With this template feature I can now ask for this info as ech new topic is created

These two bits of info are also generally of interest to other users so they’re defined as custom user fields - which sometimes get filled in. If template fields could be populated from a linked custom user field (if it has a value in it) then for frequent flyers they can fill in their user fields and not have to fill in the template fields in every time. Occasional flyers can just fill in the template fields as and when they need support.

As a further suggestion, the icing on the cake would be for the link to work in reverse. If someone enters data onto the template that’s not in the linked custom user field then the custom field is updated when the topic is posted.

[Don]

Hello

This is one of the best improvement. It gives so many opportunities.

Some notes:

1. It seems the form_templates.errors.valueMissing.number is a missing string.

2. It seems the tel validation is not working.

3. On mobile the form template in composer is not scrollable.

4. On mobile when the form template is available the footer buttons doesn’t do anything. I think it would be good to hide these.
   

+ Would be useful to add validation to prevents negative numbers to number type. Use case (price)

+ Would be also useful to add dynamic conditional fields feature.

---

Thanks

[Simon_Manning]

As already mentioned, this will be very handy for support contexts and I particularly like the suggestions from @packman regarding custom user fields.

Is adding form templates to groups also on the roadmap (or could it be)? Where messaging a group is used for private support, this will be especially useful for front-loading questions before a member of staff arrives.

---

@packman

If someone enters data onto the template that’s not in the linked custom user field then the custom field is updated when the topic is posted.

Depending on the visibility of the custom field, this could have privacy implications. For example, the user might choose to share the information via a form template in a private category but not want to share that information with the wider community via their profile.

Depending on the nature of the information, it might also have one value that is appropriate for their profile and/or most forms but they might want to provide a different value in a particular instance.

I like the idea of filling in the form from those fields and being able to update the fields if the entered values differ but perhaps that should be a prompt. This is a really quick and dirty mock-up but maybe something along these lines after creating the topic (only if a value differs and possibly only if non-empty):

[pgr]

My feature request for this great new feature, is, I believe, common in software support forums.

People neglect to specify their version of the software. That’s it. Simple, but it is the cause of many, many useless back-and-forth posts that are tiresome to the people who help out a lot of people (and we don’t want to tire the most important people in the Community).

So I would want a form to ask

• Your FabulousApp version is… (dropdown with options)
• Your PHP version is… (dropdown with options)

Now, suppose that someone posts frequently on the forums. This information does not change frequently, although it might change say, once a month.

The form should keep that values that this same user selected in their previous post, as defaults, that’s my feature request right there. What do you think?

[Canapin (Coin-coin le Canapin)]

I think that in some cases, having a pre-filled field may lead to users overlooking it and not changing the value when it’s needed.

Purely speculating, though.

[Simon_Manning]

@pgr

So I would want a form to ask

• Your FabulousApp version is… (dropdown with options)

@Don

+ Would be also useful to add dynamic conditional fields feature.

These two combined is what I would like to see for my use case. With multiple apps, I want the user to be able to select their app, then select their version from a list that corresponds to that app.

@Canapin

I think that in some cases, having a pre-filled field may lead to users overlooking it and not changing the value when it’s needed.

This is certainly my experience for choices. With a default value on an email contact form, the vast majority of submissions have that default value regardless of which app or version they’re actually using.

[packman (Chris McMahon)]

@Simon_Manning

the vast majority of submissions have that default value

That’s probably true for default values but in what I envisaged the field values would be those previously entered by the user in their custom fields. These could be old/outdated but I think in my use case there would be far fewer wrong values than there are currently no values.

[Simon_Manning]

@packman

These could be old/outdated but I think in my use case there would be far fewer wrong values than there are currently no values.

Absolutely. To my mind these are mostly two different categories of information: state at a point in time and user preference/identity/etc. What I was referring to with my experience of default values was more about the former.

[huh.how (Thomas Ingram)]

Two requests!

1. A code field that automatically fences the content with ```
   • It could have a language dropdown, with a default.
2. An attribute that allows users to duplicate a field (I picture a + button below that field).
   • Imagine if a user wants to post two codeblocks, or multiple images. They can input one, click the + and add another.

[tomve (Tom)]

This is a great new feature, and potentially well timed for a project I’m working on.

After playing about with it briefly I have two questions:

1. Currently when the user edits a topic post they have created through a form template it just shows the default post editor.
   Are there plans to also show the form template editor when editing a post?

2. Will there be an option to add custom input types?
   I’m thinking about a map where a user can select their location by dropping a pin on the map. So it would be good to have the option to define such custom field types.

[jerlendds]

This is perfect timing for my use case! I’m wondering if there’s plans to eventually allow customization for how a form template ends up being rendered in a topic.

e.g. In the following image the checkbox field type is rendered as the text on:

Would someone eventually be able to map the form field types to customized output?

e.g. In my case I want a checked/on checkbox to map to the checkbox formatting, [x], and the lack of a check/off state to []

I might have to start learning ruby and hacking around on this project, this form update has given me lots of neat ideas. Thanks for the great work guys!

[iamntz (Ionuț Staicu)]

This is absolute great way to enforce some behaviour in a particular category (my painpoint was job posting, where everyone posted however they feel like )!

A bunch of features extra would be nice:

• the ability to „switch to no template” (optional). This would be nice to be limited by users, by level, by group etc; Some kind of „trust me bro, I know what I’m doing!”
• multiple fields on the same row (think first name + last name). A good enough fix would be to allow admins to set a class name for the form template;
• a repeater (i.e. group a bunch of fields and let users to add more of those);

[huh.how (Thomas Ingram)]

It would be good to have the ability to:

• Paste content into an Upload field^[1].
• Add a composer in addition to the textarea, where users have access to the normal suite of features.^[2]

---

1. The upload functionality in Discourse posts is great. This one’s more difficult to use, requiring images already be saved to disk for example. ↩︎

2. If I want a user to select a dropdown in addition to a post, with the current approach (a textarea) I dramatically decrease their ability to create their post normally; no pasting images, no edit bar, etc. ↩︎

[Arkshine]

I tried the form here to report a bug about the theme. Here is my feedback:

• The form itself is a great idea
• No formatting tool is a big miss.
  • Even if markdown syntax is basic, selecting and using the toolbar is often easier/faster. It helps in making a readable message.
  • This can work if the report is a simple but advanced issue; you might need to hide details or insert a table.
• No inline upload is not convenient.
  • E.g., showing a problem step by step, before/after results, etc.
  • In case of multiple screenshots, you must explain what screenshots you should look at.
• Same as Thomas, pasting an image would be welcomed. It took me some time to figure out where my screenshots were saved.
• Conditional input – when selecting “other,” it would be nice to have an input appearing for that.

Overall, really nice! I’m looking forward to how it will be improved.

[Truong_Jennifer]

If you have multiple forms enabled for a single category, it isn’t intuitive that there is a dropdown for you to select a form. When you create a new topic, it automatically populates the first form template, which again, if you don’t know what you’re looking at, then you wouldn’t realize there could be other forms.

When you deselect the form, you do see the text “Select form templates” which is clear to me that there is a list of form(s) that I choose from. The composer still shows the form even though one is not selected. This is where I would second, @iamntz about having the option to switch to no template.

[Truong_Jennifer]

Just want to add on to my previous reply and to give a bit more context to our specific use case. We’re looking to implement this in our Site Feedback category. Ideally, we want form templates for things like requesting tags, and keep the default composer (no template option), if the form does not exist or won’t do the job properly.

So, what we’re envisioning would be to create new topic in category and see this:

From there, see “Select form templates”, where from there you can either compose normally or see that form(s) do exist in this category for standardized requests/feedback.

I can see the argument that some users won’t see or use the form template, if they can compose, but I was trying to stay within the current styling with the placeholder text within the field instead of a label outside of the field. But that’s why it could be an optional feature where the admins enable/disable it.

[sunjam (james.network)]

@Truong_Jennifer

I can see the argument that some users won’t see or use the form template

If the selection button was clearly highlighted it would be much easier to encourage users to click it, similar to your Create Topic button

[Truong_Jennifer]

After playing around with the forms more, we discovered a workaround for a “no template” option would be to create a simple “free response” form that can serve as a no template (as seen in the screenshot below).

@sunjam

If the selection button was clearly highlighted it would be much easier to encourage users to click it, similar to your Create Topic button

Adding to this idea, if we didn’t want to change the color to highlight the dropdown, I think adding a down arrow would be a helpful indicator that there is a drop-down selection, just like the categories drop-down.

We discovered that the forms are ordered alphabetically. It would be amazing to have the option to reorder the forms or the option to select the default form that should appear when creating a new topic.

Needless to say, we like what this feature has to offer, and would be excited for such enhancements to it.

[Tris20 (Tristan)]

Perhaps I’ve missed it, but is there any way to have a hyperlink in a form? For example, say we had a checkbox for the terms and conditions. In the description it would be useful to have a hyperlink to the actual terms and conditions.

Is this already possible?

Is there also any way to automatically populate the title field when the user creates a new post, such as with their username, or even just some default title?