Eclipse Scout Beginners Guide

First you need to decide if the users of your application should communicate via HTTPS with the Scout frontend server. We strongly recommended this setup for any productive environment. This is why even the Scout “Hello World” example is configured to use HTTPS.

As a default Tomcat installation is configured to use HTTP only, we need to first verify if the installtion is properly configured for HTTPS too. In case HTTPS support is already enabled for your Tomcat installation, you may skip this section.

Otherwise, check out the configuration process described in the Tomcat Documentation to enable SSL/TLS.

This section describes the creation and usage of a self-signed certificat in a localhost setting.

The first step is to create a self-signed certificate using the keytool provided with the Java runtime. The example command line below will create such a certificate using the alias tomcat_localhost and place it into the keystore file tomcat_localhost.jks

The second step is to uncomment the HTTPS connector element in the Tomcat’s server.xml configuration file. Make sure that parameter keystoreFile points to your newly created keystore file (if you are using a windows box, make sure not to use the backslash characters in the path to the keystore). After a restart of Tomcat you should then be able to access Tomcat on https://localhost:8443/manager/html

The third step is to export the newly created self-signed certificate from the tomcat_localhost.jks keystore file into the tomcat_localhost.der certificate file.

In the fourth and last step we add the self-signed certificate to the known certificates of the Java runtime. Make sure that you modify the cacerts file of the Java runtime that is used in your Tomcat installation and modify the path to the cacerts file accordingly.

Your Scout application should now properly communicate over HTTPS in your Tomcat installation and after having installed the "Hello World" application to Tomcat it should become available on https://localhost:8443/org.eclipse.scout.apps.helloworld.ui.html.

In case the Scout frontend server cannot access the Scout backend server your self-signed certificate might be missing in the Java installation. To verify that the certificate has been included in file cacerts file use the following command.

Once you no longer need the self-signed certificate file in your Java installation make sure to remove the certificate again.

If you should prefer to work with HTTP only, you need to modify the security settings of your Scout application. This can be done with the steps described below.

More on this topic can be found in the Scout Architecture Documentation.

We are now ready to move the Hello World application from our development environment to a productive setup. The simplest option to move our application into the 'wild' is to build it using Maven. This produces two WAR files ^[2].

The first WAR file contains the Scout backend server with all business logic. The second WAR file contains the Scout frontend server that is responsible for communicating with the web browser part of the Scout application.

To start the build right click on the project helloworld and select the context menu Run As → Maven build…​ as shown in Figure 8. In the dialog that appears enter clean verify into the Goals field and press Run.

Afterwards the compilation starts, executes all test cases and bundles the result into two WAR files. The output of the build is shown in the Console view within Eclipse. As soon as the build is reporting success you can find the built WAR files:

To see the new files within Eclipse you may need to refresh the target folder below each project using the F5 keystroke.

To start the New Wizard wizard press Ctrl+N or use menu File  New  Other…​. In the first wizard step type the name of the object you want to create into the Wizards field as shown in Figure 12.

Start the New Wizard and type Class in the Wizards field. Select Class Click on Next to open the New class wizard

You can choose define the following properties:

Click on Finish when you are done with the class definition. The java editor will open and you can start editing.

Start the New Wizard and type Package in the Wizards field. Select Package Click on Next to open the New package wizard

In the New package wizard you can define the following properties:

Click on Next to create the project. The Project Browser

The import section of a java class needs to be kept up-to-date. New imports need to be added and no longer used ones should be removed. Eclipse offers a the shortcut Ctrl+Shift+O to accomplish this task.

In case an import cannot be resolved because several candidates exist, a selection list is displayed.

Renaming a class without SDK support is not so easy. The class and possibly the compilation unit need to be renamed. Then every reference to the class within the workspace needs to be updated.

All this work is accomplished by using the Class rename Wizard.

Renaming a package without SDK support would be a tedious undertaking. All classes in the package and its subpackages would have to be modified as well as the directory structure on disk. Then every reference to the package within the workspace needs to be updated.

All this work is accomplished by using the Package rename Wizard.

The New Scout Project wizard can be used to create a new Scout project from scratch.

To open the wizard press Ctrl+N or use File  New  Other…​ and type "Scout" into the Wizards search field. Then, select the entry "Scout Project" and click on Next. This leads to the initial dialog of the New Scout Project wizard as shown in Figure 15.

A detailed description of the indiviudal wizard fields of Figure 15 is provided in the next section.

By clicking on the Finish button the wizard is started and a new Scout client server application is created in the form of a Maven multi-module project.

The New Scout Page wizard can be used to create a new page and related classes. To start the wizard use File  New  Other…​ or press Ctrl+N.

In the case of Figure 16 the package org.eclipse.scout.apps.helloworld.client.helloworld has been selected in the Package Explorer. The only wizard field that then needs to be filled in manually is the Name field.

By clicking on the Finish button the wizard is started and the specified components are created.

The New Form wizard is be used to create a new form including a form data, permissions and and related service. To start the wizard use File  New  Other…​ or press Ctrl+N.

In the case of Figure 17 the package org.eclipse.scout.apps.helloworld.client.helloworld has been selected in the Package Explorer. The only wizard field that then needs to be filled in manually is the Name field.

