First Application

From Morfik Wiki

Building your first application with Morfik The best approach to mastering a new software development tool such as Morfik is to 'learn by doing'—so here is your chance to do just that. In this chapter, you will create your first web application from start to finish using some of the core features found in Morfik. No prior knowledge of Morfik is necessary.

Introduction

This article focuses on what you can do with Morfik. At this stage you do not need to know how or why—you will learn about those later.

Creating your first application—a guest book

At this stage, you might be saying to yourself, “Hey, wait a minute! I don't know anything about Morfik, or building a web application for that matter!” Well, fear not! We're not only going to show you how to build a web application from start to finish, we're going to prove how quick and easy it can be—even if you know nothing about application development!

We're going to build an online guest book application that lets users post messages to a message board. These tasks require a database (to store users and comments), user interfaces and a menu to navigate around the application.

During the process of creating this application—with its specific functionality—you will be exposed to many of Morfik's core features.

If you haven't already done so, please first install Morfik. Complete instructions are available here. Otherwise, start Morfik and let's begin!

Step 1—create the project

To build an application with Morfik, you must first create a project for the application. To create the project, use the 'New Project Wizard':

On the Home|New tab of the Ribbon bar, press 'New Project Wizard'.

The Wizard will first ask which template you wish to use for your new project (Figure 1). Select the 'Default' template to create a template project with three pre-configured forms. The 'Blank New Project' template will go through the same steps in the Wizard, but no template forms will be created.

Figure 1: Select the 'Default' template in the New Project Wizard

Press the Next button to continue.

You will now be asked for the name of the project (Figure 2). Specify 'GuestBook' as the name of the project and leave the location in its default state.

Figure 2: Defining Project File Name in New Project Wizard

Press the Next button to continue.

It is better to keep the files related to each project separate from each other. Select 'Yes' to create the project in a new folder (Figure 3).

Figure 3: Telling the New Project Wizard to creating the project in a new folder.

Press the Next button to continue.

The Wizard will ask for the target platform and compiler (Figure 4). Select 'Windows, Intel x86'.

Figure 4: New Project Wizard - Target Platform and Compiler

Press the Next button to continue, and then Finish to close the Wizard dialog box.

Wait a moment as the Wizard creates and opens the new project in the IDE. Click on the cross on the Index Form to close it—we'll come back to it later. This is what you should now see:

Figure 5: The New Project Wizard has successfully created a new project.

Congratulations! You've successfully created a web application! Granted, it doesn't really do anything useful, but that's not the point. By specifying settings in a Wizard, and without having written a single line of code, you now have an application that can be compiled, executed, deployed and has a built-in high-performance database!

Step 2 - Create and configure Guests Comments Table

We will create a table to store information about guests and their comments. We use the Table Wizard to create the table and will call the table 'Guests'.

Press the 'Table' button on the Ribbon Bar's 'Project|Document Wizards' tab to display the Table Wizard. Enter "Guests" as the table name as shown in Figure 6.

Figure 6: New Table Wizard - Table Name

Press the Next button to continue.

We now need to label the various columns of the 'Guests' table. Press the 'Add' button to create a new column. Set Name to GuestID and the Type to AutoNumber (Figure 7) and then press the OK button to close the Field dialog box.

Figure 7: Defining fields (columns) in the New Table Wizard

Press the Add button again to create another new column. Set Name to FirstName and Type to Text and then press the OK button to close the Field dialog box. Repeat the above steps to create five more columns:

Once the above fields are added to the table, you should have the list of fields shown in Figure 8.

Figure 8: Completed list of fields

Press the Next button to continue.

You can now specify that the GuestID should be used as the primary key to uniquely identify each record in the table (Figure 9). Select the 'Yes, use the following field(s) as the primary key' radio button and then press the ellipsis button to display the Define Primary Key dialog box. Select 'GuestID' column in the "Define Primary Key" dialog and then press the OK button to close the dialog box.

Figure 9: Defining the Primary Key in the Table Wizard.

