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.
end

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'])
end

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.

74 Likes
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?
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
Tagging users (with interests/passions/skills etc)
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?)
Modification homepage
Automatically add a user to a group
Modification homepage
Require users to join at least one group at sign-up
Locations Plugin
How to make users to explicitly agree to ToS
(Paulina) #153

@angus I can confirm, it works like a charm :slight_smile:

1 Like
(Allen) #170

Many thanks for this awesome plugin!

I am trying to update Bio field in user profile through wizard. As target field I selected bio_raw, for the input field I tried various including text area and composer. So far I have not managed to get user input from Wizard to update Bio field in user profile. Updating checkbox (consent in my example) works. Am I doing something wrong?

(Angus McLeod) #171

It seems to be working fine on my sandbox. Can you link me to an example of it not working?

Wizard: https://discourse.angusmcleod.com.au/w/profile-update

Wizard input:

51%20pm

Profile after submission:

10%20pm

Wizard settings:

1 Like
(Allen) #172

hmm, i created an additional step, identical to my first, and that one works. I did some field name changes in a convoluted way on my first attempt, and that probably messed up something. Anyhow, I will just delete the whole wizard and start over again, I am confident it will work now. Thanks for confirming that it wasn’t some odd problem with the profile field.

(jacob) #173

Here’s an error I found while using the plugin today. Could this be the cause to the wizard not changing themes appropriately?

1 Like
#174

I noticed that the validation done does not appear to strip leading and trailing white spaces. Was able to create fields that have a minimum length and then uses spaces to meet that minimum. For example I could put a minimum of 5 and then simply put in 5 spaces and it is successful.

(Sam Saffron) #175

@Osama do you remember the wrapping we did for themes? I think it may make sense to add this for plugins as well? Not sure, but something to think about. Worth a 15-20 minute round of investigating what issues there are and how plugins should deal with this on static pages. I keep seeing these errors on meta.

5 Likes
(Jacob) #178

Is there a way to have wizard fields in a custom title? It doesn’t work for me and one other person said they can’t use user fields. I’m assuming you can’t but I am still gonna ask. sorry for bump, idk forum etiquette or where I should ask this

(Christoph) #179

Could you clarify how exactly the wizard acts after the final step? The OP mentions that

But what happens in all other cases?

The way I have setup the wizard, the user is redirected to the PM that was created by one of the wizard actions, so I’m guessing that the user is redirected based on the (last?) wizard action. But what if a user is invited and a PM is created? (etc)

Oh, and I just realized that the last action of my wizard is actually not the pm but updating a field in the user profile. So I’m not sure what the logic is. :thinking:

Ultimately, what I’m trying to find out is whether there is a way of directing the user to /latest or a specific category or topic once the wizard is completed (except, of course, in the case of topic invites). In particular, I don’t want new users to be redirected to the PM that was created by the wizard. Is there any way of preventing that?

(Angus McLeod) #180

There is now!

https://github.com/angusmcleod/discourse-custom-wizard/commit/a1f4d6fdf9fa2cfe352490046dab41969284a4b4

If there are no create_topic or create_message actions in the wizard, then the user will just be directed to latest.

If there are create_topic or create_message actions, then whatever action appears last in the wizard will determine what the user is redirected to. The action doesn’t need to be in the last step.

For example, if you have a create_message in step 2 and a create_topic in step 4 of a 5 step wizard, the user will be redirected to the topic.

I’ve added a ‘skip redirect’ option for create_topic and create_message which should address the your use case.

https://github.com/angusmcleod/discourse-custom-wizard/commit/b78c2f0c0ffd3327b9d72ee3da094f1370b43402

2 Likes
(Christoph) #181

Thanks a lot for those features!

I just received a wizard generated PM from a user who signed up 9 months ago. Was she redirected to the wizard because I had the required option activated? If so, it was totally not clear to me that this would happen if I don’t have after time activated (which I don’t have).

As I think about it more, I’d even say it is logically inconsistent that “required” automatically overwrites everything else.

I’m not sure if I’m expressing myself clearly, so, in concrete terms, I wanted to use the wizard for the onboarding of new users when they sign up (and existing users wouldn’t even know the wizard exists) and I don’ t want to allow them to skip the wizard, hence I activated After signup and required. It looks like it’s currently not possible to do that without also bugging existing users with the wizard. Is that intentional?

(Jacob) #182

I have a wizard that makes a topic, users can do it multiple times. If you hit enter at the end of the wizard it will take you to the last topic you made through the wizard instead of making a new topic.

(Angus McLeod) #183

@tophee The ‘Required’ setting does not affect whether or not you see the wizard. It only affects whether you can skip the wizard or not once you’re in it. Was that one case the only case of an existing user seeing the wizard? Did she say how (e.g. was she signing in?) she saw the wizard? The settings you have currently should work for your desired use case. If they are not, there’s an issue.

I’m a little confused. Could you spell out in more detail how you’ve set up each step of the wizard, what happens and what you expect to happen? Thanks.

(Jacob) #184

Capture
This is what my last page looks like. If they click done, it will create a new topic like normal, but if they hit enter while in the “Reason and Comments” text bar to submit the page, it will take them to the last post they made.


When I click enter in the text area it leads me here. This is a deleted test from 5 hours ago and it doesn’t make a new topic.

When I click done it completes like normal and creates a new topic.

(Christoph) #185

Yes, because I immediately turned off the wizard to make sure that it doesn’t happen again.

I did not communicate with her but I can see that she was logging in (i.e. visiting the forum), yes. The forum is not public. I am also pretty sure that her logging in was a reaction to the digest email she received just a fee moments earlier. So it is likely that she clicked on a link in that mail to get to the forum.

Then there is an issue. But how do we track it down?

(Angus McLeod) #186

@tophee Are you able to check with her that she actually saw the wizard and what she did beforehand? That would help me figure out why she saw it, assuming she saw it. It’s tricky to debug something without any firm context, or reproducible steps.

@SmokedFish Could you show me what settings you have for that step? How is the create_topic action set up? What role does the “Reason and Comments” input play?

(Jacob) #187


This is my topic, there are no topic fields.
Capture
This is the “Reason and Comments” settings. I use the wizard for my game staff to give a ban reason for players they ban in-game. Its only purpose is for the admins to give a reason for the ban. It still works but you can’t hit enter, you have to click the done button.

(Christoph) #188

That may be difficult as she is a non-tech user who rarely logs into the forum at all. Is there any other way I might be able to get that information? Logs? Data explorer? Crystal ball?

Is there anything in particular that she could have done (or not done) that might have played a role?

I poked around a bit and found that she she had forgotten her password and requested a reset password email. Somehow, I have a strong suspicion that may have had an effect…?

I also noticed that, as a result of the PM, she showed up in the stats as a “new contributor”:

image

(As an aside: is there a way of avoiding that? Because it essentially means that if you use the wizard for new-user onboarding and have it produce a PM (in my case to register new users in their group), every new user always becomes a “new contributor” the day they sign up, effectively turning your “new contributor” stats into “new user” stats.)

(Angus McLeod) #189

@SmokedFish Thanks for the detail. I’ll look into it in the next couple of days; latest on the weekend.

She had never posted or created a pm before now? Perhaps she signed up for a new, seperate account with the same name?