By clicking on the Finish button the wizard is started and the specified components are created.

To add additional form fields to a form the current edit position needs to be inside of a Scout group box. Typing Ctrl+Space then provides access to the most frequently used Scout widgets as shown in Figure 18.

When a template is selected, it is possible to customize it by navigating between the different Edit-Groups with the Tab Key (this works exactly like other templates in the Eclipse Editor). With this mechanism you can quickly define the class name, the parent class and other properties. To exit the Edit-Mode just press Enter.

For adding new columns in a table set the current edit position inside a Scout table. The Scout table itself may be located inside of a TableField as shown in Figure 19 or can also be located inside of a Scout TablePage.

Next to adding columns the content assist shown in Figure 19 can also be used to add key stroke actions and menus to tables.

Adding new Codes to an existing CodeType is supported by the content assist as shown in Figure 20.

Translated text entries are most frequently added when working in the Java editor view.

When the the current edit position is inside the String parameter of the TEXTS.get() code, the content assist (opened with Ctrl + Space) provides support for the NLS entries as shown in Figure 21.

Selecting one of proposal entries (like "DateOfBirth" in the example) shows the available translations on the right hand side. To select a specific proposal entry you may double click on the entry or hit the Enter key. To create a new text entry select New text…​ at the end of the proposal list.

Adding a translated text can then be done in the New Entry wizard provided by the Scout SDK as shown in Figure 22.

To manage translated application texts for different languages the Scout SDK includes a NLS editor. This editor helps to efficiently deal to edit all the property files that are used with the default setup of Scout.

The NLS editor can be accessed for each text provider service of a Scout application via the *.nls files of the shared Maven modules of the application. In the case of the "Hello World" application you will find the Texts.nls file in module org.eclipse.scout.helloworld.shared. To open the editor for the "Hello World" application select the Texts.nls file first and then use context menu Open With  NLS Editor.

The screenshot below shows the opened NLS editor. In the first column the key values are shown that are used in accessing translations through TEXTS.get("key"). The second columns holds the default translations followed by columns holding the translations for other translated languages.

Actions on the top right corner:

Import and Export requires additional components.

Hide inherited rows checkbox

On the top of each column, the text fields allow you to filter the entries in the table. With the Reset button on the right you will empty those filters.

The entries in the table can be directly edited by pressing F2 or double-clicking into a text cell.

On each row it is possible to call following context menu:

The mapping between the properties files is registered in the "Text Provider Service" class. Per default the files follow this pattern: <your application>.shared/src/main/resources/<identifier of the project>/texts/Texts<language>.properties

where:

If NLS keys are used in the code that do not exist in a properties file, an ugly placeholder is displayed to the user. To find such missing translations the Menu Scout → Search missing text keys…​ may be handy. The result is listed in the Eclipse Search view.

The search also takes the scope of each NLS key into account. So that the key is considered to be available there must be a TextProviderService with that key on the classpath of that module.

Reported false positives can be suppressed using the following comment at the end of the corresponding line: NO-NLS-CHECK. Matches on that line are then not reported in future searches anymore.

In case your workspace contains modules from the “Hello World” tutorial, you may want to multi-select them and to either close them by invoking the context menu “Close Projects” or to delete them by invoking the context menu “Delete”. The initial code for the “Contacts” application is then generated using the New Scout Project wizard. For the wizard fields you may use the values below and as shown in Figure 26

To create this initial application click on Finish. The project wizard then creates a number of Maven modules as shown in Figure 27.

We start with removing the *.helloworld and \*.settings packages in all Maven modules of the "Contacts" application. To delete packages, first select an individual package or packages in the Eclipse package explorer as shown in Figure 27 and then hit the Delete key.

The packages to delete is provided per Maven module in the list below.

The deletion of these outlines results in a number of compile errors in classes WorkOutline and Desktop. All these errors will be resolved in the following two sections where we modify the two classes to our needs.

Instead of adding a new "Contacts" outline to the application we reuse the generated code and rename the "Work" outline into "Contacts" outline. For this, we perform the following modifications to class WorkOutline.

To quickly find class WorkOutline we first open the Open Type dialog from the Eclipse IDE by hitting Ctrl+Shift+T and enter "workoutline" into the search field as shown in Figure 28. In the result list, we select the desired class and click the OK button to open the file WorkOutline.java in the Java editor of the Eclipse IDE.

We start with the package rename. To rename the package org.eclipse.scout.contacts.client.work to org.eclipse.scout.contacts.client.contact click into the word "work" of the package name and hit Alt+Shift+R. This opens the package rename dialog as shown in Figure 29 where we replace "work" by "contact" in the New name field. After pressing the Ok button Eclipse informs the programmer that the code modification may not be accurate as the resource has compile errors. This warning can be acknowledged by clicking Continue.

In next step we rename class WorkOutline to ContactOutline. In the Java editor we can rename the class by clicking into the class identifier WorkOutline and hitting Alt+Shift+R. Inside the edit box we can then change the class name to ContactOutline and hit the Enter key to execute the change. If Eclipse shows a Rename Type dialog just hit button Continue to let Eclipse complete the rename operation. To get rid of the compile error in method execCreateChildPages we simply delete the content in the method body.