Press the Next button to continue.

We're done defining the Guests table. Press the Finish button on the Wizard to close it (Figure 10).

Figure 10: Completed New Table Wizard Complete

You will see the table and the fields that you just created in the Table Design View (Figure 11). Any further adjustments to the fields can be applied from here, but we will leave the default settings for this application.

Figure 11: Table Design View

While we are here, let's add a dummy record to the Guests table for testing purposes. Press the [F12] key to switch to Table Data View (Figure 12). Answer 'Yes' if asked for confirmation on saving the table.

On the Home|Records tab of the Ribbon bar, click on the New Record command.

Add the following values in the record:

FirstName : Jon
LastName : Citizen
EmailAddress: jon@citizen.com
Comment: Some Test Comment
ContactMe: 1

Figure 12: Table Data View

The GuestID column will automatically be assigned the value 1 when the record is updated. On the Home|Records tab of the Ribbon Bar, press the Update button to save the new record.

Close the Guests table. The table is now ready to be used in your project and you should be able to see the new table under the 'Tables' category in the Project Panel.

Step 3—Create and configure Data Entry Form

We now create a new form (using the Form Wizard) to allow guests to enter their details and comments.

Press the Form Button in Project|Document Wizards on the Ribbon bar. This will start the Form wizard (Figure 13). Enter GuestForm as the form name.

Figure 13: Defining the Form Name in the New Form Wizard

Press the Next button to continue.

You can now select a layout for the new Form. We will be using both the header and the footer space, so place checks in both the "Yes, include a header band" and "Yes, include a footer band" (Figure 14).

Figure 14: Choosing header and footer in the New Form Wizard

Press the Next button to continue.

We want the Form to be linked to the data in the Guests table created in Step 2.

Select the 'Yes, link to the following data source' radio button and then press the ellipsis button to display the Data Source dialog box (Figure 15). In the Data Source dialog box, select the 'Guests' table.

Figure 15: Defining the 'Guest' table as the Data Source in the New Form Wizard

Press OK to close the dialog box and return to the wizard, then press the Next button to continue.

We can now select a style for the form. Since this form is used for data entry, select the 'Single Form' radio button (Figure 16).

Figure 16: Defining form style in the View Mode of the New Form Wizard

Press the Next button to continue.

We are now asked about whether we require a navigation bar on the new form (Figure 17). We won't be using a navigation bar in this form so select 'No'.

Figure 17: New Form Wizard—Navigation Bar

Press the Next button to continue.

We want the New Form Wizard to automatically add controls to our form, so select the 'Yes, add controls automatically' radio button (Figure 18).

You could also change the default controls that are selected for the fields. Click on 'Customize...' button to view the selected controls. You will notice that the Wizard may have selected a TextEdit control for the 'ContactMe' fields. Since this field is of Boolean type we can change the control from TextEdit to a CheckBox by clicking on the TextEdit control for the field and selecting CheckBox in the list of displayed controls. Once CheckBox is selected, click on OK to close the dialog.

Figure 18: New Form Wizard - Controls

Press the Next button to continue to the final step of the Wizard (Figure 19).

Figure 19: The completed New Form Wizard

Finally, press the Finish button and wait a moment as the Wizard creates and opens the new Form as shown below in Figure 20.

Figure 20: Form Design View

Step 4—Change Properties and add Events to the Form

Now that the wizards have created our Guest table and the GuestsForm, we can make changes to some of the form Properties and add a couple of Events before viewing it at runtime.

Changing Properties

The Property Inspector allows you to change the properties and characteristics of Forms, Reports and Controls and the objects within them. The Property Inspector panel appears along the left side of the workspace by default, but can be docked by clicking on the Pin icon or detached for use in a dual monitor scheme.

To work with Properties, Events or Styles, click on the Properties button in View|Panels on the Ribbon Bar. The panel displayed (Properties/Events/Style) alternates every time the Properties button is clicked. Alternatively, press F11 to bring up the Property sheet (Figure 21).

