Morfik 07 - Applications, Modules and Documents
From Morfikwiki.com
In today’s world of increasingly complex software, developers generally divide applications into pieces (generally in separate files) in order to make the work more manageable and to allow for easier reuse of code. Let’s establish that for all purposes we will call these pieces "modules".
This chapter is intended to give you some familiarity with how the Morfik WebOS AppsBuilder treats project modularization in terms of behaviors and features. This will help you better understand how things work with the projects that you will be creating and help you in planning your strategy for the creation of applications that might be complimentary or need to run on the same hardware.
The Morfik WebOS AppsBuilder offers a document-based view of your work, right from the start. The project explorer, which is the main view you see as soon as you open a project, is a categorized list of the documents that compose your project. There are several different types of documents; some of them are code modules such as forms, reports, web services and such, while others are queries and tables
We will start with an overview of the all the types of documents that can comprise a Morfik project, concentrating on code modules. We’ll see how they are created and how they work and then move on to take a look at the binary modules that the Morfik WebOS AppsBuilder generates.
Contents |
[edit] Document Types
The interface of the Morfik WebOS AppsBuilder is centered on the concept of documents that comprise your applications. Each document type is used for a different purpose in creating an application, from defining how information will be stored to how it will be presented to the user and how the user will interact with it.
 | Forms are documents for entering, displaying and editing information via the web. These are the documents that will compose your applications interface and define how users interact with it. |
 | Tables define how and what data will be stored by your application in a database. |
 | Queries are for asking questions to your application’s database in order to obtain a specific subset of data it has stored. |
 | Reports are documents for presenting information in a way suitable for printing and previewing how it would look on paper. |
 | Web Methods define ways for communicating between the browser and web servers, allowing your application to publish services for internal or public consumption. |
 | Modules are for developing building blocks of programmed code such as classes and data types that will be used throughout your application. |