Next, we change the outline title in method getConfiguredTitle by replacing the string "Work" with "Contacts", setting the cursor at the end of the word "Contacts" and hitting Ctrl+Space to open the Scout content assist as shown in Figure 30.

To enter a new translated text we double click on the proposal New text…​ to open the Scout new entry wizard as shown in Figure 31.

As the last modification we change the return value of method getConfiguredIconId to value Icons.CategoryBold and end with the code shown in Listing 1.

To conclude the modifications we must get rid of the faulty import statement. To do this we could in principle press Ctrl+Shift+O to organize the imports automatically. However, we want to register the organization of imports as a so-called “Save Action”. This can be done in the Eclipse preferences.

Invoke the top-level menu “Window/Preferences” and enter “Save Action” as a filter text to narrow down the tree on the left side of the preferences window. Then, chose the “Java/Editor/Save Actions” node and check the boxes "[x] Format Source Code" and "[x] Organize imports". As you may have guessed, this formats the source code and organizes the import statements every time the user saves a Java class.

After having done so, perform a dummy modification in the class ContactOutline (e.g. add a space somewhere in the class body) and save the file. As a consequence, the faulty import statement at the beginning of the class file should have vanished and the class should show no compile errors anymore.

The second class to adapt for the "Contacts" application is the Desktop class. This class is implemented exactly once in each Scout application and holds the available outlines and top level menus of the application in the form of inner classes.

For the "Contacts" application we adapt the initial implementation to have outline view buttons for the "Contacts" and "Search" outlines. The top level menus are then adapted to hold the menus "Quick Access", "Options" and a menu for the logged in user.

Start with opening the class in the Java editor using Ctrl+Shift+T to quickly access the class. In the source code of method getConfiguredOutlines remove SettingsOutline.class from the list of return values as shown in Listing 2.

Then, perform the following changes in class Desktop

At the end of these changes the inner class structure of class Desktop will look similar to the sample shown in Listing 3.

In the first step of the "Contacts" tutorial we have created the initial project setup that will serve as the basis for all the following tutorial steps.

As the "Contacts" application is in a clean state you can now test the application using the following steps. The user interface of the application will now look as shown in Figure 32.

From the coding perspective we now have all necessary maven Modules for the "Contacts" application including Java package and class names to match with the complete Scout "Contacts" demo application. This point is important as it simplifies the comparison of intermediate stages of the tutorial application with the Scout demo application. The same is true for the user perspective: The layout of the current state of the tutorial matches with the complete "Contacts" sample application.

A substantial part of the "Contacts" application deals with persons. In addition to the "Persons" page we will also add a Scout form to enter/edit persons in a later tutorial step. For the "Contacts" application we use this fact to justify the addition of a specific Java package that will hold all classes related to persons. This person package can be created with the following steps.

We will also need a separate package for organizations and some common elements.

The pages for the persons and the organizations will also display country information. To display country names we will be using a special column, that maps the country codes received from the backend application to translated country names. As the Java class Locale already contains both country codes and country names we can take advantage of this class and use it in a Scout local lookup call.

In package org.eclipse.scout.contacts.client.common create a new class CountryLookupCall according to the implementation provided in Listing 4.

In this section we create the Scout page that will be used to list all entered persons to the user of the "Contacts" application. Out-of-the box this page will support the sorting and filtering of all the persons. This "Persons" page is then added to the navigation tree below the "Contacts" outline.

We can now add the Scout person page as described below.

The Scout New Page Wizard then creates an initial implementation for the PersonTablePage class very similar to the listing provided in Listing 5 below.

Before we start to add the columns to the table of the page we need to do some minor adaptations to Listing 5.

We are now ready to populate the inner class Table of the person page with the columns to display various person attributes.

Table pages are an important UI element of Scout applications as they frequently play a central role in the interactions of a user with the application. Out of the box table pages offer powerful options to sort, filter and re-arrange the data contained in the table. This functionality offers a good starting point to decide which columns to add to a table page.

To decide about the columns to add the following criteria have been useful in practice.

For the person page of the "Contacts" application we will add the following columns.

To add the first column PersonIdColumn we open class PersonTablePage in the Java editor and place the cursor inside of the body of the inner Table class. We then open the Scout content assist with Ctrl+Space and select the Column proposal as shown in Figure 35.

In the first edit box we type "PersonId" as shown in Figure 36 and press Enter.

To configure this column as an invisible primary key we modify the newly created column class according to Listing 6.

We can now add the additional columns FirstNameColumn, LastNameColumn, CityColumn below. After entering the class name press Tab twice to move the cursor to the label text of the field. In the case of the first name enter "FirstName" and hit Ctrl+Space to open the wizard to add the translated text "First Name" as described in Section 3.6.1.

For these three columns the default implementation is fine and does not need any adaptations. Listing 7 below provides an example for this type of columns.

For column CountryColumn we will use a smart column. We again use Ctrl+Space to open the wizard and enter "Country" for the class name box and press Tab once and select AbstractSmartColumn as column type. Next we press Tab again to enter "Country" as the translated text.

In the created class CountryColumn we need to add the generic type parameter to the super class declaration (AbstractSmartColumn<String>) and add the method getConfiguredLookupCall according to Listing 8.