Figure 21: Form Properties Inspector

Set the following property of the form:

Select the "GuestID TextLabel" and "GuestID TextEdit" controls on your form by holding the shift key and clicking on each control and press Delete to remove them from your form. There's no need for the user to see or edit the GuestID value.

We now add text to the Header of the Form. Resize the Header to around 65 pixel height by moving the mouse between the Details Band and Header Band and dragging the border. Display the Insert Ribbon. Click the TextLabel button in the Standard Group then click on the Header band of the form. This should place a TextLabel control onto the Header band. Set the following properties of the TextLabel:

While TextLabel1 is selected, click on Style in the Home|Appearance ribbon and choose 'Big Heading'.

In the form Footer, select the TextLabel control with caption 'click here to add the form footer...' and update its caption property to following:

You could also resize the TextEdit controls that are placed on the form and update the TextLabels and CheckBox caption properties with a more descriptive text.

Once the above changes are applied to the GuestsForm, it should look similar to Figure 22.

Figure 22: Updated Data Entry Form

Adding Events

Now let's work with a couple of simple Events in this Form. Event properties cause an associated procedure or function to run when a particular event occurs. In our example, when the GuestsForm form is loaded a blank record has to be added to the Guests table to store the details that are about to be entered.

Make the 'Events' tab for GuestsForm active (Figure 23).

Figure 23: Form Events List

To create a blank record when GuestForm is loaded, we need to add a line of code to the "On Ready" Event of the Form. Please note, no records are actually added to the table until the form is submitted. You can either write the code manually or use of the "Web Actions" wizard, which includes a number of pre-defined events that could be used in your project. In this example we will make use of the Wizard.

Press the ellipsis button on the 'On Ready' event to open the Web Actions Wizard (Figure 24). Select Dataset from the Categories list and 'AddNewRecord' from the Actions list.

Figure 24: Web Action Wizard

Press the Next button to continue.

Select the "GuestsForm" from the drop-down (Figure 25) and then press the Finish button.

Figure 25: Web Action Wizard - Form Name Parameter

The Code Editor creates this new Event in the Form.

FX Code

Procedure GuestsForm.WebFormReady(Var Ready: Boolean); 
Begin 
    AddNewRecord('GuestsForm'); 
End;

Published Message Sub WebFormReady(ByRef Ready As Boolean)
    AddNewRecord("GuestsForm")
End Sub

published message void WebFormReady(ref Boolean Ready)
{
    AddNewRecord("GuestsForm");
}

Now let's add the Submit Button on GuestsForm. Once clicked, it will save the entered details as a new record in the Guests table.

On the Insert|Standard Ribbon Bar, click on the Button icon then click on the bottom right hand side of the GuestsForm Footer area. You should now have a button on the Form Footer with default caption of Button1.

Make sure Button1 is selected and use the Property Inspector to change the Caption property to Submit.

Double-click on Button1 to create an 'On Click' event code stub in the editor so you can add a simple line of code (as shown below) to submit the record.

FX Code

Procedure GuestsForm.Button1Click(Event: TDOMEvent); 
Begin 
    SubmitPage(Nil);
End;

Published Message Sub Button1Click(Event As TDOMEvent)
    SubmitPage(Nothing)
End Sub

published message void Button1Click(TDOMEvent Event)
{
    SubmitPage(null);
}

You now have two Events for GuestsForm. We will come back to this Form to add conditions to check the information that is entered, but for now let's Preview the Form.

Step 5—Preview and test the Data Entry Form

Now that we have created and configured the main Data Entry Form for our application, let's do a quick preview and test of the Form.

If necessary return to Design View, then right click on the GuestForm. In the context menu, click on 'Form' and then select 'Preview Form' from the submenu (Figure 26).

Figure 26: Preview Form

The project is compiled and a blank GuestsForm is displayed.

Figure 27: Form in Debug Browser

