Skip to end of metadata
Go to start of metadata

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.core.web.struts.form.KualiTransactionalDocumentFormBase or a descendant class, and typically, our form classes will go into the package org.kuali.module.{our module}.struts.form. 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
  • discoverDocumentTypeName() - a method which returns the KEW document type name for the given encapsulated document
  • formatReversalDate() - a (perhaps misplaced?) method which formats an accounting document's reversal date
  • 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

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.module.financial.web.struts.form.AdvanceDepositForm has a method, getAdvanceDepositDocument(), which returns the document encapsulated by the form as an org.kuali.module.financial.document.AdvanceDepositDocument object.

The children of KualiTransactionalDocumentFormBase

Form classes follow the document hierarchy, creating what has been termed "parallel hierarchies." For instance, org.kuali.module.financial.document.AdvanceDepositDocument extends org.kuali.kfs.document.AccountingDocumentBase, which in turn extends org.kuali.kfs.document.GeneralLedgerPostingDocumentBase and hey, what do you know, that happens to extend org.kuali.kfs.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.struts.form.KualiAccountingDocumentFormBase, which in turn skips two generations and extends KualiTransactionalDocumentFormBase. In short, it is important that our Form class hierarchy (and our Action class hierarchy) follows the document hierarchy to come extent.

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.module.financial.bo.AdvanceDepositDetail objects which it calls "advanceDeposits". Here's the getter and setter from AdvanceDepositDocument:

From org.kuali.module.financial.document.AdvanceDepositDocument (comments removed)

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

Form org.kuali.module.financial.struts.form.AdvanceDepositForm (comments removed)

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.

Next

Unable to render {include} The included page could not be found.
  • No labels