After the country column we add the four columns PhoneColumn, MobileColumn, EmailColumn and OrganizationColumn that are initially not visible in the user interface. As an example for such a column Listing 9 is provided below.

We have now created a person page with corresponding table columns. However, this new UI component is not yet visible in the user interface. What is missing is the link from the application’s contacts outline class to the newly created PersonTablePage class. This is what we will do in the following section.

In this section we add the person page to the contacts outline created during the initial project setup of the first step of this tutorial. This will make the person page visible in the navigation area below the "Contacts" outline.

For this we have to add a single line of code to method execCreateChildPages of class ContactOutline according to Listing 10

The application is now in a state where we can restart the backend and the frontend server to verify our changes in the user interface.

This section creates and adds a table page for organization to the "Contacts" outline. To create an organizations page the same steps are required as for the creation of the person page. The description is therefore kept on a higher level and in the text below only the main steps are described. Where appropriate, pointers are provided to the detailed descriptions for the creation of the person page.

The implementation of class OrganizationTablePage using the Scout new page wizard then looks as shown in Listing 11.

As in the case of the person page you can now add the columns for the inner Table class. For the organization page add the columns according to the specification provided below.

As in the case of the person page we have to add the newly created class OrganizationTablePage in method execCreateChildPages of the outline class ContactOutline as shown in Listing 12.

In the second step of the "Contacts" tutorial we have created a person page and an organization page to display data of persons and organizations.

The "Contacts" application is in a clean state again and you can (re)start the backend and the frontend of the application and verify the user interface in your browser. The user interface should look like the screenshot provided in Figure 37.

When comparing the state of the "Contacts" tutorial application with the Scout demo application in Figure 24 the main difference is the missing person data. Adding access to a database is the focus of the next tutorial step.

This section describes the installation of the necessary components and classes that handle the database creation/access of the "Contacts" application.

To add the support for the Scout JDBC components and the Derby database we first need to declare the corresponding dependencies in the pom.xml file of the Maven server module. This can be done using the following steps.

After adding the database dependencies to the server’s pom.xml file we need to update all Maven server modules for the "Contacts" app. To do this, select the three modules org.eclipse.scout.contacts.server.* and hit Alt+F5 as shown in Figure 38. Start the update with OK.

The next step is to create the org.eclipse.scout.contacts.server.sql package.

We are now ready to copy the classes related to the database infrastructure from the "Contacts" demo application to our tutorial workspace.

The simplest way to do this is to open a second Eclipse IDE with the workspace where you have imported the Scout demo applications. If you have not done this yet go to the beginning of this tutorial Chapter 4 and catch up now.

In the demo application workspace navigate to the same package org.eclipse.scout.contacts.server.sql and copy over all its classes. After copying these classes make sure that the structure of your server Maven module looks as shown in Figure 39.

The imported classes are described in the following sections. Additional information is provided where these classes are relying on Scout concepts that have not previously been introduced.

Scout Config properties can greatly improve the flexibility of Scout applications. For the "Contacts" application this feature is used to keep its database setup configurable. Moving from a in-memory setup to a disk based database is then possible without any reprogramming.

The Scout backend (and frontend) applications initialize config properties from matching values found in file config.properties. For missing property values the default values defined in the config property classes are used.

In the case of the "Contacts" application the config property files are located in the subfolder src/main/resources of the Maven modules that specify the frontend and the backend application.

These added property values then match the config properties defined in the class DatabaseProperties provided in Listing 15. Remember that this is one of the database infrastructure classes we have copied before.

In the Scout framework config properties are always typed and need to implement interface IConfigProperty. For commonly used types Scout already provides classes. A boolean property may be created by extending Scout class AbstractBooleanConfigProperty.

Accessing the actual property values in the code is demonstrated in the next section.

Accessing databases with the Scout framework is implemented with SQL services that extend base class AbstractSqlService. As the "Contacts" application will be working with a Derby database we also need a Derby specific SQL service.

This is why we have copied over class DerbySqlService. The only project specific method is getConfiguredJdbcMappingName as implemented in Listing 16.

This listing also demonstrates how to use the config properties in the code. With the property values defined in the previous section the "Contacts" application is working with an in-memory database.

To change the setup to a disk based version, we would have to change the value for the property contacts.database.jdbc.mappingName from jdbc:derby:memory:contacts-database to jdbc:derby:<path-to-dir>. For a Windows box a concrete example could look like this: jdbc:derby:c:\\derby\\contacts-database.

Now we look at how the actual SQL statements of the "Contacts" application work. For our application all statements are collected into a single class. While there are many more options how to organize SQL and Java code this setup has its own advantages.

The SQL statements related to the database structure are provided in Listing 17. The statements (or building blocks of statements) in interface SQLs are plain SQL in many cases. In the other cases the statement texts include Scout specific syntax extensions with : as a prefix character. Examples are :<identifier> and :{<identifier>.<attribute>}.

The next section discusses how the components introduced above are used by the "Contacts" appliction to create an initial "Contacts" database during the startup phase of the application.

The database setup service is responsible to create the "Contacts" database during the startup of the application. In order to implement such a service, a number of Scout concepts are combined into class DatabaseSetupService.

How these elements are used in class DatabaseSetupService is shown in Listing 18. The actual creation of the "Contacts" database is performed by the method autoCreateDatabase.