Add some information in the fields and click on the Submit button. Once data is submitted, close the debug browser window. Save and close the GuestsForm in the Design View. To see the new record, open the Guests Table in Data View.

Step 6—Create a new Query

In preparation to display a list of comments, we want to combine data from the FirstName and LastName fields into an expression called 'FullName' and use this as the data source for the comments list form. We can use the Morfik Visual Query Designer to create a Query that does this.

Click on the Morfik Power Menu (Blue power button at the top left) and select New Item|New Query as shown in Figure 28.

Figure 28: Creating a new query

In the New Project Item dialog set the name of the query to 'CommentsQuery' (Figure 29) and click OK.

Figure 29: New Query Name

In the Visual Query Designer, select the Home Ribbon and click on Tables|AddTable (Figure 30). Select the 'Guests' Table and press OK to use it in this query, then click on Cancel to close the Data Sources dialog.

Figure 30: Query Data Sources

Double click on (or alternatively drag and drop) "Comment" field in Guests Table to be added as a field to the Query.

To create an expression called 'FullName' that concatenates the FirstName and LastName fields in the Guests table, add the following to the next filed in the query as shown in Figure 31:

FullName : ("FirstName" || ' ' || "LastName")

Make sure the 'Show' Checkbox is ticked for the FullName expression to be displayed.

Figure 31: Visual Query Designer

To view data in the query, select the Home Ribbon and click on click on the View|Data View (Figure 32). When prompted, confirm that you would like to save the Query.

Figure 32: Query Data View

In the Data View, you can see two records with comments and full name of the guest who posted it. We will use this query as the data source for the Comments List Form in the next step. Save and close the query by clicking on the cross on 'CommentsQuery' tab.

Step 7—Create and configure Comments List Form

We will now create a second form for our GuestBook application that shows a full list of existing comments. Once again, use the Morfik Power Menu and select New Item|New Form. Call the new form 'CommentsListForm' and click on OK to open the new form in Design View. Dock the Property Inspector and you should have your form as shown in Figure 33:

Figure 33: New Comments List Form

Let's now setup the following properties of CommentsListForm:

Place a TextLabel control on CommentsListForm form by clicking on Insert Ribbon Bar and then on Standard|TextLabel, then clicking on the Details Band of the Form. While selected, set the following properties of the TextLabel (TextLabel1) that is placed on the form:

Place a second TextLabel next to the first and set these properties:

Expand the Document Header Band and set its height to 70px. Place a TextLabel (TextLabel3) control in the DocumentHeader band and set the following properties:

While the Header TextLabel is selected click on the Home Ribbon Bar and then on Appearance|Style. Select 'Big Heading'.

Click on the Detail Dand and set the following property:

Your form should look like the form in Figure 34:

Figure 34: Updated Comments List Form

The form is now ready to display guests comments. Right click on the form to show the context menu and select Form Preview Form to show the form in the Debug Browser (Figure 35).

Figure 35: Comments List Form Preview

Close the Debug Browser. Close and save the CommentsListForm in the Design View.

Step 8—Add menu options to the Index Form

Now that the two forms—GuestsForm and CommentsListForm—are tested and ready use, we add the relevant links on the main page.

If you recall, in Step 1 we created our project using the 'Default' template option, which automatically includes three forms—About, Content and Index.

The Index Form is the main form in the template. By default, it includes a subform where we can open the two new forms. In order to open these forms, we will create two URLs using the Publish URL feature.

Let's first create a URL for the Data entry form (GuestsForm):

Open the Index Form in Design View.

Select Subform2 in the Index Form and set its Form Property to 'GuestsForm', as shown in Figure 36.

Figure 36: Setting Form Property of Subform2

GuestsForm will now be displayed in the Subform2 area of the Index Form (Figure 37).

Figure 37: SubForm2 showing GuestsForm

This page needs a new name so that we can link to it.

Click on In the Home Ribbon Bar, click on URLs|Publish URL (Figure 38).

Figure 38: Publish URL

In the Page URL combobox, call this page 'GuestBookDataEntry' (Figure 39). We will use this Page URL shortly.

