Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Scout/Tutorial/3.7/Minicrm/Add a form to edit the data"

< Scout‎ | Tutorial‎ | 3.7
m (Update the company with the new values)
(Pass the primary key and reload page)
Line 201: Line 201:
 
== Pass the primary key and reload page ==  
 
== Pass the primary key and reload page ==  
  
If you open the generated ''EditCompanyMenu'' you see that there has been generated code inside a method ''execAction''. This code actually opens the form. What is missing here is the forwarding of the ''companyNr''. The ''companyNr'' is inside the table in the ''CompanyNrColumn'' in the row the user currently selected. To get that value simply rewrite the code like this:
+
If you open the generated ''EditCompanyMenu'' you see that code for the ''execAction'' method has been generated for you. This code opens the form.
 +
 
 +
What we're missing on the server side is the ''companyNr''. We need it in order to select the correct data.
 +
 
 +
The ''companyNr'' is available in the ''CompanyNrColumn'' of the table. We just need to find the value in said column for the selected row. Here's how:
  
 
<source lang="java">
 
<source lang="java">

Revision as of 11:16, 13 October 2010

Note.png
Scout Tutorial
This page belongs to the The Scout documentation has been moved to https://eclipsescout.github.io/.. It explains how to add a form to a table page such that you can edit the data on the database. You need to The Scout documentation has been moved to https://eclipsescout.github.io/. in order to continue.


We need to create a form containing various fields, we need to have a process service that allows us to select, insert, and update data on the database, and we need a context menu to call the form, possibly passing along an id (the primary key) to the form if we want to edit a particular row.

Create a form

We now build a form to add and edit companies. Expand the node client of your Scout project, scroll down to the node Forms, right click on it and select New Form...

Newform.jpg

As name for the form choose Company. As you can see on the New Form Wizard a form ID called CompanyNr will automatically be created. This ID is later needed to pass the primary key of the company you want to display the data for in the form.

Newformwizard.jpg

When you click Next, you'll see permissions and a process service will also be created for this form. We'll discuss these later.

InnerFormClasses.jpg

Click Finish to create the form.

When you now expand the tree below your CompanyForm you can see a MainBox. This is the mandatory root element for every form. Inside this MainBox you can now add fields as you wish by right clicking on it and choosing New Form Field.

Newformfield.jpg

On the New Form Field wizard you need to choose a template for the field. First, we want to add a field for the company's name, therefore choose String Field. Click Next and enter the name of the field ("Name") and then click Finish.

Fieldtemplates.jpg

Now proceed in the same way and add a field for the Short Name.

You should already have an Ok button (OK Button template) and a Cancel button (Cancel Button template). The two buttons don't need a name since they'll get appropriate names from their template.

Note.png
Ampersand in Field Names
Button names usually contain an ampersand. This is used for a keyboard shortcut. Thus, &Ok means that Alt-O will activate the Ok button.


Modify the form's ProcessService

Go to the server node of your Scout project, open the node Process Service and expand it. Double click on the entry CompanyProcessService in order to open it.

public class CompanyProcessService extends AbstractService implements ICompanyProcessService{
 
  public CompanyFormData prepareCreate(CompanyFormData formData) throws ProcessingException{
    if(!ACCESS.check(new CreateCompanyPermission())){
      throw new VetoException(Texts.get("AuthorizationFailed"));
    }
    // TODO business logic here
    return formData;
  }
 
  public CompanyFormData create(CompanyFormData formData) throws ProcessingException{
    if(!ACCESS.check(new CreateCompanyPermission())){
      throw new VetoException(Texts.get("AuthorizationFailed"));
    }
    // TODO business logic here
    return formData;
  }
 
  public CompanyFormData load(CompanyFormData formData) throws ProcessingException{
    if(!ACCESS.check(new ReadCompanyPermission())){
      throw new VetoException(Texts.get("AuthorizationFailed"));
    }
    // TODO business logic here
    return formData;
  }
 
  public CompanyFormData store(CompanyFormData formData) throws ProcessingException{
    if(!ACCESS.check(new UpdateCompanyPermission())){
      throw new VetoException(Texts.get("AuthorizationFailed"));
    }
    // TODO business logic here
    return formData;
  }
}

As you can see, the generated process service contains four methods. If you check from where they are called (Ctrl+Shift+G), you will notice that the callers are two form handlers: a NewHandler and a ModifyHandler.

These two handlers are inner classes of the company form. You can see them in the Scout SDK as well: expand the CompanyForm node and you'll find the Handlers node right there.

Form handlers are used to start a form in a particular mode. For instance, if you want to use your form to add a new company, you want to bring it up empty. On the other hand, if you want to use it to edit an already existing company, you want to bring it up already containing the company's values.

Generally speaking, we'll use execLoad and execStore for every handler. Here's how our CompanyProcessService methods are called:

Form Handler Handler Method Process Server Method
ModifyHandler execLoad load
execStore store
NewHandler execLoad prepareCreate
execStore create


