Forms Cog

The Forms cog lets server admins and managers create dynamic forms and have members fill them out easily. The various form types integrate with other Vor cogs and question types with Discord’s native components. The goal is for the system to be intuitive and provide failsafes.

1. Creating Forms

⭐ Both creating and editing existing forms is handled through the Form Builder.
⭐ The minimum requirements for a form to exist is it needs a title and a submission channel.

Form Builder

  • The Wrench: Use the 🔧 buttons to configure specific categories.
  • Question Builder: Add up to 5 questions per form (Discord limit). Questions can be short text, paragraph, or select menus for users, roles, and channels.
  • Enable/Disable: You can pause submissions to a live form by toggling the Enable setting.
  • Preview: On the Questions Builder, you can preview the modal in its current state.

⚠️ If the question type is one of the Discord selects, only a maximum of 25 items (i.e. channels, roles etc.) can be selected. This is a Discord limitation.

2. Form Types

The submission behaviour changes based on the form type.

  1. Standard: De-facto form, doesn’t do anything fancy. Submissions are sent directly to the submission channel.
  2. Voting: On submission, the bot automatically adds Yes and No voting buttons.

  3. Anonymous Voting: Similar to Voting, but only the vote count is shown at any given moment. The voters are hidden, and regular members cannot see who voted for which option.

  4. Ban Appeal:
    • Only applicable when using Vor moderation to handle bans
    • Only sent to the banned user if the noappeal flag is turned off.
    • !ban <user> <reason> ✅
    • !ban <noappeal> <user> <reason> ❌ - It is a good idea to turn Visible in Slash off and not attach Ban Appeal forms inside your server in Form Panels.

⚠️ Only one ban appeal can exist per server and it can only contain questions of type Short Text or Paragraph. Select menus are not allowed in DMs.

  1. Tag Form:
    • Only applicable for Vor tag calls
    • Provides a button alongside the tag call that lets the user to fill out a live, short-term questionnaire
    • Once you have created a tag form, use /tag form link
    • You can unlink them at any time using /tag form unlink

⚠️ The form button will only pop up based on an eligibilty system. The people eligible to fill out a tag form are:
(a) The people mentioned in the message that called the tag
(b) If the tag call is a reply to the message, the user who authored said message
If there are no eligible users, the tag will not provide a button.

⚙️ Additional Settings

  • Cooldown: This defines how long users must wait before submitting to this form again (e.g. 24h, 7d).
  • Max Submissions: Limit how many times a single user can fill out a form. (e.g. once for a feedback form).
  • Anonymize Submitter: Hide the username and avatar of the submitter when the form is sent.
  • Mention Roles: Ping specific staff on the submission message.

⚠️ These settings can change at any time. Note that the max submissions is independent of the cooldown. For example, take a form with max submissions = 1 and cooldown = 24h. The user can only submit 1 form ever, cooldowns do not reset the max submissions.

3. Filling out Forms

There are two ways for members to fill out forms:

(a) Slash Command

Users can run /form fill [name] to launch the form modal directly from any channel. Autocomplete will list enabled forms by their title.

⚠️ The Visible in Slash form setting should be enabled for autocomplete to show the form.

(b) Panels

Form Panels are messages with configurable content and buttons. The buttons allow users to launch form modals just like the slash command.

  • Get started by using /form panels
  • Configure content for the panel, and attach forms to the panel
  • Use Send to send the panel to the channel you have run the command in.
  • Use Refresh to update the buttons if you add or remove forms from the panel later.

⚠️ A maximum of 5 forms can be attached to one panel.
ℹ️ Roles marked as Manager Roles for the Forms cog bypass restrictions such as Cooldown and Maximum Submissions. This is to allow them to see if there are any issues with the server forms.

4. Managing Submissions

Submission List

Use /form submissions to browse through past entries.

  • Manager Mode: If you are a manager, you will see Accept and Reject buttons for orphaned Ban Appeal and Voting forms.
  • Filter: When entering the command, there is an optional filters for managers to only show submissions from a specific user.

⚠️ This command is available to everyone in the server. But, non-managers can only view their own submissions and cannot manage submissions.

5. Failsafes

  • Force Send: If the bot ran into an error sending a form (e.g. a channel was deleted), users can use /form force to attempt a resend once the issue is fixed.
    • This applies to submissions whose respective Discord message was deleted as well.
    • Issues may happen due to developer error too. If you are unsure what is going wrong, please contact the bot developers.
  • Diagnose: Use /form diagnose to check if your submission channels and roles are still set up correctly.
  • Approve/Reject: Handle approval or denial of orphaned submissions through the /form submission list.
  • Soft Deletion: Deleted forms are only marked as deleted to prevent accidental wiping of important data. If you have any privacy concerns or would like your server’s data exported, please contact the bot developers.

⚠️ Note for Bot Developers: You cannot delete a form if it has associated submissions. The submissions must be cleared first, and ideally this happens at the request of a user.

6. Configuration

  • Enabled: Global toggle for the Forms system.
  • Log Channel: The channel where Vor logs activity related to the Forms system.
  • Manager Roles: Roles granted permission to create forms, edit settings, and look through all submissions. Server administrators have these permissions by default.

⭐ You can use /config cog <Forms> to set these configs up.

7. Commands Summary

Command Description
/form create Create a new form for the server.
/form edit Modify an existing form’s settings or questions.
/form list View all forms in the server with shortcut buttons to create or modify forms.
/form delete Mark a form as deleted and hide it from users.
/form fill The main command for users to start a form.
/form submissions Review submissions with pagination and other management buttons.
/form panels Create and send button-based panels to channels.
/form diagnose Diagnose forms and check up on settings, submission channel, etc.
/form force Try to manually send a submission that originally had an error sending, or was deleted.