Example Code for using Embperl::Forms and the wizard.pl application
===================================================================
On Unix you can access this example using
make start
and then accessing
http://localhost:8531/eg/forms/wizard/action.epl
Continue with step 6
On Windows this example assumes that Embperl is extracted under
C:\perl\msrc\embperl
and Apache is installed at
C:\Programme\Apache Software Foundation\Apache2.2
In this example Embperl is installed on Windows and uses Apache as CGI script.
The same should also work with mod_perl and Unix. You only have to modify
the httpd.conf accordingly.
The example assumes the Perl is already install and available in your PATH.
1.) First of all install Embperl
cd C:\perl\msrc\embperl
perl Makefile.PL
-> Answer all question with 'N' (because we don't use mod_perl in this example)
nmake
nmake install
2.) Copy CGI Script to Apache directory
copy epocgi.pl "C:\Programme\Apache Software Foundation\Apache2.2\cgi-bin"
copy embpcgi.pl "C:\Programme\Apache Software Foundation\Apache2.2\cgi-bin"
3.) Modify the configuration file
It is located at
C:\Programme\Apache Software Foundation\Apache2.2\conf\httpd.conf
At the end add the following directives:
# ----------------------------
AddType text/html .epl
AddType text/html .ehtml
Alias /forms c:/perl/msrc/embperl/eg/forms
SetEnv PERL5LIB c:/perl/msrc/embperl/eg/forms
SetEnv EMBPERL_OBJECT_ADDPATH c:/perl/msrc/embperl/eg/forms/lib
SetEnv EMBPERL_SESSION_HANDLER_CLASS no
# optAllFormData + optRawInput
SetEnv EMBPERL_OPTIONS 0x2010
<Location /forms/pages>
Order allow,deny
Allow from all
Action text/html /cgi-bin/embpcgi.pl
Options ExecCGI
</Location>
<Location /forms/wizard>
Order allow,deny
Allow from all
Action text/html /cgi-bin/epocgi.pl
Options ExecCGI
SetEnv Embperl_Appname setupwizard
SetEnv Embperl_Object_Base base.epl
SetEnv Embperl_Object_App wizard.pl
</Location>
# ----------------------------
4.) Start Apache on the command line
cd C:\Programme\Apache Software Foundation\Apache2.2
bin\httpd
-> Apache will write it's logfiles in C:\Programme\Apache Software Foundation\Apache2.2\logs
5.) Call a simple page
Per default Apache listens on Port 8080 on Windows, in case you have installed
it on a different port please change the followings URLs accordingly.
Open the following URL in a browser:
http://localhost:8080/forms/pages/loop.htm
This shows the environemnt of the CGI script. This is a very simple Embperl page.
6.) Calls the wizard
Open
http://localhost:8080/forms/wizard/action.epl
This will show you a wizard where you can enter setup informations. The wizard will
ask page by page what is necssary. It will ask different things depending on your input.
For example you can choose different ways to get to the internet and it will ask the
access data (can call different pages internaly) depending on your choise.
If you choose "import" on the first page, you get an form that modifies itself dynamicly
depending on what type you chosse at the top of the page.
7.) The files
Here is an overview of all files underneath the eg/forms directory:
- eg\forms/Embperl:
Directory for modules of the Embperl::MyForm namespace which are used to customize
the forms and add addtional controls
* MyForm.pm
This defines the Embperl::MyForm Object which overwrites some methods to tell
Embperl::Form where to located additional objects.
- eg\forms/Embperl/MyForm/Control:
Directory for Custom controls
- eg\forms/Embperl/MyForm/DataSource:
Directory for custom datasource objects. Datasource object are used to fill
select or radio controls, as far as they don't have static data in the form
definition itself. Use the datasrc => attribute to specify a datasource object.
The example comes with two datasource
objects. These two only return static data, but datasource objects can return
any data for example from a database.
* languages.pm
* netmask.pm
- eg\forms/css:
* EmbperlForm.css
Stylesheets
- eg\forms/js:
* EmbperlForm.js
* prototype.js
Necessary JavaScript code
- eg\forms/lib:
Generaly code
* footer.epl
This file is included in every page at the bottom. It is called from base.epl
* header.epl
This file is included in every page at the top. It is called from base.epl
* wizard.epl
This file contains the HTML layout for the wizard. It contains several methods
which can be overwritten in the page objects to customize the layout.
* wizard.pl
Thie is the controller object of the wizard. It controls the workflow.
- eg\forms/pages:
* loop.htm
Simpley Embperl page as example
- eg\forms/wizard:
This directory contains the actual pages of the wizard and it's configuration
* base.epl
This file defines the HTML layout of the page in which ths wizard is embedded.
* wizconfig.pl
This file contains the configuration of the wizard.
The method "getpages" must return an array ref of all page files that are
used by the wizard.
The method "init" is called on every request and can be used for initialization
purposes.
Every of the remaining files in the directory define a page for the wizard:
action.epl
do.epl
dsl.epl
exportslave.epl
finish.epl
gateway.epl
importslave.epl
inetconnect.epl
isdn.epl
name.epl
network.epl
organisation.epl
Every page contains four methods:
- title:
Is used to specify the title of the page
- condition:
The page is only displayed if the method return true, otherwise it is skipped
- show:
This method contains the code and HTML which is actually shown for the page,
including the form elements.
- verify:
This method is called after the user has pressed Next. If it is used to verify
the user input. If the input is ok, it should return true, othwise it should
return 0 and set $fdat{-msg} to the error message.
8.) Inclunding forms
A form is defined by a fields definition which is passed to the showfields method.
A fields definition consists of a set of controls. Each control has a set of
attributes.
Available controls can be found at embperl/Embperl/Form/Control
Each control contains a description of the possible attributes.
Some controls (like select, selectdyn, radio, checkboxes) can get it's input
from a datasource control (see above). In the example code most of the datasrc
attributes are renamed to xdatasrc because the datasource object are not
included in the example code.
Each control definition can also contain a validation rule. See Embperl::Form::Validate
for more informaion on validation rules.