At the time of the database creation no user is yet logged into the application. This is why we use a run context associated with the super user. The context is then used to execute the runnable that creates the organization and person tables.

The usage of CONFIG is already covered by the previous section. Introductions for SQL, LOG and the Scout platform annotations are provided below.

Changing the basic log level of an application is a frequently used scenario. As Scout is using Logback per default we can adapt the log level in the logback.xml configuration files as shown in Listing 19. For the "Contacts" application these configuration files are located in folder src/main/resources of the Maven modules that define the frontend and the backend applications. More information regarding these configuration files is provided in the Logback manual.

This section reviews the backend infrastructure that has been created so far and identifies the pieces that are missing to fetch person and organization data to send it to the frontend server of the "Contacts" application.

During the creation of the person page and the organization page the Scout wizards created more than just Scout pages that are visible in the user interface. It also added corresponding classes in the shared module and the server module of the "Contacts" application.

The new page wizard basically added the complete round trip from the client (frontend server) to the server (backend server) and back. Using the organization page as an example, the setup created by the page wizard involves the following classes.

On the client side the server roundtrip is implemented in method execLoadData as shown in Listing 20.

This roundtrip between class OrganizationTablePage and OrganizationService works through the following steps.

On the server side fetching the data from the database will be implemented in class OrganizationService according to Listing 21.

In the next section we will implement the database access logic in the getOrganizationTableData methods of the server classes OrganizationService and PersonService.

We are now ready to fetch data from the Derby database using the available infrastructure and the SQL statements prepared in class SQLs. For the implementation of method getOrganizationTableData in class OrganizationService we will use the two SQL snippets provided in Listing 22.

Taking advantage of the SQL convenience offered by the Scout framework, we can add the missing functionality with two lines of code. See Listing 23 for the full listing of method getOrganizationTableData. After adding the two additional lines, we update the imports of the classes with pressing Ctrl+Shift+O.

Note that the identifier "page" in the NVPair object will be mapped to the same identifier used in the ORGANIZATION_PAGE_DATA_SELECT_INTO statement.

Finally, we have to also implement the loading of the person data in class PersonService. The implementation of method getPersonTableData is provided in Listing 24.

In the third step of the "Contacts" tutorial we have added the infrastructure to work with a Derby database. The infrastructure is used to create and populate the initial database. In addition person and organization data is now fetched from the database on the "Contacts" backend server and handed to the "Contacts" frontend server via a page data object.

The "Contacts" application is in a clean state again and you can (re)start the backend and the frontend of the application and verify the result in your browser. Person and company data is now visible in the user interface as shown in Figure 40.

We start with the sketch of the form layout as shown in Figure 41.

The upper half of the form shows a picture of the person and contains some primary attributes such as first name and the gender of the person.

The lower half of the form contains tab boxes. A "Contact Info" tab provides contact details of the person and adding notes for the person in the form of free text is possible in the "Notes" tab.

Figure 42 below shows how the sketched form can fit with the logical grid layout of the Scout framework. Scout containers have two columns (indicated in red) per default and as many rows (indicated in yellow) as needed.

Individual form fields consist of a label part and a field part and occupy a single cell in the logical grid. Examples for fields using the default configuration are the first name field or the email field. When needed, fields can be configured to occupy several columns or rows. An example for this case is the image field that will hold the picture of the person. This field is configured to occupy 5 logical rows.

With Scout’s container widgets such as group boxes, tab boxes and sequence boxes complex layouts can be achieved. Containers provide a lot of flexibility as these widgets can be nested hierarchically as shown in Figure 43

The sketch above details the organization of the container components to match the desired layout for the person form. The different container widgets can all be used with their default settings except for the address box.

For the address box we will have to modify its size and its inner organization. As group boxes occupy two columns per default we will need to reduce the width of the address box to a single column. The second change is to the inner layout of the address box. To force the location box to come below the street field we have to change the inner layout of the group box to a single column as well. Otherwise, the location box would be shown next to the street field.

In the next section we will start to implement the person form with the layout described above.

In this section we implement the person form with its container widgets as described in the previous section. To be able to use the form to create and edit persons we will add "New" and "Edit" context menus to the table in the person page. Finally we will also add a "Create Person" entry to the the "Quick Access" top level menu of the application.

Start the form creation with the Scout new form wizard following the steps listed below.

Now open the newly created class PersonForm in the Java editor and perform the changes listed below as shown in Listing 25.

We are now going to add the layout containers according to Listing 26. First add class GeneralBox using the Scout content assist selecting the Group Box proposal. Delete method getConfiguredLabel, as we are only using this group box to organize fields.

After the general box add a tab box container class by choosing the Tab Box proposal in the Scout content assist. Inside of class DetailsBox create the individual tab containers "Contact Info", "Work" and "Notes" as inner classes of the details box according to Listing 26.

To actually open the person form the form needs to be integrated in the user interface. In Scout application forms are typically opened by first selecting a specific row in a page and then using a context menu. For the "Contacts" application we will follow this pattern too.

Open class PersonTablePage in the Java editor and create the context menus "New" and "Edit" in the inner class Table according to Listing 27.