The first four of these documents are visually editable documents and represent high-level objects of your application, while the latter two are mainly code modules and can only be edited as such. It is important to note that while forms and reports are visually editable they are also code modules and can be edited textually as well.
[edit] Code Modules
Regardless of the programming syntax of your choice, whether it be Pascal, C#, Basic or Java, the WebOS AppsBuilder will create and work with exactly the same modules. The modules will be declared with the appropriate syntax of each language but will all be functionally equivalent.
Code modules are, generally, treated as the normal types of modules defined in each of the target syntaxes. In Object Pascal they are units, in C# and Basic they are namespaces and in Java they are packages. These "types" of modules are normally used in everyday applications by developers who use these languages and should pose no mystery to those with some experience in the language of choice.
When you choose to create some types of code modules such as forms and reports you are actually creating two modules with the same name. One will be used on the Browser side and the other in the Server side of your application.
Figure 1 - Morfik IDE editing the two modules of a form.
Observe, in Figure 1, that there are three tabs directly underneath the code editor. The first tab takes you to the visual designer, the second one takes you to your client-side module while the third one takes you to your server-side module.
In listing 1 you can see the Browser side code for a blank Morfik Form, in Object Pascal.
Listing 1 - Browser side code (in Morfik Pascal) for an empty/blank form.
Unit Form1;
Interface
Type
Form1=Class(Form)
Private
{ Private declarations }
Public
{ Public declarations }
End;
Implementation
End.
In listing 2 you can see the Server side code for a blank Morfik WebOS form, in Object Pascal. Note that this code is totally identical, at this stage, the Browser side code in listing 1. The two modules will differentiate as you start writing code for your specific application. It is interesting to note that when you click on a component on a Morfik WebOS AppsBuilder in design time and choose to treat one of its possible events, the AppsBuilder IDE will choose the appropriate module (Browser or Server) in which to create the corresponding event handling method.
Listing 2 - Server side code (in Morfik Pascal) for an empty/blank form.
Unit Form1;
Interface
Type
Form1=Class(Form)
Private
{ Private declarations }
Public
{ Public declarations }
End;
Implementation
End.
In listings 3, 4 and 5 you can see the corresponding code in Basic, C# and Java respectively. There is only one listing for each of these additional languages since the browser and server side listings would have been identical.
Listing 3 - Browser/Server side code (in Basic) for an empty/blank form.
Namespace Form1
Public Class Form1
Inherits Form
End Class
End Namespace
Listing 4 - Browser/Server side code (in C#) for an empty/blank form.
namespace Form1
{
public class Form1 : Form
{
}
}
Listing 5 – Browser/Server
package Form1;
public class Form1 extends Form
{
}
[edit] Forms
Forms are visually editable documents that compose your application’s interface. These modules lead a dual life, since they also contain code that establishes how the user interacts with your application and can be edited both visually and in code form. Perhaps we should even say that forms lead a triple life, because when you create a form and define its visual appearance you are also creating two code modules, as we have just seen, one for the browser side and the other for the server side of your application.
It might seem complex and it would really be so if Morfik did not take care of the complexity for you. In Figure 2 you can see a form of the sample BookTrader project loaded in the IDE. This is the visual representation of the form and it gives you a very good perception of how the user will view your application.
Figure 2 - A form of the BookTrader sample project loaded in the IDE.
If you look closely at the screen represented in Figure 2 you will notice just below the visual representation of the form, in the IDE, the presence of three tabs. These tabs allow you to alternate between the three "parts" of your form: visual representation, browser side code and server side code. The "Designer" tab calls up the visual editor for your form’s interface while the other two tabs give you direct access to the code for each browser and server side code. You can cycle through these views using the F12 key.
Figure 3 - The same BookTrader sample form from Figure 2, loaded in Internet Explorer.
Listing 6 - Full source code (Pascal) for the browser side module for the form shown in Figure 3.
Unit HomeForm;
Interface
Type
HomeForm=Class(Form)
Rectangle3 : Rectangle;
Rectangle2 : Rectangle;
TextLabel3 : TextLabel;
TextLabel4 : TextLabel;
TextLabel5 : TextLabel;
TextLabel6 : TextLabel;
TextLabel7 : TextLabel;
TextLabel8 : TextLabel;
TextLabel9 : TextLabel;
TextLabel10 : TextLabel;
TextLabel11 : TextLabel;
TextLabel12 : TextLabel;
TextLabel1 : TextLabel;
TextLabel14 : TextLabel;
TextLabel15 : TextLabel;
TextLabel16 : TextLabel;
TextLabel17 : TextLabel;
TextLabel18 : TextLabel;
TextLabel19 : TextLabel;
TextLabel20 : TextLabel;
TextLabel21 : TextLabel;
TextLabel22 : TextLabel;
TextLabel23 : TextLabel;
TextLabel24 : TextLabel;
Rectangle1 : Rectangle;
TextLabel2 : TextLabel;
Rectangle4 : Rectangle;
Rectangle5 : Rectangle;
TextLabel25 : TextLabel;
TextLabel26 : TextLabel;
TextLabel27 : TextLabel;
TextLabel28 : TextLabel;
TextLabel29 : TextLabel;
TextLabel32 : TextLabel;
TextLabel33 : TextLabel;
TextLabel34 : TextLabel;
TextLabel35 : TextLabel;
TextLabel36 : TextLabel;
TextLabel37 : TextLabel;
TextLabel38 : TextLabel;
TextLabel39 : TextLabel;
TextLabel42 : TextLabel;
TextLabel43 : TextLabel;
TextLabel44 : TextLabel;
TextLabel45 : TextLabel;
TextLabel46 : TextLabel;
TextLabel47 : TextLabel;
Rectangle6 : Rectangle;
TextLabel48 : TextLabel;
TextLabel13 : TextLabel;
Procedure TextLabel25Click(Event: TDOMEvent); Message;
Procedure TextLabel29Click(Event: TDOMEvent); Message;
Procedure TextLabel30Click(Event: TDOMEvent); Message;
Procedure TextLabel26Click(Event: TDOMEvent); Message;
Procedure TextLabel27Click(Event: TDOMEvent); Message;
Procedure TextLabel32Click(Event: TDOMEvent); Message;
Procedure TextLabel35Click(Event: TDOMEvent); Message;
Procedure TextLabel33Click(Event: TDOMEvent); Message;
Procedure TextLabel34Click(Event: TDOMEvent); Message;
Procedure TextLabel3Click(Event: TDOMEvent); Message;
Private
{ Private declarations }
Public
{ Public declarations }
End;
Implementation
Procedure HomeForm.TextLabel25Click(Event: TDOMEvent);
Begin
OpenForm('Hello World','Self:_','');
End;
Procedure HomeForm.TextLabel29Click(Event: TDOMEvent);
Begin
OpenForm('BookList','Self:_','');
End;
Procedure HomeForm.TextLabel30Click(Event: TDOMEvent);
Begin
OpenForm('ParentForm 1','Self:_','');
End;
Procedure HomeForm.TextLabel26Click(Event: TDOMEvent);
Begin
OpenForm('Sorted Book List','Self:_','');
End;
Procedure HomeForm.TextLabel27Click(Event: TDOMEvent);
Begin
OpenForm('Grouped Book List','Self:_','');
End;
Procedure HomeForm.TextLabel32Click(Event: TDOMEvent);
Begin
OpenReport('Book Catalogue 1','');
End;
Procedure HomeForm.TextLabel35Click(Event: TDOMEvent);
Begin
OpenForm('Books On LifeStyle','Self:_','');
End;
Procedure HomeForm.TextLabel33Click(Event: TDOMEvent);
Begin
OpenForm('Query Interface','Self:_','');
End;
Procedure HomeForm.TextLabel34Click(Event: TDOMEvent);
Begin
OpenForm('Event Handling','Self:_','');
End;
Procedure HomeForm.TextLabel3Click(Event: TDOMEvent);
Begin
OpenForm('ParentForm 2','Self:_','');
End;
End.
In comparing the source code in listing 6 with that of listing 7 you will notice that all action in this simple form is actually performed on the client side of the application. The action involves handling a browser-side event and calling the standard function OpenForm in order to display a new form.
Listing 7 - Full source code for the server side module for the form shown in Figure 3.
Unit HomeForm;
Interface
Type
HomeForm=Class(Form)
Rectangle3 : Rectangle;
Rectangle2 : Rectangle;
TextLabel3 : TextLabel;
TextLabel4 : TextLabel;
TextLabel5 : TextLabel;
TextLabel6 : TextLabel;
TextLabel7 : TextLabel;
TextLabel8 : TextLabel;
TextLabel9 : TextLabel;
TextLabel10 : TextLabel;
TextLabel11 : TextLabel;
TextLabel12 : TextLabel;
TextLabel1 : TextLabel;
TextLabel14 : TextLabel;
TextLabel15 : TextLabel;
TextLabel16 : TextLabel;
TextLabel17 : TextLabel;
TextLabel18 : TextLabel;
TextLabel19 : TextLabel;
TextLabel20 : TextLabel;
TextLabel21 : TextLabel;
TextLabel22 : TextLabel;
TextLabel23 : TextLabel;
TextLabel24 : TextLabel;
Rectangle1 : Rectangle;
TextLabel2 : TextLabel;
Rectangle4 : Rectangle;
Rectangle5 : Rectangle;
TextLabel25 : TextLabel;
TextLabel26 : TextLabel;
TextLabel27 : TextLabel;
TextLabel28 : TextLabel;
TextLabel29 : TextLabel;
TextLabel32 : TextLabel;
TextLabel33 : TextLabel;
TextLabel34 : TextLabel;
TextLabel35 : TextLabel;
TextLabel36 : TextLabel;
TextLabel37 : TextLabel;
TextLabel38 : TextLabel;
TextLabel39 : TextLabel;
TextLabel42 : TextLabel;
TextLabel43 : TextLabel;
TextLabel44 : TextLabel;
TextLabel45 : TextLabel;
TextLabel46 : TextLabel;
TextLabel47 : TextLabel;
Rectangle6 : Rectangle;
TextLabel48 : TextLabel;
TextLabel13 : TextLabel;
Private
{ Private declarations }
Public
{ Public declarations }
End;
Implementation
End.
We will look more closely into the design, coding and usage of forms in Chapter 5 - Working with Forms.
[edit] Reports
Reports are, also, visually editable documents that compose not only your application’s interface with the user, but how he/she can printout data in a convenient and well tailored form. These modules lead a dual life, since they can also contain code that establishes certain data is formatted or calculated. Differently from forms, reports have no browser side code as all work is handled on the server and when the finished report is ready it is downloaded to the browser in the for of a PDF (Portable Document Format) file.
In Figure 4 you can see the visual representation of a simple report of the BookTrader sample application. You will note that the Morfik Report Designer offers an easy to use, band oriented, interface which will be quite familiar to all that have, at one time or another, used almost any kind of reporting tool.
Figure 4 - Report from the BookTrader sample application being visually edited in the IDE.
The same report that is displayed in editing mode within the IDE, in Figure 4, can be seen in its final PDF representation, in Figure 5.
Figure 5 - Report of the BookTrader Sample application being previewed as a PDF.
In listing 8 you can see the entire source code for the report shown in figures 4 and 5. No, there is no mistake! It is not an error in the printing of the book. No code, whatsoever, was needed to generate this great looking report in PDF format.
Listing 8 - Full source code for the report shown in Figure 5.
Unit "Book Catalogue 1";
Interface
Type
"Book Catalogue 1"=Class(Report)
TextLabel2 : TextLabel;
TextLabel4 : TextLabel;
TextLabel8 : TextLabel;
TextLabel6 : TextLabel;
TextLabel7 : TextLabel;
TextLabel9 : TextLabel;
TextLabel1 : TextLabel;
TextLabel5 : TextLabel;
TextLabel10 : TextLabel;
Container1 : Container;
Container2 : Container;
Private
{ Private declarations }
Public
{ Public declarations }
End;
Implementation
End.
We will look more closely at designing, coding and usage of reports in Chapter 6 - Working with Reports.
[edit] Modules
Module documents in the Morfik WebOS AppsBuilder are specifically designed to be code libraries where you can organize whatever code you design to be reused throughout a project. You can see in Listing 9 the full source code for a simple module, in Object Pascal.
Listing 9 - Full source code (Pascal) for a module that implements a class that adds numbers.
Unit MyClasses;
Interface
Type
Calculator = Class
function Add(X, Y: integer): integer;
End;
Implementation
Function calculator.Add(X, Y: integer): integer;
Begin
Result := X + Y;
End;
End.
[edit] WebMethods
Before looking specifically at the Morfik WebMethod Document, let us look at what are Web services. Web services are pieces of software created to allow for direct interaction between different applications, which might or might not be running on diverse platforms. Web services are created according to public standards to guarantee general interoperability and compatibility. Web services have well defined interfaces that are described in a machine readable form (an XML file that complies with the WSDL standard).
WebMethods, in Morfik WebOS AppsBuilder, are an excellent means for the browser to request non-visual information from the server. For example, any database requests, state management or validation would be naturally suited for implementation as web services as their execution does not alter the layout of the presentation layer. It is the classic way that you can create the asynchronous nature that consumers have come to expect from AJAX applications.
WebMethods and Web services will be looked into in a lot more detail in Chapter 8 - Creating and Using WebMethods.
[edit] Database Documents
The Morfik tools work with two main database documents: tables and queries. The documents are the very heart of any database application. Both of these types of documents are covered in greater detail in Chapter 3 - Working with Databases.
[edit] Module Scope Rules
Just as any other programming environment Morfik has a set of rules as to how code modules become aware of other code modules. This awareness is essential for the consistent logical partitioning of an application and for the reuse of code throughout its modules. Modules are identified in different, but analogous ways in each of the languages supported within the Morfik WebOS AppsBuilder. In each language a module consists of a file which defines Units in Object Pascal; Packages in Java and Namespaces in Basic and C#. Listings 1 through 5, shown earlier in this chapter easily allow you to see how these are declared in each language.
In order for a module, be it a code module, a web services module, a form or a report to reference objects and functions in another module, it must first establish a reference to this other module. Again, this is done in different but highly analogous ways in each of the supported languages using either the uses or import reserved words.
In listing 10 you see the sample code for a form that uses a class declared in a module. The module being referenced in this case is the same one that appears in Listing 9 of this chapter.
Listing 10 - Source code for the Index form of a simple application that adds up two numbers.
Unit Index;
Interface
Type
Index=Class(Form)
TextEditX : TextEdit;
TextEditY : TextEdit;
TextLabel1 : TextLabel;
TextLabel2 : TextLabel;
TextLabel3 : TextLabel;
ResultText : TextLabel;
Button1 : Button;
Procedure WebFormCreate(Sender: TObject); Message;
Procedure WebFormDestroy(Sender: TObject); Message;
Procedure Button1Click(Event: TDOMEvent); Message;
Private
{ Private declarations }
Public
{ Public declarations }
End;
Implementation
Uses MyClasses;
var
Calc: Calculator;
Procedure Index.WebFormCreate(Sender: TObject);
Begin
Calc := Calculator.Create;
End;
Procedure Index.WebFormDestroy(Sender: TObject);
Begin
Calc.Free;
End;
Procedure Index.Button1Click(Event: TDOMEvent);
Begin
ResultText.Caption := IntToStr(Calc.Add(StrToInt(TextEditX.Text),
StrToInt(TextEditY.Text)));
End;
End.
The modules that compose the Morfik Run Time Library (RTL) do not need to be explicitly referenced by other modules. All modules in the RTL are implicitly referenced by all modules in a Morfik WebOS application.
[edit] Binary Modules
The binary modules generated by the Morfik WebOS AppsBuilder can be divided in two main groups: Applications and Plug-ins. Applications are self sufficient web servers that can be run directly while plug-ins are actually add on modules that must be accessed through the use of an application.
[edit] Applications
An application created with Morfik WebOS AppsBuilder is what the Internet industry has termed a ’rich client’ or ’smart client’. It is a lot more than the usual HTML page, as it is dynamic, is usually connected to a database, has a second tier business or logic layer and can be fully customized to take or allow user interactivity. As we have seen, it uses a set of technologies known as AJAX (Asynchronous Javascript And XML) to build such dynamic interfaces while not relying on browser plug-ins which might or might not be present on each individual machine.
Morfik’s WebOS AppsBuilder is amongst only a few of these rich clients that can be run off your desktop as well. This is because a Morfik application created using Morfik’s WebOS AppsBuilder has a web server and SQL server tightly integrated into it. This ability, to work seamlessly over the Internet as a web application or on the desktop like a software application, is why Morfik calls the final product - an executable - an ’XApp’ - a cross between web and desktop applications, pronounced ’eks-App’.
Morfik’s WebOS AppsBuilder compiles or synthesizes your project into a single executable that can be run on any PC running on a windows operating system.
[edit] Automatic Startup
In order to insure availability from networked computers an XApp, on the Windows platform, can be setup to run as a service. Currently you have to first run the XApp normally by double clicking on the application icon and then when the XApp icon appears in the system tray, right mouse click and then choose the menu command that installs the XApp as a service. To uninstall this service you need to first stop the service. Then run the XApp again in the normal mode follow the same procedure as in the case of installing the XApp as a service except, but this time choose the menu command that uninstalls the service.
[edit] Plug-ins
A Plug-in is a Morfik WebOS project that has been compiled with the "XApp Mode" compiler option set to "Plug-in XApp". When this option is set the Morfik WebOS AppsBuilder compiler will output a dynamically loadable module. In the Windows platform this will be a Dynamically Linked Library (DLL) and in the Linux platform it will be a Shared Object (so). In Figure 6 you can see the Compiler tab of the WebOS AppsBuilder’s Options dialog with the "XApp Mode" option set to generate a plug-in.
Figure 6 - Compiler options, generating a plug-in XApp.
[edit] Running Multiple Applications on the Same Computer
There is no problem in running multiple Morfik applications on the same PC, provided that they run on different HTTP Ports. However, there are times that you may have to run multiple applications on a single port, mostly port 80.
The following steps are the instructions on how you could have multiple Morfik WebOS applications running on a single Port. Please note that in this context an XApp refers to an application that is created in Morfik WebOS AppsBuilder.
- Choose one of your applications to be your Host application (HostApp) and set the HTTP port for the HostApp to 80.
- Open the second application (2ndApp) and in Tools\Options\Compiler set the "XApp Mode" to "Plug-in XApp" and compile the project. This generates a dynamically loadable module (DLL or SO) rather than an executable. Please note that while you are designing and testing the 2ndApp project, the "XApp Mode" option should be set to the default "Stand-alone XApp" until the project is ready to be compiled as a Plug-in. It is not possible to run a plug-in application by itself.
- Create a new .ini file next to the HostApp.exe and give it the same name as the Host application (in our example it is called HostApp.ini).
- Enter the following code inside the HostApp.ini file
[XAppPlugins]
2ndApp=2ndAppPlugIn
[2ndAppPlugIn]
Host=2ndApp.localhost.com
Name=2ndApp
Path=C:\2ndprojectFolder\2ndApp\2ndApp.dll
(replace the references to 2ndApp with your plug-in application name)
- In order to test your applications at design time, open the "C:\windows\system32\drivers\etc\hosts" file in your development computer and make sure the following entries exists
127.0.0.1 localhost.com
127.0.0.1 2ndApp.localhost.com
- On the deployment PC make sure that the Host entry changes to the actual URL that you have allocated for the second plug-in application and change the Path to the location that the second application resides on your deployment computer.
In order for all of this to work all applications (HostApp and Plug-ins) need to have their corresponding .Mxd and Mxr files.
You can add any number of Plug-in XApps on the deployment computer provided that you add their corresponding entries in the HostApp.ini file, as just shown. Note, however, that in order to start a new plug-in application, the HostApp application need to be restarted.
Once the Host application is running, each plug-in and the Host application can be accessed using their corresponding URLs.
[edit] Wrapping it up
Morfik WebOS AppsBuilder provides a set of constructs that allow you to, in a very easy manner, work with all the major elements of an application. Through the use of these constructs you can easily assemble your application from parts that you build and tailor to your particular needs.
