Update (Dec 18, 2018): This topic was originally to design the Wizard. If you want to know how to use the Wizard to update your site settings, please visit this topic.
One thing we’ve never been 100% happy with on Discourse is our on-boarding experience for new users.
Right now, when a Discourse forum is installed and an admin signs in, they are expected to read the Admin Quick Start Guide. During this process they end up having to jump to the admin section, fill in site settings, upload logos into a topic, then go back into site settings to point at the newly uploaded assets.
I think a much better solution for getting a Discourse forum set up and running is to use a Wizard to guide the forum’s owner through the setup process. I started working on this last week and it’s coming along nicely so I thought I’d share it with you!
The admin user will see a new interface when configuring their site:
(bear in mind the above is a work in progress – we’re likely going to tweak it a lot before it ships!)
Here’s the steps I’m imagining for the minimum viable product:
Rough Outline
Step 1: Language (locale)
Step 2: Forum name and description
Step 3: Privacy Settings
Step 4: Contact information
Step 5: Color Scheme (might just be dark theme / light theme at first)
Step 6: Upload Logos and Favicon
Step 7: Invite Staff Users
Technical Concerns
This is a new, full screen ember application. It’s only downloaded when you visit the wizard.
Steps can be created programmatically, so plugins will be able to add them.
Staff will be able to re-enter the wizard rather than going through Site Settings.
I created a new component to preview the color scheme when selecting it from a drop down. If you select “Dark” from the color scheme the preview below updates automatically!
Make sure TOS and Privacy are set up in there as well, with the right “company name”.
We probably also want a plugin to hook into this even in V1 so we know it works. So maybe one of our bundled plugins should “add a step”? Perhaps Akismet, asking for a key so it can function? Or something similar to that.
Can you elaborate here what you mean by set up? I’m assuming just capturing the company name fields from the TOS and automatically updating the topic should be enough?
I’ve made some more progress on this. The first step a user receives is now to select their language (thanks @zogstrip) . If it’s different than the current one, it will refresh the page and the wizard will continue in that language.
Does the first step (language selection) affect the locale used for importing the database fixtures or do we still need to configure DISCOURSE_DEFAULT_LOCALE in app.yml?
Should be fine for now. Technically we want to offer site owners choices of default user contributed post licensing, but I’d prefer we “accidentally” defaulted to Creative Commons myself as we already do anyways…
Unfortunately not. The wizard runs once Discourse has already started up, so the choices you make in it are equivalent to configuring the site settings yourself. You will still need that setting for now.
Having said that, I do think it would be possible to regenerate those fixtures via the wizard. We should revisit at a later date.
Can you elaborate? Is the idea that in some languages upper case is more common, and the setting should change it depending on locale?
I guess @elijah is thinking about locale dependent default settings. Not sure what’s the best way to solve this and it’s probably out of scope for the wizard’s first version.
Basically to add a step from the plugin you do this:
plugin.rb
on(:wizard_build) do |wizard|
wizard.append_step('akismet') do |step|
step.add_field(id: 'akismet_api_key', type: 'text', value: SiteSetting.akismet_api_key)
step.on_update do |updater|
updater.apply_settings(:akismet_api_key)
end
end
end
You also then have to fill in the translation keys for the step and the labels. This is pretty straightforward but if you want to see an example view the akismet commit.
Notice that this API doesn’t use any Javascript! If you’re just using basic form elements like text fields, drop downs and radio buttons you can just assemble the step using the ruby DSL. If you want to do something more advanced such as the color scheme preview in the screenshots earlier in this topic, you’ll have to write your own Ember component.
If you’re curious how this works: the API creates a bunch of objects that are serialized the JSON. The accompanying Ember app is smart enough to read that JSON and render a multi step wizard, submitting each step to the server as it goes along.
And it’s merged! Our initial plan of having 5 steps ballooned up to 13!
I’m quite proud of it already, so I’m excited to hear feedback from the world at large and continue to tweak it even further.
If you’re interested in helping us test the feature, if you are an admin you can access the wizard at the /wizard path even if your forum is already configured – otherwise the first admin who logs in is invited to complete it via a notice.
as we already do anyways…