mRFC 0007: Midgard Site Creation Wizard

This document describes a wizard for making setting up new websites with Midgard CMS easier. This mRFC been submitted to the Midgard Community for discussion and approval under the Creative Commons Attribution-ShareAlike license.

Background

New users of Midgard CMS are constantly having problems with the question "What do I do now?". After they have finished the actual installation struggle Midgard does not provide any obvious solutions on how to get started with creating a new website with the CMS.

Earlier this problem was very difficult to solve, as there were as many ways to use the Midgard Framework as there were users, but now that MidCOM and midcom-template are the default ways of building new sites things are lot easier.

In addition to newbies, Midgard site creation also includes several repetitive and boring tasks for experienced Midgard users. With a smart wizard system most of these could be automated, bringing the time needed for setting up a Midgard site from 30 minutes to only few minutes.

Vision

When Midgard has been installed the user is given an URL where to access the "Midgard CMS Start Page". The URL would be determined from the server's hostname, or failing that default to localhost.

The Midgard CMS Start Page would have a welcome message, Midgard logo and some system information (installed software versions etc). In addition to these, there would be a "Login to create a website" link leading to the Wizard.

The Wizard would ask for SG0 admin authentication, and after guide the user through the site creation process and set up all the required base data. After this the only action needed before starting to use the site would be to create the Apache VirtualHost, and even that could be automated with a Nadmin Studio -style apacheupdate.pl script.

Midgard CMS Start Page

Midgard CMS Start Page would be a simple host powered by the midcom-template. It would only include a root topic with the "Welcome to Midgard CMS" article and a subtopic that would provide access to the Midgard Site Creation Wizard but would be hidden from non-admins by having ViewerGroup set to SG0 admin group GUID.

There should also be links to the main Midgard community resources like the Midgard Documentation site, IRC channel and mailing list.

Wizard

The Wizard would be implemented as a MidCOM component to gain access to features like the localization engine and datamanager. This should not be a problem since MidCOM will be available in all Midgard installations starting from 1.6.0. The Wizard will have the following screens:

1. Set up organization

This screen presents the user with two forms, selectable via radio buttons. The first form enables user to input an organization name and admin user username and password, and the second one provides list of existing organizations (sitegroups) to select from.

A new sitegroup will be generated if required. In addition to the sitegroup administrator group, the Wizard will also create two additional groups: "Layout owners" and "Content owners".

2. Set up host

This screen presents the user with a host creation form which queries the hostname (by default the current hostname), and as "advanced options", port and prefix. If port hasn't been filled 80 will be used.

The host will be created and set to use midcom-template as the root page.

If the user tries to create the host on top of "Midgard CMS Start Page" an error message will be raised. Same with trying to create the host on top of another existing Midgard site.

The Wizard will also touch the /tmp/apachemodified flag file so that a possible apacheupdate.pl script will notice that the midgard-data.conf VirtualHost definitions should be regenerated and Apache restarted.

The host can override step 3. by providing a custom style defined by style GUID in root page parameter "midgard.admin.sitewizard","custom_style".

Application initialization (optional)

If the root page includes a page element named "__init", it will be evaluated by the site wizard. This page element can be used for running some application data initialization code, like creating a root topic.

The init snippet should contain executable PHP code. To provide the site wizard information on whether the initialization succeeded, the initialization run should be handled by defining a function template_init which will take the host object and sitegroup ID as arguments:

bool template_init(obj host, int sitegroup);

The template_init function should return a boolean on whether the initialization succeeded. If the boolean is false site wizard will clean up the host and return user to the host creation form. The initialization function must also clean its data up in case of failure.

The initialization function can provide information on what failed in the initialization by putting a string into the following variable:

$GLOBALS["midgard_admin_sitewizard_init_errstr"]

3.1. Configure host (optional)

If the root page included a DataManager schema array in page element named "__schema", a datamanager-powered screen for configuring the website will be presented. Using the schemas the application developers can allow the application to be configured.

The contents of the datamanager form will be stored into object defined by parameter "midgard.admin.sitewizard","config_location", possible values being "host" and "sitegroup".

3. Setup layout

This screen presents the user with a selection of prebuilt layouts to start from. The layout list is generated by listing styles that have their names prefixed with "template_".

The list will display the style name, and optionally description and credits if those have been added as specific parameters. A preview screenshot will also be displayed if an image for it has been stored into the style with name "__preview.jpg". The image should be 250x150 pixels.

A child style of the selected style will be created into the user's sitegroup and the host will be set to use that. The organizations's "Layout owners" would be set as the owner of the child style.

Description displayed in the style list can be stored into parameter "midgard.admin.sitewizard","template_description", credits into parameter "midgard.admin.sitewizard","template_credits" and possible licensing information into "midgard.admin.sitewizard","template_license". Possible values for the template license include:

"GPL": GNU General Public License
"CC-devnations": Creative Commons Developing Nations license
"CC-by-2.0": Creative Commons Attribution license 2.0
"CC-something": Some other Creative Commons license, check correct name from license path
"Proprietary": All rights reserved

3.1. Configure layout (optional)

If the style included a DataManager schema array in style element named "__schema", a datamanager-powered screen for configuring the style will be presented. Using the schemas the style template designers can allow style users to easily customize the styles by uploading images, setting up colors, etc.

The contents of the datamanager form will be stored into the child style.

4. Set up site structure

This screen would present the user with a list of "Site types", or site structure definitions. These definitions would be stored in PHP array format as snippets named with prefix "structure_" in the "_config" snippet directory of the component.

The site structure definitions would provide some basic site structures like a corporate website with its "About us", "Products" and "News" topics powered by appropriate components, or a blog with topics like "Blog", "RSS aggregator" and "Photos".

When the site structure has been selected, the appropriate topic structure will be created, and the parameters set to the host record for midcom-template to use the new topics.

The root topic of the new site will be named by default using the hostname and prefix of the website, suffixed with "root topic", and the AIS topic will be named in the same way, except with a "__" prefix and "AIS topic" suffix.

TODO: define the site structure definition format. TownPortal uses the following:

$TownPortal['group_site_structure'] = array (

        'feature_title' => array (

        'component' => 'component name',

        'url'       => 'url name of the feature',

        'icon'      => 'icon name',

    )

);

5. Set up Apache VirtualHost

The final screen in the wizard will congratulate the user on the successful creation of a new Midgard-powered website. In addition, it will provide an example VirtualHost declaration that can be copy-pasted to the midgard-data.conf file and instructions on how to get started with the site.

Datagard requirements

For the vision to work, Datagard, Midgard's new database setup tool must have some features:

Forced installation of MidCOM and the "Midgard CMS Start Page" host
Setting up the "Midgard CMS Start Page" host so that Apache will serve it

Schedule

Together with prebuild binary packages, this site creation wizard will make Midgard much more accessible for new users. Unfortunately it will be too late for the Midgard 1.6.0 release, but it could be aimed to the next minor release.

Once the mRFC 0007 has been passed Nemein Oy will develop the site creation wizard. Funding from a Finnish Midgard hosting company has already been arranged.

Midgard documentation and marketing should also be modified to accommodate the new easy way of getting started with Midgard.

Future ideas

The site Wizard could have a partner mode where resellers of a Midgard hosting company could set up sites for their clients.

If Midgard has the Quota patch enabled, the screen 1. of the Wizard could also have the needed fields for setting a quota for the organization.

In addition to midcom-template, the Wizard could also be adapted to support TownPortal and OpenPSA host creation but this will need more configurability.

Definitions

Wizard: An user interface that leads an user through some dialog steps. See WikiPedia definition.

Back