In addition to the context menus defined for the person page we also add a "Create new person" menu on the desktop under the "Quick Access" top level menu. To do this open class Desktop in the Java editor and navigate to the inner class QuickAccessMenu. We can then add a NewPersonMenu using the Scout content assist and selecting the Menu proposal entry. The final implementation for the "Create new person" menu is provided in Listing 28.

We have now created the initial implementation of the person form including context menus to open the form from the person page and the "Quick Access" top level menu of the "Contacts" application. At this point it is already possible to verify that the person form can be opened on the user interface via the context menus. A screenshot of the current state is shown in Figure 45.

This initial implementation of the person form is also ready to add the individual form fields into the container boxes. For the fields of the person form we can directly extend the abstract form field classes offered by the Scout framework. Only for the implementation of the gender field we need a Scout code type that represents the possible values for the radio buttons.

In this section we will add a gender code type for the "Contacts" application. As code types can be used for the specification of the options of a radio button group, we will be able to implement the gender field by providing a reference to the code type. To keep things simple, the gender code type will contain a "Male" code and a "Female" code.

Code types are frequently used in both the frontend and the backend of an application. This implies that code type classes need to be implemented in the application’s shared module. As the gender code type is related to persons we will implement this class in the person package.

Follow the steps described below to create the gender code type.

Now click button Finish to start the wizard. Then, open the newly created class GenderCodeType in the Java editor and set the ID constant to "Gender". The created class will then look like Listing 29 except for the missing inner code classes. We will add these inner codes as the next step.

To add an inner class MaleCode code to the gender code type perform the steps below.

Then repeat the steps above for the female code.

In this section we will add the form fields to the layout containers of the person form. We will start with filling the general box with the picture field, followed by the other fields in the upper part of the person form. Finally, we fill the individual tab boxes into the details box in the lower part of the person form.

As the first field we add the field that will show the picture of the person to the GeneralBox container.

Using the combination of the PictureField and PictureUrlField as its master field has two benefits. First, having a field that contains the the URL makes sure that this information is also stored in the form data and second, the method execChangedMasterValue can then be used to trigger the refresh of the actual picture when the picture URL is changed.

For security reasons, the browser is not allowed to load content from other servers by default. For our demo images, we add a well-considered exception. Open the config.properties file of your UI server project and make sure it contains the following line:

The remaining fields for the general box can then be added using the Scout content assist or by copying Listing 32 into the code below the picture field, again not forgetting the getters above the MainBox.

Whenever we add several fields to a Scout container field the individual fields will be displayed according to their order specified by the @Order annotation in the source code. Using the default two column layout, the Scout layouting engine uses the first fields to fill up the first column before the remaining fields are assigned to the second column. In general the Scout layouting engine tries to balance the number of fields over all available columns. For the general box this rule has the effect that the picture field (this is the first field according to its order value) is assigned to the left column and all other fields are assigned to the right column.

After having added all the fields to the general box of the person form we can now fill the individual tabs of the DetailsBox container. We start with adding the content to the tabs "Work" and "Notes" as described below.

Now add the string fields listed below to the "Work" tab as inner classes of the container field WorkBox. Use the Scout content assist to add the fields and select String Field as the type of each field.

The "Notes" tab represented by the container field NotesBox only contains a single string field. This field will not need a label, span 4 rows of the logical grid and hold a multi line text according to Listing 33.

Next is the implementation of the address box in the "Contact Info" tab. The address box is realized as a single column group box that holds a street field, a city field and a country field. According to the form layout defined in Section 4.6.1 the city field and the country field will be located on the same logical row and in the same cell of the logical grid.

In the Scout default layout each form field uses up a single cell of the logical grid. Whenever we like to be more economical with the space occupied by several fields, we can work with a Scout sequence box. Inner fields of a sequence box will be arranged on a single row from left to right and the spacing between the inner fields will be minimal.

Taking advantage of these properties we implement the location box as a sequence field according to Listing 34. To further optimize screen real estate we also switch to on-field labels for the city field and the country field.

While string fields are used for the street field and the city field, the country field is implemented as a smart field. Scout smart fields can be viewed as a powerful drop down lists with search-as-you-type support. In the case of the country field the smart field is backed by the lookup class CountryLookupCall that we already used for the country smart column in the person page.

After the address box the "Contact Info" box contains the three fields mentioned below. Use the Scout content assist to add the fields and select String Field as the type of each field.

We have now completed the implementation of the form layout and added all form fields of the person form. The application is now in a state where we can verify the layout of the person form and check the handling of the different input fields. (Re)start the application and enter some values into the various fields of the person form.

To view and enter person data with the form we have yet to add the interaction with the database in the backend of the "Contacts" application. This is the topic of the next section.

This section shows how we can integrate the person form created in the previous sections with the "Contacts" backend application to load and store person data with the database.

Most of the necessary infrastructure such as the transfer objects between the frontend and the backend application has already been created by the Scout form wizard. In the text below we will first discuss the setup created by the new form wizard and then add the missing code snippets to interact with the database.

On the frontend side, the Scout new form wizard has also created the two form handler classes ModifyHandler and NewHandler. By convention a ModifyHandler is used to change existing data and a NewHandler implements the creation of new data.

Form handler classes provide a number of callback methods that are invoked at various stages during the life cycle of the form. The implementation created by the Scout wizard includes the methods execLoad and execStore for each form handler. In these methods the form fetches data from the Scout backend application and/or sends new data to the backend server.

