Tutorial1: Building a data entry form

Tutorial1: Building a Data Entry Form

This document will lead you step by step through the process of building and testing a form with Ebase Xi, and will familiarize you with working with the Ebase Xi Designer.

Part 1: Building a simple form

In this tutorial, we will create a simple one-page form. We will pretend this is to be used by the film industry to collect nominations for the annual Oscars event.

Note, if you have a problem at any time, enter Ctrl Z to undo the most recent change.

Create a form and place fields on the page.

Start the Ebase Xi Designer.

Click File > click Preferences > General tab, check Default Presentation Template: is set to ebaseSamples:/Presentation/Templates/xiDefault.

Create a new project: right click in the tree panel on the left-hand side of the designer window and select New > Project, name the project Tutorials.

Create a new folder for the tutorial: right click on the Tutorials project and select New > Folder, name the folder Tutorial1.

Create a new form: right click on the Tutorial1 folder, select New > Form and name the form Oscars. The system will now open the form editor and display the first page Page_1.

We are going to divide the form into two parts – About the nomination and About the applicant. To achieve this we will use Group Panel Controls which support header and trailer texts.

Drag a Group Panel Control from the Palette onto the page and drop it on the bottom of the form header text – a black line is displayed to show the drop location.

Hint: when dragging/dropping controls, you can drop them in either the WYSIWYG View Panel or the Outline View Panel.

Double click on the group header text <no group header set> and change this to About the nomination.

Now we will add fields to this Group Control. Click on the group header text to select the control then click the Add/import multiple fields icon on the WYSIWYG View toolbar (at the top of the central panel).

Add the following fields (use the keyboard down arrow or click the Add Field icon to add more fields):

Field Name	Field Type	Display Type
Nominee	Character	Text
Award	Character	Dropdown
Reasons	Character	Textarea

Let the Field data length and label text columns take default values. Click OK to add the new fields.

Note that for each field added, both a Field and a Field Control have been created. A Field is a form-level element that is available for display on any page - Fields are shown in the Fields View. A Field Control represents the display of a field on a specific page, and each Field Control is linked to an underlying Field - Field Controls are shown in both the Outline View and the WYSIWYG View on the pages where they appear. Ebase Xi is a little unusual in that many presentation properties are configured on the Field, not on the Field Control where you might expect to find them; this includes Display Type: Text, Dropdown, Textarea, Checkbox etc, Display Length, plus other presentational properties.

9. We will now add the second Group Panel Control after the first one. To do this, drag another Group Panel Control from the Palette and drop it onto the first Group Panel Control in the Outline View; the black line showing the drop location should be underneath the control icon – to indicate drop after as opposed to drop inside.

Hint: we could alternatively have used the WYSIWYG View to do this: drag the new control over the group header text of the first Group Panel Control; a small blue box is displayed at the top left of the control – with the left mouse still held down, move the mouse pointer over this box which then pops up a control tree panel showing all parent controls. Drop the new control after the first Group Panel Control as described above.

Double click on the group header text of the new control and change this to About you.

Click the Add/import multiple fields icon on the WYSIWYG View toolbar again. Add the following fields:

Field Name	Field Type	Display Type
Name	Character	Text
Address	Character	Textarea
Postcode	Character	Text
Email	Character	Text

As before, let the Field data length and label text columns in the wizard take default values.

We will now add a submit button. Drag a Button Control from the Palette (section General) and drop it after the second Group Control; using the Outline View is the easiest way to do this – ensure that the black line showing the drop location is underneath the target control icon.

Double click on the button and change the text to Submit Application.

At this point, the Designer view should look like this:

Try running the form to see how it looks in a browser – click the run icon on the main form toolbar. You will notice a few differences; this is because the WYSIWYG View adds a number of things

e.g. indicators for empty texts, to make page design easier. You can see how a page will truly appear at anytime by clicking the Toggle designer view icon on the WYSIWYG View toolbar.

This is a toggle switch so clicking it again returns to the assisted display.

Note: in the browser, there is no data entry field opposite the 'Award' label. This is because we have declared the Award field as a dropdown list but have not yet told the system which values to display in the list. We’ll fix this in a moment.

We will now make some of the fields mandatory.

Click on the Nominee field in the WYSIWYG View – anywhere will do, and then click the Mandatory checkbox in the Properties View (section Field Control).

Hint: clicking the help icon at the top of the Properties View displays the help page for the properties currently being displayed.

You can also press the F1 key from any point in the Form Editor to get local help on the element currently in focus.

Repeat the process for fields Award, Reasons and Name.

Hint: You can do this in a single operation by holding down the Ctrl key to select multiple Field Controls and then right clicking and selecting Set Mandatory.

Now we have the basic form, we can set about enhancing it.