Figure 39: Creating Publish URL for the current state

We now need to make and name a page that displays the user comments.

Select Subform2 and set the Form Property to 'CommentsListForm' so that CommentsListForm is displayed within SubForm2. Once again, click on Publish URL in the Home Ribbon Bar and call the URL for the page 'CommentsListForm', then click OK.

The URLs for the two forms are now ready. We will now place two TextLabel controls in sidebar section of the Index Form and then use the Hyperlink Property to link these to GuestBookDataEntry and CommentsListForm.

Place a TextLabel control in the side bar under the About link and apply the following property changes:

Place a second TextLabel control in the side bar, under the 'Comments Entry' link and apply the following changes to its properties:

Figure 40: Design and Run time view for Index form

Let's now run the project by clicking on the Run Button. The project is compiled and the Index page is loaded in the browser.

Clicking on 'Comments Entry' and 'View Comments' loads the GuestsForm and CommentsListForm pages respectively.

Step 9—Updates in the Data Entry Form

There are a couple of simple routines that we could apply to this project to improve its functionalities.

It would be good to load the CommentsListForm after a comment is submitted in GuestsForm.

To achieve this, open GuestsForm in Design View. Open the Properties Inspector and make the Events Tab active. In the list of Events for GuestsForm, double click in the 'On After Submit' event. This is a browser-side event and the editor for the browser code is loaded. Add the following line of the code in the 'WebFormAfterSubmit' event:

FX Code

Procedure GuestsForm.WebFormAfterSubmit(Failed: Boolean);
Begin
    OpenPage('CommentsListForm','"OpenMode=Refresh"');
End;

Published Message Sub WebFormAfterSubmit(Failed As Boolean)
    OpenPage("CommentsListForm", """OpenMode=Refresh""")
End Sub

published message void WebFormAfterSubmit(Boolean Failed)
{
    OpenPage("CommentsListForm", "\"OpenMode=Refresh\"");
}

Also in the GuestsForm, we can check the values in the TextEdit controls and show a message if no value is entered. Double click in 'On Before Submit' and add the following code:

FX Code

Procedure GuestsForm.WebFormBeforeSubmit(Var Cancel: Boolean);
Begin
    If (Control_LastName.Text.Trim = '') OR
       (Control_FirstName.Text.Trim = '') OR
       (Control_EmailAddress.Text.Trim = '') OR
       (Control_Comment.Text.Trim = '') Then
       Begin
           Cancel := True;
           ShowMessage('All fields require data!')
       End;
End;

Published Message Sub WebFormBeforeSubmit(ByRef Cancel As Boolean)
        If (Control_LastName.Text.Trim() = "") Or 
           (Control_FirstName.Text.Trim() = "") Or 
           (Control_EmailAddress.Text.Trim() = "") Or 
           (Control_Comment.Text.Trim() = "") Then
            Cancel = true
            ShowMessage("All fields require data!")
        End If
End Sub

published message void WebFormBeforeSubmit(ref Boolean Cancel)
{
    if ((Control_LastName.Text.Trim() == "") || 
        (Control_FirstName.Text.Trim() == "") || 
        (Control_EmailAddress.Text.Trim() == "") || 
        (Control_Comment.Text.Trim() == ""))
        {
            Cancel = true;
            ShowMessage("All fields require data!");
        }
}

Conclusion

Congratulations! You've just completed your first Morfik application! To further empower the notion of 'learning by doing', we suggest you go through the sample projects that are installed with Morfik. Looking at the inner workings of a professionally developed application is another great learning approach.

How Do I: Create New Projects?

Learn how to create new Morfik projects in this video presentation. Two methods of creating new projects are explained. The quick method where a project is created based on the default settings and using the "New Project Wizard" with options to customize the new project. You will also see how some of the project options can be altered after the project is created.

Related Topics

• What you need before getting started
• Installing Morfik
• Customizing the environment
• Getting to know Morfik application workspace