Adapt the default implementation of the form handlers according to Listing 35.

With the implementation provided in Listing 35 the classes ModifyHandler and NewHandler orchestrate the complete roundtrip between the frontend and the backend of the "Contacts" application.

The only part that is now missing is the implementation of the form service methods create, load and store on the backend of the "Contacts" application. For these methods we can again rely on the default implementations created by the Scout new form wizard.

Modify the person service methods according to Listing 36.

In the fourth step of the "Contacts" tutorial we have added the person form to add, view and change persons. Using the person form as an example we have learned how to implement complex form layouts using the Scout layouting mechanism, Scout container fields and individual form field properties.

We have also seen how we can use context menus to integrate the forms in the user interface of the application and have implemented the interaction of the frontend with the backend application including the persistance of person data in the database.

The "Contacts" application is in a clean state again and you can (re)start the backend and the frontend of the application and verify the result in your browser. We can now verify the creation of new person entries and the modification of existing person data in the current state of the "Contacts" application. The created person form is shown in Figure 47. In case you copied some code snippets from the tutorial, you may see the text "undefined text {…​}" in some labels in the person field. You may want to define these texts using the Scout content assist for defining new texts as was already presented earlier in this tutorial.

This section explains the form field validation on the level of a single field. As an example we will use the email address field defined in the "Contact Info" tab. The validation implemented in Listing 37 checks the length and the format of the entered email address.

In the next section we use the address box to demonstrate the joint validation of several fields.

Often the values of several fields have to be considered jointly to evaluate if the entered data is actually valid. As an example we will add a more complex form field validation on the level of the AddressBox group box widget that takes into account the data entered into the street, city, and country fields.

The implemented validation for the address box example should enforce the following set of business rules.

The simplest rule is about entering only valid countries. This rule is already implemented as the country smart field only allows the user to select a single entry of the list of valid countries. A possible implementation to enforce the other rules is provided in Listing 38.

Whenever the content of the street field, the city field, or the country field is changed the mechanism implemented above triggers a re-evaluation of the mandatory status of the city field and the country field. As the Scout default form validation ensures that every mandatory field receives some content the application prevents the user from entering address data that does not satisfy the business rules mentioned above.

The verification of user input can also be triggered before the form is closed. This behavior can be implemented by overriding method execValidate on the form level. As an example we use this mechanism to make sure that a user can only enter persons that have at least some name information.

Now add this validation to the person form using the implementation provided in Listing 39.

As we have now implemented a number of form field validations we are now ready to test the result in the running application. Re-start the "Contacts" application and try to trigger the different validation rules. Figure 48 shows the response of the user interface when trying to save invalid person data.

In this section we show how to refactor a group of fields into a Scout template field that is ready for reuse. As an example we refactor the picture field into a template field. Later in tutorial step Section 4.8 we can then reuse this field in the company form to show the company’s logo.

The generic approach to refactor a form field into a template field is listed below.

For refactoring the picture field we can exactly follow these steps. To create the empty field data class perform the following steps.

We are now ready to implement the template field class according to the following steps.

The next step is to replace the original code of the picture field with the newly created template field. Delete the field PictureUrlField and remove all the code from the field PictureField and let PictureField extend the newly created template field as shown in Listing 42.

As the last step we need to slightly modify the SQL statement that loads and stores the picture URL information. The reason for the change is the replacement of the picture url field by an url property defined as a member of the picture field. For this change perform the steps listed below.

Based on the picture field example we have now walked through the complete process to turn normal fields into template fields. This process remains the same for refactoring container fields into template fields.

Using the refactored picture template field we want the user to be able to enter and update the URL of the shown picture. For this we add a simple form with a single field and a context menu to the picture template field using the Scout new form wizard as shown in Figure 49.

Now adapt the content of the URL form according to Listing 43. As you can see, there is no roundtrip to a backend server and the form only contains a single editable field.

We can now add an "Edit URL" menu to the picture template field. The implementation of the edit context menu is provided in Listing 44.

Based on the example with the picture field we have now walked through the complete process to turn normal fields into template fields. This process remains the same for refactoring container fields into template fields.

To reduce the amount of copy & paste for the implementation of the company form in the next tutorial step, we recommend that you refactor the following fields into templates.

You can follow the steps described in the previous section for the picture field. To be able to copy & paste the code in the following tutorial step you may use the following class names.

Note that both the AbstractAddressBox and the AbstractNotesBox need their own form data object, whereas the AbstractEmailField does not.

Replacing the concrete fields with the template fields in the person form will result in a number of compile errors in the field getter methods of the person form. In the case of the "Contacts" application these getter methods are not needed and can simply be deleted.

Moving from concrete fields to template fields also implies some minor changes as we have seen with the picture template field. Therefore make sure to modify the SQL statements in class SQLs accordingly.

In this step of the "Contacts" tutorial we have covered two important concepts for implementing business applications.

The "Contacts" application is in a clean state again and you can (re)start the backend and the frontend of the application and verify the result in your browser. Using the created picture template field we can now update the image in the picture form as shown in Figure 50.

In the next tutorial step we are going to implement the company form to enter and edit company information. For the creation of this form we can reuse the template fields that we have created.

