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.
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.
The form templates can be created, edited, and deleted at Admin ▸ Customize ▸ 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
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.
|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)|
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.
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:
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:
- 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
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!