Project Management Tutorial - Adding Entity Attributes

From jVantage

Contents 1 Introduction 2 Auto-Insert Fields 2.1 Development Mode 3 Entering the Application 4 Entering Data 5 Summary

Introduction

In the last section we started building a project management application by defining an application top-level record, and then creating a PM2_COMPANY (Company) table. The company table is a database Singleton that will serve as the topmost entity in the application. Because the entity is defined as a singleton, jVantage will only allow one instance of a Company to be created. If we had decided that our project management tool should support multiple companies we could have easily done so by not declaring the entity as a singleton. Since we have, the Company can servce as a natural entry point into our project management application.

Now that we have a company entity we must specify additional attributes and behaviors to make it useful. We need fields that complete the picture in terms of data such as name, description, phone number and so on. As you'll see during this section of the tutorial, adding these attributes is a trivial exercise. Remember, when we define fields or attributes for an entity (using data dictionary types), jVantage automatically provides the behaviors needed for it to be functional immediately. The amount of versatility and control the jVantage allows over each field is quite broad. We can specify that the field is only visible to members of one group, editable by members of another group and completely invisible to a third group, all without touching a single line of code or even restarting the application. Even stipulate that some fields should be disabled based on the value users enter into other fields on the same form all from within the jVantage development environment without writing any programming code and without restarting the application. Let's get started.

Auto-Insert Fields

First, we need to navigate to the table definition view within the application we created. Do this by following this navigation path:

Root Context > pm2 > PM2_COMPANY

This takes you to the following screen.

Most of the fields on this page were explained in the previous section. The most significant thing to notice about this page is the Table Fields list. When we submitted the table form, jVantage created a table in the underlying database. Since we have not yet specified any attributes for the table, the only field we have is the ID, which is the primary key of the table. All tables created with jVantage contain this field (or column). For the most part this column can be ignored during development although there are certain places where this ID can be used directly.

To make the company and city entities useful we will add the following fields:

• Name
• Description
• Address
• City
• State
• Zip Code
• Phone
• Photo

Probably 95% of all entities use the Name attribute. For this reason, jVantage supports Auto-Insert fields, which are simply fields that are commonly used and can, therefore, be added with a single mouse click. This means that we can add and name and description to our company entity simply by selecting them from the auto field insert menu.

This results in a new list of fields as shown below. Even though there are only two simple fields associated with our company entity, we already have a functioning application. We can go into the application and insert the name and description for the company right now. First, we should apply our changes. Because jVantage utilizes rather sophisticated caching to optimize performance, we must specifically tell jVantage to reload the latest changes so that they can take effect. This is could be comapred to compiling a typical program, except that it only takes a few seconds. To do so, click on the icon in the upper right corner (shown in the screenshot within the red elipse). Applying changes usually takes about five to ten seconds.

Development Mode

One more thing before we enter the application. Remember that from a user perspective, applications created with jVantage behave like all other applications, meaning end-users have no way of knowing that the application they are using was created using jVantage. This, of course, is what we want. However, as developers we must be able to move from the development environment into the application itself, and back very easily. By default, when we enter an application we're building, jVantage provides no way to get back to the development environment other than navigating back through the Root Context. To solve this jVantage supports a special operating mode called Development Mode. When in Development Mode, jVantage provides a special hyperlink that can be used from within the application to navigate back to the development environment. The link is only visible to the developer who is in Development Mode (but not necessarily all developers - it is session oriented). Regardless of how many end-users may be logged into an application, they will not see the icon, however, any number of developers (who have access to jVantage itself) can simultaneously and independently enter and exit Development Mode.

Development Mode also causes other differences in the way jVantage behaves (but again, only for the individual developers who have selected it). For instance, jVantage allows applications to be stopped and restarted from the Root Context view. When applications are stopped they cannot be used. However, jVantage allows developers in Development Mode to continue accessing the application. This is a powerful administrative and debugging feature because it allows developers and administrators to access and use applications without the worry of having end-users online.

