[ic] What Does it Take to Create Wizards

[interchange-users@interchange.redhat.com]

Quoting Zack Johnson (zack@office.standardprinting.net):
> The wizard feature takes the cake!  However, I'm having a hard time finding
> documentation for it.

There is no documentation -- it isn't really a feature, like much of the
stuff in the UI. It is just a collection of Interchange features and
constructions.

The main part of the wizard is the [table-editor ...] tag with
the wizard option selected. I have never gotten to documenting
the table-editor UserTag, but it is what the UI uses for editing
DB stuff.

> After looking at the "Commerce Launcher" it seems
> like the following are the basic ingredients:
> 
> include/wizard_checklist
> include/wizard_profiles
> wizard/access
> wizard/autoload
> wizard/index.html
> (any additional pages, like: wizard/step_one.html)
> 
> IN TABLE 'ichelp': HTML help for each step (e.g. wizard.step_one)

That is basically it.

> 
> I have several questions regarding the above:
> 
> 1) Are the names of the files/fields changeable?  e. g. can/should I use
> 'mywiz/access'? How about 'ichelp': mywiz.step_one?

Yes -- if you look at the different pages of the supplied wizard,
we just name variables arbitrarily.

> 2) I think I understand checklist.  If I don't want one, must I still have
> the file?  I notice it calls wizard_profile

The checklist is not required.

wizard_profile is to supply the checks for whether the box should
be checked as complete or not, but also to supply check for the
different forms if they have ui_profile="*something" in the parameters.

> 3) Profiles looks relatively straightforward.  However, what are all the
> options that can go with [set][/set]?

Those are the same as OrderProfile, and used to be documented. That appears
to be one of the documentation pieces that died when the changeover was
made....many of them won't be useful, but some might.

> 4) What do 'access' and 'autoload' do?

Stefan answered that.

> 5) The table-editor tag in 'step_company.html' from the 4.8 Commerce
> Launcher looks profound.  Could someone walk us through it?

The state_options setting (which I won't show) sets up the option string so
that it is broken into Option groups if you have the right browser -- it
groups the State names based on your country.

--------------
[tmp country_options]
    =--select--[loop search='
		    fi=country.txt
		    rf=0,name
		    tf=name
		    ra=yes
		    ml=1000
	    '],[loop-code]=[loop-pos 1][loop-calc] return '*' if "[loop-code]" eq 'US'; [/loop-calc][/loop][/tmp]

[comment]
    The above just sets up a list of countries in an IC-style option
    string. It could have been done with a lookup except at one point, I
    broke down the countries into regions of the world. I think it just
    wasn't changed back.

    You can put the chunks in a page by itself (sans the [tmp]) to see
    what they generate.
[/comment]

[table-editor 

	bottom_buttons=1
	defaults=1
	no_bottom=1
	no_top=1
   	row_template="[scratch row_template]"

	left_width=180
	table_width=500
	wizard=1

[comment]
	The above just sets up the display of the wizard form. You can play
        with the options to see the difference.

        The row_template is the template HTML that describes how the
        items will look. If you don't set it, it will be like what you
        see in the Interchange UI table editor pages.

        The wizard=1 setting tells [table-editor] that a database table
        is not required or needed, and that no primary key for item
        access is required. If no table=tablename parameter is specified
        it actually sets up a dummy database object to use for the
        routines that need a table reference.
[/comment]

	ui_profile="*company"
[/set]

[comment]

	Just says we will use profile_company to check the form. It is:

	[set profile_company]
	    company=required
	    domainname=required
	    address=required
	    city=required
	    state=regex [A-Z][A-Z]
	    zip=required
	    country=regex [A-Z][A-Z]
	[/set]

	Pretty self-explanatory, I think.

[/comment]

	hidden.ui_return_to="__UI_BASE__/wizard/index"
	mv_failpage=@@MV_PAGE@@
	mv_nextpage="[either][cgi ui_nextpage][or]__UI_BASE__/wizard/step_email[/either]"
	mv_prevpage="[either][cgi ui_prevpage][or]__UI_BASE__/wizard/index[/either]"

[comment]
	Sets up the actions for the buttons. ui_return_to is where you go on
	hitting Cancel, mv_nextpage is for Next, and mv_prevpage is for Back.
	mv_failpage is where it goes when it fails the profile check -- i.e.
	right back to the current page.
[/comment]

	ui_wizard_fields="company domainname address city state zip country phone fax tollfree"

[comment]
	The variables that will be set as a result of this form. They go
	in the $Values hash.
[/comment]

	widget.company=text_40
	label.company="Your company name"

	label.domainname="Main domain name"
	widget.domainname=text_40
	help.domainname="Base Internet domain name, e.g. yourcompany.com"

[comment]
	The rest are just the widget callouts.
[/comment]

	label.address="Street address"
	widget.address=text_40

	label.city="City"
	widget.city=text_40

	passed.state=`$Scratch->{state_options}`
	widget.state=select
	label.state="State"
	help.state="Two-letter state code"

	widget.zip=text_10
	label.zip="ZIP/Postal code"

	label.country="Country"
	passed.country=`$Scratch->{country_options}`
	widget.country=select

[comment]
	Here is where we use the previously-generated country_options
	Scratch variable as the options for the select box.

	We could have done much the same thing with:

	    label.country="Country"
	    database.country=country
	    lookup.country="code,name"
	
[/comment]

	label.phone="Telephone number"
	widget.phone=text_20
	help.phone="If you don't wish to provide this, leave blank and it will not be shown."

	label.fax="Fax number"
	widget.fax=text_20
	help.fax="If you don't wish to provide this, leave blank and it will not be shown."

	label.tollfree="Toll-free number"
	widget.tollfree=text_20
	help.tollfree="If you don't have one or don't wish to provide it, leave blank and it will not be shown."


]

--------------------------

When the user is done with the form, the ui_wizard_fields:

    company domainname address city state zip country phone fax tollfree

will have some values in them, presumably checked for some requirements.
They can hit Next, and go to the next set of inputs. After all the 
inputs are collected (the checklist helps the user determine whether
they are all complete) the developer can do something with the information.

Maybe that will give a bit better idea of what is going on, but I was not
planning to release the wizard for general use; too much documentation and
explanation to do. Perhaps someone will do a HOWTO that can help.....

-- 
Red Hat, Inc., 3005 Nichols Rd., Hamilton, OH  45013
phone +1.513.523.7621      <mheins@redhat.com>

If you like what you're gettin', keep doin' what you're doin'. -- Hector