Custom Wizard Plugin

(Angus McLeod) #1

Repo: GitHub - angusmcleod/discourse-custom-wizard: A plugin for Discourse that allows you to create custom user wizards.

This plugin allows you to make custom wizards for your forum. Custom wizards can provide information, take user input and perform actions based on that input.

You will automatically see an example of it in action when you sign up for a new account on my sandbox.

It builds on top of the Setup wizard in Discourse, abstracting various aspects of it into a configurable component or setting. The Discourse Setup wizard is its own Ember app. This plugin extends that app in various ways to make it customizable by admins via a new Wizards route in the Discourse admin panel.

Custom Wizards can:

  • Display text or images in a structured format. Text can be taken from translation files or entered via the admin panel.

  • Take user input via text boxes, textareas, dropdowns, or radio buttons.

  • Perform actions based on user input. The actions currently available are:

    • Update user profile fields.

    • Create a new topic.

    • Create a new message.

Custom Wizards are each given a distinct url in the /w/ namespace. You can automatically redirect users to wizards:

  • After they create an account, or accept an invite (e.g. an introduction to your community). If they have accepted an invite to a topic they will still be automatically redirected to that topic after they complete the wizard.

  • After a certain time (e.g. when you update terms and conditions). When the specified time is reached all users (including those currently logged in / active) will be redirected to the wizard.

Custom Wizards can be:

  • Single or multiple submission.

  • Required or optional.

There is also an option to turn off the functionality that saves user input to the db (but still allows it to be used in Actions), which may apply in special cases.

The configuration should be self explanatory, so I won’t attempt to describe it in detail here, but to give you a sense of what’s involved, this is what the configuration for Step 2 of the Welcome wizard that you see after signing up an account on my sandbox looks like.

The Wizard Step itself looks like this.

You can also add your own step handler logic from a separate plugin if you have custom logic you need to perform on user input when the user clicks “Next” or “Submit”.

From your plugin.rb add.

CustomWizard::Builder.add_step_handler('wizard_id') do |builder|
  # your logic.

You can see what is available via the builder object here.

You can also inject additional assets into custom wizards from a separate plugin. For example the Locations Plugin has these lines in its plugin.rb

if defined?(CustomWizard) == 'constant' && CustomWizard.class == Module
  CustomWizard::Field.add_assets('location', 'discourse-locations', ['components', 'helpers', 'lib', 'stylesheets'])

And has a wizard-specific component in /assets/javascripts/wizard that wraps the normal location-form component so it can be used in a wizard.

The end result being the location form in Step 3 of the Welcome Wizard in my sandbox.

Any custom component can be added to a custom wizard in this fashion.

A note of caution. This is a complex plugin. I have tested it a fair bit, but there is a lot of functionality here and it will take a little while to iron it out. I suggest you use it for simple use cases at this stage.

Right way to customize login page and others things
Discourse Tour - do we have such one?
Addressing gender balance in online communities
Locations Plugin
Unable to find Discobot's editable text?
Discourse-common asset availability: difference between development and production?
Custom page for users
Horizontal admin menu buttons cut off
Ask users for information *after* sign-up (welcome page?)
Automatically add a user to a group
Modification homepage
Modification homepage
Require users to join at least one group at sign-up
Locations Plugin
How to make users to explicitly agree to ToS
Possible bug on Signup Flow with Social and Custom User Fields
How to edit sign up form?
Discourse Policy
How to make users to explicitly agree to ToS
New Users > Starting Registration with a Prompt/Post
(Jeff Atwood) #2

I really like that desktop background, where can I get it? :star_struck:

Oh also good work on the plugin too

(Angus McLeod) #3

:slight_smile: It’s from this sweet little pattern library.

Image pattern option for category backgrounds
(Felix Freiberger) #4

Whoa, that’s a really cool plugin! :heart:

One thing I noticed: After signing up, I see this banner:

I think this is a side effect of letting non-admins access wizards, and shouldn’t happen, right? Clicking the links sends me to which is a blank page due to a 403 (as expected).

(Daniela) #5

I can’t complete the 3rd step.

I wrote the city, selected the nation, clicked on Find Location, clicked on the right Locations tab which appeared, but when I click Done nothing is happening.

I’m using Firefox and Win10, here what I see in the browser console:

This afternoon I’ll try again with chrome

(Angus McLeod) #6

Yeah it seems it’s a browser thing. Apparently in Firefox and IE you can’t access DOM events globally like you can in Chrome. Which is useful when you’re trying to avoid overriding core templates :slight_smile: Oh well. Fixed.

hm yeah. It’s a side effect of the way the plugin uses an existing wizard method so that it doesn’t have to override perform_account_activation in the UsersController in order to redirect users on signup. This should fix it for now.

Both issues are similar actually. There was some repurposing of existing logic which meant fewer overrides of core functionality and more long term stability. But the repurposing creates side effects. It’s a balancing act sometimes.

(Daniela) #7

Yep, now it works.

The only thing is that when I click on Show Map it says that I live in the middle of nowhere, more precisely in the middle of the Appennine and near the banks of a river (I do not even know how to fish :fish: ). Obviously it’s a Mapzen problem and not the plugin itself.


How can I forcefully ask existing users of my forum to fill their location and bio field if its not filled by them with this plugin?

(Daniela) #9

If you look at the images in the OP you can see a setting “users are directed to wizard after the start time until wizard is completed or skipped” that, from what I understand, is exactly what you need

(Angus McLeod) #10

Yup, as @Trash notes, it seems like you want the After Time setting and a form step with text and textarea components tied to an action that populates location and raw_bio.

There’s something I need to fix first though, so don’t implement it in production yet (existing values for profile fields are not populating form fields tied to profile fields properly).

(Angus McLeod) #11

Ok you should be good to go now. Let me know how it goes.


You are superfast man. Thanks a ton. :slight_smile:


Excellent plugin! A++ stuff.

We currently have 2 options for "when to show the wizard"

Would you be able to add these options as well.

  1. Users who are at least x days old should be shown this wizard
  2. User should have posted at least x posts
  3. User should have created at least x topics
  4. User should have at least x solutions
  5. User should have at least x read time (in mins)
  6. User should belong to “x” group

(Angus McLeod) #14

Good suggestions, thanks. I don’t have a lot of time for new feature development right now. Maybe in a couple of weeks.



Also - I just found an issue with the plugin.
I’m getting a blank scree.
I’m using a brand new instance (with latest updates)
I was trying to do something really simple - (which was updating the name of the user after sign-up)

Its taking me here and the page is blank


(Angus McLeod) #16

Hm, I replicated your wizard on my sandbox and it’s working fine:

I can’t access Could you check the browser console for errors?


I can check and tell you right away.


Error from the console

(Angus McLeod) #19

Go to and see if you can find the exception


I can see this