Cookbook

A collection of examples for solving common tasks in Portofino.

Master/Detail Page

CRUD pages are based on a single database table. However, we can combine multiple pages to build a master/detail view. The "master" page acts as a filter for one or more "detail" pages, e.g., given a "project", you may browse the project's "work packages" as well as its "members".

The wizard creates these pages automatically when it detects certain patterns in the database. However, we can also create them by hand, and we'll see how here.

TODO

Cascading Selection Providers

Use case: State > Region > City (select the state, then the region among those inside the selected state, and so on). TODO

Historical Values With Selection Providers

Use case: birth_certificate --> city. Cities can change their name or be merged with other municipalities over time. When we look at an old birth certificate, we see the city as it was named then; but when we create a new birth certificate, we don't want to allow cities that no longer exist with that name at the present time.

TODO

Scheduling a Recurrent Task

Portofino includes the Quartz scheduler as an optional module.

TODO

Internationalization (aka I18n aka translating strings)

Server-side

TODO

Client-side with Angular

TODO

Microservices

Spring Boot

See https://github.com/ManyDesigns/Portofino/wiki/Spring-in-Portofino#spring-boot

Docker

TODO

Connecting through a JNDI DataSource

When running in a container such as Tomcat, Portofino can optionally connect to one or more databases configured in the container and exposed via JNDI. In that case, the DB connection is not specific to Portofino, and can be shared across multiple applications in the same container.

For a full reference please consult your container's documentation, e.g., Tomcat's.

For example, on Tomcat we may add

<Resource
    auth="Container"
    name="myDB"
    type="javax.sql.DataSource"
    driverClassName="org.postgresql.Driver"
    url="jdbc:postgresql:mydb"
    username="manydesigns"
    password="manydesigns"
    validationQuery="select 1"
/>

to the global context.xml file, and

<resource-ref>
    <description>My DB</description>
    <res-ref-name>myDB</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
</resource-ref>

to the Portofino application's web.xml file.

Assuming we've configured the container and application correctly, we can then set up the connection in Portofino using the wizard or writing the database.xml file directly like so:

<database databaseName="myDB">
    <jndiConnection jndiResource="java:comp/env/myDB"/>
    <schemas>
        <schema schemaName="public">
            <tables/>
            <annotations/>
        </schema>
    </schemas>
</database>

Important notice Portofino comes with a pre-configured hibernate.properties file to set up common properties. These include settings for the C3P0 connection pool that, unfortunately, doesn't work with JNDI. So, in case you want to connect via a JNDI datasource, you'll have to disable C3P0. To do so, please remove the C3P0-related properties from hibernate.properties. If your application needs to connect both to a JNDI datasource and a non-JNDI datasource where using C3P0 makes sense, you can still enable C3P0 on a per-database basis by providing a database-specific hibernate.properties file as shown in demo-tt.