Make the Reasons field larger: in the Fields View, click on the Reasons field– its properties are displayed in the Properties View.

In the Presentation section, change the Display Length property to 50, and the Number of Rows property to 8.

17. Create a dropdown list of awards by first creating a Static List of award values and then associating the list with the Award field:

· Right click on the Tutorial1 folder in the tree and select New > Static List and name the new list OscarAwards

· Enter values in the list - use the keyboard down arrow or click the icon to add new values:

Display Text	Return Value
Best Actor	A
Best Director	B
Best Supporting Actor	C
Best Music Score	D

· Click the Save icon at the top of the editor

· Click on the Oscars form in the open items panel at the top of the screen to return to the form editor (or double click on the Oscars form icon in the tree)

· Click on the Award field in the Fields View – its properties are then displayed in the Properties View. Click on the … button to the right of the Static List property in the Lists section and select the OscarAwards list we just created.

Add some texts:

Drag a Text Control from the Palette (section General) and drop it at the top of the page – as the first child of the Page Control. Again this is most easily achieved using the Outline View.

Cut and paste the following text into the popup:

Welcome to the new democratic Hollywood Oscars nomination process. You can make as many nominations as you like, and we will select our shortlist of candidates based on the most popular choices.

Drag another Text Control from the Palette and drop it after the Email Field Control. Cut and paste the following text into the popup:

Supplying your email enters you in our fabulous holiday for two at the Hollywood Oscars competition.

Hint: If you use the Outline View as the target for the drop, hover the mouse over the icon of the Email Field Control – this indicates add after the control as opposed to add to.

Add some styling:

Right click on the Welcome text at the top of the page and select the Style Assistant icon to open the control’s Style Assistant. This dialog allows you to style a control.

Click the … button opposite the Text property and in the displayed dialog box set the Bold property dropdown to Bold, the Size property to 18px and the Color property to Green.

Click OK twice to see your styling changes in the WYSIWYG view.

These styling properties can either be local values or linked from a Property Set in the form’s Presentation Template.

Right click on the Supplying your email… text and select the Style Assistant icon to open the control’s Style Assistant. Click the … button next to the Text property and in the displayed dialog box set the Color property to red.

Tweak the presentation.

At the moment the field labels Nominee, Award, Reasons etc are quite a long way from their corresponding data entry boxes, so we will move them closer together. Click on the About the nomination text (or click on the first Group Panel Control in the Outline View) to select the first Group Control. In the Properties View, you will see that the Layout type property is set to Field Grid – with this layout all child controls are displayed in a table with each control on a new line. Selecting the control displays a yellow box above the control as shown below and in this box there are two slider icons which can be used to change the table column widths used in the layout. Drag the first slider icon to the left to change the width of the label column. Repeat this exercise for the second Group Panel Control.

Re-run the form to check that it looks OK in a browser. Click the Submit Application button and see what happens when the mandatory fields are not completed.

Part 2: Introducing validation

None of the fields in the Oscars form have any obvious need for validation, so we will introduce a new field. We will ask our users whether they work in the film industry, and if they do, we will issue an error message saying they can't make a nomination.

Add a new field IndustryWorker after the Name field:

Click the New Field icon at the top of the Fields View and add a new field IndustryWorker, press Return
In the Properties View change the following properties for the field:

· Display Type (Section Presentation) to Checkbox

· Field Type (Section General) to Boolean

· Label Text (Section Texts) to "Do you work in the film industry?"

Drag the field from the Fields View to the WYSIWYG View and drop it after the Name field.

Add a validation check to run against this field:

Right click on the new field in the WYSIWYG View and select Events

The Validation tab is already selected. Click on the script builder wizard icon .
At the top of the panel:

Set the target folder to the Tutorial1 folder (this should already be set)
Select Language FPL

Select Add a validation check and click OK
From the dialog box, select the equals condition (=) from the center dropdown and enter Y in the right-hand box, then click the Add Condition button
Enter "Sorry, you cannot submit a nomination" in the error message field.
Click OK.

Click on the Oscars form in the open items panel at the top of the screen to return to the form editor. Then run the form and verify that it works as expected:

Click the checkbox for the IndustryWorker field and click Submit application
An error message should appear above the field
Uncheck the new field and try again. It should work OK.

In this example, we have used the script builder wizard to generate a simple script. In practice, you are more likely to create a new script to add whatever programming logic you require and then add this to an event. See Server-side Programming for details of available scripting languages.

That completes this tutorial. There are still quite a few things we need to do to make this into a working application – perhaps the most obvious is to add some programming logic to the Submit Application button to collect the details entered and then do something with this information – typically this would be one or more of: writing to a database, calling a web service, sending an email. These subjects are explored further in other tutorials.