Scout/HowTo/3.9/Showing forms on an AbstractPage

The Scout documentation has been moved to https://eclipsescout.github.io/.

This how-to describes how to show forms on an AbstractPage.

Introduction

The how-to Open a Form in a View explains how a form can be shown in a view. This how-to takes things a bit further by showing you how to dynamically creating and destroying the forms when selecting a certain page in your outline.

Steps

Building a page with forms

• Create an empty page extending AbstractPage:
• Define the pages icon, its name and set its Leaf property to true:

 @Override
protected String getConfiguredIconId() {
  return org.eclipse.minicrm.shared.Icons.Forms;
}
@Override
protected String getConfiguredTitle() {
  return TEXTS.get("FormPage");
}
@Override
protected boolean getConfiguredLeaf() {
  return true;
}

• Add a member for each form to be shown:

 FirstForm firstForm;
SecondForm secondForm;
ThirdForm thirdForm;

• Override execPageActivated() to create the forms and display them. Use setDisplayViewId() to define in which view the form shall be placed:

 @Override
protected void execPageActivated() throws ProcessingException {
  firstForm = new FirstForm();
  firstForm.setDisplayHint(IForm.DISPLAY_HINT_VIEW);
  firstForm.setDisplayViewId(IForm.VIEW_ID_PAGE_DETAIL);
  firstForm.setEnabledGranted(false); // add this line, if you want the form to be read-only
  firstForm.startModify();

  secondForm = new SecondForm();
  secondForm.setDisplayHint(IForm.DISPLAY_HINT_VIEW);
  secondForm.setDisplayViewId(IForm.VIEW_ID_E);
  secondForm.startModify();

  thirdForm = new ThirdForm();
  thirdForm.setDisplayHint(IForm.DISPLAY_HINT_VIEW);
  thirdForm.setDisplayViewId(IForm.VIEW_ID_PAGE_SEARCH);
  thirdForm.startModify();
}

• Override execPageDeactivated() to clean up when the user leaves the page:

 @Override
protected void execPageDeactivated() throws ProcessingException {
  if (firstForm != null) {
    firstForm.doClose();
    firstForm = null;
  }
  if (secondForm != null) {
    secondForm.doClose();
    secondForm = null;
  }
  if (thirdForm != null) {
    thirdForm.doClose();
    thirdForm = null;
  }

  // this is a hack to make sure the forms are correctly displayed when changing between form-pages without changing to a table-page first
  // this is no longer needed with Scout 3.9.0 M4 (Kepler Milestone 4)
  try {
    Thread.sleep(500);
  }
  catch (InterruptedException e) {
  }
}

The results will look something like this:

Refreshing the forms

If you want to forward the page refresh (F5) to the forms on the page, you need to override the execPageDataLoaded() method:

 @Override
protected void execPageDataLoaded() throws ProcessingException {
  if (firstForm != null) {
    firstForm.refresh();
  }
  if (secondForm != null) {
    secondForm.refresh();
  }
  if (thirdForm != null) {
    thirdForm.refresh();
  }
}

Of course, your forms need to implement the refresh() method. Ideally, this method contains the code, which is usually in the ModifyHandler.execLoad() method:

@FormData(value = FirstFormData.class, sdkCommand = SdkCommand.CREATE)
public class FirstForm extends AbstractForm {

  public FirstForm() throws ProcessingException {
    super();
  }
 
  ... rest of form content ...

  public void refresh() throws ProcessingException {
   // code that was in ModifyHandler.execLoad()
   IFirstService service = SERVICES.getService(IFirstService.class);
   FirstFormData formData = new FirstFormData();
   exportFormData(formData);
   formData = service.load(formData);
   importFormData(formData);
   setEnabledPermission(new UpdateFirstPermission());
 }
 
 public class ModifyHandler extends AbstractFormHandler {

   @Override
   public void execLoad() throws ProcessingException {
     refresh();
   }

   @Override
   public void execStore() throws ProcessingException {
     IFirstService service = SERVICES.getService(IFirstService.class);
     FirstFormData formData = new FirstFormData();
     exportFormData(formData);
     formData = service.store(formData);
   }
 }
}

Note: There is currently a bug in the implementation of UTCDateField which will cause an exception when refreshing a form containing an UTCDateField (Bug 399585 has been opened)