 |
Summary | Discourse Surveys plugin allows you to create surveys directly within your Discourse forum posts using simple Markdown syntax. |
 |
Repository Link | https://github.com/discourse/discourse-surveys |
 |
Install Guide | How to install plugins in Discourse |
The Discourse Surveys Plugin allows you to create surveys directly within your Discourse forum posts using simple Markdown syntax. The plugin currently supports a variety of question types such as radio buttons, checkboxes, dropdowns, number inputs, text areas, star ratings, and thumbs up/down ratings.
Features
-
7 Different Field Types: Radio buttons, checkboxes, dropdowns, text areas, number selection, star ratings, and thumbs up/down
-
Required/Optional Fields: Mark fields as required to ensure completion
-
Emoji Support: Use emojis in your survey options
-
HTML Support: Rich text formatting in questions and options
-
User Authentication: Automatic login prompts for anonymous users
-
Response Tracking: Prevents duplicate submissions from the same user
-
Permission Aware: Respects topic and category permissions
-
Mobile Responsive: Works seamlessly on all devices
Usage
Basic Survey Structure
All surveys must be wrapped in [survey] tags:
[survey name="my-survey" title="Customer Feedback Survey"]
<!-- Survey fields go here -->
[/survey]
Survey Attributes
-
name: Unique identifier for the survey (defaults to “survey”) -
title: Optional title displayed at the top of the survey -
public: Set visibility (future feature) -
status: Survey status (future feature)
Field Types
1. Radio Buttons (Single Choice)
[radio question="What is your favorite color?"]
- Red
- Blue
- Green
- Yellow
[/radio]
2. Checkboxes (Multiple Choice)
[checkbox question="Which features do you use? (Select all that apply)"]
- Email notifications
- Mobile app
- Desktop notifications
- API access
[/checkbox]
3. Dropdown Selection
[dropdown question="What is your age group?"]
- Under 18
- 18-24
- 25-34
- 35-44
- 45-54
- 55+
[/dropdown]
4. Text Area (Long Form Text)
[textarea question="Please provide detailed feedback:" required="false"]
[/textarea]
5. Number Selection
[number question="Rate this feature from 1-10:" min="1" max="10"]
[/number]
6. Star Rating
[star question="How would you rate your overall experience?"]
[/star]
7. Thumbs Up/Down
[thumbs question="Would you recommend this to others?"]
[/thumbs]
Field Attributes
All field types support these attributes:
-
question: The question text (required) -
required: Whether the field must be filled (true/false, defaults totrue) -
min: Minimum value for number fields -
max: Maximum value for number fields
Complete Example
Basic Survey Markdown
Here is a basic example of survey Markdown including all available fields:
[survey name="awesome-survey-thumbs" title="Awesome Survey"]
[radio question="Choose any one option:"]
- cat
- dog
[/radio]
[checkbox question="Choose multiple options:"]
- red
- blue
- green
[/checkbox]
[dropdown question="Gender:"]
- Male
- Female
[/dropdown]
[number question="Rate this survey from 1 to 10:"]
[/number]
[textarea question="What is your feedback about xyz?" required="false"]
[/textarea]
[star question="How would you rate overall experience?"]
[/star]
[thumbs question="Were you satisfied with our services?"]
[/thumbs]
[/survey]
Survey Rendering
Below is an example of how the above Markdown renders in Discourse:
Advanced Usage
Using Emojis in Options
[radio question="Choose your favorite animal:"]
- 🐈 Cat
- 🐶 Dog
- 🐦 Bird
- 🐠 Fish
[/radio]
HTML Formatting in Questions
[radio question="Which <strong>programming language</strong> do you prefer?"]
- JavaScript
- Python
- Ruby
- Go
[/radio]
Mixed Required and Optional Fields
[survey name="mixed-survey"]
[radio question="What is your role?" required="true"]
- Developer
- Designer
- Manager
- Other
[/radio]
[textarea question="Any additional thoughts?" required="false"]
[/textarea]
[/survey]
Survey Results
Currently, this plugin does not have any backend UX to view the survey results directly. Instead, you can rely on Data Explorer queries to fetch and analyze survey responses. Here is an example query:
-- [params]
-- text :survey_name = survey
SELECT s.id, s.name, s.post_id, sf.question, COALESCE(sr.value, sfo.html) AS value, sr.user_id, sr.created_at as responded_at
FROM surveys s
JOIN survey_fields sf ON sf.survey_id = s.id
JOIN survey_responses sr ON sr.survey_field_id = sf.id
LEFT JOIN survey_field_options sfo ON sfo.id = sr.survey_field_option_id
WHERE s.name = :survey_name
ORDER BY s.id DESC
Permissions and Security
-
Login Required: Anonymous users must log in before submitting responses
-
One Response Per User: Each user can only submit one response per survey
-
Topic Permissions: Users must have read access to the topic to view surveys
-
Posting Permissions: Users must have posting permissions in the topic to submit responses
-
Archived Topics: Surveys in archived topics cannot accept new responses
-
Deleted Posts: Surveys in deleted posts are no longer accessible
Limitations
-
Only one survey is allowed per post
-
Survey structure cannot be modified after receiving responses
-
All survey field questions must be unique within a single survey
-
Survey field questions cannot be blank
Technical Details
Database Schema
The plugin creates four main database tables:
-
surveys: Main survey records -
survey_fields: Individual fields within surveys -
survey_field_options: Options for choice-based fields -
survey_responses: User responses to survey fields
Styling
The plugin includes responsive CSS that adapts to your theme. Custom styling can be added by targeting these CSS classes:
-
.survey- Main survey container -
.survey-field- Individual field wrapper -
.field-[type]- Specific field type containers -
.submit-response- Submit button