A FormHandler's methods are are executed in a specified order. With that, you can control a form's processing at different moments or with the form in different state:

  1. execLoad: Loads form state before it is made visible
  2. execPostLoad: After the form is loaded, changes to fields inside this method result in marking the form as changed and thus requiring a save.
  3. execCheckFields: Executed before execValidate but after AbstractForm.execCheckFields(). Returning false cancels processing.
  4. execValidate: Executed after AbstractForm.execValidate().
  5. execStore: After this method call, the form is in the unchanged state with no save required. Executed before AbstractForm.execStored().
  6. execDiscard
  7. execFinally

Please consult the javadoc of these methods for details.

Furthermore you can see in the source code generated that Permissions are checked. These checks exist on both the client and on the server side. On the client side, these are simple convenience checks to prevent the user from changing fields if they cannot be saved. We need similar checks on the server side to handle service calls from outside the client. The process service could potentially be used by an interface, for example.

Load the data for the form

To begin with, we want to edit an existing company.

Go to the load method of the CompanyProcessService and select the data to be displayed using the SQL method SQL.selectInto.

    SQL.selectInto("" +
            "SELECT SHORT_NAME, " +
            "       NAME " +
            "FROM   COMPANY " +
            "WHERE  COMPANY_NR = :companyNr " +
            "INTO   :shortName," +
            "       :name"
        , formData);

The INTO clause of your SQL statement will refer to form fields by prefixing them with a colon. These are the bind variables. A field called ShortName will be referred to as :shortName. Don't forget the naming conventions: downcase the first character.

If your form data is up to date, you can use content assistance after the colon: press CTRL-Space to complete on the fields. If some (or all) of the fields are missing, you need to update your form data.

Updateformdata.jpg

Note.png
Update Form Data
Every form comes with a form data object which will be used to communicate between client and server. Its code can be created automatically by using the context menu on the form itself. Right click on CompanyForm and pick Update Form Data.


In the WHERE clause you need to specify the company's primary key. This is contained in the variable companyNr. Remember, when we created the form this id was created for us as well. You can find it in the Variables section of the CompanyForm.

From Form to FormData to Form

If you want to load data from a service, you need to export data from the form into the form data (the primary key in particular). Once the call returns you need to import the data from the form data back into the form.

Forms provide an import and export method, respectively. Therefore loading data into and storing them from a form into a form data is just a single method call. This has already been automatically added by Scout in the FormHandler methods:

    @Override
    public void execLoad() throws ProcessingException{
      ICompanyProcessService service = SERVICES.getService(ICompanyProcessService.class);
      CompanyFormData formData = new CompanyFormData();
      exportFormData(formData);
      formData = service.load(formData);
      importFormData(formData);
      setEnabledPermission(new UpdateCompanyPermission());
    }

Start the Form

The last thing to do is to actually call the form and to open it. In order to do that we need a menu on the CompanyTablePage. Go to your CompanyTablePage expand it, go to the table, click on the Menu node, right click and choose New Menu....

Newmenu.jpg

Enter the name of the menu: Edit Company... (and add a new translated text). Specify CompanyForm as the Form to start and click Finish.

Editcompanymenu.jpg

Note.png
Use of Ellipsis
A menu name should end with an ellipsis (three dots: ...). Since the text is also proposed as the key, you will have to delete them.


New Scout Text Entry With Ellipsis.jpg

Update the company with the new values

Now we need to edit the store method in the CompanyProcessService and add the sql statement for the update.

      @Override
      public void store(CompanyFormData formData)  throws ProcessingException { 
       if(!ACCESS.check(new UpdateCompanyPermission())){
          throw new VetoException(Texts.get("AuthorizationFailed"));
       }
 
       SQL.update(
           "UPDATE COMPANY SET" +
           "       SHORT_NAME = :shortName, " +
           "       NAME = :name " +
           "WHERE  COMPANY_NR = :companyNr", formData);
 
       return formData;
      }

Pass the primary key and reload page

If you open the generated EditCompanyMenu you see that code for the execAction method has been generated for you. This code opens the form.

What we're missing on the server side is the companyNr. We need it in order to select the correct data.

The companyNr is available in the CompanyNrColumn of the table. We just need to find the value in said column for the selected row. Here's how:

      @Override
      public void execAction()  throws ProcessingException {
        CompanyForm form = new CompanyForm();
        form.setCompanyNr(getCompanyNrColumn().getSelectedValue());
        form.startModify();
        form.waitFor();
 
        if (form.isFormStored()){
          reloadPage();
        }
      }

The method startModify starts the modify handler. The waitFor interrupts the execution at this point, until the form is closed again. With isFormStored we check wether the user has closed the form by pressing the OK-Button (form values are stored) or by pressing the Cancel-Button (form values are discarded). In the first case we reload the current table the see the changes instantly.

Back to the top