Entering the Application

There are a few different ways to enter an application. One is to select View Content from the Relationship Menu of the Table View. Another is to navigate to the application development view and click on the home URL.

Root Context > pm2 > Home URL

Clicking on View Content takes us into the application. The application is very simple at this point.

The look of the application leaves a little to be desired to be sure, but the interesting thing to note is that it works. First, notice that there is a Modify this Company button displayed in the middle of the screen and also a Keyword search panel at the bottom. The interface says a little bit about the view that we are looking at in the title; Viewing Company. Finally, there is the actual data that is associated with the entity itself; ID, name and description.

In a moment will click on the Modify this Company button and insert the name and description of the company. Before we do, there are at least a couple things that should be pointed out about the interface. In the upper right corner below the help and logout icons, is a set of numbers. These numbers are useful for development purposes.

Web 

The amount of time it took for jVantage to process and respond to the request to view the page from the moment the request was received within the web container to the time that the response was returned from the web container.

EJB 

The amount of time it took for jVantage to process and respond to the request to view the page from the moment the request was received within the EJB container to the time that the response was returned from the EJB container.

SID 

The Session ID of the logged in user.

This diagram depicts the Web and EJB times graphically. These numbers are called Performance Measures, and they can be useful for performance tuning your applications. Of course, they can and should be disabled in production environments.

The session ID is a unique number that is assigned to each new user that logs into any jVantage application. This number is one of the things that sets jVantage apart from other development tools. To demonstrate this, we will go ahead and enter and name and description for our company. Then we will go into the jVantage development environment and view the session information to see how the activity is reflected within the jVantage kernel. Next, we will use this number to examine the log files and see how that activity is recorded.

Entering Data

When the Modify this Company button is pressed, the following form is displayed. Notice of the ID name and description fields are present with input controls that are appropriate for the corresponding data.

After the form is populated and the submit button is pressed, your are returned to the company view page as shown below. Notice that a keyword search panel is also displayed, which includes a pulldown list that allows you to narrow the scope of your searches. Since we only have one entity type in our application, the list shows only two options; All and Companies. All indicates that the keyword search should be carried out against all entity types in the application. As we add new entities to our application, this list will grow to include an entry for each one. Another point that is worth mentioning is that searching can be a sticky issue in any application due to data access security. If, for instance, some information in the application is of a sensitive nature, it can be a difficult problem to ensure that the user executing a search is only presented with information for which he or she has been granted access. As we'll find out later in this tutorial, jVantage provides an interactive and extremely simple mechanism for specifying what users should have access to what data. jVantage leverages this information to filter all search results to ensure that users are only allowed to see data that they are supposed to see. Granting and revoking privileges to data can be done on-the-fly from within the development environment.

Having said this, since we have not yet specified any explicit security for our application, jVantage will allow us to execute a search that will be carried out against the full body of data in our application. Now that we have added our company we can execute a search for a part of the name of the company and see the jVantage already supports built-in searching capabilities for our application.

Given the search criteria above, pressing the Go button results in the following screen being displayed. Later in this tutorial when we cover access control you may want to experiment with changing access privileges and then refreshing screens from within the application to see how these changes immediately take effect. These changes are reflected in search results, but also directly on user interfaces. For instance, if we went into the access control system and revoked a given user's visibility to the name field, we could immediately refresh the screen and the name field would disappear (if we logged in as that user). If we revoked the modify privilege for the company entity, the modify button would disappear. The Access Control capabilities supported by jVantage are very fine-grained, extremely powerful and dynamic.

Click on the Acme Construction Company link from the list we would be returned to the company view.

Summary

In this section we added a couple common attributes to the company entity, name and description. We saw the jVantage automatically provided edit and search capabilitieswith absolutely no additional effort. There was also a brief description of the performance measures that allow developers to fine tune their applications.

In the next section, we'll add some custom field types and experiment with form validation and mouse over help.

Project Management Tutorial - Adding Custom Entity Attributes