Using Panel Grid Layout in Oracle ADF Faces UI for perfect alignment

While working on a number of client projects recently, I’ve discovered the Panel Grid Layout in ADF is the perfect choice for laying out screens when there are complex data items of different types. Whilst the Panel Form Layout is great for screens with only a few simple items, I’ve found it doesn’t work quite so well in terms of layout and alignment, with more complicated UIs.

Read my blog post to find out when the Panel Grid Layout is the perfect choice!

Prerequisites

  • Download the the application ADFAligningFields.zip to have a better understanding of the page designs described below in design time and runtime
  • Download and install Oracle JDeveloper 12.2.1 as the application is developed using this version of the Oracle ADF framework.
  • Run the database script ADFAligningFields.sql which is part of the application downloaded.
  • Modify the database connection details in the Model project to the appropriate database that the application is going to connect and run the database script against it.

Application Content

ADFAligningFields is a standard ADF application that contains a Model and a ViewController project.

Model

The model contains EmpVO and EmpEO as the view and entity objects respectively which are bound to the pages. All the other view objects like StaticCountry, StaticCity, StaticSex, StreetName are helper view objects. They are used to configure the list of values of the attributes in the EmpVO view object. The EmpVO is exposed in the application module ie., AppModule.

ViewController

The ViewController contains three different pages that are used to show the UI in this blog.

  • TestPageSameType.jspx page shows the fields that are mostly Input Text and Date.
  • TestPageDistinctTypes.jspx page shows the fields that are Input Text, Date and Select One Choice. It highlights how a mix of these fields causes misalignment.
  • TestPagePanelGridFix.jspx page shows the fields that are Input Text, Date and Select One Choice. It also shows how the solution described in this blog fixes the alignment issues.

The simple case - Panel Form Layout works well

When it comes to placing fields in the ADF Faces UI in a simple form, Panel Form Layout is one of the basic UI containers that comes to mind.
If the components are as simple as Date fields and Input Text fields, a 2 column Panel Form Layout provides a nice, clean layout, as shown below. Refer TestPageSameType.jspx in the application to see the page layout.

If the same UI is shown with all the fields marked as read-only or disabled, Panel Form Layout does a good job in aligning the fields and mapping the labels to the content. This can be achieved by marking all the fields as read-only or disabled in the TestPageSameType.jspx in the application.

When all the fields are editable

When all the fields are read only

When all the fields are disabled

Note: In the three screenshots above you can see the fields and labels are nicely aligned, providing a clean layout.

Where it get’s complicated - Panel Form Layout is not such a good option

In situations where the UI needs to render with mixed fields including Select One Choice (i.e. drop down lists), Date and Input Text fields, the alignment is not as clean, when using the Panel Form Layout.

You can see in the screenshots below, ADF Faces takes up some vertical space for the Select One Choice fields, making the UI look and feel a bit clunky. Refer TestPageDistinctTypes.jspx in the application to see the page layout.

Using the layout provided by the Panel Form Layout, some of the fields are automatically clubbed together, which doesn’t make sense for the end-user and also doesn’t look good from a UI perspective.

If the same UI is shown as a set of read-only or disabled fields, the result is not very good either - the Select One Choice fields are not aligned with their respective labels. For example in the screenshot below, Country, Street Name, City and Sex show alignment issues when compared to other fields. This can be achieved by marking all the fields as read-only or disabled in the TestPageDistinctTypes.jspx in the application.

When all the fields are editable Note: In the screenshot above, there is a gap between Sex and Age but no gap between *City and Country or City and Street Name*

When all the fields are read only Note: In the screenshot above, Sex, City, Country and Street Name are misaligned with their own labels. While all other components are aligned with their labels.

When all the fields are disabled

Note: In the screenshot above, Street No., Street Name, City and Country seem to be grouped together while Date of Joining seems to be separated.

A Better Option - Use Panel Grid Layout container to fix the alignments

In my experience, I have found the Panel Grid Layout is a much better option, in these more complex scenarios – let’s take a look …. Refer TestPagePanelGridFix.jspx in the application to see the page layout.

Firstly, we drag a Panel Grid Layout container in the jspx page and embed all the fields in the Grid Cells. It is important to remember that when using the Panel Grid Layout the labels and the editable fields need to be handled separately. The label of the editable component goes into one cell and the actual component goes into a separate, adjacent cell.

