Introducing Experimental Form Templates

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.

multiple_form_templates

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 :wrench: Admin ▸ Settings.

Managing the templates

The form templates can be created, edited, and deleted at :wrench: 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 :heavy_plus_sign: 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!

44 Likes

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 :smiley:

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.

10 Likes

Hello :wave:

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

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.
    Screenshot 2023-10-17 at 8.04.50

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

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


Thanks :slight_smile:

13 Likes

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.


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):

5 Likes

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?

4 Likes

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. :thinking:

Purely speculating, though.

9 Likes

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.

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.

2 Likes

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.

2 Likes

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.

2 Likes

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.
13 Likes

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.

2 Likes

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!

2 Likes

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 :smiley: )!

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);
6 Likes

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. ↩︎

8 Likes

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

  • The form itself is a great idea :+1:
  • 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. :smile:
  • 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. :slight_smile:

7 Likes

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.

4 Likes

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. :slight_smile:

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. :upside_down_face:

2 Likes

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

2 Likes