Tutorial2: Building a Form with
Database Connectivity
See also: All Tutorials, Working with Databases, Controls, Form Editor
In this tutorial we will build a form with database integration, and assume that you have already completed the Building your first form tutorial and therefore have a basic familiarity with using the Verj.io Studio.
In this tutorial, we are assuming that the government has
introduced an education program for mature students. A certain number of
approved courses are offered by approved course providers. At the end of each
course, the student must sit a final test. If successful, they are issued with
a certificate, and the government will refund the cost of the course on
presentation of the certificate id. This form is an online application allowing
successful students to apply for the refund. The form will consist of three
pages: applicant details, course details, applicant bank details (for the
payment).
We will save all applications in the database (table APPLICANTS) and we will allow changing of existing applications as well as insertion of new applications. The key for the APPLICANTS table is the national insurance number. We will also be using two additional tables for dropdown lists: COURSE_PROVIDERS and COURSES. These three tables already exist in the database EBASE_SAMPLES provided with Verj.io.
If you need to create the EBASE_SAMPLES database,
scripts can be found in folder Server/databaseSchemas in the server installation.
We are going to import the fields used in this form from the
database schema. This is the simplest
way to create a form with database integration as it ensures that the
correct field type and length specifications are created, creates all the
mappings between the database resources and the form fields, and it involves
the least typing!
Check Studio
Preferences
Open the Studio Preferences Dialog by selecting File > Preferences from the menu and click the Page Editor tab. At the bottom of the page, check Page Navigation Panel Control. This ensures that the Page Navigation Panel Control is added to all new pages. This can be reversed at the end of this exercise, if required.
Import the database tables into the Verj.io
Studio:
Create a Dynamic List of course providers:
Note: This list will display column COURSE_PROVIDER from table COURSE_PROVIDERS. (i.e. the equivalent SQL is select course_provider from ebase_samples.course_providers).
Create a
second Dynamic List of course names:
This will
use column COURSE_NAME from table COURSES.
This list is a bit more complicated than the last one: firstly, we want to load
more columns from the database table when the user makes a selection, and
secondly, we only want the user to see the selection of courses provided by the
particular course provider they have selected using the previous list (course_providers_list).
Create a new form and import the fields
Hint: the fields are shown in the Fields View with
the most recently added fields at the top. These can be shown in alphabetic
order by clicking on the Sort fields icon .
Create an additional field to ask the user if they want
to modify a previous application:
You have now successfully created the form fields and we
will now start to customize the form display.
Create three pages P_Applicant, P_Course and P_Bank
Ø
By dragging the individual fields from the Fields
View to the Outline View or WYSIWYG View (this is the central panel)
·
When dragging to the WYSIWYG View, drop the
first field after the <no group info set> text – a solid black line
indicates the drop position
·
When dragging to the Outline View, a solid
black line indicates the drop position (under the target control icon means add after, to the right means add to)
Ø
By dragging multiple fields from the Fields
View to the Outline View or WYSIWYG View: hold down the Ctrl key to multi-select
the fields, then release the Ctrl key and drag the selections.
Drag and drop the Field Controls to rearrange them
Ø
Right click on the Group Panel Control in
either the Outline View or the WYSIWYG View and select Add
control to Group Panel then Existing
fields. Hold down the Ctrl key, select the fields,
then click Add. Drag and drop the Field
Controls to rearrange them
Fields for page P_Applicant:
NI_NUMBER PrevApplication APPLICANT ADDRESS POSTCODE DOB EMPLOYMENT_STATUS |
Outline View should look like this: |
Fields for page P_Course:
COURSE_PROVIDER COURSE_NAME COURSE_NUMBER COURSE_DURATION REFUND_VALUE CERTIFICATE_ID |
Outline View should look like this: |
Fields for page P_Bank:
BANK_NAME BANK_ACCOUNT_NAME BANK_ACCOUNT_NO BANK_SORT_CODE |
Outline View should look like this: |
Create three scripts which we will use with this form.
Create the named scripts below by right clicking on the Tutorial2
folder and selecting New > Script (Javascript) or New > Script (FPL) depending on your
preference. Examples are shown below for Javascript and FPL (the Ebase
built-in Form Processing Language).
Then cut and paste the script code below; if using Javascript
paste the code after the two importPackage statements at the top of the script;
if using FPL, check the syntax by clicking the Verify icon. Then save the script with the Save icon .
Script readApplicant:
This script
will be used to read in an existing application from the applicants table if
requested to by the user. If the record cannot be found, we will issue an error
message.
Javascript: |
FPL: |
if ( fields.PrevApplication.value
) { var rows = resources.APPLICANTS.fetch(); if ( rows == 0 ) { fields.PrevApplication.value
= false; event.owner.addErrorMessage("Could
not find a saved record for NI " +
fields.NI_NUMBER.value ); } else { resources.COURSES.fetch(); } } |
if [ PrevApplication = 'Y' ] fetch applicants; if [ $FOUND = 'N' ] PrevApplication = 'N'; message 'Could not find a saved record for NI ' + ni_number; else fetch COURSES; endif endif |
Script updateApplicant:
This script will be used to save the application to the
database at the end of form processing. If it's a new application, we use an insert, and if it's a modification
to an existing application, we use an update.
Javascript: |
FPL: |
if ( fields.PrevApplication.value
) { resources.APPLICANTS.update(); } else { resources.APPLICANTS.insert(); } |
if [ PrevApplication = 'Y' ] update APPLICANTS; else insert APPLICANTS; endif |
Script clearCourseDetails:
This script is used to clear previously selected course
details.
Javascript: |
FPL: |
fields.COURSE_NUMBER.value = null; fields.COURSE_DURATION.value = null; fields.REFUND_VALUE.value = null; |
course_number = null; course_duration = null; refund_value = null; |
Customize the P_Applicant page
NI_NUMBER |
Mandatory |
PrevApplication |
Immediate Validation |
APPLICANT |
Mandatory |
ADDRESS |
Mandatory |
POSTCODE |
Mandatory |
DOB |
Mandatory |
EMPLOYMENT_STATUS |
Mandatory |
Hint: you can do this faster by multi-selecting the controls with the Ctrl key, then using the right click menu.
Customize the P_Course page
39. In the Pages View, click the P_Course page
select course_name, refund_value, course_number, course_duration from courses where course_provider = xxx
You can see the mappings between the form fields and the list by clicking the “…” button opposite the Dynamic list mappings property.
These mappings have been created
automatically by the system - any form fields are mapped to corresponding
like-named list fields when the list is first associated with the field.
COURSE_PROVIDER |
Mandatory, Immediate Validation |
COURSE_NAME |
Mandatory, Immediate Validation |
COURSE_NUMBER |
Display Only |
COURSE_DURATION |
Display Only |
REFUND_VALUE |
Display Only |
CERTIFICATE_ID |
Mandatory |
(Setting Immediate Validation returns control to the Verj.io server whenever the user changes the value of the
field. For the COURSE_PROVIDER field, this will then result in the execution
of script clearCourseDetails
(see next action point) and will build the course names list which is dependent
on the value of the COURSE_PROVIDER field. For the COURSE_NAME field,
setting Immediate Validation
means we can immediately see the additional values loaded from the list -
course number, course duration and the refund value for this course.)
Customise the P_Bank page
Set the database
update script to run at the end of form processing
Add texts
On the Final Page tab of Form
Properties set:
From |
To |
<no group header set> |
Mature student application for refund |
<no group info set> |
Page 1: Applicant |
NI number |
NI Number |
PrevApplication |
Retrieve previous application? |
Dob |
Date of birth |
From |
To |
<no group header set> |
Mature student application for refund |
<no group info set> |
Page 2: The course you have completed |
Course number |
Course ID |
Course duration |
Course duration (weeks) |
Refund value |
Refund for this course (£) |
Certificate ID |
Your certificate ID |
From |
To |
<no group header set> |
Mature student application for refund |
<no group info set> |
Page 3: Bank details |
That ends the design of the form pages. Click on each page in turn and check that the page looks OK. To see how the pages will appear in the browser, click on the Toggle studio view icon on the WYSIWYG toolbar. This turns off all enhancements and assistants added by the Form Editor. Click this icon again to return to the assisted view.
And finally we can test the form: return to
the form editor and click the Run icon on the
form toolbar
51. Try
entering an invalid NI Number in the NI Number field and click the Next button (examples of valid NI numbers: AB123456C, JG103759A, WL457123)
52. What
happens if you enter a new valid NI Number and check the Retrieve previous application checkbox ?
53. Run the form, entering all the
details and submit the application. Then run the form again, entering the same
NI Number in the first field and clicking the 'Retrieve previous application?'
box. The details you entered initially should be fetched from the database
54. Note
how the contents of the course names list changes as you change course provider
55. Note
how the display only values for course number, course duration and refund value
change with the course name selection (these are being populated by the COURSES_list Dynamic List)
56. Click View > Execution log
on the studio menu to see a log of form activity and scripts executed
57. If
you have made a mistake following the instructions, you may receive an error
message at runtime. Hopefully the message will be specific enough to enable you
to resolve the error. If you get error message:Naming
exception error retrieving datasource jdbc/xxxxx, check that the Dynamic Lists have EBASE_SAMPLES specified as the
database
Change the error
message displayed for an invalid National Insurance number
When we enter an invalid National Insurance number, we get the error message: Field does not match xml regex pattern [A-CEGHJ-PR-TW-Z]{1}[A-CEGHJ-NPR-TW-Z]{1}[0-9]{6}[A-DFM]{0,1} This is clearly not a meaningful message to most people. So let’s be more helpful.
Format
of a National Insurance number is:<br><br>
AANNNNNNA
- in other words: 2 letters, 6 numbers, one letter<br><br>
The
2nd letter may not be D, F, I, O, Q, U or Z<br>
The
final letter is optional
In this exercise
we have set up the basic form for this application. In real life, we would
still have quite a lot to do, e.g. including a list for employment status,
addition of many more explanatory texts and customization of the layout and
styling etc.