In the sixth step of the "Contacts" tutorial we have added the Scout form to edit and create organizations. The focus of this part of the tutorial was on re-using previous work and applying the concepts that have been introduced in previous tutorial steps.

The "Contacts" application is in a clean state again and you can (re)start the backend and the frontend of the application and verify the result in your browser. As shown in Figure 52 company data can now be viewed and entered in the user interface.

Before we can change the organization field on the person form from a string field to a smart field we need a organization lookup call that provides the necessary data to the smartfield. We have been using this approach for the country field already. The difference to the lookup call for countries lies in the fact that we no longer have a static list of entries but need to fetch possible the organizations dynamically. We will therefore need to access the database to provide the data to the lookup call.

As this is a common requirement the Scout framework comes with the base class AbstractSqlLookupService and a default mechanism to route lookup calls from the frontend sever to database calls on the backend server. The necessary infrastructure can be created using the Scout lookup wizard according to the steps described below.

The Scout wizard will then create the lookup class OrganizationLookupCall and the corresponding lookup service with the interface IOrganizationLookupService and its initial implementation OrganizationLookupService. We will only need to provide some implementation for the lookup service. The service interface and the lookup call class can be used as provided by the Scout wizard. Listing 47 shows the code generated for the lookup call

We are now ready to implement method getConfiguredSqlSelect of the organization lookup service. Open class OrganizationLookupService in the Java editor and change the implementation according to Listing 48.

The SQL statement that backs the lookup service is provided in Listing 49. Lookup services can provide data for three different use cases. The most straightforward case is the mapping of a key to a specific lookup row. Next is the case where the lookup service returns a number of lookup rows that match a provided substring and finally the case where the lookup service simply returns all available rows.

Now we can use the organization lookup call to transform the organization field in the "Work" tab of the person form into a smart field. To do this we open class PersonForm in the Java editor and navigate to its inner class WorkBox. Then, update the implementation of the OrganizationField according to Listing 50

This change has the effect, that now we can assign an organization in the person form by typing a substring of the organizations name into the organization field. The conversion of the field into a smart field has the additional benefit that only valid organizations can be selected that respect the referential integrity defined by the database.

As a next step we also modify the organization column of the person page. For this open class PersonTablePage in the Java editor and navigate to its inner class Table. Then, change the implementation of OrganizationColumn according to Listing 51.

Using the created organization lookup calls we have now completed the modifications on the person form and also used the lookup call to display the a person’s organization in the person page. The next section will focus on the necessary modifications and new components to re-use the person page as a sub page of the organization page.

In this section we will implement a drill-down functionality on the organization page. The goal is to let the user of the application expand a row in the organization page to provide access to the persons of the organization.

Scout node pages are useful when we want to display different entities that are related to a specific entry in a parent page. In the "Contacts" demo application this mechanism is used to link both persons and events to an organization as shown in Figure 54. Note that this is a screenshot of the "Contacts" demo application, not the tutorial application that we are building here.

In the "Contacts" demo application this hierarchical page structure is implemented as follows.

For the "Contacts" tutorial application we will create the exact same structure but only add the person page as child page to the organization node page.

To implement this sequence of linked pages we will follow the dependencies of the linked classes. We start with adapting method getPersonTableData in the person service by adding an organization id parameter. Using this parameter we can then restrict the person search to the subset that is linked to the specified organization. For this change we first update the person service interface as shown in Listing 52.

We now adapt the method implementation in the person service according to Listing 53.

Having modified the person service we add a organization id property to the person page. We can then populate this property when the person page is attached to the organization node page. Finally we can use in method execLoadData according to Listing 54.

In the cases where the modified person page is shown as a child page of the organization page we can now improve the usability of the page’s new menu. When creating a person under an existing organization we create the new person with a pre-filled organization id. See the modified execAction method in NewMenu of Listing 54.

The next step in the setup of the page hierarchy is the creation of the organization node page. Node pages allow to define a list of child pages that typically represent different entities. As mentioned before we will only have the person page as a child page in the "Contacts" tutorial application.

To create the organization node page follow the steps listed below.

After the wizard has created the initial implementation of the node page open class OrganizationNodePage in the Java editor and adapt its implementation according to Listing 55.

We have now created an organization node page that contains a person page as its child page. The only missing step to create the discussed page hierarchy is the link between the organization page with the organization node page. Create this missing link by adding method execCreateChildPage to the organization page as shown in Listing 56.

The difference between Scout table pages and node pages is also reflected in the different signatures of AbstractPageWithTable.execCreateChildPage and AbstractPageWithNodes.execCreateChildPages. Table pages can have a single child page while node pages may contain a list of child pages.

In the seventh step of the "Contacts" tutorial we have introduced a typical Scout user interface pattern for 1:n relationships. We have created a dynamic lookup call and used the lookup call to provide the data for a smart field and a smart column.

To implement a drill-down functionality for the organization table we have created a page hierarchy using the existing organization page and person page. To link the two table pages we have also created and integrated a Scout node page.

The "Contacts" application is in a clean state again and you can (re)start the backend and the frontend of the application and verify the result in your browser. As shown in Figure 56 the organization specific person data is now presented in a hierarchical form in the navigation area of the application.