Portofino tutorial part 2: The first application

Posted by Paolo Predonzani
on March 19, 2009

Following the installation, our next concern is how to get something useful out of Portofino. In part 2 of this tutorial we start building a very simple application for product management. It's only one class and one attribute and requires approximately 5 minutes to be completed.

Creating models with the upstairs and downstairs levels

How do you create an application in Portofino? This question can be answered from at least two perspectives: the philosophy and the mechanics.

The philosophy is simple: don't write code, write models.
Just like code, models describe what an application does and how it works. Just like code, models define the "stuff" applications are made of: forms, workflows, reports, permissions, etc. Just like code, models can be developed incrementally: you start with a small model and then you refine it or complement it with other models.
However, unlike code, models do all this in a more abstract, logical and compact way. Also, while a change in one part of code tends to break other parts, a model stays coherent despite changes in its parts.

The mechanics are also simple: Portofino provides an environment where you can create the models (the upstairs level) and another environment where you can run the models (the downstairs level). The upstairs level is for modelers who develop the application. The downstairs level is for the end users of the developed application.
Why such strange name as upstairs/downstairs? We've tried with the mode rigorous "metamodel", "model", "model's schema" and "model's data", but these terms seem to generate more confusion and glazed eyes than necessary. "Upstairs" and "downstairs" are just simpler and work better.

Now start Portofino and connect to it (if you followed part 1 of the tutorial it's probably at http://127.0.0.1:8080/ or http://127.0.0.1:8080/myapp). The almost empty page you see is the downstairs level. Now locate the "Go upstairs" link in the top-left corner of the page and click on it. The page that appears (and all pages you can navigate from there like "classes", "workflow actions", etc) are the upstairs level.

The following figure shows an empty downstairs level (on the left) and the upstairs level (on the right).
 

Generally you will want to keep the two levels open at the same time in different browser tabs. In this way any change you make upstairs can be immediately seen and tested downstairs. 

Creating the first class

As we want to build a product management app, our first class will be PRODUCT. Select the "Classes" tab, then click on "create".
 

A form appears asking to fill in some fields. Enter the following values:
 

Let's see the fields in more detail:

• Name is the name of the table that will store the objects of this class. Portofino will create the table for you so you don't have to worry about issuing DDL commands manually.
• Pretty name and Pretty plural are the singular and plural words that Portofino will use in the generated user interface downstairs to refer to this class.
• Order is the relative order of this class when displayed in a list of tabs.
• Tab is a flag. If checked, the class will appear as a tab downstairs, meaning that it is a main class.

For this tutorial you can safely ignore the values in the "advanced information" section. Click on Create. A new page will confirm the values you have just entered.

Creating the first attribute

At this point PRODUCT is created but is still not useful as it does not have any attributes. A product is at least characterized by its name, so we're going to create a text attribute for this purpose. Scroll down the page to a section containing three tabs, the first of which is named "Attributes":
 

The section displays no elements at the moment. Click on Add attribute. A new page appears asking you to select the type of attribute. You can choose between blob, boolean, date, decimal integer, relationship, text and workflow attributes. In this case choose "text attribute".
 

A text attribute is, at a database level, a VARCHAR column. Again, you don't have to worry about these details. All you have to do is to fill in the form to describe the new attribute, as shown here:
 

The fields in more detail:

• Class is pre-set to PRODUCT as that is the class that will own the new attribute.
• Name is the name of the column to be added to the table.
• Pretty name is the name to be used in the generated user interface downstairs.
• Required produces a NOT NULL constraint on the column.
• Length is the maximum length of the VARCHAR
• Multiline: whether the attribute is to be shown as a single line input field or as a multiline text area. Leave this flag unchecked.
• In name, In summary, and In details describe where the attribute should be display. Make sure they are all checked.
• You can ignore Order, Group name and Description for now.

Click on Create. Your first class and attribute are now complete and ready for testing.

Testing everything downstairs

Click on the "Go downstairs" link. The homepage is still empty but the tabs bar contains a new item: Products. Click on it.
You should now see a search page. There are no objects to search so let's create the first object. Click on the Create link. You should see a form like the one below:
 

You can recognize this as a form for the PRODUCT class you have just created. Enter a name and click Create.

Navigate around, familiarize with the user interface and with the five basic operations: Search, Create, Read, Update and Delete (sometimes referred to as SCRUD or simply CRUD).

Where to go from here

So far we've created one class and one text attribute. As a useful exercise you can add more attributes and explore other attribute types.
Here are a few suggestions:

• add an integer attribute to PRODUCT called units_sold
• add a decimal attribute to PRODUCT called revenue
• add a date attribute to PRODUCT called introduction_date
• add a boolean attribute to PRODUCT called in_stock 

For information, the basis of data modeling is covered in the following chapters of the reference manual:

• Classes
• Attributes

In Part 3 of this tutorial we'll discuss a more interesting model with more classes, a relationship and a graphical portlet.