Wizard reading large parchment

SlothCMS - initial wizard

Published on 2018-06-10 10:34

Even though my day job requires me to write code and tests for the code, my main mode of operations are workflows. So when I started writing SlothCMS my starting point was the initial wizard where users set things up.

Despite setting up more than enough of Wordpress, Drupal and couple of other CMSes when the blank page was in front of me I didn't know what was really important and what could be set up later. At the moment I am quite sure that wizard has enough input fields and not one more.

The most important thing to decide is what is vital information for basic functioning of the CMS. When you are creating a CMS which uses database you need to have at least three workflow screens dedicated to accessing the database. One where you ask the human for access information to the database, one in case the wizard can access the database and one error screen when the wizard cannot access the database.

In case of flat CMSes you need to check if PHP scripts have read and write permissions to the file system. In SlothCMS this step is handled during the first run check where front-end asks the back-end if configuration files exists and if they are writable. If there are configuration files, the first run checker redirects the human to login page. Otherwise the human is redirected to the initial wizard.

Server settings

As the first step of the wizard my choice was to ask the human about the web site itself. Most important question is the web site's name/title because the name is used quite often in title tag inside the head tag and quite often as a logo, depending on the front-end developer's choice. Second field which I chose to add was subtitle because I use it quite often.

There were couple of fields which I thought were important and were removed at least once so far. Main language is one which will find its way back to the wizard in the future because I would like to translate SlothCMS but at this point when SlothCMS is at pre-alpha stage I don't even have good dataset to offer the human. But when it comes back it'll be the first screen of the wizard because offering human to use the CMS in their language from the beginning is better than offering language selection later.

(Un)fortunately Date Format is one thing which won't find its way back to wizard probably ever again. It was an interesting idea and if someone was able to create a good implementation in an initial wizard I'd be more than happy to look at it because dates can be very tricky. I am quite sure that I could create a decent implementation but that's not good enough. Temporarily SlothCMS will use a default date format "Month day, Year" and when I start working on internationalization there will be a database with most common date formats for every language.

Timezone is another tricky one. It's tricky because you can host your server in a different timezone and won't even know about it. Or you can choose to host it somewhere else than you are now. Should the wizard follow your timezone or your server's timezone or let you decide? After going back and forth my decision was to leave timezone settings out of the initial wizard because it's not a vital information to run the CMS.

User settings

When it comes to user there are two or three necessary fields which need to be filled:

  1. username
    • SlothCMS requires it
    • generally optional when e-mail works as a username
  2. password
  3. e-mail

SlothCMS's initial wizard asks for user's display name but by the end of May 2018 it can be a bit tricky to store all three things because it can easily be classified as personal information. Luckily there is a plan to implement encryption on users config file before leaving pre-alpha stage.

When human fills these fields and clicks "finish" button they are redirected to success page when the back-end responds with information that config files were created and saved. When back-end responds with an error, initial wizards goes back to step one, web site settings, and shows an error. In the future I'll have to work on error states more closely but for the time being it's a good enough solution.


When you are designing an on-boarding wizard ask only for information which is necessary. You can ask for unnecessary information but you need keep in mind that it'll distract the human from getting to where you are leading them. You don't want to communicate to other humans that you are pain in the behind to work with.