Transactional Document Forms

The best way to conceptualize Struts is by understanding that it is a "model-view-controller" paradigm: it divides the data on a page, the actions a page takes, and how the page looks to the viewer into three separate chunks. Forms represent the "model" portion of the paradigm: they are the data on a page.

What kind of data are we trying to show on a transactional document page? Typically, the transactional document itself. Let's take a look, then, at how Form classes for transactional documents wrap the form.

Extending KualiTransactionalDocumentFormBase

The forms we create for specific transactional documents should extend the succinctly named org.kuali.kfs.kns.web.struts.form.KualiTransactionalDocumentFormBase or a descendant class, and typically, our form classes will go into the package org.kuali.kfs.module.<modulename>.document.web.struts. KualiTransactionalDocumentFormBase extends a long hierarchy of form classes which, thankfully, we almost never need to concern ourselves with - all of that stuff is typically populated by the data dictionary or works on its own. That means that KualiTransactionalDocumentFormBase declares only these methods:

• a default no argument constructor which sets up the document action flags
• getTransactionalDocument() - a method that returns the encapsulated document as a transactional document
• getForcedReadOnlyFields() - returns a Map with field names as keys of fields that are forced to be read only during the current rendering cycle
• setForcedReadOnlyFields() - sets that Map of read only fields
• reset() - to reset the check boxes

A note about getTransactionalDocument(): most classes which extend KualiTransactionalDocumentFormBase declare a method to cast the document as the specific document related to the given form. For instance, org.kuali.kfs.fp.document.web.struts.AdvanceDepositForm has a method, getAdvanceDepositDocument(), which returns the document encapsulated by the form as an org.kuali.kfs.fp.document.AdvanceDepositDocument object.

The children of KualiTransactionalDocumentFormBase

Form classes follow the document hierarchy, creating what has been termed "parallel hierarchies." For instance, org.kuali.kfs.fp.document.AdvanceDepositDocument extends CashReceiptFamilyBase which extends org.kuali.kfs.sys.document.AccountingDocumentBase, which in turn extends org.kuali.kfs.sys.document.GeneralLedgerPostingDocumentBase and hey, what do you know, that happens to extend org.kuali.kfs.sys.document.LedgerPostingDocumentBase, and that, finally, extends TransactionalDocumentBase. Forms also have hierarchies, and they often follow at least similar parentage as the document hierarchy. In our example, AdvanceDepositForm extends org.kuali.kfs.sys.web.struts.KualiAccountingDocumentFormBase, extends FinancialSystemTransactionalDocumentFormBase that extends KualiTransactionalDocumentFormBase. In short, it is important that our Form class hierarchy (and our Action class hierarchy) follows the document hierarchy to some extent.

See the hierarchy here 
 

Creating new slots for adding to collections

For the most part, Form classes in KFS are fairly thin. There is one special thing that must be done in the Form: for each collection in our document, we need to have the Form create a "new slot" for that collection.

For instance, AdvanceDepositDocument declares a List of org.kuali.kfs.fp.businessobject.AdvanceDepositDetail objects which it calls "advanceDeposits". Here's the getter and setter from AdvanceDepositDocument:

public List<AdvanceDepositDetail> getAdvanceDeposits() {
   return advanceDeposits;
 }

 public void setAdvanceDeposits(List<AdvanceDepositDetail> advanceDeposits) {
   this.advanceDeposits = advanceDeposits;
 }

The form then needs to declare some property called "newAdvanceDeposit". AdvanceDepositForm does so:

private AdvanceDepositDetail newAdvanceDeposit;

 public AdvanceDepositDetail getNewAdvanceDeposit() {
   return newAdvanceDeposit;
 }

  public void setNewAdvanceDeposit(AdvanceDepositDetail newAdvanceDeposit) {
    this.newAdvanceDeposit = newAdvanceDeposit;
  }

Then, when on lines in the JSP page where we need to read in the fields of a new advance deposit record, we simply refer them to property KualiForm.newAdvanceDeposit. If an "add" button is clicked, then the Action class should validate the new AdvanceDepositDetail and then move it from the form into the document itself.

What is getDefaultDocumentTypeName() ?

All transactional document forms should override this method so that framework will know the document type to be instantiated. Default constructor of KualiDocumentFormBase does a lot of initialization and the first step in the sequence is to instantiate a document which uses the document type name.

@Override
protected String getDefaultDocumentTypeName() {
        return "IB";
}

Next