As the fields require a 2 column layout with 5 rows, we drag the Panel Grid Layout and configure a 4 column layout where the first 2 columns identify the first field's label and component, the next 2 columns identify the second field's label and component.

Next, we need to identify the percentage of width that each column requires. This completely depends on the length of the label text and/or the editable component width. In our example below, I have identified a percentage width of 5%, 10%, 5% and 25% respectively for the 4 columns. This takes a bit of guess-work and is often best identified by trial and error. I’ve found the percentages suggested above fit the example in this use-case.

After we've configured the Grid columns, the Panel Grid Layout component, as viewed in the JDeveloper Design time preview, should look something like this - 5 rows and 4 columns.

For each Grid Row, the first and third Grid Cells will be used for component labels, and the second and fourth Grid Cells will be used for the components themselves. Adding the label is pretty straight forward, we just drag the component from the data control and add it as an ADF Label, from the options listed.

After we've added the labels, we set the horizontal alignment of the Grid Cells to align at the end, so that all the labels are right aligned.

Similarly, now we drag the actual components, into the second and fourth Grid Cells. The components need to be dragged without the Label, as shown below.

To nicely align the objects, we set the alignment for the components to be at the start. This ensures the alignment will be consistent for all fields in each row.

Additionally, for the Select One Choice (drop-down), and Date components, the “Simple“ property should be marked as 'true'. Setting this property ensures that ADF removes the label associated with the component, while showing the component. We no longer require the label explictly for the component, as we have already added it, manually, in the previous step.

When we go ahead and run the page, we see that by using the Panel Grid Layout, the Grid Cells have fixed all the alignment issues that we encountered before, when we were using Panel Form Layout. If the same page is shown with read-only or disabled components, the page still has a good look and feel, as you can see below. This can be achieved by marking all the input components as read-only or disabled in the TestPagePanelGridFix.jspx in the application.

When all the fields are editable

When all the fields are read only

When all the fields are disabled

The screenshot below provides an overview of the Grid Rows arrangement, as shown in the Structure window of Oracle JDeveloper 12.2.1. With so many grid rows and cells, it can often be difficult to identify a specific component like "First Name", in the jspx page. This window helps in tracing the components quickly.

Summary

In summary, the Panel Grid Layout can be used for any type of editable components including Select One Choice (drop down) fields, Input List of Values, Combo Box, Input Texts, Images, Links etc., as the rendering of the components is governed by the Panel Grid, which is consistent throughout the Grid Rows and Grid Cells.

This begs the question, when would we use the Panel Form Layout instead of a Panel Group Layout or vice versa?

Use a Panel Grid Layout when
  • There is a mixed combination of Select One Choice fields (or any other fields that could cause distortion) and Input Text / Date fields
  • There are only Select One Choice fields but the UI has to be shown in Read-Only mode. (Remember that Select One Choice items do not align well in Read-Only mode.)
  • You have multiple Show Detail Items / Panel Headers in the same page and you need to have a consistent alignment throughout the page, across the Show Detail Items / Panel Headers.
Making the right decision

There is an advantage in using a Panel Form Layout - specifically, ADF automatically handles the design time layout and alignment for us with a simple drag and drop of the View Object attributes from data control. In this case, we have very little control over the layout, however,this approach is very fast, and therefore, doesn’t take much development time.

On the other hand, if we use a Panel Grid Layout, we have much more control and results in a higher quality UI and layout. However, it does cost more in development time, as the layout and alignment must be done manually.

All in all, I would recommend using the Panel Form Layout, for simple forms where the auto-layout generates reasonable UIs.

When you have many complex items and need control over the UI layout and alignment, the Panel Grid Layout gives you much more control and therefore, I find is the best choice when you are building more complicated forms.

Note: The screenshots provided in this post are based on ADF 12c Faces components and JDeveloper Studio Editor Version 12.2.1.0.0 and Google Chrome 51.0.2704.103 m

Kapil Kapani

Kapil Kapani is a leading Oracle ADF and FMW Consultant at Rubicon Red with experience working in major Government and Financial institutions based in Australia and abroad.

Subscribe to Oracle PaaS, Oracle Middleware and DevOps

Get the latest posts delivered right to your inbox.

or subscribe via RSS with Feedly!