DreamBeans® User’s Guide
Copyright © 2002-2007 Konsensys, All Rights Reserved.
DreamBeans® is a US registered trademark of Konsensys
Product Version 1.2
Document Version 1.2.4
Chapter 1 Introduction
The DreamBeans® product is a new paradigm of software development.
Traditional Development
Create database 
Create forms Create
code Test
DreamBeans® Development
Create forms
Test
As shown in the picture below, DreamBeans® has a "preview" pane allowing you to see changes immediately as you add components to forms and set properties. Next, select the "Run" menu item to test your generated servlet! Unlike other products, DreamBeans® eliminates most of the coding.
Overview
Who really has the RAD (Rapid Application Development)?
|
Java IDE + Java Server Faces or VB/c# .Net |
DreamBeans |
|
Use one tool within an IDE (integrated development environment) to design web forms and another tool to specify database tables. |
Automatically creates/imports a database field corresponding to a form field -- saving you time. |
|
Use either a wizard or editor to write a complicated database query. And it is up to you to figure out how optimize the query. |
Automatically generates and optimizes database queries for you -- saving you time. |
|
Use an editor to write the "code-behind" that glues multiple web pages into an application and then spend weeks testing and debugging it. |
Automatically generates logically correct (first order logic) "code-behind" for you -- saving you weeks of time on larger projects. |
Other technology like Java Server Faces, .Net Controls, etc. can not be used to visually construct complete software applications, because those technologies lack the “logic semantics” to express a software application’s behavior in a declarative manner. With other products, you have to write code to “glue” the context of the current data entry form to selections made on previous forms. Further, you still have to use tools to define database tables, indexes, referential constraints, and queries.
In contrast, each DreamBeans® GUI icon corresponding to bean is a syntactic component of a logic programming language. The logic programming provides a fully declarative means of expressing the application logic. Thus, creating a complete software application is as simple as selecting DreamBeans® icons (beans) and setting property values.
The logic programming allows DreamBeans® to automatically generate the application logic (code-behind). This fully visual construction of a program that works right the first time, allows to you focus on "what" you want your application to do, rather than spending time determining "how" to make the application. This visual construction of a program makes DreamBeans® the fastest RAD (rapid application development) and prototyping tool for Java servlets available.
This combined AI + Java development paradigm has several key advantages over the JSP paradigm.
1. Much Faster Development (several times faster development than with JSP/ASP-based tools)
2. Safer (guaranteed logical correctness and guaranteed database referential integrity)
3. Easier Developer Learning/Use (much higher level of abstraction)
4. Easier End-User Learning/Use (generates applications with a more consistent look, feel and behavior)
Warning!!!
DreamBeans® is for “professional” software developers!
If a person clicks on an “Insert” button in your generated application a dialog box will sometimes pop up saying the insert failed because it is a duplicate. Then, you have to determine into which “unique” table field the user attempted the insert and decide if this is a correct guarding condition (e.g., you don’t want duplicate usernames or duplicate product serial numbers) or if your application needs a design change (e.g., remove the “unique” constraint on the table field). On complex applications, an experienced software developer is needed to determine where the problem exists in their design.
Likewise, a “ResultTable” bean may appear to display “wrong” results, when put into a form that contains fields from many database tables. This happens when you have not sufficiently thought through the “relationship” between database tables used in a Form that affects how the database query is generated that populates a displayed table, tree, or chart.
Further, the generated application must run on a Java application server and SQL database. For example, even though DreamBeans® can generate all your database tables, you must first create a SQL database that those generated tables can go into. And you must know how deploy the generated jar file to a Java Application server and also register your application’s “context” with the Java application server.
If you lack the above knowledge and skill, then you should look at other products. For example, FileMaker Pro® and Microsoft Access® come with many template applications that have the “logic” already debugged for you. You can use those template applications as a base that you just customize by adding a field or two, etc. Or you can purchase an off-the-shelf application and customize it.
Picking the right tool for the job
The DreamBeans® product is best for data-intensive, web applications having many data entry forms, tables, trees, graphs, and charts.
Examples of such applications are: customer relationship management applications (e.g., sales tracking, help desk, work order tracking, problem reporting, and defect tracking) and analytic applications (decision support and expert systems).
Chapter 2 Installation
Prerequisites
The following environment must be present to install and use the DreamBeans® technology:
· The generated servlets require Sun Microsystems 1.5 or later JRE (Java Run-time Environment)
· The Windows, Linux x86, and Solaris sparc versions of DreamBeans already contain the 1.5 JRE. However, the MacOS, Solaris x86, or the “Generic” versions require you have version 1.5 or later of Java installed.
· The development environment requires that you have either Microsoft’s Internet Explorer or Mozilla installed, which are used to “preview” your application’s web pages inside the development environment. NOTE: On Linux x86, Solaris x86, and Solaris sparc: you must have the Mozilla browser installed in /usr/local/mozilla. You can NOT use the Firefox browser within the IDE, because the current version of Firefox is not designed to be embedded within another application (Firefox libraries are statically linked).
· Generated servlets are compatible with web browsers that support HTML 4 and CSS 2 (such newer versions Microsoft’s Internet Explorer, FireFox, Mozilla, Netscape, and Opera browsers)
· The DreamBeans IDE requires a minimum of 256MB of memory for itself. Thus, you PC should have at least 512MB of memory.
Download
Download the installer specific to your hardware/OS platform (Windows, Linux x86, Solaris x86, Solaris sparc, Mac, or “Generic” Unix), from http://www.konsensys.com.
Configuration and Setup
The Windows-based installer is an EXE, which means you can just double-click it to start the installer. On Linux and Unix, invoke the installer using the “sh” command. For example:
sh DreamBeans_Linux_x86.sh
That’s it! You’re now ready to use the DreamBeans® library in your IDE.
Licensing
You are granted a binary license subject to the terms described in the DreamBeans installer. If you have installed DreamBeans, then you have explicitly agreed to the license terms. In essence, you can distribute the DreamBeans IDE and run-time jar file without reverse-engineering or modification.
DreamBeans includes software from Sun Microsystems, the Java.net projects, the Apache Foundation, dom4j.org, mortbay.org, w3c.org, and jfree.org.
Chapter 3 Quick Start
The following example will take about 20 minutes to create an application that would take several hours to a day to create using other tools. This quick start example will teach you about 80% of the DreamBeans® language basics. The section following this example will briefly cover the remaining 20% of the basics.
Application Example: Multi-User Address Book
This example will create an address book, with username/password accounts. Because this example is a little complex, it requires a little explanation: The entry form will contain “Login” and “New Account” tabs. The first form displayed will offer the option to login with a username and password. The second form will offer the ability to create a new user name and password.
n “Contacts” form will contain a scrollable table of people’s names and phone numbers. Selecting a row in the table will display more details about the person. Further, this form will have buttons to enter new people/addresses, change existing entries and remove entries.
The first and last name fields will be “sounds-like” searchable. That is, when click on the search button, it will match the first name that “sounds-like” the name you spelled. This feature is useful when you don’t remember the exact spelling of a person’s name.
Okay, let’s get started!
Step 1) Create a new project: Create a project called “MyContacts”, by selecting the “Project | New…” menu item, as shown in the picture below:
Fill in just the wizard fields specifying the name of your project, “MyContacts” and where you want your project located. You will next see a dialog box displayed with a number of fields defining the application to be created.
Step 2) Create a reusable application object: Use the “New…” button in the project tree pane to display a gallery of components that can be added to a project. Select a “BaseForm” from the gallery, as shown in the picture below:
A BaseForm is a “business object” defining both a data entry form in an application and a base table in a relational database. Adding a data field to a BaseForm adds a field to both a form and relational database table at the same time. How can this be reusable? For example, suppose you only wanted to display some fields from a table? DreamBeans® has two unique features that will be shown in the next two steps that make this possible.
Selecting the “BaseForm” will bring up a wizard, where you can type in a name like, “AccountInfo”. The only required fields in the form are “Form name” and “Table Name”. By default, the Table Name is set to the Form Name with any white space characters removed (because some SQL databases don’t like table names that contain white spaces).
When the “AccountInfo” form you just created is displayed in the component pane, set its cascade_delete property to “true”. This tells an application that then when a record is deleted from “AccountInfo” to find all other tables having associated records and delete them as well. That is, if you delete a person’s ID from the database, you also want to remove that person’s phone numbers, addresses, etc. In other words, the deletion of a record “cascades” into deletions of related records in other tables.
Note that this “cascade_delete” property is an ease of use feature that is specified very differently from how cascade delete is specified in SQL databases. In a SQL database, you specify a cascade delete in each dependent (child) table, which can be many child tables. With DreamBeans®, you only specify the cascade delete in one place – the parent table. While the DreamBeans® method isn’t quite as flexible as the SQL method (handle every special cases), it is much easier to use for the common cases. DreamBeans® is designed to make generation of the “typical” application as quick and easy as possible. In contrast, SQL databases have the design goal of handling every special case a business might possibly need, which often makes doing the common things complex and difficult. DreamBeans tries to make the common tasks as simple as possible and
Step 3) Add the fields that define this reusable application object: Click on the “Add…” button in the component pane. This will display a gallery of components which can be added to your BaseForm, as shown in the picture below:
Select a “Text” bean from the bean palette and set the Text field’s property, field_label, to “Username”.
In the property pane, set the Text field’s properties field_value_required to “true” and field_value_unique to “true” (as shown in the picture below): This specifies that each user will have a unique name and that they must enter a name when they use this form.
Using the same method as in the previous step, add a PasswordField from the bean palette to AccountInfo, setting the PasswordField’s field_label to “Password” and field_value_required property to true. Set the maxCharacters properties of the Username and Password to 32 characters. You can also specify the minCharacters for each field also. If a person types in too many or two few characters into the username and password fields, a dialog box will display an error message.
You have finished creating the reusable application object. Now, we’ll revisit the question of, “Suppose we only want to display some fields from a table”? When you add a re-usable application object (e.g., AccountInfo”) to an application, you can click on the form_field_properties, which will display a table, as shown below. With this table, you can specify all the important display characteristic of each contained field, including visibility. No other JavaBeans (or VB controls) development tool has this form_field_properties feature that allows you to change the properties of a superclass’s (reusable application) components!
The second unique feature that provides re-usability of a form, as will be shown in the next step, where you can add HTML, buttons, etc. to each instance of the reusable application object. The next step will show how your new application object will be reused twice in this application.
Step 4) Create a header to go at the top of each form: Select “New…” again and then select Box bean (found under the HTML tab), set its name to “My Contacts Header” and set the desired_position property to 0 (puts it at the top of a Form). Then use the “Add…” button in the component pane to add a “HeaderText” bean (found under the “Text” tab) to the Box and set its content property to “My Contacts”. You can experiment setting various properties like color, style, font family (e.g., Arial, Helvetica, Times, etc.) without having to write any HTML code.
Step 5) Create “Login” and “New Account” forms: Select the application object, “MyContacts” in the project tree and use the “Add…” button to add a “TabbedForm” and give it some name, for example, “Access Forms”.
Use the “Add…” button two times to add two instances of the “AccountInfo” bean to the TabbedForm. Set the form_name properties of the two added AccountInfo forms to “Login” and “New Account” respectively. Set their content_alignment properties to “CENTER”, which will cause all text and fields to be centered on the page.
Next, add a “My Contacts Header” bean (under the “HTML” tab) to your “Login” and “New Account” forms. To each form add a “PageText” bean (under the text tab), and set the text_content property to something like “Enter you user name and password.” Set the desired_position of each PageText bean to 1.
Add a “ButtonPanel” bean to each form. Add a “DbButton” and “Quit” button bean to each ButtonPanel. Select the DbButton button in the “New Account” form, and set the button_label property to “Add” and set the action property to “INSERT”.
NOTE: If the web page does not display elements in proper positions, click on the “Backup” button. After a couple of seconds the backup will complete. Next, select “Revert”. This will force the time stamp on the generated files to change, which will force Java to recompile the web page.
You have now finished creating forms for logging in and creating new accounts, including the database table, SQL code, and “code-behind” – without writing any code! With the Windows, Linux x86, and Solaris versions of DreamBeans, you will see exactly what the Login form will look like in the “Preview” pane (as shown below).
Note: If you don’t like the colors, etc. you can click on the “Style…” button to change them.
Step 6) Create “Contacts” form: Select “servletapplication.My_Contacts” (the top level component), and add a “GroupForm” bean. Set the form_name of the GroupForm to “Contacts”. Then select the previously added “DbButton” beans. When you select their form_on_success property, a list of available targets appears. Select “Contacts”. This says that if the “Login” find operation or “New Account” insert operation is successful to go to the “Contacts” form.
Add your “My Contacts Header” bean to the “Contacts” bean you added in the previous step. Next add a ResultTable (found under the “Multifield” tab) to the “Contacts” bean..
Note, the group_layout property in the GroupForm, “Contacts”, is set to “COMBINED”. This will cause all the contained forms to be displayed together (laid out) as a single form. If set to “CARD” then each added Form will be displayed separately. This allows you create a tree hierarchy of forms to display.
Add an AccountInfo bean to the Contacts form. Select AccountInfo’s form_field_properties property, which will display a table of AccountInfo’s field properties. Set all the fields to NOT be visible in the form and NOT be visible in a table.
And sest the editing_enabled property to false. This tells DreamBeans that the AccountInfo table is read-only (not modifiable) in the Contacts form.
Note: AccountInfo is added to the Contacts form to inherit the log-in information entered in the previous form (that is, inherit the context). Any time you want to inherit choices made in previous forms, then you must add the same beans (tables) used in the previous forms to the current form.
Add a ResultTable to “Contacts” (found under the Multifield tab). This will create a scrollable table of your contacts.
Now you have a choice. You either use the “New…” button in the project pane to create a reusable BaseForm or use the “Add…” button in the component pane to create a “one-off” BaseForm. If you are 100% certain that you will never use the form/table anywhere else, you can use the “one-off” version.
In this example, we’ll be lazy and just add the BaseForm beans directly to the “Contacts’ form.. Add a BaseForm to “Contacts”. Set the form_name property to “Person.” And set it’s cascade_delete attribute to true, so that if a person is deleted from the database, and associated phone numbers, addresses, etc. will also be deleted.
Add a Link field to “Person”. Click on the linked_table_name property “AccountInfo” from the list of tables. The BaseForms, “Login” and “New Account”, both have “AccountInfo” as their base table. The linked_table_name property says that the “Person” table is linked to the AccountInfo table. Thus, only persons linked to an account will be displayed. VERY IMPORTANT! Set the link field’s field_value_unique to “false.” This allows multiple records (Persons) linked to the same account. In database speak, AccountInfo is a non-unique, foreign key. Otherwise, after you enter the first person’s data, you would not be able to enter any more person records into the database..
It is subtle database design issues such as uniqueness of link fields (foreign keys), that require a professional software developer. In other words, DreamBeans® is a product to improve the productivity of professional developers – not eliminate the need for the professional developer.
Add a GroupField field to “Person” and set the field_label property to “Name”. A GroupField is a container of other fields. The GroupField groups the contained fields into a single field for indexing (sorting done first-to-last contained field) and layout (horizontal or vertical). Set the field_value_unique property to “true” (specifies that the contained fields combined as a single key is unique).
Add three Text fields to “Name”, and set their field_label properties to “Last”, “First”, and “MI” respectively. Set the field_value_required properties to “true” for “Last” and “First” (but not “MI” because not everyone has a middle initial). Sorting will be done by last name, then first name, then middle initial. On “Last” and “First”, set the field_search_constraint property to “sndx”. This will allow successful search on misspellings that still “sound-like” the desired name. Set the maxCharacters property of First and Last to 32. Set the maxCharacters property and field_column_width property of MI to 1.
Add a BaseForm to “Contacts” and set its form_name property to “Street Address”.
Add Text fields to “Street Address”, “Street 1”, “Street 2” and set the field_column_width property of each to 60.
Add a FieldPanel to the BaseForm, “Street”, set the FieldPanel layout_direction property to “HORIZONATAL”. And to the FieldPanel add the Text fields “City”, and “State”. You may wish to set the width of “State” to 2 characters and set the property, case_style, to “Uppercase all”. Set the maxCharacters property of Street 1 and Street 2 to 32. Set the maxCharacters property of City to 64. FieldPanels are used to control the horizontal and vertical layout of your fields. You can nest FieldPanels inside each other to create a custom layout.
Add an IntegerField to the FieldPanel and set the IntegerField’s field_max_value to 99999, field_min_value to 0, and field_column_width to 5.
Add a Link field to the “Street Address” Form and set the Link field’s linked_table_name to “Person”. This Link field indicates that street address table references the person table. That is each person has an address.
Important: Set the field_visible_in_result_table of all the address fields to false. You don’t wan the table cluttered up with too much information. When you click on an entry in the displayed table, it will automatically fill in all the form fields with the details.
At this point, you have learned everything you need to complete the application. If you wished, you could add more BaseForms, such as “Email”, “Phone”, “Important Dates”, etc. to make the application as fancy as you wish.
On every field in “Street Address”, set the field properties sorted to “false” and field_visible_in_result_table to “false.” You don’t want the table to have too much information. When you click on a name in the ResultTable, it will automatically fill all the fields in your form with all the details.
You can add a couple more BaseForms for email addresses and phone numbers. We’ll wrap this up by simply adding the buttons required to make to finish off the demo.
Add a ButtonPanel to “Contacts” and set its field_layout_direction property to “VERTICAL.” Add two more ButtonPanels to the first ButtonPanel and name them ButtonPanel1 and 2. The nesting of ButtonPanels is used to organize the layout of the various kinds of buttons. Add two more panels to ButtonPanel1 and name them ButtonPanel3 and 4.
Add a DbButton to ButtonPanel3, and set its label to “Search”.
Set ButtonPanel4’s field_layout_direction property to “VERTICAL.” Add two more ButtonPanels to ButtonPanel4. Name them ButtonPanel5 and 6.
Add 3 DbButtons to ButtonPanel5 and label them “Add”, “Change”, and “Remove.” Set their action properties to “INSERT”, “UPDATE”, and “ERASE” respectively.
Add a “Clear” button to ButtonPanel6.
Add a Quit button to ButtonPanel2.
Your “Contacts’ form should like something like the following:
Your are done! You are now ready to click on the “Run” button, which will start up a Java webserver and web browser initialized with the URL of the ServletApplication you just created.
When programming using servlets/JSP (or ASP), you have to: create the database tables with separate tool, referential constraints (such as specifying cascade delete on tables depending on the “AccountInfo” table), and indexes; write SQL queries, create the forms, write session-tracking code, write JDBC code to: access the database, write either Javascript or applets to handle client-side constraint checking on fields, make the tabbed panes work, make the buttons work (search, insert, update, etc.), write more Java code to “link” the username/password account in the previous form to the associated names and addresses in the next form, write code for soundex-based searching. And it all has to be tested and debugged!
This will take a minimum of 4 times longer than using DreamBeans® servlet-beans. Even using a Microsoft Access-like project, you still have to define tables, define queries, define forms, and write macros – taking twice as long as DreamBeans® servlet-beans technology.
The remaining 20% of the basics
In the previous section, you have learned 80% of the DreamBeans® basics: How to create a ServletApplication, create a re-usable object, create forms with text, fields and buttons, navigation between forms, etc. This section of this chapter will cover the other 20% of the “basics.”
Button Placement
As you saw in the Address Book demo above, buttons are placed and organized within a ButtonPanel. Normally, a ButtonPanel is placed anywhere in a top-level form. A top-level form is a form that is displayed as single page. For example, you might enter information into a GroupForm that contains fields from several subforms. An “Enter” button, at the top-level would add the entered information into each of the contained subforms’s associated database tables.
Field Placement
Every BaseForm contains a FieldPanel, which has a “VERTICAL” layout that positions each added field below the prior field. When you add fields to a BaseForm, the BaseForm adds each field to its FieldPanel.
You can also add a FieldPanel to a BaseForm, which will become nested inside the BaseForm’s FieldPanel. And you can add both fields and FieldPanels to other FieldPanels. By setting the layout of each FieldPanel to “HORIZONTAL” or “VERTICAL”, you can create a custom layout of your fields.
CARD layout
If the group_layout property of the GroupForm, “Contacts”, were set to “CARD”, then the forms “Name”, “Address” and “Phone” would each be displayed as individual pages – each would be a “top-level” form and each may contain one or more ButtonPanels filled with Buttons. With CARD layout, the GroupForm, “Contacts”, would never be displayed (only the contained forms are displayed).
You can nest GroupForms with CARD layout to create a tree organization of Forms. This allows you create a very complex application with a large number of forms with a logical grouping and visual organization.
Scope
You will remember in the MyContacts example (in the previous Quick Start section) that DbButtons have the two properties form_on_failure and form_on_success. These specify the next form to call (visit) depending on whether the database action fails or succeeds. The GotoButton also has a form_target property.
When you select one those properties (form_on_failure, form_on_success, or form_target), a list of possible destination forms are shown – but not all forms appear there. That is because some forms are out of “scope”.
1) A form has no visibility into the contents of another form. Like most “procedural” programming languages, the calling procedure has no visibility to code inside the called procedure. Likewise, when a Form “calls” a GroupForm that has a CARD layout, the first Form contained within the GroupForm is displayed (like execution of the first statement within a procedure). Technically, each Form is the predicate of a Horn clause. The above explanation is just an analogy to something familiar to the ordinary programmer.
2) A target form is within scope if it is at the same or higher nesting level of Forms, which is analogous to procedure scope rules in languages that support nested procedures like Pascal, Modula, and Ada.
Fortunately, you don’t have to remember the rules. DreamBeans will only display the in-scope Forms in the list of target options.
In the “MyContacts” example, shown in the picture below, “New Account” is within the scope of the “Login” form, because they are both nested at the same level within the GroupForm, “Access Forms”. And both of those forms have “Contacts” within their scope because “Contacts” is nested one level higher in the tree. However, “Person” is not within the scope of “Login” because it is inside another form.
Context
In the MyContacts example above, each user has their own set of names and addresses – their own context. DreamBeans® determines which names and addresses to display for a user based on the previous “context”. The “Login” form sets the context for the “Contacts” form, which the “Contacts” form determines the context via the “Link” field, named “AccountInfo”.
The current context is the form the end user is currently viewing. Previously visited forms are prior contexts. If the target form of a button (or a form’s goto_on_row_selection property) has already been visited, then the context (stack) is unwound back to that previously visited form. In other words, the DreamBeans® language does not allow “recursion.” This makes the generated applications much more intuitive for the user.
For those familiar with logic programming languages like Prolog, each DreamBeans® Form (context) corresponds to a Horn clause, where fields that do not have constant values are logic variables and buttons are operators. The default group_relation property, LinkJoin, is the logical “and” of predicates in a clause.
The Link field is the means by which DreamBeans® automatically detects the primary and foreign key relationships. When you delete a row (and you set the cascade_delete property of a form to true), then DreamBeans® uses the Link field to find all dependent rows in other tables and remove them as well (preventing “orphan” rows). If the cascade_delete property is set to false, then DreamBeans® won’t allow the row to be deleted if dependent rows in other tables exist (preventing “orphan” rows).
A Link field is a little bit similar to a “SEQUENCE” field in Oracle, an “AUTOGENERATE” in IBM’s DB2, an “AUTOINCRMENT” in MySQL, and “AUTONUMBER” in Microsoft Access, etc. The difference is that Link fields are immutable for the life of a row and not displayed in forms or tables. Their purpose is strictly for setting context.
Important note: Use the Link field to relate one table to another. Never create duplicate fields across tables. This is a cause of database inconsistencies, where a field is updated in one table but not updated to the other tables. If you only use Link fields and display the linked forms together on a GroupForm, then such database inconsistencies will never occur.
Forms containing fields from many database tables
Suppose you purchased a defect tracking tool, and you customize it by entering your company name and product into some configuration tables. When a person uses your defect tracking tool, your company and product name will appear at the top of every form.
However, when a customer selects the “Insert” button to enter a problem report, you don’t want to have your company and product name fields updated! You just want the customer’s problem data to be inserted. You can set the editing_enabled property to “false” on those BaseForms (tables) that you do not want to be affected by a database operation.
Important note: Setting the form_style property to “Display-Only”, does not set the editing_enabled property to “false.” In the defect tracking tool example above, you might set the current date and generate a new defect ID automatically, which is inserted into fields that are “Display-Only.” You might have display-only fields that have values set by assigning a constant value (via the field_constant_value property of a form field), a default value (via the field_default_value property of a form field), via calculations (via the field_output property of a CalcField), or date/time field being set to the current time, etc.
NULL values not allowed
One reason other products can not generate the “code-behind” from an iconic specification, is that their semantics are not based on formal logic. If you want to translate a “declarative” (high-level) specification into correct code, then there must be some rules based on a formal system of logic to generate the code.
Horn clause logic is a “decideable” (computable) subset of first-order logic, where all assertions are bi-valued (true or false). Relational logic is subset of Horn clause logic. Thus, relational logic is also bi-valued. There is no known tri-valued (true, false, don’t know -- NULL) system of logic that is computable. Therefore, there is no known means to “compute” correct code for a tri-valued system…
And that is why relational tables containing NULL values are a frequent source of logical inconsistencies in a database. There is no way for a database management system to compute a way to prevent or fix problems, when NULL values are allowed. So, if you want to work at higher-level of abstraction, then you have to be a little more disciplined in your “logic.”
There are two cases to deal with:
1) No value is needed. For example, first name and last name might be required, but the middle initial is optional (not everyone has a middle name). For this case, set the field_value_required property of a form field to false and the default will be used. Another example is a retail store might collect customer information during a sale. Some customers may decline to provide information. The default value for a customer name would be set to “Anonymous”.
2) You only know some of the values at this time. This indicates an insufficiently normalized database. Any time, you have some fields with values you don’t know, those fields should be broken out into a separate table (a separate BaseForm). For example, you might know a new employee’s name, but not yet know the assigned department. The department field should be in a separate table, with a “Link” field to link to the employee table. You can then insert a value into the department table when you find out the assigned department.
NULL values were added as a feature to relational databases by ignorant database designers, who lacked a competent understanding of relational logic. The only reason NULL fields exist today, is for backward compatibility for people accustomed to sloppy database design practices. NULL fields should never be used in new applications.
The database management system from Oracle Corporation is particularly bad (non-relational), because it dose not make a distinction between a NULL field and a field having the value of an empty string. That is, you might want the default value stored in a field to be an empty string – not “I don’t know” (NULL).
This position may seem a little extreme. However, consider that a programmer very rarely looks at the machine code generated by a compiler, because 99.9% of the time, the “bug” is in your own software – not the code generated by the compiler. DreamBeans® is a computer language. And you need confidence that the generated application code is correct. That could not be achieved if NULL values were allowed.
Therefore, DreamBeans® language does not allow NULL values in tables. Before a DreamBeans® generated application inserts a row into table, DreamBeans® checks that all values are instantiated to non-NULL values. For databases like Oracle that do not make a distinction between NULL and empty strings, you must assign some non-empty string as a default value (for example, “-----“).
Using external (foreign) tables.
Most “real-world” applications require accessing data in existing database tables. To access an external table:
1. If you have not already done this:
a. Select the “Project | Properties… menu item.
b. Select the “Database” tab in the Properties window and specify the name of the “external” database vendor, database name, port number, user name, and password.
2. Select an “ImportedBaseForm” from the “New” or “Add” buttons.
3. Set the form_name property of the ImportedBaseForm.
4. Set the table_name property of the ImportedBaseForm by selecting a table from the list of tables in the database.
5. Set the form_field_properties property of the ImportedBaseForm.
The example property editor (above) allows customization of how fields from an external database (an ImportedBaseForm) will be displayed.
Note that the form_field_properties property of the ImportedBaseForm has a couple of extra properties for each table field for specifying how each field is displayed. For example, You must specify if a VARCHAR, TEXT, or STRING data type in the database is displayed as either a “Text” or “TextArea” field in an HTML form. And, for each displayed table field, there is a property to specify the display width.
Note #1: You can not add, change, or remove the fields of an ImportedBaseForm from within DreamBeans. This prevents you from accidentally losing all your data or breaking your other existing applications that depend on existing table definitions.
Note #2: You can not use the “LinkField” to reference an external table, because the external table will probably lack a primary key field (column) having the same name as the table name and having the data type of integer (long or big int). Therefore, to specify the “link” (relationship) to external tables, you must explicitly specify the “common columns”, using the explicit_common_columns property of a GroupForm, which is a comma-separated list of common columns. For example, “Account.PersonID=Salary.PersonID, Account.PersonID=Department.PersonID” says that the “PersonID” in the “Account” table is the same as the “PersonID” table in the “Salary” and “Department” tables.
Note #3: DreamBeans® does not guarantee the relational integrity of those databases not created by DreamBeans®, because imported databases are not as disciplined in their design as those created by DreamBeans®.
Chapter 4 ServletApplications
Your servlet application will extend javarex.beans.servlet.ServletApplication (which implements the javax.servlet.Servlet interface). This special implementation of the Servlet interface also extends java.awt.Container, which allows you to add DreamBeans beans just like you would when constructing an applet. DreamBeans® provides a specialized viewer to preview a form prior to execution.
When you use the ServletApplication wizard to create a new ServletApplication, with <your app name>, several tasks are automated for you:
· A template <your app name>.java file is created
· A <your project name>.css file is created with default styles defined
· The two files mentioned above are added to your project
· The Servlet and DreamBeans® libraries are added to the required library list
· All the servlet context and init parameters are created and set default values
· An images directory is created in your project area containing a few button icons
If you put a check in the “Is a portlet” check box, which is displayed when you create a new ServletApplication, then DreamBeans® generates a special type of ServletApplication, call a PortletApplication. Generated PortletApplications are JSR 168 compliant. See the PortletApplication section of this chapter for a more detailed description of portlets.
Customizing the look and feel
Clicking on the “Style..” button brings up a GUI to change the look and feel of all the components as shown in the picture below:
The GUI modifes a “cascade style sheet”, which is used by the application to provide a consistent look and feel across all applications in the project.
The ServletApplication. property, “style_sheet_inlined” has a default value of “false”, which causes the style sheet to be linked to the generated web page rather than in-lined. This allows you want to experiment with different styles without stopping/restarting your Java web server. NOTE: Remember to put a “/” in front of a relative URL to the style sheet, otherwise, your web server will assume the file is a servlet and generate a ClassNotFound error.
There is a small performance advantage to in-lining the style sheet definitions. When, in-lined, the ServletApplication holds the style sheet definitions in memory rather than the web server reading in the style sheet from disk for each browser request. Normally, this would only be useful in very high-traffic websites.
If you are not using a version control system, then you should backup the copy of <your app name>.css before modifying it. If you mess up the styles and need to revert back to the original version, it will be much easier if you have a backup copy.
Valid syntax
Only the beans on the “DreamBeansForms” page of your beans palette can be directly added to a ServletApplication. In other words, your ServletApplication is a set of forms. Thus, the only things you can add to a ServletApplication are forms.
You can add as many forms as you wish to a ServletApplication.. DreamBeans® also provides a pseudo-form, HTML_frameset as a convenience to quickly create (you guessed it) an HTML <FRAMESET>.
ServletApplication bean properties
When you pass a cursor over a property, a “hint” pops up that explains the purpose of the property. For most properties the property name and hint are sufficient explanation. The following are additional comments on some properties that require a little more explanation:
The autocommit property has the default value of true. That is, it specifies that any database operation is to be immediately executed. However, if your database supports transactions (COMMIT and ROLLBACK) and you plan to use COMMIT and ROLLBACK in your application, then set autocommit to “false”.
commit_timeout sets the number of seconds to wait before rolling back a transaction. This requires that autocommit property is set to false. For example, a customer is ordering books on-line and you had set the database transaction isolation level to “SERIALIZABLE”, thus no one else can complete their orders until the first customer, who has left for the day, completes his order. This is known as a “live wait”. The DreamBeans® middleware tracks the time each transaction is pending and will tell the database to roll back a pending transaction after a timeout period. The default value of “-1” specifies there is no timeout period.
The debug_depth property is used to specify the amount of debug information to output while your application is running. In most cases you not need this property. However, if you don’t understand the “logic” of why your application is behaving the way it is behaving, then you can turn on debugging. “GUI Forms” and “Logical Table” are useful to you. The other (deeper) levels are primarily for use by Konsensys.
The locale property is used to specify the default language and country, e.g., “en_us”. It is not fully used throughout the DreamBeans product, as DreamBeans in not internationalized. It is here mostly as a place holder.
The max_inactive_period property specifies how long, in minutes, a user’s session lasts with no activity. The default value is 60 (minutes).
The new_window property specifies whether you want your application opened in a new browser window or not. The default value is false.
The SSO_form (Single-Sign-On form) property specifies the name of the “login” form in your application. Leave this property blank if you do not require a person to login or register prior to using your application.
Note #1: The SSO_form property displays a menu list of form names that you have already added to your application. Therefore, you have to add a login form before you can set this property. Single-Sign-On is useful in two circumstances.
1. A user wishes to use an application more than once, without out having to log into the application each time (only requires logging in once).
2. You have a suite of applications in your project, and you only want the user to login once for any or all of the applications in your project.
Note #2: A user is automatically logged out when max_inactive_period expires.
Note #3: You specify a successful login by setting the login property of DbButton to true. This tells the button, that if the database operation is successful (e.g., matches the entered user name and password to a record in the database) to mark the person a logged in. To complement this, the Quit button has a logout property, which tells the Quit button to both exit the application and also log the person out.
The style_sheet_name property is a URL to the cascade style sheet used for this application.
The version property allows you specify a version number for your application.
Servlet context parameters
All servlet context parameters, specific to DreamBeans®, have the prefix “javarex_”. Servlet context parameters are generally specified in your WEB-INF/web.xml file.
JDBC_database_name, JDBC_driver, JDBC_URL, JDBC_username, and JDBC_password are used to access a SQL database via JDBC. Note, that there is a minor security issue with storing the username and password to a database in a web.xml or conf file. Be sure to set the directory and file access to restrict readability of that file. You might be asking why not have the ServletApplication prompt for a username and password? A “lights out” (24 by 7) automated environment might automatically restart a crashed server and no one would be around to provide a database username and password. Having the database username and password in a protected web.xml is adequate security for most of the world.
See the chapter on “Databases” for more details specific to choosing and configuring a database with DreamBeans®.
When a servlet starts up and the property, javarex_output_path_HTML, is a non-empty string, then HTML files corresponding to each form is output to the specified directory path.
When a servlet starts up and the property, javarex_output_path_SQL, is a non-empty string, then SQL defining all the tables and views is output to a .sql file in the specified directory path.
javarex_style_sheet_name the URL of the style sheet used by your ServletApplication. or sent by the web server (linked to the generated web page).
Chapter 5 PortletApplications
PortletApplication is a ServletApplication
A portlet is special type of servlet. A portlet is designed to be displayed in a special type of web page, called a portal. A portal is a container that displays multiple portlets on single web page. That is, a portal is means of gathering multiple sources of data/applications onto a single web page. There is a free, open source portal from Apache.org, called Jetspeed. And there are several commercial versions available, e.g., Plumtree Software’s Portal product.
A portlet does not generate “<HTML>”, “<HEAD>”, nor “<BODY>” tags. The HTML generated by a portlet is captured by a portal “container” and typically displayed within an HTML table. The following describes how to generate JSR 168 compliant portlet using DreamBeans®.
PortletApplication bean properties
Select “New” from the component pane and then select the “ServletApplication” icon. A dialog box with ServletApplication properties will be displayed. If you select the “Is a portlet” check box, then DreamBeans® will generate a special type of ServletApplication called a PortletApplication. You then add forms, etc. to the PortletApplication just as you would a ServletApplication.
Unfortunately, the JSR 168 standard for portlets does not specify how data in form fields is passed in the request to a server. To make this simple for you, DreamBeans® provides an intelligent “StateField” that you can add to your forms.
The “StateFields” you add to your forms are smart. If an HTTP request parameter matching the name of a StateField is not found; the StateField tries to find a matching portlet request “attribute” name; if the StateField finds no match, then it tries to find a matching portlet request “property” name; if the StateField again finds no match, then it tries to find a matching portlet “preference” name.
After you create your portlet, use the “package” menu item under the “Project” menu to create a “.war” file. Copy the war file to your portal and use the portal’s configuration pages to tell the portal about your application, specify the row and column it will appear within the web page, preferences, security constraints, etc.
Chapter 6 Forms
On the bean palette you see the following beans located under the DreamBeansForms page:
BaseForm., GroupForm., TabbedForm, GotoButtonForm, RedirectForm., and HTML_frameset.. The class hierarchy is as follows:
The BaseForm. and GroupForm. are both of type DataForm. The BaseForm contains data fields (associated with a base table), The GroupForm contains a group other Forms (associated with a derived table).
An ImportedBaseForm is special type of BaseForm that imports its field definitions from an existing database table.
The TabbedForm is a GroupForm with “CARD” layout that displays tabs for each Form added to the TabbedForm. Each tab’s label corresponds to the form_name property of the added Form. At run-time, selecting a tab, displays the corresponding Form.
The GotoButtonForm. contains no data fields. The buttons are used strictly for selecting other form destinations (similar in function to an HTML link).
The RedirectForm is used within a “reusable” GroupForm (a class you make that extends Groupform).
HTML_frameset. is pseudo-form and exists as convenience.
All of these will now be discussed in more detail.
The default value for the form_requst_method property is “POST”, because a “GET” has a limit of 1024 bytes in the URL. If you have a web page that has some large “textarea” fields or a large number of fields, the size of the HTTP query string might be larger than 1024 bytes, which is the maximum size allowed by an HTTP “GET”. The reason this property is made available so that you set it GET, is for case you want skip the default entry form, by passing some parameters specifying the form name and some field values.
BaseForm
A BaseForm. is an object that contains a BaseTable. A BaseTable is persistent database table (either a DreamBeans® object-relational table or an object wrapper around a SQL relational table). When you add fields (beans) to a BaseForm, it implicitly adds fields to the BaseTable. You can also add text, images, calc fields, result tables, etc. to BaseForms. When you create a class that extends BaseForm you have a re-usable object that can be added to your bean palette.
Important Note: You can make your new BaseForm. re-usable by using the BaseForm wizard in the DreamBeans® object gallery (invoked by the “New…” button in project components pane). This will create new class for you extending BaseForm and create an entry in for your new class in the bean palette. After adding your data fields, calc fields, text, etc., you can compile and select your new bean from the palette.
For example, if you create a reusable “AccountInfo”, it will appear in bean gallery as a component that can be added to GroupForm as shown in the picture of the GroupForm’s bean palette below:
When you select your new bean from the bean palette and add it to your application, you will see the bean property, form_field_properties.. When you click on this property, a table will pop-up that allows you to edit various field attributes, e.g., visibility, read-only vs. modifiable, required vs. optional, style, etc. You can even add more text, images, tables, calc fields, etc. to the bean. This allows you customize each instance of your new bean for different contexts.
The example property editor (above) allows customization
of your re-usable object (bean).
Important Note: The BaseForm. listed on the bean palette is for use where you do not plan on re-using the form. Use the object gallery to create a re-usable BaseForm bean. If you do use the bean palette version to define the same table in more than one place and accidentally make two incompatible definitions, you may have trouble tracking down the problem.
Setting the BaseForm.’s form_name property, will automatically set the table_name. property as the default. You should override this by explicitly by either settting the table_name property first or setting the table_name property to a slightly different name. The reason for creating a unique table name is that you might several instances of this BaseForm, each with a different form_name that all access the same table.
ImportedBaseForm
Using external (foreign) tables.
Most “real-world” applications require accessing data in existing database tables. To access an external table:
6. If you have not already done this:
a. Select the “Project | Properties… menu item.
b. Select the “Database” tab in the Properties window and specify the name of the “external” database vendor, database name, port number, user name, and password.
7. Select an “ImportedBaseForm” from the “New” or “Add” buttons.
8. Set the form_name property of the ImportedBaseForm.
9. Set the table_name property of the ImportedBaseForm by selecting a table from the list of tables in the database.
10. Set the form_field_properties property of the ImportedBaseForm.
The example property editor (above) allows customization of how fields from an external database (an ImportedBaseForm) will be displayed.
Note that the form_field_properties property of the ImportedBaseForm has a couple of extra properties for each table field for specifying how each field is displayed. For example, a VARCHAR, TEXT, or STRING data type in the database can be displayed as either a “Text” field or a “TextArea” field in an HTML form. And, for each displayed table field, there is a property to specify the display width.
Note #1: You can NOT add, change, or remove the fields of an ImportedBaseForm from within DreamBeans. This prevents you from accidentally losing all your data or breaking your other existing applications that depend on existing table definition.
Note #2: To specify a “link” (relationship) to other tables, you can use the form_field_properties to change the “type” of an integer valued field to either a Link field or ChooseOne field.
Note #3: To specify a table in a different database (some database vendors would call it a different catalog or different schema). Prefix the table_name with a name of the database and period (just as you would in a SQL query). For example, “accounts.customer” specifies the “customer” table in the “accounts” database.
GroupForm
A GroupForm. is a form containing other forms. You can add as many forms to a GroupForm as you wish (including other GroupForms – nesting as deeply as you wish). When you add forms to a ServletApplication., you are actually adding the forms to a GroupForm contained within the ServletApplication.
You can make your new GroupForm. re-usable by using the GroupForm wizard in the DreamBeans® object gallery (under the menu item “File | New…”). This will create a new class for you extending GroupForm. After adding your subforms, calc fields, text, etc., you can compile and select your new bean from the palette.
There are two important bean properties for the GroupForm.: group_layout. and group_relation.
group_layout.
The group_layout. property has two values: COMBINED and CARD. When group_layout is COMBINED, then all the subforms are combined and displayed as a single large form in an HTML page. If group_layout is set to CARD, then each subform is displayed on a separate HTML page. The top-level GroupForm. contained within a ServletApplication. has a “CARD” layout.
For example, the “CompanyAndProduct” GroupForm might contain a BaseForm called “Company” and a BaseForm called “Product.” If group_layout is set to COMBINED, you would see an HTML page containing the data fields “Company Name” and “Product Name.”
If the group_layout is set to CARD, then your ServletApplication would first display the Company form. You would have to add a DbButton to the “Company” form to submit the “Company” form. If a row in the Company table is found, then the ServletApplication would display the “Product” form.
Important Note: If a GroupForm has a CARD layout, then you may not add anything but Forms or a TabPanel. If a GroupForm has COMBINED layout, then, you can add buttons, text, images, etc. to the GroupForm. The valid components you can add to GroupForm are automatically selected and displayed when you select the “Add” button. So, there is no need to worry about memorizing that information. However, if you add components to a GroupForm with a COMBINED layout and then change the layout to CARD – then you will have some problems!
To better understand how COMBINED and CARD layouts are used, see the address book example in the “Quick Start” chapter.
group_relation
The group_relation property defines the relational operation across the contained subforms (BaseForms and GroupForms). The group_relation properties allowed are:
LinkJoin, Join, Left Outer Join, Right Outer Join, Difference (SQL92 “EXCEPT), Intersection, Union, Product and Quotient (the division of one table by another).
Note: 99% of the time, the only group_relation you will ever need is “LinkJoin”. A “LinkJoin” is different than the “VIEW” in a SQL database. In a SQL database, a “VIEW” can be any kind of query. In DreamBeans®, a “LinkJoin” operates like the logical “AND” operation in a logic programming language, like Prolog (a natural join using the link fields as named logic variables is done).
The exact type of SQL code generated for SQL databases depends on whether implicit common columns are used. For example, Join generates the SQL, “NATURAL JOIN” when the property “uses_implicit_common_columns” is set to true, and generates “JOIN” when set to false (the default).
Note: A GroupForm must contain at least two data forms, when group_relation is not a LinkJoin. This should be obvious. For example, how could do a join with only one table?
Using external (foreign) tables.
To specify the “link” (relationship) to external tables, you must explicitly specify the “common columns”, using the explicit_common_columns property of a GroupField, which is a comma-separated list of common columns. For example, “Account.PersonID=Salary.PersonID, Account.PersonID=Department.PersonID” says that the “PersonID” in the “Account” table is the same as the “PersonID” table in the “Salaray” and “Department” tables..
GotoButtonForm
The GotoButtonForm bean generates an HTML page with buttons -- but no data fields. This kind of form is useful when you want to offer a list of options that take you other forms. You can add GotoButtons from the DreamBeansButtons page. You can also add PageText, HeaderText, HTML_component, and Box beans (both found on the DreamBeans® Misc page). A Gotobutton has a target destination. Clicking this button causes your ServletApplicaton to go to the target destination web page (similar to clicking on an HTML link).
RedirectForm
The best way to explain the RedirectForm is via an example of how it would be used. An example of its use would be a reusable GroupForm with a CARD layout that contains three “account” forms: an account login form for existing users, a form for new users to create their account username and password, and a form to change their account username and password. After successfully, completing any one of these forms, you want to go to the “next” form outside of this reusable GroupForm. The RedirectForm allows you to create a reusable “account” bean that you can reuse in multiple applications, without having to hard-code the name of the “next” form to display.
You add a RedirectForm as the last form within your reusable GroupForm. The forms within your reusable GroupForm would have buttons specifying the RedirectForm as their target. The RedirectForm automatically redirects to the “next” form following the reusable GroupForm.
HTML_frameset
The only thing you can add to an HTML <FRAMESET> are other <FRAMSET>’s and <FRAME>’s. The same is true here. You can only add an HTML_frameset or HTML_frame beans.
The HTML_framset is a pseudo-form. It’s just a convenience for quickly creating a web page with frames, when you don’t want to take the time to create an HTML page using an HTML editor (it’s a little faster and easier to use DreamBeans® for constructing simple framsets). You can only add a single HTML_framset to a ServletApplication. Further, if you add an HTML_frameset, you may not add anything else to the ServletApplication.
Chapter 7 Form Fields
There are four basic types of fields: data fields for storing various pieces of information, a group field that combines other fields as a single field, the Link field for relating rows in one table to rows in another table, calc fields for computing results from information in tables an inserting calculated results into tables, and finally state fields for providing global state information across forms (within a session). The class hierarchy is outlined in the diagram below:
This diagram shows the class inheritance structure of FormFields.
All form fields inherit from FormField which inherits from HTML_component. Those fields whose values have a textual representation inherit from BasicText. Fields with no textual representation inherit directly from FormField.
A non-data field, Link, inherits from IntegerField, which inherits from BasicText.
Most calc fields inherit from FloatingPoint, which inherits from BasicText.
Data Fields
Text-based
As mentioned previously in this section, data fields that have a textual representation inherit from the class, BasicText. Examples of such classes are:
· Text (a single line of text field),
· TextArea (a multi-line text field),
· IntegerField,
· FloatingPoint,
· Date,
· and Timestamp.
FileField
FileField is special type of data field that displays a file upload field and button. When the file is uploaded to from the browser/PC to the server, the database stores the file as a file. The FileField has a property to specify the mime types (file types) to list for selection.
Link
Link is special type of data field that is “foreign key” referencing a row in another table. It’s value is automatically generated by DreamBeans, and normally not visible in a form. Adding a Link field to BaseForm is your way saying that the BaseForm is “linked” to another BaseForm. If you want to indicate one table uses another table, you simply put a Link field in the BaseForm and give it a field name that is the same as the name of the table you want to “link.”
DreamBeans® uses the Link field to relate one table to another. The DreamBeans® Link field is a unique feature that eliminates the need to define primary keys, foreign keys and referential constraints on keys. This allows developers to focus on what content and operations they want, without worrying about referential integrity problems.
Non-text-based
Examples of non-text fields that inherit directly from FormField are Checkbox and ChooseOne.
· Checkbox is the visual representation of a Boolean field.
· ChooseOne displays either a list of radio buttons or a menu list depending on whether its field_display_type property is set to “Radio Buttons” or “Menu List” option.
ChooseOne is slightly more complex and powerful field that requires a little further description. You can think of a ChooseOne field as a type of Link field (a foreign key pointing to a row in another table). The referenced row in that other table is identified by choosing from a list values displayed either as radio buttons or menu list. An example, will clarify this.
Suppose, you want to create an application that lets someone assign an employee to a department:
1. Create re-usable BaseForm called “Employees” and add a Text field called “Name”.
2. Create re-usable BaseForm called “Department” containing a Text field called “Department Name” and a ChooseOne field called “Employee Name”.
3. Next, use the “Add” button to add the “Employees” BaseForm, and in the ChooseOne’s choices_field_name property field, select the field “Name”.
When you run your application, a menu list employee names (or set of radio buttons) will be displayed from which a person can select a name to add to a department.
NOTE:
1. You must use the “Add” button to add the BaseForm containing the list of choices to a ChooseOne field.
2. The first field in the added BaseForm is normally the primary key (automatically created there by DreamBeans) and is used as an invisible “value” corresponding to each choice.
3. The ChooseOne field has a choices_field_name property that specifies which field in the added BaseForm contains the list of choices to display. If not specified, then the ChooseOne field assumes the second field (the field following the primary key) in the choices table is the field containing the choices to display.
The selected choice’s corresponding value is an invisible “link” referencing the named employee in the “Employees” table (not the actual name). Thus, an employee can change their name in the “Employees” table (e.g., if getting married), and you won’t have to make any changes in the “Departments” table.
GroupField
The GroupField is a visual means of specifying a composite index. The GroupField contains other FormFields. That is, the purpose of a GroupField is sorting (composite indexing) of a group of fields together. The search order is by the first subfield, then the second subfield, etc.
For example, you could have a GroupField called “Name”, containing the Text fields, “First”, “MI” (middle initial) and “Last”. If the GroupField’s property, sorted, is “true”, then the GroupField, “Name” would be sorted first by “First”, then by the “MI”, then by “Last” name.
Note: If you are using SQL database, you can only nest subfields one level deep. When the DreamBeans® middleware generates SQL code for your database, it will define a column for each subfield and a composite index key (comprising each of the subfields).
Multidimensional arrays
GroupField is a very easy and powerful means of creating multidimensional arrays. All you have to do is put Link fields into a GroupField with the GroupField’s property, field_value_unique, set to “true”. Each Link field becomes an index for one of the array dimensions.
For example, consider a two dimensional spreadsheet where you wish to itemize quarterly expenses and calculate totals for each quarter. First you would create the classes Expense and Quarter by extending the BaseForm class. The Expense form would contain a list of expenses like electricity, gas, rent, wages, etc. The Quarter form would have three fields: 1) Integer field, named “Quarter”, with field_min_value set to 1 and field_max_value set to 4. 2) Integer field, named “Year”, with field_min_value of 2000 and field_max_value of 3000. 3) FloatingPoint field, named “Total”.
Next create a class called QuarterlyExpense, with a “unique” GroupField containing two Link fields named, “Quarter” and “Expense”. A second field in QuarterlyExpense would be a FloatingPoint field, named “ExpenseItem” with a field_default_value of 0.
A GroupForm, “Expense By Quarter” would contain the subforms Expense, Quarter and QuarterlyExpense. You would add a ResultTable to this GroupForm as well (setting all of Quarter’s fields to not be visible in the ResultTable). The ResultTable would display a two dimensional array of expense by each quarter.
FieldPanel
FieldPanel
When you add data fields to a BaseForm, they are implicitly added to a FieldPanel contained within that BaseForm. The default FieldPanel has a default layout of “VERTICAL”, which means each data field you add will be added below the previous field.
Sometimes you may want arrange data fields horizontally next to each other. To make this possible, you can add a FieldPanel to a BaseForm and set the FieldPanel’s layout property to “HORIZONTAL”. Then you can add data fields to that panel.
You can nest FieldPanels to create as fancy a layout as you might desire.
Calc Fields
Calc fields have properties that define the operands. If the “operand_type” property is “FIELD”, then the “operand” property is interpreted as the name of the field. Otherwise, “operand_type” is “CONSTANT” and the “operand” property is treated as a constant value to be part of a calculation. If the “field_common_column” property is not blank, then the specified field is set to the calculated value.
The simplest calc field is CopyField. CopyField inherits from BasicText. It copies values from one field to another field (where the two fields are not common columns).
All the other calc fields inherit from FloatingPoint.
The Translation field converts string values to floating point values for use in other calculations. For example, you might want translate “HIGH” to 100, “MEDIUM” to 50, etc. The property “calculation” contains a comma separated list of string:value pairs. For example, “high:100, medium:50, low: 10, none:0”
ArithmeticField has two properties, “operand_one” and “operand_two”. It performs the operation specified in its “calculation” property (“+”, “-“, “*”, “/” or “SQRT”).
StatField has the property, “stat_column_name”, which specifies the column (field) to use in a statistical calculation. The “calculation” property specifies the type of statistical calculation (“SUM”, “MIN”, “MAX”, “COUNT”, “SUM OF PRODUCTS”, “AVG” and “STD”). “SUM OF PRODUCTS” is a common operation in probability and statistical calculations, where one column in a row is multiplied times another column and the product summed across all rows. This requires two columns, which are specified as comma separated field names in the “stat_column_name” property.
The IfField provides an if-then-else construct. The IfField bean performs a conditional calculation (“=”, “<>”, “<”, “<=”, “>” and “>=”). You can add one or two other calc fields to this field. If the condition evaluates to true, then the first subcalc field is executed. If a second subcalc field is present and the condition evaluated to false, the second subcalc field is executed.
The GroupCalcField is a container of other calc fields.You can add a GroupCalcField to an IfField to conditionally execute a group of calculations.