Kuali Rice 2.3.5 KRAD Guide

There are two primary objectives of the Rice project:

Decisions for the Rice roadmap in addition to other work items are made by committees made up of representatives from the Kuali projects and institutions. These committees are the following:

Rice is comprised of a set of high-level modules that encompass the application functionality. Each of these modules contains a set of service interfaces and components (known as the API module), and a set of reference implementations (known as the implementation module). As of the Rice 2.0 release, these modules include:

Rice provides various options for how it can be deployed and integrated with other applications. Each of these deployment modes has advantages and disadvantages which require the needs of the application to be considered. The following is a brief description of each option:

Phase 0: In teams that are just forming or in the early phase of software development maturity, there is typically no UI guidance or review.  The design space is 100% open across developers and feature teams -- there is higher danger of meaningless inconsistencies (as opposed to intentional ones).  Developers don't disagree with each other's approaches, they simply aren't aware of them and, if they were, they'd be able to quickly converge to a common approach. This can create transfer of learning problems for users, and requires more developer time and more UX and QA time to find and fix UI problems and, ultimately, produces more code that has to be maintained.

Phase 1: In teams that have formed and taken the first steps to organize and manage their user interface efforts, there are common UI guidelines.  Today, in addition to the KRAD framework of controls, you can take a look at the Kuali Student project's User Interaction Model that documents the design components, design patterns, and style guide they will use.  This covers the type of common UI guidelines shown in the preceding figure, particularly helpful for where there is not yet a common UI control or template that developers can use.  These types of guidelines are also helpful for guiding when to use a particular control, or to make any customization choices available with that control – and are a recommended part of any project.  Kuali projects are free to use this as a model or create their own.

Phase 2: In the next step in growing a user interface design leadership process, teams create common UI templates / models, which enable "lighter-weight" efforts to design and code.  The UX effort is up-front and the benefit is inherited by all developers and feature teams afterward.  There are multi-disciplinary team members collaborating with developers, including business analysts and UX staff trained in UI design.  Consultations and collaboration across feature teams help span UI boundaries and ensure consistency.

Phase 3: In the final stage of maturation in user interface design management, users are engaged throughout the process with all feature teams, providing input through controlled user evaluations (rigorous research methodology, no pressure / biasing).  Managing UX is a habit at this point, part of the development culture.  Roles and rewards are in place, but there is momentum, the engine runs on its own steam, developers are championing the collaboration process.

KRAD aims to provide common UI controls, making it easier for developers to achieve consistency across an application, and across a team of developers working on different parts of an application.  Examples of the UI controls can be seen in the Rice Test Drive on the KRAD tab (log in with the user name equal to one of the following: admin, quickstart, admin1, admin2, supervisrsupervisor, or director - these provide varying levels of permissions). 

Rice 2.0 KRAD is the first version, so with each successive version, more UI aspects will move from a design guideline stage, where every developer has to read and apply a guideline, to a design template stage, that each developer can use and follow, and, ultimately, to a reusable UI control that each developer can use. 

There are two accessibility guidelines that apply to web applications:  WCAG 2.0 (Web Content Accessibility Guidelines) and ARIA (Accessible Rich Internet Applications).  WCAG 2.0 sets the baseline for web page content, while ARIA builds upon this baseline, to enable richer, more dynamic interaction with web content (developed with Ajax, HTML, JavaScript, and other technologies).

WCAG 2.0 is a mature standard, though it is new to many of us.  (If this content is familiar to you, you could jump directly to the ARIA section that follows this.) WCAG 2.0 is an update to WCAG 1.0, which was for static web pages only (could not require jScript).  Running without javascript is no longer a requirement.  WCAG 2.0 recognizes the web as an interactive space, not solely for passive reading.

There are 12 guidelines, organized under 4 principles: perceivable, operable, understandable, and robust.  For each of the 12 guidelines, there are testable success criteria, at each of these levels: A (must have), AA (should have), and AAA (may have).

Comprehensive information is available from the W3C here, about how to meet WCAG 2.0.

There are many free accessibility code checkers, and it is recommended that developers check their code with one of these tools.  For example, here is a short list of accessibility checkers you could consider:

A more comprehensive list of code-checkers is available at http://www.w3.org/WAI/ER/tools/complete.

The KRAD team did an extensive baseline evaluation to understand where the KNS and new KRAD framework stand on these criteria, and made several changes.  For example,

Several other bugs were fixed and changes made, including adding alt-text in many places. 

Our intent moving forward is to invest in making KRAD's UIF accessible, enabling applications built with the framework to inherit the benefit.  The first version of KRAD, in Rice 2.0, meets most of the A-level criteria, and many of the AA criteria, and in the areas where it does not meet, there are requirements listed for Rice 2.2 to bring us up to compliance. 

The good news is that applications can resolve most of the aspects where Rice 2.0 KRAD doesn't yet have the built-in accessibility support for you to inherit, and there will be additional support in Rice 2.2 KRAD.  

Following are 7 areas that application developers using Rice 2.0 KRAD should consider in their applications:

The new ARIA guidelines enable interactive web applications to be accessible – you no longer have to create an alternate version without jScript.   ARIA represents an extension to both HTML and XHTML, providing new attributes to dynamically convey how interactive features (controls, widgets, Ajax live regions, and events) relate to each other and what is their current state.  The goal is to make these into standard features in HTML5.

From the WAI-ARIA Primer: 

"Authors of JavaScript-generated content do not want to limit themselves to using standard tag elements that define the actual user interface element such as tables, ordered lists, etc. Rather, they make extensive use of elements such as DIV tags in which they dynamically apply a user interface (UI) through the use of style sheets and dynamic content changes. HTML DIV tags provide no semantic information. For example, authors may define a DIV as the start of a pop-up menu or even an ordered list. However, no HTML mechanism exists to:

In short, JavaScript needs an accessibility architecture to write to such that a solution can be mapped to the accessibility frameworks on the native platform by the user agent."

ARIA gives us several new constructs to do this, to dynamically convey how interactive features relate to each other and what is their current state:

There is a 7-step process recommended when applying ARIA to web application code (steps drawn from the in WAI-ARIA Primer, examples supplied by this training module):

There are four major "take-aways" in this accessibility section:

Spring provides a configuration system that allows us to configure how to instantiate, configure, and assemble objects in our application. Furthermore, this configuration can take place outside of Java code. As simple as it might sound, this is a very powerful construct that has changed many aspects of application development. An application of this includes configuring the dependencies for an object (other objects it depends on). This is known as Inversion of Control, the opposite of the object getting its own dependencies (for example with a ServiceLocator for service dependencies).

KRAD along with the rest of Rice use this feature of Spring to set dependencies such as services, DAOs, and data sources. This gives applications built with Rice much greater flexibility, as the implementations for these dependencies can be changed and configured for us with the Spring configuration.

Besides setting other object dependencies, the Spring configuration can be used to set values for primitive properties (String, Integer, Boolean …). In addition, we can instruct Spring on how to set the property value, whether it be by a standard setter, constructor argument, or annotated method. Essentially Spring allows us to give a formula for creating and populating an object instance completely outside of code. This so called formula is known as the bean configuration.

Spring supports various methods for bean configuration, the most common of these being XML. Each XML file must adhere to the Spring bean doctype and is sometimes referred to as 'Spring Bean XML'. The following is the shows the doctype definition for the 3.1 release:

  1 
  2 <beans xmlns="http://www.springframework.org/schema/beans"
  3     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4     xmlns:beans="http://www.springframework.org/schema/beans"
  5     xsi:schemaLocation="http://www.springframework.org/schema/beans
  6         http://www.springframework.org/schema/beans/spring-beans-3.1.xsd">
  7             

Note this sets up use for the bean namespace. Spring provides many other XML namespaces that are used for various purposes. If one of these are used, the corresponding definition must be declared with the bean doctype. One of these other namespaces, the 'p' namespace, will be covered later on in this section.

Once we have our XML file setup, we can begin specifying the bean configuration. Each file may contain as many bean configurations as we like (we will see later on certain best practices for Spring file organization). To start a new bean configuration, we use the bean tag:

  1 
  2 <bean id="address" class="edu.myedu.sample.Address">
  3 </bean>
  4             

As we will see in a bit, the bean configuration is loading into a container managed by Spring. In order to identify a bean configuration, we must give it a unique name using the id attribute. In addition we see here an attribute named class. Recall the purpose of the bean configuration is to construct and populate an object, so we must tell Spring what type of object we want created

The above definition is perfectly acceptable and would result in Spring creating a new Address object. However, now let's add some property configuration. In order to do this, we must know the available properties on our Address object:

public class Address {

  private String street;

  private String city;

  private String state;

  // getters and setters

}

We see Address has three properties we can configure. To specify a value for one of these properties, we can use the property tag. When using the property tag we must specify the name attribute which must match the property name of the class we want to populate, and then the value attribute which is the value we wish to inject.

  1 
  2 <bean id="address" class="edu.myedu.sample.Address">
  3     <property name="street" value="197 H St"/>
  4     <property name="city" value="Bloomington"/>
  5     <property name="state" value="IN"/>
  6 </bean>
  7             

The above configuration is equivalent to the following Java code:

  1 
  2 Address address = new Address();
  3 address.setStreet("197 H St");
  4 address.setCity("Bloomington");
  5 address.setState("IN");  
  6             

Notice that in order for Spring to instantiate our object with the above bean configuration, we needed to have a default no-argument constructor. However, if our class requires a constructor argument, that's no problem. We can use the constructor-arg tag to specify the values for the arguments. Suppose our Address class looks like the following:

  1  
  2 public class Address {
  3     private String street;
  4     private String city;
  5     private String state;
  6     public Address(String street, String city, String state) {
  7         this.street = street;
  8         this.city = city;
  9         this.state = state;
 10     }
 11         // getters and setters
 12 }
 13             

We can then use the constructor-arg tag so Spring can pass the appropriate arguments for instantiation:

  1 
  2 <bean id="address" class="edu.myedu.sample.Address">
  3     <constructor-arg  index="0" value="197 H St"/>
  4     <constructor-arg index="1" value="Bloomington"/>
  5     <constructor-arg index="2" value="IN"/>
  6 ></bean>
  7             

Note when specifying the constructor-arg, we indicating the order the argument should be given to the constructor using the index attribute. Spring supports other mechanisms for matching the arguments, such as matching by the argument class type.

In order to populate a property type that is a collection, we must use some additional tags provided by Spring. These tags correspond to the type of Collection we want to create: list, map, set, or properties.

Suppose we have the following property of type List<String>:

  1 
  2 private List<String> phoneNumbers;

We can then configure this property in our bean configuration as follows:

  1 
  2 <property name="phoneNumbers">
  3     <list>
  4         <value>812-333-9090</value>
  5         <value>812-444-9900</value>
  6     </list>
  7 </property>
  8             

Notice that instead of using the value attribute, we are using the body of the property tag to specify the property value. We then use the list tag to specify we want to create a List collection type. Finally, we configure entries for the List using the value tag. This is equivalent to the following Java code:

  1 
  2 List<String> phoneNumbers = new ArrayList<String>();
  3 phoneNumbers.add("812-333-9090");
  4 phoneNumbers.add("812-444-9900");
  5             

Now let's take a look at a Map example. Suppose we had the following property with type Map<String, String>:

  1 
  2 private Map<String, String> stateCodeNames;
  3             

Our corresponding property configuration would look as follows:

  1 
  2 <property name="stateCodeNames">
  3     <map>
  4         <entry key="IN" value="Indiana"/>
  5         <entry key="OH" value="Ohio"/>
  6         </map>
  7 </property>
  8             

Here we use the map tag to indicate a Map collection type should be created. Then we specify entries for the map using the entry tag. This requires us to specify the entry key and entry value using the key and value attributes respectively.

As mentioned previously, we can use the bean configuration to specify values for primitive and collection property types, along with properties of other object types. These are known as dependencies of the object to other objects. Since these are properties holding other objects, which themselves have properties which we can specify using bean configuration, we associate these objects by referencing beans. In Spring this is called bean collaboration.

For referencing other bean definitions Spring provides the ref tag. The ref tag can be used by specifying the bean, local, or parent attributes. All of these attributes take as a value the id for the bean you wish to reference (matching either the actual id value given on the bean, or one of its names or aliases). The difference between these attributes pertains to container and scoping rules (discussed later on). The most common case with Rice is to use the bean attribute.

For example, in our Address objects, let's now change the state property (of type String) to type State. The State class is as follows:

  1 
  2 private class State {
  3     private String stateCode;
  4     private String stateName;
  5         // getter and setters
  6 }
  7             

And our Address class now looks like:

  1 
  2 public class Address { 
  3     private String street;
  4     private String city;
  5     private State state;
  6         // getters and setters
  7 }
  8             

First we can create one or more new bean configurations for our State object:

  1 
  2 <bean id="state-IN" class="edu.myedu.sample.State">
  3     <property name="stateCode" value="IN"/>
  4     <property name="stateName" value="Indiana"/>
  5 </bean>
  6 <bean id="state-OH" class="edu.myedu.sample.State">
  7     <property name="stateCode" value="OH"/>
  8     <property name="stateName" value="Ohio"/>
  9 </bean>
 10             

Now in our bean configuration for Address, we can reference one of these state bean configurations using the ref tag:

  1 
  2 <bean id="address" class="edu.myedu.sample.Address">
  3     <property name="street" value="197 H St"/>
  4     <property name="city" value="Bloomington"/>
  5     <property name="state">
  6         <ref bean="state-IN"/>
  7     </property>
  8 </bean>
  9             

In Java code, this would be:

  1 
  2 Address address = new Address();
  3 address.setStreet("197 H St");
  4 address.setCity("Bloomington");
  5 State state = new State();
  6 state.setStateCode("IN");
  7 state.setStateName("Indiana");
  8 address.setState(state);
  9             

If we wanted to change our address to use the OH state code instead, we simply change the bean attribute on the ref tag:

  1 
  2 <bean id="address" class="edu.myedu.sample.Address">
  3     <property name="street" value="197 H St"/>
  4     <property name="city" value="Bloomington"/>
  5     <property name="state">
  6         <ref bean="state-OH"/>
  7     </property>
  8 </bean>
  9             

In addition to referencing other bean definitions for setting object properties, Spring gives us an option to construct the bean inline (so called "Inner Beans"). These beans do not require an id attribute to be specified, and as a consequence and not accessible for reference by other bean configurations. We create these inner bean configurations exactly as we do other bean configurations. The only difference is they do not need an id attribute (as stated), and the bean tag falls within a property tag.

To see this in action, let's suppose we did not any bean configurations for State in our XML. Using inner beans, we can accomplish the same result:

  1 
  2 <bean id="address" class="edu.myedu.sample.Address">
  3     <property name="street" value="197 H St"/>
  4     <property name="city" value="Bloomington"/>
  5     <property name="state">
  6         <bean class="edu.myedu.sample.State">
  7             <property name="stateCode" value="IN"/>
  8             <property name="stateName" value="Indiana"/>
  9         </bean>
 10     </property>
 11 </bean>
 12             

As of Spring version 3.0, we can configure so called 'Compound' property names. This is a basically a shortcut for setting a property on a reference (nested) object. Let's again take the example of the Address class with a property of type State. We saw earlier how we can use bean references or inner beans to create and populate the State object for the Address property. Using component property names, we can sets property values on the State object using the property tag without a nested bean tag:

  1 
  2 <bean id="address" class="edu.myedu.sample.Address">
  3     <property name="street" value="197 H St"/>
  4     <property name="city" value="Bloomington"/>
  5     <property name="state.stateCode" value="IN"/>
  6 </bean>
  7             

In order for this to work, the State object must have been already constructed (with the Address constructor, bean inheritance, or other means). If the state object is null, a NullPointerException will be thrown when Spring tries to set the stateCode property.

As we have seen and will continue to see, the use of XML configuration for constructing objects has many benefits. However, one drawback is the XML is much more verbose than code. To help with this problem, Spring introduces the 'p' XML namespace. This namespace essentially adds the ability to specify property values as attributes on the bean tag instead of the inner property tags. The attribute name given with the p namespace should match the name of the property to populate.

For example, our previous bean configuration for address can be rewritten as:

  1 
  2 <bean id="address" class="edu.myedu.sample.Address" p:street="197 H St" p:city="Bloomington" p:state="IN"/>
  3             

Using the p namespace we can also configure references to other beans. The syntax for doing this is to add '-ref' after the property name.

  1 
  2 <bean id="address" class="edu.myedu.sample.Address" p:street="197 H St" p:city="Bloomington" p:state-ref="state-IN"/>
  3             

Here Spring will look for a bean configuration with id equal to "state-IN", and use the object constructed from that bean configuration to set the state property on Address.

With the p-namespace we can also set compound property names such as 'state.stateCode'. Using the p-namespace for setting property values is limited however. For instance, there is no mechanism for setting collection property types.

Bean configuration can be inherited for another configuring another bean using the parent attribute on the bean tag. The value for the parent attribute is the id or name for the bean which configuration should be inherited from. Configuration such as the class, property and constructor arguments, initialization methods, and so on, will be inherited for the child definition. The child bean definition can override the inherited configuration, and add to it.

As an example let's assume we have a Car class defined as follows:

  1 
  2 public class Car {
  3     private String make;
  4     private String company;
  5     private String color;
  6 }
  7             

We can then define bean definitions as follows:

  1 
  2 <bean id="fordCar" class="edu.myedu.sample.Car" p:company="Ford"/>
  3 <bean id="blueFusion" parent="fordCar" p:make="Fusion" p:color="Blue"/>
  4 <bean id="redFusion" parent="fordCar" p:make="Fusion" p:color="Red"/>
  5 <bean id="blueEscape" parent="blueFusion" p:make="Escape"/>
  6             

Notice for the three child beans we did not have to specify the class attribute since it is inherited from the parent. In the 'blueFusion' and 'redFusion' beans we are extending the 'fordCar' bean to specify the car make and color. For the 'blueEscape' bean we extend 'blueFusion' to override the make property. There is no restriction on the number of levels the bean inheritance can have.

When a bean configuration is inherited that includes property configuration for a collection class, we must explicitly indicate to merge the entries. This is done by adding merge="true" to the collection tag.

  1 
  2 <bean id="address" class="edu.myedu.sample.Address">
  3     <property name="phoneNumbers">
  4         <list>
  5             <value>812-333-9090</value>
  6             <value>812-444-9877</value>
  7         </list>
  8     </property>
  9 </bean>
 10 
 11 <bean id="joesAddress" parent="address">
 12     <property name="phoneNumbers">
 13         <list merge="true">
 14             <value>333-122-4000</value>
 15         </list>
 16     </property>
 17 </bean>
 18             

With the merge attribute set to true, Joe's address will have three phone numbers configured. Taking the merge attribute off (or setting to false) will result in Joe only having one configured phone number.

So far we have looked at how we can use XML to provide bean configuration. Now let's look at how Spring uses that information to manage our objects.

The objects created from the bean configuration are managed within a container. An application may contain more than one bean container, depending on configuration. A bean container is associated with a set of bean configurations, loaded from a set of XML files (or other configuration mechanism if used). Through code, we can then ask for an object from the container through the container interface.

One type of bean container Spring provides is an ApplicationContext. This container is associated with an application or a module of the application and provides services, resources, and other objects for that application/module. The application context is initialized when the application starts up and maintained throughout the application lifecycle. In Rice, each module has an associated ApplicationContext that is configured and initialized with the Rice Configurers.

Figure 2.2. Bean Factories

In addition to the application contexts, other bean factories can be maintained by an application. For example, as we will learn about in Chapter 4, the KRAD Data Dictionary module maintains a bean factory that holds the dictionary metadata. A set of XML files provides the bean configuration for the data dictionary. These XML files are separate from the ones that provide configuration for the application context containers.

For the objects Spring creates for us, we can define a Scope. The scope specifies how long the created object should live. To specify the scope for a bean, we use the scope attribute on the bean tag.

  1 
  2 <bean id="MyBean" class="..." scope="singleton">
  3             

The default scope for a bean is 'singleton'. An object with scope singleton is created only once per bean container. When requests are made to obtain an object for the correspond bean, the same object instance is always returned. By default, the singleton object is created during container initialization, however we may add lazy-init="true" to the bean tag to indicate that the object should not be created until a request for the object is made.

Another scope we can use is 'prototype'. When a bean is marked with a scope of prototype, a new object instance is created for each request. Prototype objects are not created initially during container initialization.

Besides the singleton and prototype scopes, Spring also provides the request, session, and global session scopes. Furthermore, you can create your own scope!

The result of running the create project script is a new maven based Rice client project. This includes the directory structures for building out your application, along with the necessary configuration files. Let's start by looking at the directories that were created.

Project Root (eg '/java/projects/myapp') – This is the root folder that was created to hold all the project contents. Within this folder you will find three sub-folders, a '.classpath', '.project', 'instructions.txt', and 'pom.xml' file.

.settings – This folder contains settings configuration for the Eclipse IDE

src – This folder is for the application source files and resources. Within this folder is the standard maven directory breakdown:

target – This folder holds the build output such as generated classes and wars.

Along with the directories several files are created. These are as follows:

* All of these files are located within the src/main/resources directory

In addition to the files created within the project, two files are created in the '{user home}/kuali/main/dev' folder. These include:

Next, we need to provide some configuration for our application that is custom to our environment (for example, database connectivity). We can do this by modifying the properties available in {project}-config.xml (located in the /kuali/main/dev folder in user home).

Although there are many configuration properties available for customization, the following are required for getting started:

Now we have our project setup and are ready to begin development. Note at this point that the application is completely runnable. We could do a maven deploy, copy the generated war to our tomcat server, and start up the application. However we are going to first import our project to Eclipse so that we will be ready to further develop the application code.

Navigate to the Eclipse installation directory. There you should find an executable named 'eclipse.exe'. Once this file is found double click it to start the IDE. When Eclipse starts up for the first time, it will ask you to choose a workspace. This is a directory that Eclipse places newly created projects, and will also read current projects from. A standard within the community is to use '/java/projects' for your working space. Note you can select the checkbox to use the directory as your default and Eclipse will not prompt on the next startup.

When working with Eclipse for the first time, there are additional plugins you will likely want to get. None of these are required by Rice and depend on your institutional development environment and how you plan to create your project. However, most projects today use SVN or GIT for source code control. Therefore an additional Eclipse plugin is needed for communicating with the repository. Also if you have chosen to use Maven (or used the create project script) the Eclipse Maven plugin will be very useful as well.

To bring a new project into eclipse, select the File-Import menu option. This should bring up a dialog as show in the example below.

Figure 2.3. Import New Project Eclipse

For the import source select 'Existing Projects info Workspace'. This should bring up a dialog that looks like the example below.

Figure 2.4. Selecting Project Eclipse

Here click the 'Browse' button to locate the directory for the project. After selecting the project location click the 'Finish' button. Eclipse will then import the project contents and you are ready to begin coding!

To run our project we again have many options. One of these is to deploy to an external servlet container such as Tomcat. Using the Eclipse Web Tools platform, we can configure a Tomcat server and control all the deployments, startups, and shutdowns from Eclipse.

Another approach is to use a Jetty Server. Rice provides a JettyServer class that can be used to launch Jetty and host an application. To use this we just need to create an Eclipse launch configuration which will run the server as a Java main class, and provide arguments for the deployment (such as context, web app location and so on).

To begin using the Rice development framework, we must first configure an application module. This information tells the KRAD framework where to find resources for our module (such as dictionary and OJB files) along with other metadata about our module. We could choose to have one module for our whole application, or break into many modules (if using maven each KRAD module generally corresponds with a maven module).

To configure a module we create a ModuleConfiguration. A ModuleConfiguration is a bean wired in Spring XML specifying the following information:

The following is an example module configuration bean:

  1 
  2 <bean id="sampleAppModuleConfiguration" class="org.kuali.rice.kns.bo.ModuleConfiguration">
  3     <property name="namespaceCode" value="KR-SAP"/>
  4     <property name="initializeDataDictionary" value="true"/>
  5     <property name="dataDictionaryPackages">
  6         <list>
  7             <value>edu/sampleu/travel/datadictionary</value>
  8         </list>
  9         </property>
 10         <property name="databaseRepositoryFilePaths">
 11             <list>
 12                 <value>OJB-repository-sampleapp.xml</value>
 13             </list>
 14         </property>
 15         <property name="packagePrefixes">
 16              <list>
 17                 <value>edu.sampleu.travel</value>
 18              </list>
 19         </property>
 20 </bean>
 21             

Note in particular here the dataDictionaryPackages property. This is where the framework will pick up data dictionary files for loading (which we will be using a lot in this training manual). We can specify individual files or directories. If a directory is given, then XML files added to that directory will automatically get picked up and loaded on application startup.

When the Rice enabled application is started, the configuration for each module will be read and, in some cases such as the dictionary and OJB, used to initialize services.

After we have our module configuration, we then need to configure a module service. This is a service that will provide metadata for our module. Responsibilities of the module service include determining whether a data object belongs to a module, and if the object is external to the application (in which case the module service will also provide links for the object's lookup and inquiry). If we don't need to customize a module service (which is the case if the module has external data objects), then we can simply use the provide service base and set the nested module configuration property to our module bean:

  1 
  2 <bean id="sampleAppModuleService" class="org.kuali.rice.krad.service.impl.ModuleServiceBase">
  3     <property name="moduleConfiguration" ref="sampleAppModuleConfiguration"/>
  4 </bean>
  5             

We begin our training for the Kuali Rapid Application Development framework with the data access layer. Enterprise applications generally have a large number of CRUD (Create Read Update Delete) operations; therefore, the access of data is a very important concern of development. KRAD builds on top of other tools to provide general facilities that greatly reduce the development time. These facilities are known as the KRAD Persistence Framework.

The foundation of the KRAD Persistence Framework is the third party ORM (Object Relational Mapping) tool. ORM tools target the persistence of data with a relational database. This is achieved by mapping a Java object that contains the data to one or more database tables. When a persistence operation is requested, the ORM tool performs the work of translating the request along with the corresponding object(s) to the necessary DML statement. This provides a great advantage to the application as it generally requires no database dependent code (database specific code might be required in certain cases). More information on particular ORM tooling will be provided in the sections 'OJB Primer' and 'Using JPA'.

In order to prepare our application for persisting data using an ORM tool, we must build the objects that will hold the application data. From the established data model, we can determine the objects needed using a mapping strategy. Although the strategies and options available depend on the ORM solution we are using, generally we have the following mapping options:

Once we have determined how an object will relate with its database table(s), each object property is associated with a table column through configuration. This configuration will also give the ORM tool information on data type conversion and constraints. The final piece to our object mapping is specifying any relationships. This includes one-to-one, one-to-many, and many-to-many relationships.

Now let's set aside the mapping concerns and have a closer look at our 'data' objects. Technically, these objects are not complex at all. First, they must adhere to the POJO (Plain Old Java Object) and JavaBean guidelines. These guidelines are as follows:

In addition to the 'primitive' property types a data object may contain, a data object may also be composed of nested data objects (representing a one-to-one relationship), or a collection of data objects (representing a one-to-many relationship).

Next, well that's it! However, as we will see in just a bit, in order to take advantage of the additional persistence features KRAD provides, there is one additional thing we need to add.

KRAD refers to any object that provides data as a 'Data Object'. Data objects provide a very central role in an enterprise application. Within the suggested KRAD architecture, they are not bound to just the data access layer, but can freely move between the other application layers as well. This means we can use data objects in our services, and we can use them to build our user interfaces.

Best Practice: Keep data objects simple! Try to avoid introducing any business logic or presentation logic into the objects.

A special type of data object in KRAD is known as a Business Object. These are data objects that implement the interface org.kuali.rice.krad.bo.BusinessObject. There are two primary types of business object: those that persist to the database and those that do not. Those business objects that do persist to the database should implement the org.kuali.rice.krad.bo.PersistableBusinessObject interface. This interface adds persistence related methods that are invoked throughout the framework.

Generally, when creating a new data object, it is more convenient to extend one of the provided base classes that implement the necessary interfaces. For persistable objects, this base class is org.kuali.rice.krad.bo. PersistableBusinessObjectBase. Within this base class, default implementations for the persistable methods exist along with properties for the common fields required for all persisted objects. These are described in more detail later on in this section. Business objects that do not persist to the database can extend org.kuali.rice.krad.bo.TransientBusinessObjectBase.

In order to take advantage of all the features KRAD provides, it is recommended that all persistable objects (and therefore tables) contain two properties:

Additional functionality exists for a few special types of business objects. One of these special types is business objects that have an active status. That is, each record has a state of active (which generally means the record is valid for using) or inactive (meaning the record should not be used due to being old or not currently valid). Objects of this type should implement the Inactivatable interface. This interface requires the methods isActive() and setActive(Boolean active) to be implemented.

The simplest form of inactivatable business objects are those that maintain a single field that indicates the active status as a Boolean field. Another common case is that of an active date range (also known as effective dating). These objects maintain two fields that work together for determining the active status. This first of these fields is the active begin date which indicates the date on which the record becomes active. This field can have a null value indicating the record is active for all dates before the end date. The second field is the active end date which indicates the date on which the record becomes inactive. This field can have a null value indicating the record has no inactive date set.

Record is active if:

  1 (activeFromDate == null ||
  2     asOfDate >= activeFromDate.getMillis()) &&  (activeToDate == null ||
  3     asOfDate < activeToDate.getMillis());   

where the asOfDate is the current date or a date we wish to simulate the active check for.

For inactivatable business objects that use effective dating, the org.kuali.rice.krad.bo.InactivatableFromToImpl class can be extended which holds the necessary properties and implements the logic necessary to determine the active status (note that this class implements the Inactivatable and InactivatableFromTo interfaces).

When an object is marked as inactivatable, KRAD will give us some nice features for handling the active status:

Another special type of business objects are code/name objects. These objects all contain a field that represents a code, and a field that gives the name for that code (or description). In many cases these are the only two fields present. Business objects of this type should implement the org.kuali.rice.krad.bo.KualiCode interface (or extend org.kuali.rice.krad.bo.KualiCodeBase). When presenting code values that have a related object of type KualiCode, the framework will do translation to display the name or the code and name.

All OJB files must begin with the standard XML declaration, and then the OJB doctype tag (root element):

  1 <?xml version="1.0" encoding="UTF-8"?>
  2 <descriptor-repository version="1.0">
  3 ...
  4 </descriptor-repository>  

Next, our OJB file must contain a jdbc-connection-descriptor which configures the database connection OJB will use for the contained mappings:

  1 <jdbc-connection-descriptor
  2     jcd-alias="dataSource"  default-connection="false"
  3     jdbc-level="3.0" eager-release="false" batch-mode="false" useAutoCommit="0"
  4     ignoreAutoCommitExceptions="false">  <object-cache
  5     class="org.apache.ojb.broker.cache.ObjectCachePerBrokerImpl" />  
  6     <sequence-manager className="org.kuali.rice.core.framework.persistence.ojb.ConfigurableSequenceManager">
  7         <attribute attribute-name="property.prefix" attribute- value="datasource.ojb.sequenceManager" />
  8     </sequence-manager>
  9 </jdbc-connection-descriptor>   

Note that jcd-alias="dataSource" refers to the name of the data source configured in spring bean XML. Also note the use of the Rice ConfigurableSequenceManager. This allows configuration through the Rice configuration API of the sequence for a property (such as starting sequence value).

New data object mappings are added to OJB by adding a class-descriptor tag. One or more class descriptors can be added to an OJB file after the jdbc-connection-descriptor. With the class descriptor, we must specify the fully qualified java class for mapping with the class attribute and the database table name with the table attribute:

  1 <class-descriptor class="org.kuali.rice.krad.demo.travel.account.TravelAccount" table="TRV_ACCT">
  2     ... 
  3 </class-descriptor>      

Now that we have our object-table mapping with the class descriptor, we can start mapping the primitive fields of our object using a field-descriptor tag. We place the field descriptors inside our class descriptor, indicating they all belong to that class. With the field descriptor we must specify the property name using the name attribute, and the table column name using the column attribute. In addition, we need to specify the JDBC type for the table column using the jdbc-type attribute. This indicates to OJB how it should convert the value between the database and object layers.

  1 <field-descriptor name="name" column="acct_name" jdbc-type="VARCHAR" />     

Some common jdbc types and their corresponding Java type are as follows:

Based on the given jdbc type, OJB can then convert the database value to the appropriate type for the base Java types. However, KRAD provides some additional data types, and applications may develop their own as well. In these cases, OJB will not be able to convert the value itself. However, OJB does provide a conversion facility that we can hook into and perform the necessary conversion.

We must create a class that implements the OJB interface org.apache.ojb.broker.accesslayer.conversions.FieldConversion. This requires us to then implement two methods. The first is named javaToSql and is invoked to convert the custom Java type to one of the Java types supported by OJB. The second method is named sqlToJava and is invoked to convert the value coming from the database to our custom type. In short, OJB will perform the standard conversion based on the table above, then invoke our converter class to convert from the base Java type to the custom type.

public class OjbKualiDecimalFieldConversion implements FieldConversion {
    private static final long serialVersionUID = 2450111778124335242L;  
    /** 
     * @see FieldConversion#javaToSql(Object) 
     */  

    public Object javaToSql(Object source) { 
        Object converted = source;  
        if (source instanceof KualiDecimal) { 
            converted = ((KualiDecimal) source).bigDecimalValue();
        }  
        return converted; 
    }
                 
    /** 
      * @see FieldConversion#sqlToJava(Object) 
      */ 

    public Object sqlToJava(Object source) { 
        Object converted = source;  
        if (source instanceof BigDecimal) { 
            converted = new KualiDecimal((BigDecimal) source);  
        }  return converted; 
    }
}   

This is an example of a converter provided by KRAD for the custom KualiDecimal type. In the javaToSql method, we are converting the KualiDecimal to a BigDecimal, which OJB can then convert to the JDBC type. In the sqlToJava method, we take the BigDecimal value coming from the database and create a new KualiDecimal type.

Once we have a converter class (or one is provided), we need to tell OJB to use it by specifying the full class name for the converter on the field descriptor using the conversion attribute:

  1  <field-descriptor name="price"
  2         column="PRICE" jdbc-type="DECIMAL"
  3         conversion="org.kuali.rice.core.framework.persistence.ojb.conversion.OjbKualiDecimalFieldConversion"/>  

It is necessary to add the conversion attribute for each property that has a custom type.

Rice provides the following custom data types and OJB converters:

These three data types provide a standard way of handling scale and rounding. In the case of KualiDecimal, the scale is set to 2, and the rounding behavior is 'Round Half Up'. KualiInteger has a scale of 0, and uses 'Round Half Up' rounding as well (for operations with decimal types).

In addition to the convertors provided by Rice for the custom data types, a few additional special convertors are provided.

The first of these is OjbCharBooleanConversion. A typical practice in legacy systems (before the introduction of database Boolean types) is to represent a Boolean by a single character string. Some common mappings are 'T' for true : 'F' for false, or 'Y' for true : 'N' for false. The Rice Boolean converter can be specified for a field to convert these string values to the correct Boolean property type. Other variations of the Boolean converter exist for other mapping strategies such as '1' : '0', 'A' : 'I', 'true' : 'false', and 'yes' : 'no'.

Finally, Rice provides a converter for encrypting secure database contents. The name of this converter is OjbKualiEncryptDecryptFieldConversion. This converter relies on the EncryptionService implementation to perform the encryption. Values are encrypted for storing in the database and then decrypted for object population.

All field descriptors must have the name, column, and jdbc-type attributes. In addition to these we can make use of other OJB attributes to provide further column information.

Foremost among these is the primarykey attribute. This attribute simply takes a Boolean value of true (by default false for all columns) to indicate the column for the field descriptor is a primary key. All class descriptors must have at least one field descriptor with the primarykey="true" attribute. OJB uses the primary key information in many places, including determining whether to do an insert or update statement (see 'The BusinessObjectService' for more information). In addition, primary keys are used for linking relationships.

Compound keys are configured by adding the primarykey="true" attribute to more than one field:

  1 <class-descriptor class="org.kuali.rice.kew.doctype.DocumentTypePolicy" table="KREW_DOC_TYP_PLCY_RELN_T">
  2     <field-descriptor name="documentTypeId" column="DOC_TYP_ID" jdbc-type="VARCHAR" primarykey="true"/>
  3     <field-descriptor name="policyName" column="DOC_PLCY_NM" jdbc-type="VARCHAR" primarykey="true"/>
  4 ...          

A single primary key field can also be a surrogate key for which a sequence is used to generate the key values. We can indicate to OJB that the primary key is a sequence using the autoincrement and sequence-name attributes:

  1 <class-descriptor class="edu.sampleu.bookstore.bo.Book" table="BK_BOOK_T">
  2     <field-descriptor name="id" column="BOOK_ID" jdbc-type="BIGINT" primarykey="true" autoincrement="true" 
  3      sequence-name="BK_BOOK_ID_S" /> 
  4 ...  

In this class descriptor for Book, we have a primary key field named 'id'. Furthermore, the values for the book id field are generated by a sequence named 'BK_BOOK_ID_S'. When OJB performs an insert on the BK_BOOK_T table, it will retrieve the next value from the book id sequence and use it as the id for the new record.

Now that we have our primary key fields set, recall the recommendation that all persisted objects carry the version number and object id properties. We can map these properties with the follow field descriptors:

  1 <field-descriptor name="versionNumber" column="VER_NBR" jdbc-type="BIGINT" locking="true" />
  2 <field-descriptor name="objectId" column="OBJ_ID" jdbc-type="VARCHAR" indexed="true" />   

Note the locking and indexed attributes. The locking attribute tells OJB to use this column to perform optimistic locking and only one field descriptor may have this attribute set to true. The indexed attribute indicates to OJB that we have a database index on this field. OJB can then use that information for optimizing queries.

After mapping all of the class primitive fields using field descriptors, we must then map our relationships to other data objects. In code, these relationships are properties just like the primitive fields that persist to table columns. However, the difference with these properties is their type is another data object (in the case of 1-1) or a collection of other data objects (in the case of 1-many).

First, let's take the case of 1-1 relationships. To map these we use the reference-descriptor tag. A class descriptor can contain one or more reference-descriptor tags. When using a reference descriptor tag we must specify the name attribute which holds the name of the property we are describing (similar to the name attribute in a field descriptor). Then we must specify the class of the related object using the class-ref attribute.

For example, suppose we had the following property in our Book data object that references a BookType:

public class Book extends PersistableBusinessObjectBase {   
...
    private BookType bookType;       

Our corresponding reference descriptor will then be:

  1 <reference-descriptor name="bookType" class-ref="edu.sampleu.bookstore.bo.BookType"/>     

We are not quite finished though with our reference descriptor. OJB can now determine we have a foreign key relationship from Book to BookType, and it knows the primary key fields for BookType, but which fields of Book are the actual foreign keys? To fill in this information, within our reference descriptor we must add a foreign key field for each primary key field of BookType.

  1 <reference-descriptor name="bookType" class-ref="edu.sampleu.bookstore.bo.BookType">
  2     <foreignkey field-ref="typeCode" />
  3 </reference-descriptor>

When using the foreignkey tag, we must specify the field-ref attribute whose value is the name of the field in the class holding the relationship (in this case Book) that is the foreign key. The number of foreignkey tags must match the number of primary key fields in our class descriptor. Note also the order the foreign keys are declared must match the order in which they join to the primary keys. For example, if our reference target class has primary key fields code and subCode, and we have foreign keys fkCode and fkSubCode, the following configuration would be incorrect:

  1 <reference-descriptor name="subCode" class-ref="edu.sampleu.SubCode">
  2     <foreignkey field-ref="fkSubCode"/>
  3     <foreignkey field-ref="fkCode" />
  4 </reference-descriptor>

Here the order of foreign keys is reversed which will cause OJB to join the fkSubCode with code, and fkCode with subCode.

Similar to the field descriptor, OJB provides additional attributes we can specify for a reference descriptor. Three of these attributes are prefixed with 'auto-' and designate how OJB should handle the reference during retrieve, update (or insert), and delete operations. The first of these is the auto-retrieve attribute, and indicates whether the reference should be retrieved when the main (or parent) object is retrieved. The attribute can be specified as 'false' (reference should not be retrieved) or 'true' (reference will be retrieved). When auto-retrieve=false is specified, the reference object will be null on the main object after retrieval. OJB provides mechanisms for retrieving the reference through code, which will be discussed in the upcoming section 'Reference Refreshing'.

The auto-update attribute specifies whether the reference object should be updated when an update is done on the main object. This attribute can have a value of 'none' – meaning no update should happen for the reference – and 'object' – meaning the reference record should be updated with the main object. In addition, an option of 'link' can be specified, which is just relevant for one-to-many relationships. This performs an update on the indirection table, but not the actual reference table.

The final auto attribute is auto-delete, which indicates whether the reference object should be deleted when the main object is deleted. Similar to auto-update, 'none', 'link', or 'object' can be given for the value.

Care must be taken when setting the auto-retrieve attribute. Having the reference ready without having to make an extra call is a great programming convenience. However, performance can suffer due to the time required to initially load the reference objects with the main object, in particular for objects with several relationships. Furthermore, optimizing the auto-retrieve setting can be difficult, due to it being a global setting, and the developer often not knowing when the reference data will be needed. Don't worry though; OJB has another attribute we can use! This attribute is named proxy and can have a value of 'true' or 'false' (the default). Adding proxy=true to our reference descriptor allows OJB to use lazy loading for our reference. Essentially, this allows us to use the reference when needed without making an additional call, but the full record is not loaded initially with the main object which will help performance. To make this work, OJB will initially create a proxy object for the property value. When a method is invoked on the proxy object (such as a getter or setter), OJB will fetch the record and populate the reference object.

if ((book != null) && (book.getBookType() != null)) { 
    return book.getBookType().getName();  
}   

Similar to the reference descriptor, the collection descriptor maps a reference (nested) data object in the database. However, collection descriptors are used for one-to-many relationships where the property is a List type.

To map these we use the collection-descriptor tag. A class descriptor can contain one or more collection-descriptor tags. When using a collection descriptor tag, we must specify the name attribute which holds the name of the property we are describing (similar to the name attribute n reference descriptor). Then we must specify the class of the related object using the class-ref attribute (again similar to reference descriptor).

For example, suppose we had the following property in our Book data object that references a List of Authors:

public class Book extends PersistableBusinessObjectBase {  
    ... 
    private List<Author> authors;   

Our corresponding collection descriptor will then be:

  1 <collection-descriptor name="authors" class-ref="edu.sampleu.bookstore.bo.Author"/>     

When configuring a collection descriptor, the foreign key direction goes from the target class to the source. That is, we need to specify the field in the target class (in this case Author) that maps to the primary key of the source class (Book). This is done using the inverse-foreignkey tag:

  1 <collection-descriptor name="bookType" class-ref="edu.sampleu.bookstore.bo.Author">
  2     <inverse-foreignkey field-ref="bookId" />  
  3 </collection-descriptor>        

The collection descriptor supports the same auto-x attributes we saw in reference descriptor. Figure 3.1, “Building Blocks” gives a picture of the reference and collection descriptors

Figure 3.1. Building Blocks

Required

Property: required

Values: true if required otherwise false

When a field is required, the field must have some input value for it to be considered valid

  1 
  2 <bean parent="Uif-InputField" p:required="true" p:propertyName="field1">...</bean>

MinLength

Property: minLength

Values: integer, 0 or greater

When a minLength is set, the input value's character length cannot be less than minLength.

MaxLength

Property: maxLength

Values: integer - 0 or greater

When a maxLength is set, the input value's character length cannot be greater than maxLength. MaxLength should be set to a greater value than minLength (if set).

  1 
  2 <bean parent="Uif-InputField" p:minLength="1" p:maxLength="8" p:propertyName="field1">...</bean>

ExclusiveMin

Property: exclusiveMin

Values: String representing a number or date value

When exclusiveMin is set to a number, and the input's value is a number, that number must be greater than exclusiveMin. If exclusiveMin is set to a date, and the input's value is a date, that date must be greater than exclusiveMin. Note that for dates, exclusiveMin validation is not enforced client-side, but the DatePicker widget will limit date selection based on this value (though the widget will limit min inclusively - not exclusively - so values should still be checked server-side).

InclusiveMax

Property: inclusiveMax

Values: String representing a number or date value

When inclusiveMax is set to a number and the input's value is a number, that number must be less than, or equal to, inclusiveMax. If inclusiveMax is set to a date and the input's value is a date, that date must be less than, or equal to, inclusiveMax. Note that for dates, inclusiveMax validation is not enforced client-side, but the DatePicker widget will limit date selection based on this value.

  1 
  2 <bean parent="Uif-InputField" p:exclusiveMin="0" p:inclusiveMax="500" p:propertyName="field1>...</bean>

dataType

Property: dataType

Values: STRING, MARKUP, DATE, TRUNCATED_DATE, BOOLEAN, INTEGER, FLOAT, DOUBLE, LONG, DATETIME

When dataType is set to one of the above types, it checks to see if the input's value can be converted into that type. This is not enforced client-side and can only be enforced during server-side validation.

  1 
  2 <bean parent="Uif-InputField" p:dataType="INTEGER" p:propertyName="field1">...</bean>

minOccurs/maxOccurs

This constraint is not yet fully supported. The name and location may change in the future. Future intended use is to constrain total collection items in a collection.

ValidCharacterConstraints allow you to constrain the allowed input on a field to a set combination of characters by using regex (Regular Expressions). There are a variety of predefined ValidCharacterConstraints available in KRAD, but the ability to easily create your own is available as well using standard regex. A ValidCharacterConstraint is set through the validCharacterConstraint property on either an InputField or AttributeDefinition. This constraint mimics, but enhances, constraints available in the original KNS called ValidationPatterns. However, do not use ValidationPatterns in KRAD as they are deprecated and no longer used.

  1 
  2 <bean parent="Uif-InputField" p:propertyName="field62">
  3     <property name="validCharactersConstraint">
  4         <bean parent="AlphaNumericPatternConstraint" />
  5     </property>
  6 </bean>
  7                 

The predefined beans for ValidCharacterConstraint are:

AlphaNumericPatternConstraint

Only alphabetic and numeric characters allowed.

AlphaPatternConstraint

Only alphabetic characters allowed.

AnyCharacterPatternConstraint

Only keyboard characters are allowed. Specifically, these are ASCII characters x21 through x7E in hexadecimal. Whitespace is not allowed by default, unless enabled through the allowWhitespace flag.

CharsetPatternConstraint

Allows any characters set through its validCharacters property.

NumericPatternConstraint

Only numeric characters allowed.

AlphaNumericWithBasicPunc

Only alphabetic and numeric characters with whitespace, question marks, exclamation points, periods, parentheses, double quotes, apostrophes, forward slashes, dashes, colons, and semi-colons allowed. This is an additional configuration of AlphaNumericPatternConstraint with some "allow" flags turned on.

AlphaWithBasicPunc

Only alphabetic characters with whitespace, question marks, exclamation points, periods, parentheses, double quotes, apostrophes, forward slashes, dashes, colons, and semi-colons allowed. This is an additional configuration of AlphaPatternConstraint with some "allow" flags turned on.

NumericWithOperators

Only numeric characters with whitespace, asterisks, pluses, periods, parentheses, forward slashes, dashes, and equals signs, dashes allowed. This is an additional configuration of NumericPatternConstraint with some "allow" flags turned on.

FixedPointPatternConstraint

Only allows a numeric value where the precision property represents the maximum number of numbers allowed, and scale represents the maximum numbers after the decimal point. For example, a FixedPointPatternConstraint with precision 5 and scale 2 would allow: 2, 555, 555.11; but would not allow: 111.222, 1.222, 5555 (this is actually the value 5555.00, so it is not allowed).

IntegerPatternConstraint

Allows any valid integer (but does not restrict length or range). There are optional flags for allowing negative integers, only negative integers, or not allowing zero as input.

DatePatternConstraint

Allows any date to be input that is a valid date in the system. Any format defined in the configuration parameter "STRING_TO_DATE_FORMATS" is allowed.

BasicDatePatternConstraint

Allows a subset of the default date formats defined by DatePatternConstraint. These formats represent the most common input for date values: MM/dd/yy, MM/dd/yyyy, MM-dd-yy, and MM-dd-yyyy. It is recommended that this constraint be used on fields which use the DatePicker widget.

ConfigurationBasedRegexPatternConstraint

The following constraints are configurations of the ConfigurationBasedRegexPatternConstraint which have a patternConstraintKey that is used to retrieve a regex pattern by key in ApplicationResources.properties (or any other imported properties file). This differs from the above ValidCharactersConstraints because those generate their regex based on flags and options set on them. These constraints can easily have their functionality modified by changing the regex they use in any imported properties file.

FloatingPointPatternConstraint

patternConstraintKey: validationPatternRegex.floatingPoint

Allows any valid floating point value (does not limit length or range). In other words, any number which may include a decimal point.

PhoneNumberPatternConstraint

patternConstraintKey: validationPatternRegex.phoneNumber

Allows any valid US phone number in this format: ###-###-####.

TimePatternConstraint

patternConstraintKey: validationPatternRegex.time12

Allows any valid time in 12 hour format, seconds and leading 0s are optional.

Time24HPatternConstraint

patternConstraintKey: validationPatternRegex.time24

Allows any valid time in 24 hour format, seconds and leading 0s are optional.

UrlPatternConstraint

patternConstraintKey: validationPatternRegex.url

Allows any valid url; the prefixes http://, https://, or ftp:// are required.

NoWhitespacePatternConstraint

patternConstraintKey: validationPatternRegex.noWhitespace

Any characters except for whitespace are allowed.

JavaClassPatternConstraint

patternConstraintKey: validationPatternRegex.javaClass

Only values that would be valid java class names are allowed.

EmailAddressPatternConstraint

patternConstraintKey: validationPatternRegex.emailAddress

Only valid email addresses are allowed.

TimestampPatternConstraint

patternConstraintKey: validationPatternRegex.timestamp

Only valid timestamp values are allowed.

YearPatternConstraint

patternConstraintKey: validationPatternRegex.year

Any year from the 1600s to the 2100s is allowed.

MonthPatternConstraint

patternConstraintKey: validationPatternRegex.month

Any valid month, by number, is allowed.

ZipcodePatternConstraint

patternConstraintKey: validationPatternRegex.zipcode

Any valid US zip code, with or without its 4 number postfix, is allowed.

In addition to the above defined ValidCharacterConstraints, you can define your own ValidCharactersConstraint by defining the regex property "value" directly. This is an additional configuration option, similar to defining a custom ConfigurationBasedRegexPatternConstraint, the only difference being that the regex value is defined at the bean level and in a ConfigurationBasedRegexPatternConstraint it is defined in an imported properties file. Both custom configurations must have a messageKey defined.

  1 
  2 <bean parent="Uif-InputField" p:instructionalText="custom valid characters
  3     constraint - this one accepts only 1 alpha character followed by a period  and
  4     then followed by a number (a.8, b.0, etc)" p:propertyName="field1">
  5     <property name="validCharactersConstraint">
  6         <bean parent="ValidCharactersConstraint" p:value="^[a-zA-Z]\.[0-9]$"
  7             p:messageKey="validation.aDotNumTest"/>
  8     </property>
  9 </bean>
 10                 

A prerequisite constraint defines what fields must be filled out with this field (the field that the PrerequisiteConstraint is defined on). When this field is filled out, it requires the field set in the "propertyName" property of the PrerequisiteConstraint to be filled out as a result.

During client-side validation, whether that field comes after or before that field is irrelevant, as the UI will only notify the user when appropriate. For example, if you haven't yet visited a field that is now required, the user will only be notified of an error after they have first visited this newly required field and have not filled it out. Alternatively, if the field that is now required comes before the field that requires it, the user will be notified immediately. These mechanisms are set up to prevent the UI from showing errors before the user had a chance to interact with the corresponding field within the overall page flow.

A field can have any number of PrerequisiteConstraints in their "dependencyConstraints" property.

  1 
  2 <bean parent="Uif-InputField" p:propertyName="field1" >
  3     <property name="dependencyConstraints">
  4         <list>
  5             <bean parent="PrerequisiteConstraint" p:propertyName="field7"/>
  6             <bean parent="PrerequisiteConstraint" p:propertyName="field8"/>
  7         </list>
  8     </property>
  9 </bean>
 10                 

MustOccurConstraint is used to identify fields that are required before this field can be filled out. This is different from PrerequisiteConstraints because the number of fields required from a different set of fields can be defined.

The MustOccurConstraint's min and max properties define how many PrerequisiteConstraints (defined in its "prerequisiteConstraints" property) in combination with the MustOccurConstraints (defined its "mustOccurConstraints" property) must be satisfied for this MustOccurConstraint to pass. Essentially, either a satisfied PrerequisiteConstraint or a satisfied MustOccurConstraint counts as one toward the min/max.

The following MustOccurConstraint is valid when field11 has a value, or is valid when both field12 and field13 has a value (min="2" and max="2" in the nested MustOccursConstraint enforces that both must be filled out). However, in this case, filling out all three fields is also valid because of min="1" and max="2" on the top level constraint (there is one PrerequisiteConstraint and one MustOccursConstraint at the top level). Alternatively, setting a max="1" at the top level would make this constraint only allow one of the two conditions to be satisfied (otherwise, it would be invalid).

  1 
  2 <bean parent="Uif-InputField" p:propertyName="field1">
  3     <property name="mustOccurConstraints">
  4         <list>
  5             <bean parent="MustOccurConstraint">
  6                 <property name="min" value="1" />
  7                 <property name="max" value="2" />
  8                     <property name="prerequisiteConstraints">
  9                         <list>
 10                             <bean parent="PrerequisiteConstraint" p:propertyName="field11"/>
 11                         </list>
 12                     </property>
 13                 <property name="mustOccurConstraints">
 14                     <list>
 15                         <bean parent="MustOccurConstraint">
 16                             <property name="min" value="2" />
 17                             <property name="max" value="2" />
 18                             <property name="prerequisiteConstraints">
 19                                 <list>
 20                                     <bean parent="PrerequisiteConstraint" p:propertyName="field12" />
 21                                     <bean parent="PrerequisiteConstraint" p:propertyName="field13" />
 22                                 </list>
 23                             </property>
 24                         </bean>
 25                     </list>
 26                 </property>
 27             </bean>
 28         </list>
 29     </property>
 30 </bean>
 31                 

A CaseConstraint provides the ability to only apply a certain constraint when a defined case/condition is satisfied. The constraint or constraints used can be any of the above constraints, in addition to nesting another CaseConstraint within itself.

CaseConstraint has the following properties:

propertyName - the name of the field the case is using in the condition.

operator - the name of the operator to use in the condition. By default, this operator is EQUALS. Other operators available are NOT_EQUAL, GREATER_THAN_EQUAL, LESS_THAN_EQUAL, GREATER_THAN, LESS_THAN, and HAS_VALUE (the field defined in propertyName just has to have any value to trigger the case constraint when HAS_VALUE is used).

caseSensitive - set this to true if the condition should be caseSensitive when comparing values.

WhenConstraint list - a list of WhenConstraints which define the values for the condition to be satisfied. If one of the values in the "values" property satisfies the condition, the constraint defined in this WhenConstraint is applied to this field. Note that the value can also be the value of another field defined by the "valuePath" property – however, this does not work client-side in this release. The WhenConstraint also defines the "constraint" to be applied if the condition is satisfied with that value.

In order to define an "ANDed" CaseConstraint, nest another CaseConstraint into a WhenConstraint property. Alternatively, defining multiple WhenConstraints define an "ORed" CaseConstraint. Also, to apply multiple constraints for one value use multiple WhenConstraints with the same value defined.

The following code makes field1 required when field2 is equal to "valueA" or "valueB". It also makes field1 only allow alphanumeric input when field2 is equal to "valueA".

  1 
  2 <bean parent="Uif-InputField" p:propertyName="field1">
  3     <property name="caseConstraint">
  4         <bean parent="CaseConstraint">
  5             <property name="propertyName" value="field2" />
  6             <property name="whenConstraint">
  7                 <list>
  8                     <bean parent="WhenConstraint">
  9                         <property name="values">
 10                             <list>
 11                                 <value>valueA</value>
 12                                 <value>valueB</value>
 13                             </list>
 14                         </property>
 15                         <property name="constraint">
 16                             <bean parent="RequiredConstraint" />
 17                         </property>
 18                     </bean>
 19                     <bean parent="WhenConstraint">
 20                         <property name="value" value="valueA" />
 21                         <property name="constraint">
 22                             <bean parent="AlphaNumericPatternConstraint" />
 23                         </property>
 24                     </bean>
 25                 </list>
 26             </property>
 27         </bean>
 28     </property>
 29 </bean>
 30             

State-Based Validation allows you to change what validations (in other words, what Constraints) are applied to an object's fields as it moves through states over time, through user interaction, or any other mechanism that may affect a "state" of an object. One example of states in practice is workflow status.

If you do not setup states, the view is considered stateless and all Constraints that you setup will apply at all times (note: this behavior is unchanged from prior releases).

To setup state-based validation you must set the stateMapping property with a StateMapping object. The object MUST include a list of states and these states MUST be in order that the states are changed.

In addition to the states themselves, you can define a map for specifying what the state's name will be in the text of validation messages. The map stateNameMessageKeyMap takes the state as a key and a messageKey as a value for its entries. The messageKey is used to retrieve the human readable version of the message from the ConfigurationService.

The statePropertyName property of StateMapping allows you to specify the name/path to the property on the form which represents the state. By default this is set to "state" (meaning on the root form UifFormBase, stateMapping will use the "state" property to determine the state of the object). This can be changed to anything and is used with the new property of View called stateObjectBindingPath (the path to the "state" property will be determined as stateObjectBindingPath + statePropertyName).

The customClientSideValidationStates property is used strictly to define what state the client-side validation (see corresponding section) should use to validate during user interaction. By default, client-side validation will always validate against the "n+1" state. What that means is that client-side validation will always validate against the NEXT state (if one exists, otherwise the current state) of the object because that is what the user is trying to get to.

To change this behavior the customClientSideValidationStates map can be used to define what client-side validation will be used at each state. Its entries take the state of the object as the key and the state you want the client-side validation to validate against at that state as the value. States which don't have a custom client-side validation state default to the "n+1" case, as normal.

Example of stateMapping with some of these properties set (note that state names themselves are for example purposes only):

  1    <property name="stateMapping">
  2       <bean parent="StateMapping">
  3         <property name="states">
  4           <list>
  5             <value>state1</value>
  6             <value>state2</value>
  7             <value>state3</value>
  8             <value>state4</value>
  9             <value>state5</value>
 10           </list>
 11         </property>
 12         <property name="stateNameMessageKeyMap">
 13           <map>
 14             <entry key="state1" value="demo.state1"/>
 15             <entry key="state2" value="demo.state2"/>
 16             <entry key="state3" value="demo.state3"/>
 17             <entry key="state4" value="demo.state4"/>
 18             <entry key="state5" value="demo.state5"/>
 19           </map>
 20         </property>
 21         <property name="customClientSideValidationStates">
 22           <map>
 23             <entry key="state1" value="state3"/>
 24           </map>
 25         </property>
 26       </bean>
 27     </property>

This example has 5 states, it defines a message key for each state, and for client-side validation when the view's object is in "state1" the client will validate against "state3" (it will also validate against "state3" in "state2" as normal). It is retrieving the current state of the object from the "state" property at the root of the form (default).

StateMapping also has some helper methods that can be called:

After you have the StateMapping object defined, you need to define states on your validation constraints to use state-based validation.

State-based Validation at the Controller

While the client-side validation is automatic (always validates against "n+1" unless configured otherwise), the server-side validation is completely up to the implementer. If you would like to validate your View (or alternatively DataDictionaryEntry), there are methods provided to do so. The main point is that server validation is NOT automatic and is application controlled. These new state-based validation methods are (some overloaded version not noted here):

For ViewValidationService (should be used for KRAD views):

• validateView(View view) - This is the main validation method that should be used when validating Views. This method validates against the current state if state based validation is setup.

• validateView(View view, ViewModel model, String forcedValidationState) - Validate the view against the specific validationState instead of the default (current state). If forcedValidationState is null, validates against the current state, if state-based validation is setup.

• validateViewAgainstNextState(View view, ViewModel model) - Validate the view against the next state based on the order of the states in the view's StateMapping. This will validate against current state + 1. If there is no next state, this will validate against the current state.

• validateViewSimulation(View view, ViewModel model) - Simulate view validation - this will run all validations against all states from the current state to the last state in the list of states in the view's stateMapping. Validation errors received for the current state will be added as errors to the MessageMap. Validation errors for future states will be warnings.

For DictionaryValidationService (recommended only when you don't have a view. Also note that state-based validation only works for DataDictionaryEntry backed objects with StateMappings setup):

• validate(Object object) – Validates against the current state (if state-based validation is set up).

• validateAgainstState(Object object, String validationState) – validates against the state specified by validationState.

• validateAgainstNextState(Object object) – validates against the next state as defined by the state mapping.

What is done in response to validation errors is also completely up to the implementation of the controller logic (it is recommended you halt action and return back the same view passed in, this will automatically display the discovered validation errors for the user).

Example of validating and checking errors (this simple example only changes the state on successful validation):

  1 //inside a controller method
  2 KRADServiceLocatorWeb.getViewValidationService().validateView(form.getPostedView(), form, "state2");
  3 if(!GlobalVariables.getMessageMap().hasErrors()){
  4    //do whatever you need to do on after a successful
  5    //validation here (save, submit, etc)
  6    form.setState("state2");
  7 }
  8 
  9 return getUIFModelAndView(form);

Figure 4.1. State-based Validation Server Errors

In this image, you may notice the "**" indicator. In KRAD, this means the field is required for the next state.

Over the past few years, web-based user interfaces have taken off. Many of these technologies have leveraged browser-based JavaScript and Cascading Style Sheets to create impressive effects or to radically increase interactivity by communicating with a web-server in between the normal request/response page cycle. Because of these huge advances, today's web application users have much higher expectations of interactivity.

The KRAD UIF aims to allow the development of rich web interfaces by offering a variety of rich components and behavior. This includes components like lightbox, suggest boxes, menu/tabs, and grid (table) features. Some of the 'behavioral' features include partial page refreshes, progressive disclosure, client-side validation, and AJAX queries. This is just a subset of the way that richer user interface functionality is offered by KRAD. Chapters 8 and 11 cover these features and more in detail.

One of the features of the Nervous System users pick up on quickly is the fact that so many screens can be generated purely through configuration. A business object lookup and inquiry, as well as the screen for maintenance documents: all can be generated entirely from an XML file. Freeing developers from having to concern themselves with the particulars of the HTML generation for these screens makes the user interface of Kuali applications more consistent, to say nothing of the boost to developer productivity it gives.

However, there were other screens which could not be so easily generated. Transactional documents depended on perhaps several JSP files, supported by hierarchies of traditional taglets. Non-document screens had to be coded in JSP as well. The KNS provided a standard library of taglets - such as documentPage, tab, htmlControlAttribute, and so on - which eased the development task a bit, but the hard fact was that developers still had to spend much more time coding these pages.

It should therefore be of little surprise that one of KRAD's major goals is improving this situation. If transactional documents and non-document screens could make use of the Rich UI support through configuration, that would make it much easier to develop these incredibly important pieces of functionality.

However, as any KNS developer knows, transactional documents are much more flexible than lookups or maintenance documents. Maintenance documents are almost always stacks of two or four columns, perhaps broken up by a standard sub-collection interface. Conversely, a transactional document can look like practically anything.

We have all had the experience of working with development frameworks to meet some special need that the framework did not provide 'out of the box'. In many cases, this is a painful process, requiring the developer to get inside the 'black box' and figure out many intricate details of the framework. Furthermore, once a solution is found, it might require we modify the core of the framework, causing maintenance and upgrade issues.

Similar issues were encountered when using the Rice KNS framework. In particular, the use of tags was problematic, in that there was no way to customize tag logic without breaking the upgrade path. In addition, the objects used for UI modeling were not extensible or customizable without modifying the Rice code. Therefore, an important goal for the UIF is to allow new UI features to be added, and current features to be modified without modifying Rice code. As we will see later, this is accomplished using a component framework and the power of Spring bean configuration.

A lot of user feedback about the Kuali Nervous System centered on the repetitive tasks of setting up configuration. Every business object has an object-relational mapping and an entry in the data dictionary; that entry is made up of field configurations, which gets tediously long fairly quickly.  And then there's building the corresponding Java code to be the actual business object. Even more pieces are added to this recipe when attempting to put together a document.

KRAD is adopting a series of design principles to alleviate some of the work required for this configuration. KRAD intends to introduce a series of simple-to-use tools to generate configuration based on defaults, letting developers focus on tweaking the configuration to match business logic.

KRAD is also simplifying configuration in general. The idea of "convention over configuration" will mean that standard defaults will be provided for what had to be manually configured before. These defaults can be overridden, but if they fit the needs of the application, no further configuration will be necessary. This will cut down a huge amount on the "XML push-ups" required by KRAD application developers, but still provide a great deal of flexibility.

The UIF builds on the KNS concept of using Spring bean XML to build UIs. XML files are created to configure and assemble UIF objects (called components). These files are then processed and loaded into the Data Dictionary container.

More Information: Although the UIF configuration is loaded into the same container as the Data Dictionary, conceptually we think of them as separate. A current practice within Rice is to have a resource directory for data dictionary files, and a resource directory for UIF files (per module). In addition, care was taken to allow for separate containers to be created (if desired at some point).

We will see that technically, using the UIF is very easy, since most things can be accomplished by a simple XML configuration. However, there is a challenge in knowing how to put the pieces together. To accomplish the amount of flexibility necessary, the UIF introduces a lot of concepts that will take some time to learn. Taken all together, these form a language for how Rice developers and UX leads will discuss, prototype, and finally build user interfaces. To help with this process, the UIM (User Interaction Model) was developed. The UIM is a collection of pages that document how to best make use of the UIF functionality. Such things as when to use one component over another, various configurations of a component, and overall UX concerns are documented within the UIM. Investing time to read through the UIM will help developers get up to speed with the UIF much quicker.

You can find the latest version of the UIM at the following URL: https://wiki.kuali.org/display/STUDENT/User+Interaction+Mode

A component is made up of three different artifacts (see Figure 5.1, “Building Blocks”). The first of these is a Java class. The Java class defines the properties and behavior the component can have. As we will see later on, the properties are what we can use to configure the component, while the behavior includes things such as how the component interacts with other components. As with any class, the properties can be primitive or collection types, or types of other objects. In this case of a component, these objects may be other components. Therefore components can be nested (or a composition). In addition, components may extend from other components to inherit properties and behavior. This forms a component hierarchy. The component class may exist anywhere on the class path.

Figure 5.1. Building Blocks

The second artifact for a component is its rendering template. The template is a FreeMarker file that renders HTML/JS contents for the component instance. The template is an optional artifact. Components may 'self-render', which means the component object will be invoked to return the HTML/JS contents (note FreeMarker content cannot be used in this mode). However, most UIF components use templates as they are much easier and cleaner to implement. We will learn all about templates in the next section.

The final piece of a component is its Spring bean definition. Spring bean XML is the mechanism by which developers configure and assemble UIF components. Creating a bean definition for the component (sometimes known as the 'base' definition) allows us to specify defaults for properties, in addition to giving the component a unique name within the bean container (note that it would be possible to use the component without a base definition, but then the class would have to be specified each time it is used).

One important property that is configured with the base definition is the template. The template property (available on all components) is the path to the template FreeMarker file that will render the component. Specifying the template through the bean configuration provides loose coupling of the component class and template. This is very important to the flexibility of the system. The template can be located anywhere in the web root for the application.

The base component definition also does a couple more things for us. One of these is setting up the component with scope prototype. All UIF components maintain state, so they must be marked as prototype within Spring. Finally, it is recommended the base definition be setup with an abstract parent bean. This setup looks like the following:

  1 <bean id="componentName" parent="componentName-parentBean"/>
  2 <bean id="componentName-parentBean" abstract="true" class="edu.myedu.Sample.Component" scope="prototype">
  3 ...
  4 </bean>    

This allows the base definition to be changed without having to copy the entire original configuration. Recall that Spring allows us to override a bean definition by specifying a bean with the same id. Therefore, if an institution wanted to change the default property for a component, they would simply include the following in the institutional spring files:

  1 <bean id="componentName" parent="componentName-parentBean">
  2     <property name="propertyName" value="overrideValue"/>
  3 </bean>    

Without the abstract parent bean, all of the initial property configuration would need to be copied (since setting the parent to "componentName" would cause a circular dependency).

When defining base definitions we are not limited to just one. In many cases, it is useful to provide different configurations of a component as different bean configurations. For example, one component we will learn about is the TextControl. The text control renders a HTML input of type text and has a size property, which configures the display size for the input. First, we might setup a bean definition that looks like the following:

  1 <bean id="Uif-TextControl" parent="Uif-TextControl-parentBean"/>
  2 <bean id="Uif-TextControl-parentBean" abstract="true" class="org.kuali.rice.krad.uif.control.TextControl" scope="prototype">
  3     <property name="template" value="/krad/WEB-INF/ftl/components/control/text.ftl"/>
  4     <property name="size" value="30"/>
  5 </bean>     

The control can then be used by bean references or inner beans:

  1 <property name="control">
  2     <bean parent="Uif-TextControl" p:size="10"/>
  3 </property>    

Notice here we are overriding the size property because we need a small input. Seeing this, we might decide we want to have a standard size for small, medium, and large inputs. Therefore we set the following bean configurations:

  1 <bean id="Uif-TextControl" parent="Uif-TextControl-parentBean"/>
  2 <beanid="Uif-TextControl-parentBean" abstract="true" class="org.kuali.rice.krad.uif.control.TextControl" scope="prototype">
  3     <property name="template" value="/krad/WEB-INF/ftl/components/control/text.ftl"/>
  4     <property name="size" value="30"/>
  5 </bean>
  6 <bean id="Uif-SmallTextControl" parent="Uif-SmallTextControl-parentBean"/>
  7 <bean id="Uif-SmallTextControl-parentBean" abstract="true" parent="Uif-TextControl">
  8     <property name="size" value="10 "/>
  9 </bean>
 10 <bean id="Uif-MediumTextControl" parent="Uif-MediumTextControl-parentBean"/>
 11 <bean id="Uif-MediumTextControl-parentBean" abstract="true" parent="Uif-TextControl">
 12     <property name="size" value="30 "/>
 13 </bean>
 14 <bean id="Uif-LargeTextControl" parent="Uif-LargeTextControl-parentBean"/>
 15 <bean id="Uif-LargeTextControl-parentBean" abstract="true" parent="Uif-TextControl">
 16     <property name="size" value="100 "/>
 17 </bean>     

Now when we need a small text control, we can reference the 'Uif-SmallTextControl' bean and not specify the size:

  1 <property name="control">
  2     <bean parent="Uif-SmallTextControl"/>  
  3 </property>      

Many of the components provided by the UIF have multiple base bean definitions.

We know that a major goal of the UIF is to provide a high level of flexibility. Furthermore, we have seen the central concept of components. So how does this component design achieve our goal?

To answer this question, let's first take a look at what criteria we should look for in a highly flexible system.

Recall besides the base 'plumbing' of the UIF, a set of components is provided to build pages with. Each of these components brings a piece of functionality to the framework. Thus we can think of them as 'building blocks' for the framework as shown in Figure 5.2, “Building Blocks”.

Figure 5.2. Building Blocks

Now let's suppose we want to customize a 'core' component.  To do this, we simply change one of the component parts (class, bean, or template). We saw previously how we can change the bean configuration for a component by providing another bean configuration with the same id. Using the abstract parent bean, we can inherit all of the original configuration and then change or add configuration as needed.

For an example of this, let's use the UIF 'required' message field which has the following definition:

  1 <bean id="Uif-RequiredMessage" parent="Uif-RequiredMessage-parentBean"/>
  2 <bean id="Uif-RequiredMessage-parentBean" abstract="true" parent="Uif-MessageField" 
  3     scope="prototype" p:messageText="*" p:messageType="REQUIRED">
  4 ...
  5 </bean>    

We decide for our application we want the required message to actually display the text 'required' instead of the configured asterisk. To do this we include a bean with the same id in our application (or institutional spring) file:

  1 <bean id="Uif-RequiredMessage" parent="Uif-RequiredMessage-parentBean" p:messageText="required" />    

Now everywhere the required message field is used the text 'required' will display instead of '*'.

Next let's consider the component template. Remember the template is a FreeMarker file located in the web root (or classpath) and generates the HTML/JS contents for the component. If we wish to change this rendering, we can create another template in a web location of our choosing.

Depending on the level of customization we need to implement, we might start by copying the current template contents, or create one from scratch. One we have the template that renders the component how we want, then we override the bean configuration as described previously and override the template property specifying the location for the new template. Besides the source location for the template, there is the templateName property which specifies a name for the template in the host language (the name by which the template is invoked). This must be unique, so that when overridding a template, we must also give a unique name for the template (unless we are overriding the base bean definition itself):

  1 <bean id="Uif-TextControl" parent="Uif-TextControl-parentBean"/>
  2 <bean id="Uif-TextControl-parentBean" abstract="true" class="org.kuali.rice.krad.uif.control.TextControl" scope="prototype">
  3     <property name="template" value="/krad/WEB-INF/ftl/components/control/text.ftl"/>
  4     <property name="templateName" value="uif_text"/>
  5     <property name="size" value="30"/>
  6 </bean>
  7 <bean id="Uif-TextControl" parent="Uif-TextControl-parentBean">
  8     <property name="template" value="/myapp/WEB-INF/ftl/components/text.ftl"/>
  9     <property name="templateName" value="myapp_text"/>
 10 </bean>    

The last part of the component we have to customize is the Java class itself. Modifying the Java class would allow us to add new properties and behavior to the component. For this, we can create a new class that extends the original component class. This new class can be anywhere in the classpath. New properties can be made available by adding properties to our extension class (with getters and setters). Customization of behavior can be modified by overriding the various lifecycle methods. These methods will be covered in Chapter 9. Once we have the new class, we associate it with the component by again overriding the bean definition:

  1 <bean id="Uif-TextControl" parent="Uif-TextControl-parentBean"/>
  2 <bean id="Uif-TextControl-parentBean" abstract="true" class="org.kuali.rice.krad.uif.control.TextControl" scope="prototype">
  3     <property name="template" value="/krad/WEB-INF/ftl/components/control/text.ftl"/>
  4     <property name="size" value="30"/>
  5 </bean>
  6 <bean id="Uif-TextControl" parent="Uif-TextControl-parentBean" class="edu.myedu.Sample.TextControl">
  7     <property name="additionalProperty" value="foo"/>
  8 </bean>    

Now that we have seen how to customize a component, how do we go about adding a new component? We can add a component using the same process we saw for customization. The difference between adding and customizing are:

Essentially we need to create the three artifacts for the component just like the core components. Once created, using custom components is no different than using the provided components.  Therefore as depicted in Figure 5.3, “Building Blocks”, core and custom components work together as part of the framework.

Figure 5.3. Building Blocks

Given that the goal of the UIF is to produce web pages (HTML, Image, and JS content); the component template provides a very important role. This section will help us understand templates better, and how they are built using the FreeMarker templating engine.

Before looking at templates in KRAD, let's step back and think about the job of building a web UI framework. We know web pages are rendered by a browser from HTML markup, along with other resources such as script and image files. So ultimately, the result from our framework is this markup that will be streamed back as the response to a request by the user. This is the output of the framework. The input to the framework will be XML configuration provided by an application developer. So how do these get connected?

Based on our Spring knowledge, we know the XML metadata will get used to create Objects in the Spring container, so these objects' instances now contain the developer's configuration. We can then expose these objects to the FreeMarker templates, which will combine the object values with static contents to produce the resulting markup (see Figure 5.1, “Building Blocks”).

Templates within KRAD are created using the FreeMarker framework. FreeMarker is a templating framework that allows template files to be assembled at runtime. To create a template in FreeMarker, we start by creating a file with extension .ftl. This can be anywhere in the application web directory or classpath.

Now we can add static HTML content (just like creating an HTML page) along with dynamic content using the FreeMarker language:

  1 <html>
  2   <head><title>${KualiForm.title}</title></head>
  3   <body>
  4     <table>
  5       <tr>
  6         <td colspan="2">${KualiForm.header}</td>
  7       </tr>
  8       <tr>
  9         <td>${menu}</td>
 10         <td>${body}</td>
 11       </tr>
 12       <tr>
 13         <td colspan="2">${KualiForm.footer}</td>
 14       </tr>
 15     </table>
 16   </body>
 17 </html>     

Notice within this file the use of '${}' notation. This is known as an interpolation, and is where data will be inserted. This data comes from a model we expose to FreeMarker before rendering the templates. The model is a map of objects that can be referenced within the FreeMarker templates. The map key gives the name by which the object is identified. In KRAD, one object that is exposed by default is the form object. This object is a wrapper for all the data that needs to be present for rendering the page, and is given the identifier 'KualiForm'.

Other objects exposed through the model are:

Now suppose we want to pull out part of our FreeMarker content into a separate file, so that it can be reused between different templates. First we create another file with .ftl extension. Let's call this file body.ftl. Now we add the FreeMarker content to our template file:

  1 <h2> This is the page body </h2>
  2 ${KualiForm.body}

Next, we can bring in the contents of body.ftl into our main template by using the FreeMarker directive named include. To use the include directive we specify the absolute or relative path to the template file that should be included using the path attribute:

  1 <html>
  2   <head><title>${KualiForm.title}</title></head>
  3   <body>
  4     <table>
  5       <tr>
  6         <td colspan="2">${KualiForm.header}</td>
  7       </tr>
  8       <tr>
  9         <td>${menu}</td>
 10         <td>
 11            <#include path="body.ftl"/>
 12         </td>
 13       </tr>
 14       <tr>
 15         <td colspan="2">${KualiForm.footer}</td>
 16       </tr>
 17     </table>
 18   </body>
 19 </html>     

Interpolations may also contain expressions (see below). For example, we can add two numeric properties together and render the result as follows:

  1 ${KualiForm.numProp1 + KualiForm.numProp2}

With FreeMarker we are not limited to just reading properties from the model, but also may invoke methods! This is done using the method name within the expression, followed by list of values to send as parameters. The parameter values may reference another model property or variable:

  1 ${KualiForm.retrieveTaxAmount(taxNumber, 'T')} 

In addition to accessing dynamic data within the model, we can create new dynamic variables within the template. To create a new variable the assign directive is used. Following the assign keyword, the name and value for the variable are given separated by an equal:

  1 <#assign myVar="Hello!"/>

Similar to model properties, the value for a variable can be written to the output stream using the ${} notation:

  1 <td>${myVar}</td> <#-- prints <td>Hello!</td> -->

When assigning a variable value, we may also use an expression. Freemarker supports all of the standard expression operators. The only notable difference is Freemarker does not support the alpha operator representation ('eq', 'ne', 'lt', 'or'). Operators are specified with the usual '==', '!=', '&&', '||' and so on. The one exception in Freemarker is for '>','<','>=','<=" operators, the alpha operator can be given as well. The full list of expression operators is found here.

Let's take a simple case of addition as an example:

  1 <#assign groupOneTotal=50/>
  2 <#assign groupTwoTotal=100/>
  3 <#assign totalBothGroups=groupOneTotal + groupTwoTotal/>

When working with model properties or variables, it is important to know the underlying datatype. The datatype determines how the variable can be used within the markup (for example in expressions, interpolations, and passing macro parameters).

The datatypes used by FreeMarker are String, Number, Boolean, and Date (Scalars); Hash, Sequence, and Collection (Containers); Methods and Custom Directives (Subroutines); and Node.

Datatypes are implied by FreeMarker in one of two ways. For model properties, the datatype is derived from the underlying Java type. For variables, the datatype will be derived based on the assigned value. All string values must be quoted. If value is not quoted, the datatype will be determined based on the format. The keywords true and false are used to indicate a boolean type.

  1 <#assign var="Hello"/> <#-- string datatype -->
  2 <#assign var=3/> <#-- numeric datatype -->
  3 <#assign var=true/> <#-- boolean datatype -->
  4 <#assign comp=model.comp/> <#-- assuming model.comp is object, hash datatype -->

Interpolations may only be used for variables/properties that are scalars. FreeMarker converts number and date types to a string format based on the environment settings. Boolean types must be explicity converted to a string using the built-in '?string'.

When passing parameter values for macro invocations, we must also be aware of the datatypes expected by the macro. Passing a quoted parameter value where the macro expects a number or boolean will cause an error. In the following example, the macro with name 'grid' expects a parameter named 'rowCount' of type number:

  1 <#macro grid rowCount>
  2   ...
  3 </#macro>
  4 
  5 Incorrect Invocation:
  6 <@grid rowCount="3"/>
  7 
  8 Correct Invocation:
  9 <@grid rowCount=3/>

FreeMarker allows us to conditionally evaluate a block of markup, or to evaluate a block of markup multiple times through the use of control statements. A control statement is implemented using one of the following directives:

if, else, elseif

We can conditionally evaluate a block using the if directive. Following the if or elseif directive is an expression to evaluate. If the expression evaluates to true, the corresponding block will be included, otherwise the block given by the else directive (or the next expression) is evaluated if an elseif directive follows. The general syntax is as follows:

  1 <#if expression1>
  2   // block
  3 <#elseif expression 2>
  4   // block
  5 <#elseif expression n>
  6   // block
  7 </#if>

In the following example we have a variable named colCount which holds an integer:

  1 <#if colCount == 1>
  2   // block 1
  3 <#elseif colCount == 2>
  4   // block 2
  5 <#else>
  6   // block 3
  7 </#if>

In this example, we first check if the variable colCount is equal to 1, if so block 1 is evaluated. If not, we check whether colCount is equal to 2 and if so evaluate block 2. If neither conditions are true, block 3 will be evaluated.

list

The list directive allows us to loop through a variable (or model property) which is a sequence (array) type and evaluate a block within each iteration. This is a useful control statement for rendering items like a table or repeated sections. The list directive is used by specifying the variable/model name followed by a variable to expose each item under. The general syntax is as follows:

  1 <#list sequenceName as item>
  2    // block
  3 </#list>

Let's take an example where we assume we have a model property named 'foods' that is a List. Within the list body, the item being iterated over will be exposed with the variable 'food':

  1 <#list foods as food>
  2   Name: ${food.name}, Type: ${food.type}
  3 </#list>

If the datatype to iterate over is a Map, we can iterate using the list directive to iterate over the keys of the map like the following example:

  1 <#list map?keys as parm>
  2   ${map[parm]}
  3 </#list>

Here the loop variable gives the key for the map entry we are iterating over.

In addition to the loop variable exposed by the list directive, two additional variables are exposed. The first gives the index for the item and is retrieved by adding '_index' to the loop variable. The second indicates whether there are more items to iterate over and is retrieved by adding '_has_next' to the loop variable.

Finally, the break directive exists to exit the list directive early, as the following example demonistrates:

  1 <#list seq as x>
  2   ${x}
  3   <#if x = "spring"><#break></#if>
  4 </#list>    

By default, templates that are executed (by include directives) all belong to the same namespace. This means each template has access to read and write the same variables. A change to the value of a variable in one template, will change the value of the variable in another. This namespace shared by templates is known as the global namespace.

To execute FTL code in a separate namespace, FreeMarker allows the creation of Macros. Macros are created using the macro directive and are given a name that can be used for invocation. For example, we can change our previous body.ftl to become a macro as follows:

  1 <#macro body>
  2   <h2> This is the page body </h2>
  3   ${KualiForm.body}
  4 </#macro>

The name for the macro follows the #macro keyword. In this example we have named our macro 'body'. Between the macro start and end tag we can add FreeMarker content just as we would for a general template file. Each time the macro is invoked, this FreeMarker content will be evaluated. Therefore macros give us a way to reuse FreeMarker markup.

Within the macro we can define new variables. As with a general template, we can use the assign directive to create a variable in the global namespace. However, since a macro has its own namespace, we can create a variable that is scoped to it as well. This is done using the local directive. The syntax for using the local directive is the same as the assign directive.

  1 <#macro body>
  2   <#local locVar="is only visible within macro"/>
  3 <#macro>

If a global variable exists with the same name, the local variable will override within the context of the macro.

Macros may parameterize the content by accepting parameters. These parameters are given when the macro is invoked and are used within the macro body for evaluating the final output. Each parameter has a name by which it is identified. Therefore, to declare macro parameters, we simply list their identifying names on the macro directive after the macro name. Each parameter name is separated by a space:

  1 <#macro macroName parm1 parm2 parm3 parm4 ...>

Within the macro the parameters become local variables. We can print the parameter value to the output stream, use in a conditional statement, or use in any other way supported by variables. For example, let's add a header, bodyContent, and footer parameter to our body macro:

  1 <#macro body header bodyContent footer>
  2   <body>
  3     <table>
  4       <tr>
  5         <td colspan="2">${header}</td>
  6       </tr>
  7       <tr>
  8         <td>${menu}</td>
  9         <td>
 10            ${bodyContent}
 11         </td>
 12       </tr>
 13       <tr>
 14         <td colspan="2">${footer}</td>
 15       </tr>
 16     </table>
 17   </body>  
 18 </#macro>

Notice in this example we are writing out the values of the given macro parameters using the ${} notation. Our body macro serves as a wrapper for the content.

For each macro parameter we can also specify whether a value is required to be given by the caller, and if not a default value to use. A default value is indicated by placing an equal sign after the parameter name, followed by the default value (which can be an expression). If a default value is not given, the parameter is assumed to be required. All required parameters must be given before parameters that have defaults. Let's take a look at an example:

  1 <#macro body bodyContent header="Header One" footer="">
  2 ...

Here we have changed the body macro to make the bodyContent a required parameter, but not the header or footer. If the header parameter is not specified by the caller, it will have a value of "Header One". Likewise, if the footer is not given, it will have a value of the empty string.

When a macro is loaded, it becomes a variable within the associated namespace. The macro name (identifier given after the macro declaration) becomes the variable name, and the assigned namespace is derived from the surrounding namespace of the FreeMarker file (see Including FTL Files).

If the macro belongs to the global namespace, it can be invoked with the text '<%' followed by the macro name. Any parameter values are then given after the macro name (separated by a space). Each parameter specification includes the parameter name, followed by the equal sign, followed by the parameter value (which can be an expression). The macro invocation is completed with the closing greater than sign.

As an example, let's invoke our body macro created in the previous section, passing a value for the 'bodyContent' parameter:

  1 <@body bodyContent="Hello KRAD World!"/>

or

  1 <#assign content="Hello KRAD World!"/>
  2 <@body bodyContent=content/>

When the macro is associated with a namespace, we must specify the namespace before the macro name, using a dot to separate each. Let's assume our body macro was associated with the namespace 'myapp'. We would then invoke the macro as follows:

  1 <@myapp.body bodyContent=content/>

Macros are very powerful constructs that allow great flexibility! Up to this point we have invoked macros by simply passing parameter values. A macro may also allow us to pass FreeMarker markup within the body of the macro tag. The macro can then render this content in one or more locations of the macro. To indicate where this content should be rendered, we use the nested directive. The nested directive may be used more than once within the macro definition:

  1 <#macro wrapTd>
  2   <td>
  3   <#nested/>
  4   </td>
  5 </#macro>
  6 
  7 Invocation:
  8 <@wrapTd>
  9   <#if renderHeader>
 10     ${header}
 11   <#else>
 12     ${footer}
 13   </#if>
 14 </@wrapTd>

Assuming renderHeader is true, and the header variable is 'Header One', the following would be output:

  1 <td>
  2 Header One
  3 </td>

Another feature available for macros is varargs (variable number of arguments). To indicate a macro accepts a variable number of arguments, the last parameter declaration must end with '...':

  1 <#macro loop parms...>
  2   <#list param.keys as key>
  3     ${parm[key]}
  4   </#list>
  5 <#macro>
  6 
  7 Invocation:
  8 <@loop parm1 parm2/>
  9 <@loop parm1 parm2 parm3/>

The parameter 'parms' becomes a hash, where the name for each additional parameter is the hash key and the corresponding parameter value the hash value. The macro may include other named parameters that are listed before the varargs declaration.

Finally, FreeMarker provides the ability to create macro functions. These are macros that will run not to render output, but to calculate and return a value. These are created using the function directive. The function directive is used the same as the macro with a few exceptions. First the function directive is assumed to return a value. Any variable that is created within the function (or a global variable) may be returned using the return directive. The return directive is used by giving the variable name after the return keyword (we also may return an expression that will be evaluated as the function return value).

Let's build an example function that returns the max of two numbers:

  1 <#function max number1 number2>
  2   <#if number1 > number2>
  3     <#return number1/>
  4   <#else>
  5     <#return number2/>
  6   </#if>
  7 <#function>

Functions also differ from Macros in how they are called. Recall functions return a value, therefore we can use them anywhere a value is expected. This includes within an interpolation, an expression, or variable assignment. In addition, passing parameter values is done using function syntax '(parm1, parm2, ...)' rather than key/value pairs. The following shows examples of invoking the max function above:

  1 ${max(number1, number2)}
  2 <#assign maxNum=max(number1, number2)/>
  3 <#if number3 > max(number1, number2)>
  4    // block
  5 </#if>

Similar to macros, functions may be associated with a non-global namespace. When this is so, the namespace must be given before the function name, and a colon separates each.

Freemarker provides several utility functions called Built-Ins that can be applied to a variable or expression. The built-ins that can be used depend on the underlying datatype, as shown by the grouping below. To invoke a built-in, we add the question character ('?') after the variable (or expression), followed by the built-in name and any parameters. The following shows the general form:

  1 ${someVariable?builtIn(parms)}

The return value of the built-in invocation becomes the value for the expression:

  1 <#assign name='Joe Smith'/>
  2 Rice <#-- prints 'Joe Smith' -->
  3 ${name?upper_case} <#-- prints 'JOE SMITH' -->

The following are other examples of built-ins provided.

String Built-Ins

substring(from, toExclusive) - Returns a substring of a given string starting at the given from index up to the given toExclusive index.

html - Escapes html markup

js_string - Escapes the string according to JavaScript string literals

length - Returns the number of characters in the string

lower_case - Lower cases the string

left_pad(length) - Left pads the string with spaces until it reaches the given length

right_pad(length) - Same as left pad, but pads with spaces to the right

contains(substring) - Returns true if the string contains the given substring

matches(regex) - Return true if the string matches the given regular expression

replace(stringToReplace, replacement) - Replaces all occurances of stringToReplace in the string with the given replacement string

split(splitString) - Splits a string into an array on occurances of the given splitString parameter

starts_with(string) - Returns true if the string starts with the given string parameter

trim - Removes leading and trailing whitespace

upper_case - Upper cases the string

Boolean Built-Ins

string - Converts the boolean to a string using "true" as true and "false" as false

string("yes", "no") - Converts the boolean to a string using the first string parameter if the boolean is true, and the second string parameter if the boolean is false

Other Built-Ins

has_content - Returns true if the variable is not null and is not empty (meaning if the variable has a size or length)

A template file may pull markup from another template file using the include directive. The include directive takes the path to the file as an argument, which may be expressed as a relative or absolute path:

  1 <#include '../footer.ftl'/>
  2 <#include '/krad/templates/footer.ftl'/>

FreeMarker also supports a second way of including template files for the purpose of library (or namespace) creation. This is done using the import directive. Again, we must give the path to the file as an argument. We can also give an additional argument that will identify the namespace the template contents should be associated with. In the next example we include a freemarker template file that contains several macro definitions, and associate them with the namespace 'myapp':

  1 <#import 'myapp.ftl' as 'myapp'/>

All the macros contained in myapp.ftl will be associated with the myapp namespace and must be invoked through that namespace. Note when using import, any output generated by the included template will be ignored.

Each component within the KRAD UIF has a template file that defines a macro for rendering the component. The template location and the macro name are then configured with the component definition. Each time an instance of the component is encountered, the macro will be invoked with the component instance.

Generally, the component macros do the following:

An important consideration when setting up a macro is how to setup the parameters. To help explain this, let's take a look at a sample text control:

  1 <@spring.input id="${id}" path="${path}" disabled="${disabled}" size="${size}" maxlength="${maxLength}"/>    

This snippet is invoking a spring input macro, which will then output the HTML input tag. We see some of the attributes this macro provides are id, path, disabled, size, and maxlength. Since this template is generic (in the sense that it should render all instances of the TextControl) the values for these attributes need to be variable. Now based on our knowledge of macros, we can create an input macro which will allow values for these variables (or attributes) to be specified by the calling template. This would look like the following:

  1 <#macro uif_input id path disabled size maxLength>
  2   <@spring:input id="${id}" path="${path}" disabled="${disabled}" size="${size}" maxlength="${maxLength}"/>  
  3 </#macro>  

The calling template would then be:

  1 <@uif_input id="${component.id}" path="${component.path}" disabled="${component.disabled}" 
  2 size="${component.size}" maxLength="${component.maxLength}"/>    

Here the component variable is the component instance that has been exported to the page.

Now let's suppose that a developer wishes to override the component class and template to provide a 'readonly' property. The template now looks like this:

  1 <#macro uif_input id path disabled size maxLength readOnly>
  2   <@spring.input id="${id}" path="${path}" disabled="${disabled}" size="${size}" maxlength="${maxLength}"
  3     readOnly="${readOnly}"/>  
  4 </#macro>    

In order for the readonly attribute to be passed in, the developer must also change the calling template and pass the corresponding component property value. This not only adds to the amount of work required for customizing a component, but also leads to general maintenance issues within the framework.

To solve this problem, KRAD passes the full component to the templates and not the individual properties of the component. Passing the full component makes changes our original macro to:

  1 <#macro uif_input component>
  2   <@spring.input id="${component.id}" path="${component.path}" disabled="${component.disabled}" size="${component.size}"/>
  3 </#macro>    

Now for the custom template, we simply make use of the new property without any changes to the calling template:

  1 <#macro uif_input component>
  2   <@spring.input id="${component.id}" path="${component.path}" disabled="${component.disabled}" size="${component.size}"
  3                  readOnly="${component.readOnly}"/>
  4 </#macro>    

In addition to providing more template flexibility, using the course grained parameters gives us a uniform way of invoking templates (as we will see in a bit, the framework provides a generic macro that can be used to render any component). Depending on the type of component, other parameters may be sent as well. The standard macro contracts are as follows:

Note that the macro parameter that contains the component instance is exposed under different names (group, field, element, ...), depending on the component type. The name is specified by the getComponentTypeName() method on the component.

KRAD also comes with macros that provide utility functions for creating templates. These can be referenced by the component macros to help with building content. For example, the div and span macros generate the corresponding HTML tags with standard attributes (such as id and class). These macros are exposed under the krad namespace, and are available by default to all component templates. The following shows an example of using the script wrapper tag:

  1 <@krad.script value="alert('hello');"/>

In Chapter 8 we will learn how to assemble UIF components into a View. The View is a component itself that, among other things, encapsulates all other components for our UI. It can also be thought of as a tree of components. The rendering processes starts by invoking the configured view template macro. The view template macro then in turn renders its child components, and so on, until the complete tree has been traversed. Therefore, the responsibility of a template is to not only render the necessary markup, but to invoke rendering for its child components. To help with this, KRAD provides the template macro.

The template macro requires the component parameter to be specified. This is the child component that should be rendered:

  1 
  2 <@krad.template component=childComponent/>
  3             

The template macro will then create the call for invoking the component macro, and passing the component parameter (and any additional parameters). Figure 5.4, “KRAD Rendering Process” depicts the rendering process.

Figure 5.4. KRAD Rendering Process

Besides invoking the template for the child component, the template macro performs the following:

We have already learned about one very important property that all components have – the template and template name. The template is the path to the FreeMarker file that will perform the rendering process (creating of HTML markup) for the component. The template name is the name of the macro by which the rendering can be invoked. Now let's look at some other properties that we get from ComponentBase:

Id – All components must have a unique identifier within a view. This id plays a critical role both server side and on the client. On the server, the id is used to pull a component from its containing view. A view can contain many components that are deeply nested. Iterating through this tree to find a particular component can require a lot of coding and add up to many wasted cycles. With the id we can 'index' the view such that a component can be retrieved in a single call.

On the client, the id becomes even more important. As is the case for many of the server side component properties, the id is used to populate the id attribute on the HTML element. This results in unique ids for all elements on the page. These ids can then be referenced by a script created by the framework or by the developer. Furthermore, it is also possible to build CSS based on the ids (although this is not the recommended strategy).

For generating the id values, there are a few options KRAD provides. First, the id can be assigned by the developer, or it can by generated by the framework. Manual assignment can furthermore be done in one of two ways. The first is to set the id by using the bean property tag. For example:

  1 <bean parent="Component">
  2     <property name="id" value="ks34"/>  

The second way to manual assign the component id is by using the bean id attribute:

  1 <bean id="ks34" parent="Component">  

Since the id bean attribute is already required in most beans (top level beans), it is often most convenient to take this approach. If both the bean id attribute and the id property are specified, the id property value will be used.

Note that when a bean inherits a bean definition, an id specified with the property tag will be inherited, while the id attribute of the bean tag will not.

  1 <bean id="ks34" parent="Component">
  2 ...
  3 </bean>
  4 
  5 <!-- this bean will not have a configured id -->
  6 <bean parent="ks34">
  7 ...
  8 </bean>   

If an id is not configured by one of the above mechanisms, the framework will generate and assign a unique id for the component. Ids are generated using a sequence that starts at 1 each time the view lifecycle is run (each request), and prefixed with 'u'. For example, the first few generated ids would be 'u1', 'u2', and 'u3'.

The component ids are assigned by the framework at the beginning of the lifecycle (the 'initialize' phase). This guarantees all components will have an id throughout the view lifecycle (important for script generation in addition to many other things). There is one twist, however. Some components are dynamically created while processing the view data (the 'applyModel' phase). For example, all collection row fields cannot be created until the collection data is available. In these cases, the configured component represents a 'prototype' for creating the dynamic components. The prototype will have an id that was manually or automatically assigned. For creating the dynamic component, the prototype is copied and then adjusted. This means the id value will be copied as well. In order to give the copy a unique id, the id is suffixed. In the example of collection rows, each id is suffixed with the line ('l0', 'l1', 'l2'...). For example, if the prototype has an id of 'u56', the field in the first collection line will have id 'u56_l0', in the second 'u56_l1', and so on. Other id suffixes used in the framework will be discussed in the various component sections.

Title – For most components, we can specify the title property. This property gives extra information for the component that will be available in the user interface. This is an example of a property that many components have, but is used differently between components. For example, one of the component types we will learn about in the next section is a Container. Components generally begin with a header (using the HTML header tag) and use the title property for the header text. Other types of components include Fields and Controls. The component types use the title property as the title attribute on the corresponding element they produce:

  1 <element title="component title property value"/>  

The title attribute value is most often shown as a tooltip when the user hovers over the element.

Title Property: The reason we say title property can be specified for 'most' components is that there are some that do not use this. Since the overwhelming majority do, it was added to ComponentBase for convenience.

Render – The render property is a Boolean that indicates whether the HTML markup should be generated for the component. When this is set to false, the configured template will not be invoked during the rendering process. By using conditional expressions to set the render property, we can make our view much more dynamic. Essentially the render property allows us to display or not display a component based on runtime conditions.

For example in the following configuration only field1 will be rendered:

  1 <bean parent="Uif-InputField"
  2     p:propertyName="field1"/> <bean parent="Uif-InputField"
  3     p:propertyName="field2" p:render="false"/>  

The default value for render is true, so if the render property is not specified the component will be rendered.

Hidden – The hidden property is similar to the render property in that it configures whether or not the component is displayed. However, when a component is hidden (and render is set to true), the corresponding template will be invoked to generate markup. The content is then surrounded with a div that contains a style of display none. This keeps the content from being visible. The content can be displayed by changing the CSS display style through script. This provides a mechanism for toggling the display of a component on the client. Later on, we will learn about jQuery, which among many other things, allows us to flip the visibility of an element by invoking the show or hide function.

ReadOnly – It is common to use the UIF for building forms that will collect data and perform a process on behalf of the user. There are a variety of components, such as controls and widgets, that allow the user to input data. These components have a state of editable (user input is allowed) or read only (user input is not allowed). To indicate a component should be in the read only state we can set the readOnly property to true. Again, this is a property that expressions are generally used for that sets the state based on a condition.

Since it varies how components allow user input, the impact of setting a component as read only varies. For example, read-only controls simply display the control value as HTML text. An action field, on the other hand (button, link, image), will not render when set to read only.

More Info: Components such as controls and action fields also support the disabled property. When these components are disabled they are in a read only state (no user input is allowed), however they are presented differently. Although the disabled appearance can be modified, generally the component appears as it does when editable (for example the actual control or button appears) but appears dimmed. The UIM provide guidelines for when to use disabled over readOnly.

By default, the component base bean definitions have the readOnly property set as a condition on the read only status of the parent. Recall that our View represents a tree of components, where each component contains zero or more child components. This is often referred to as a parent-child relationship. All components with the exception of the View have a parent. Thus if the parent is read only, the child will be as well.

One example of the parent-child relationships is the Container component. The purpose of a container is to hold other components and provide a layout. Therefore, the components in the container are child components, and the container is the parent component. Setting the container component as read only will make all components within the container read only. This is a convenient feature that simplifies configuration. For example, if we needed to make a group of fields read only, we can add the readOnly="true" property to the container component instead of adding the property to each field. Furthermore, since the View contains all the components, we can add readOnly="true" to make our entire web page read only.

Some views are always read only. One example of this is the Inquiry view which displays information about a data object instance. The InquiryView base bean has the readOnly property set to true. Therefore all components added to a view of this type will be read only without having to specify the property.

Required – When a component allows user input, the required property indicates whether the user must provide a value (or complete the input/action). This is most typically used with input fields that have a control, but can also be used with a container (group) to indicate a section must be completed (fields in the section must have input). Other components may use the required attribute in a way that is appropriate for the component.

In the case of input fields, setting required to true will do a couple of things. First, a message will be displayed to the user indicating if it is required (by default an asterisk '*'). Second, the framework will perform validation client side and/or server side that checks a value was given. If the value is empty, an error message is created and presented to the user.

Style and Style Classes – KRAD provides a lot of flexibility to make your web applications look great! All UIF components have a configured style class that performs the visual treatment. These style classes are provided within the CSS files that come with KRAD. However, if needed, using the style properties we can add or override CSS configuration for each component.

Inline style configuration can be specified using the style property. The value is then placed as the style attribute value for the corresponding HTML element. Likewise, style classes can be specified using the styleClasses property. This property is a list type with each list item specifying a style class. The configured style classes are concatenated into a string using a space delimiter, then output as the class attribute value for the corresponding element.

Progressive and Refresh – Component base contains several properties that relate to configuring progressive disclosure or component refresh functionality. This is covered in detail in Chapter 11.

Order – KRAD adds some abilities to the Spring configuration system, including more control over collection merging. In a base bean definition that contains a collection, each component in the collection can have an order specified. When inheriting the collection property in child beans, components can be specified with the same order to replace items in the parent list or given an order that inserts the component between two items of the parent collection. This feature in covered in more detail at the end of this chapter.

  1 <property name="readOnly" value="@{#parent.readOnly}"/>     

Skip In Tab Order – By default, tabbing will follow the natural order of the elements and include each element that can accept focus. When needed, the element corresponding to the KRAD component can be taken out of the tab order (will not be tabbed to) by setting the skipInTabOrder Boolean to true. An example of where this might be needed is a widget. The widget might contain several elements that work together as one focusable item. Within the item, keyboard shortcuts can be provided for navigating to the various elements. The user can simply tab again to get out of the widget (instead of having to tab possibly several times).

More finely grained control over the tabbing order can be configured as well using the tabIndex property of Control.

Finalize Method To Call – Although you can do a great number of things using XML, you also have the option of assembling components with code. One way to invoke code is with the finalizeMethodToCall. This is the name of a method on the ViewHelperServiceImpl that should be called during the finalize phase of the view lifecycle. Standard arguments to this method are the component instance and the model (view data). Two additional properties, finalizeMethodAdditionalArguments and finalizeMethodInvoker, exist for greater flexibility on invoking a method. Code support is covered in detail in Chapter 10.

Self-Render and Render Output – As described in the section on templates and Apache Tiles, most components are rendered by a FreeMarker file that combines parameters from the components with static content to produce HTML markup. Components may render without a template by generating the markup through code. This is done by setting the selfRender flag to true. When this flag is turned on, instead of invoking a template, the method getRenderOutput will be invoked on the component instance to return the markup that should be output.

Component Security – KRAD allows for fine-grained security to be defined, which integrates with the KIM (Kuali Identity Management) module. Security restrictions are indicated by setting a flag on an org.kuali.rice.krad.uif.component.ComponentSecurity instance. When a flag is set, the framework will check a KIM permission (setup for that restriction type) and, if not granted to the user, the restriction will be activated. Particular security flags will be discussed while looking at each component.

Component Modifiers – Component modifiers are classes that can be configured on a component to modify its properties through code. A component may have one or more component modifiers that get applied in the order they are configured. Modifiers can be useful in many cases. For example, the maintenance framework supports a comparison view where an 'old' and 'new' field is presented for each field. To achieve this, a component modifier was created that reads the configured group fields copying each to make the 'old' field. Then a base bean was created with the component modifier configured. All maintenance groups then extend this bean and inherit the comparison feature.

Component modifiers can also have a condition that determines whether it should run (the runCondition). In the example of the maintenance modifier, we only want to show the comparison when doing an edit operation (not for a new or copy). Therefore, the run condition is setup to check that the maintenance action is edit. The framework will evaluate this condition and only invoke the modifier if the condition succeeds.

There are many other things that can be done with component modifiers which will be covered in Chapter 10.

Template Options – Besides the properties a component class has, some component templates support options that can be configured using the templateOptions map. These can be thought of as 'pass-through' parameters since the component class is not aware of them.

Template options are used primarily with Widgets that invoke a jQuery plugin. All jQuery plugins have a standard options map (or object since this is JavaScript) that configures the plugin options. This options map is created from the template options.

Property Replacers – Another tool provided by the UIF for component configuration are property replacers. A property replacer allows us to exchange the value for a bean (component) property based on a condition. For example, we can change the control for a field from a text control to a checkbox control if some condition is true. Or, we might want to change out a complete list of container fields with another. In a sense, property replacers give us the capability to have if statements in our XML.

A component may have one or more property replacers defined. In addition, one or more property replacers can be configured for the same property. Each property replacer whose condition passes will be applied, so the order in which they are configured can matter. Property replacers will be covered in Chapter 10.

Context – One very powerful feature of the UIF is the ability to use EL (Expression Language) statements in XML. The expressions are evaluated using the Spring EL framework. Spring EL allows us to define variables that can be referenced within the expressions. The UIF provides these variables from the component context map.

Each entry of the context map represents a variable, where the map key is the name of the variable (how it will be referenced in the expression), and the map value is the value Spring should use for the variable. The framework adds standard variables to the context for all components. Some examples include the 'view' and 'component' variables. Additional variables are added based on the component. For example, components within a collection group receive the variables 'line' and 'index' for referring to the current line. Finally, custom variables can be added to the context either through the XML configuration for a component, or by code. More information on expressions will be covered in Chapter 10.

In addition to implementing the Component interface, ComponentBase implements the org.kuali.rice.krad.uif.component.ScriptEventSupport interface. This allows a component to specify whether a given jQuery event is supported, and to retrieve or set the JavaScript code for that event. For example, let's take the onblur event. If a component supports this event, it will implement the getSupportsOnBlur method and return true. Script for the onblur event can then be set through the XML by using the onBlurScript property. Finally, when rendering the component, the template tag will retrieve the onBlurScript and associate with the onblur event. A listing of all events and examples will be given in Chapter 11.

HTML provides us tags (known as 'elements') we can specify that will be read by the browser to render some type of content. Examples of this include:

As we see by the tag descriptions, these tags and others like them generate some content that is visible to the user. The components that represent these tags (or will render these tags) are known as Content Elements. The following is a mapping of the above tags to its UIF component:

A special type of content element is one that allows the user to provide data input. These elements are known as Form Elements or Controls. Controls are only valid within an HTML form which will collect the data and post to a configured server location. Controls come in different types that determine how the user can provide data. Some HTML control examples are as follows:

Within the UIF, these types of components are also known as controls. Unlike the previous content elements, there is not a one-to-one mapping between the tag and control component. Instead, the UIF provides a component for each input type. Some examples include:

Controls all implement the org.kuali.rice.krad.uif.control.Control interface, which has the base class org.kuali.rice.krad.uif.control.ControlBase.

Besides the various content elements HTML provides us, we also can use tags that allow us to group content for layout purposes. One such element is the span. The span element defines a section of the document and includes one or more content elements. Essentially, it is a wrapper for other elements.

Spans are very important for layout purposes. They give us the ability to put together more than one element and have it treated as a 'block' in the layout being employed. A good example of this is the pairing of a label and control, where the label should appear above the control. If we wanted several of these pairings to align in a horizontal row, we would need to resort to a table. Wrapping each pairing in a span, however, tells the browser these elements work together and should take up one place in the layout. Furthermore, the default display property for span elements is inline, so additional spans will align in a horizontal row.

In the UIF, these span wrappers are known as Fields. There are several different Field components provided which have preset content elements, therefore, you don't have to do the work of composing a content element with a Field. Some examples include:

In addition to wrapping content elements, the Field component also provides a label. This is a label for the span contents, and its placement is configurable.

All Fields implement the org.kuali.rice.krad.uif.field.Field interface, which has the base class org.kuali.rice.krad.uif.field.FieldBase.

So far in this section, we learned about the basic HTML content elements and the span wrapper. We could write a page with these elements, and the browser would render it based on the order of these elements and their styling. However, in many cases we want to form larger groupings with their own layouts. For this, HTML provides the div element.

The div element is similar to span in that it wraps elements. However, div elements are generally used to divide larger sections of the page and can include content elements, along with the span element. The UIF generates the div element using the Group component.

The group component is an implementation of a more general type of UIF component named Container. The main job of container components is to hold a configured list of components and render them using a layout. A container is divided into three parts: the header, the body, and the footer. Generally, these appear in the user interface as show by Figure 5.5, “KRAD Container Parts”.

Figure 5.5. KRAD Container Parts

Besides the group component, another type of container is a View. Views do many things in the framework that will be discussed throughout this manual, including the container duty. A view instance actually contains all other components of an interface. That is, a view is at the root of the component tree and is not contained within any other component. In addition, the container items we configure for a view must be groups (conceptually known as 'Pages').

Containers may restrict the types of components they can hold. For example, KRAD provides a LinkGroup which is a type of group that only allows link components to be configured. Generally, these containers restrict the components they can hold so that they can provide more specialized properties and behavior.

Today we have the ability to do a lot more in our web applications, beyond using the basic HTML elements. With the use of JavaScript and frameworks such as jQuery, we can have features such as menus, tabs, trees, and dialogs in our user interface. These features are achieved by composing the HTML elements with script. Within the UIF, components that generate such content are known as Widgets.

This is a component type that has a lot of variety. However, the commonality is we typically create widgets not by rendering HTML elements and attributes, but instead by invoking script. To be more specific, most widget templates invoke a jQuery plugin passing in parameters from the templateOptions map.

We can also think of widgets as client side components. Unlike the other UIF components that generate their HTML markup server side, widgets generate content on the client during page load. Widgets are explained further in Chapter 8.

Just as HTML elements can be composed, so can the UIF components. These compositions can be fixed based on the property type, or variable. For example, the LinkField is a fixed composition of a Link component with the Field component:

public class LinkField extends FieldBase {
    ...
    private Link link;
}   

An example of a variable composition is the Group container with the items list that can accept any component:

public class Group extends ComponentBase { 
    ...
    private List<Component> items;
}

Although it is possible to have any composition of components between the various types, there are certain guidelines:

The below figure depicts the composition of components.

Figure 5.6. KRAD Component Hierarchy

This file contains bean definitions that are related to component configuration. That is, the beans don't represent components, but classes that are used to configure a component. Some examples include component modifiers, history, binding info, and filters.

This file contains bean definitions for control components. Examples include TextControl, CheckboxControl, FileControl, and the SelectControl.

This file contains bean definitions that are related to the Document view type. This includes the Document View bean, common document group and field beans.

This file contains bean definitions for the various field components. Examples include DataField, InputField, ActionField, and ImageField.

This file contains bean definitions for the various group components. Multiple bean definitions are provided for the group component that configure different layout managers. Examples include VerticalBoxGroup and HorizontalBoxGroup. In addition, bean definitions exist for the group level (page, section, and sub-section). Finally beans exist for the disclosure option and special types of groups like the TreeGroup.

This file contains bean definitions for header and footer groups. Headers and footers are defined for various group levels (page, section, and sub-section), along with collection groups. Finally the basic h1 through h6 header components are defined.

This file contains bean definitions that are related to the incident report view.

This file contains bean definitions that are related to the Inquiry view. This includes the Inquiry View bean, and definitions for inquiry groups.

This file contains bean definitions for the provided layout managers. In addition, common layout manager configurations are provided as separate beans.

This file contains bean definitions for the Lookup view. This includes the Lookup View bean, and definitions for lookup groups.

This file contains bean definitions for the Maintenance view. This includes the Maintenance View bean, and definitions for the maintenance groups.

This file contains bean definitions for other Rice modules. Examples include the KIM person and KIM Group controls.

This file contains bean definitions for the various view and page components. This includes the default View, Form View, and Page beans. Also included is the configuration for the base theme.

This file contains bean definitions for the various widget components. Examples include DatePicker, Lightbox, Breadcrumbs, and Tree.

Note that a full listing of beans contained in the above files is given in Appendix A.

See the section called “View Themes”

Themes can easily be modified on an application basis, view basis, or component basis. There are two ways to modify a theme. First, we can create additional style sheets and script files that are included with our views. These files may set anywhere within the application web directory, or they can be accessed through a different web server. To add the additional files, we use the additionalCssFiles and additionalScriptFiles properties on the view component:

  1 <bean id="MyView" parent="Uif-FormView"> 
  2     ...
  3     <property name="additionalCssFiles">
  4         <list>
  5             <value>/css/myView.css<value> <value>http://server.com/css/myView.css</value>
  6         </list>
  7     </property>
  8     <property name="additionalScriptFiles">
  9     <list>
 10         <value>/script/myView.js</value>
 11         <value>http://server.com/script/myView.js</value> 
 12      </list>
 13     </property>
 14 </bean>    

Using bean inheritance, we can setup a new base view with the additional CSS and/or script files that other views inherit. Furthermore, individual views can add files as needed.

Within the additional style sheets, we can override the provided style classes (see 'Base Styles and Conventions'), or add new style classes. For example, we might want to add a new style class to all input fields, or buttons, or a new component we have developed. Once we have defined the style class, we must then associate it with a component. We can do this by using the styleClasses property.

The styleClasses property is provided for all components, and holds a list of class names that should be applied for that component. We can configure this property using the Spring list tag:

  1 <bean id="MyActionButton" parent="Uif-PrimaryActionButton">
  2     ...
  3     <property name="styleClasses">
  4         <list merge="true">
  5             <value>customStyleClass<value>
  6         </list>
  7     </property>
  8 </bean>   

Recall that in order to inherit collection configuration from a parent bean, we must using the Spring tags and add merge="true". It is recommended that the default style classes always be inherited.

The configured styleClasses are then specified as the class attribute on the rendered HTML element:

  1 <button id="MyActionButton" class="uif-primaryActionButton customStyleClass"  ... />  

Notice the uif-primaryActionButton class. This was inherited from the Uif-PrimaryActionButton bean.

The second way to modify themes is by providing inline styling information. This is accomplished by using the style property that is available on all components. This property is then used to set the corresponding style attribute on the rendered HTML element (known as inline styling).

  1 <bean parent="Uif-BoxGroupSection" p:style="border: 1px;"> 
  2 ...    

All of the provided components have a style class configured by default. These style classes are configured in the base bean definition(s) for the component. Similar to the naming convention employed for the bean ids (starting with 'Uif-'), the class names all begin with 'uif-'. After the prefix, the class names closely match the bean name (with the exception of casing). As an example let's look at a few of the provided action definitions:

  1 <bean id="Uif-ActionImage" ...
  2     <property name="styleClasses">
  3         <list merge="true">
  4             <value>uif-actionImage</value>
  5         </list>
  6     </property>
  7 
  8 <bean id="Uif-PrimaryActionButton" ... 
  9     <property name="styleClasses">
 10         <list merge="true">
 11             <value>uif-primaryActionButton</value>
 12         </list>
 13     </property>
 14 
 15 <bean id="Uif-SecondaryActionButton" ...
 16     <property name="styleClasses">
 17         <list merge="true">
 18             <value>uif-secondaryActionButton</value>
 19         </list>   
 20     </property>      
 21 
 22 <bean id="Uif-ActionLink" ... 
 23     <property name="styleClasses">
 24         <list merge="true">
 25             <value>uif-actionLink</value>
 26         </list>
 27     </property>     

Notice the style class configured for each bean.

In addition to providing the style class per component, the base beans are also setup to inherit classes from the parent (with the merge="true"). A good example of this is the stacked collection group section:

  1 <bean id="Uif-StackedCollectionSection" parent="Uif-StackedCollectionGroup">
  2     <property name="styleClasses">
  3         <list merge="true">
  4             <value>uif-stackedCollectionSection</value>
  5         </list>
  6     </property>   

As in the previous examples, we are applying a style class for the component named 'uif- stackedCollectionSection'. Now, let's walk up the bean hierarchy and look at the style classes we are adding:

  1 <bean id="Uif-StackedCollectionGroup" parent="Uif-CollectionGroupBase">
  2     <property name="styleClasses">
  3         <list merge="true">
  4             <value>uif-stackedCollectionGroup</value>
  5         </list>
  6     </property>
  7     
  8 <bean id="Uif-CollectionGroupBase" parent="Uif-GroupBase"/>
  9     <property name="styleClasses">
 10         <list merge="true">
 11             <value>uif-collectionGroup</value>
 12         </list>
 13     </property>
 14 
 15 <bean id="Uif-GroupBase">
 16     <property name="styleClasses">
 17         <list>
 18             <value>uif-group</value>
 19         </list>
 20     </property>    

So we can see the combined list of style classes applied will be 'uif-group uif-collectionGroup uif-stackedCollectionGroup uif-stackedCollectionSection'. This gives us a tremendous amount of flexibility for styling, since we have many levels at which to define styling. We can configure styling that applies to all groups (uif-group), then all collection groups (uif-collectionGroup), then all collection groups that have the stacked layout (uif-stackedCollectionGroup) and finally all collection groups with stacked layouts that are rendered at the section level (uif-stackedCollectionSection). At each level, we can add or modify styling.

Suppose we had declared the following styles in our CSS file:

uif-group { 
    padding : 10px;
    margin : 10px;
}

uif-collectionGroup {
    padding : 20px; 
}

uif-stackedCollectionGroup {
    border : 1px;  
}   

The applied styling for the generated element will then have a padding 20px, margin 10px, and border 1px.

KRAD also comes bundled with the Fluid Skinning System (http://www.fluidproject.org/). The skinning system contains a set of CSS files with classes that can be used for styling and layout. For example, there are many useful classes for text styling (size, color). Any of these may be used by adding the class name in the styleClasses property. More information on using Fluid for CSS layouts will be covered in Chapter 7.

When inheriting configuration from a parent bean definition (using the parent attribute), we can merge collection entries from the child to parent definition by adding merge="true" to the collection tag. Spring performs the merging by adding the entries on the child definition to the end of the entries of the parent. For example, if our parent bean specifies entries 'item1' and 'item4', then the child specifies items 'item3' and 'item5', the resulting collection will have entries with the following order: 'item1','item4','item3','item5'. In the majority of cases this is fine. However, when the order of items within the collection make a functional difference, only being able to merge entries at the end of the collection can be a hindrance.

Within the UIF, many collections do represent a case where the order matters. One example is the Group component which has a list of component items and a Layout Manager. These items will be rendered on the page based on the order in which they appear in the collection.

Therefore a property named 'order' was added to all components (ComponentBase) that can be used to declare where the component should be placed in the collection when merging.

To make use of this functionality, we must first setup the collection items in the base bean to have an order value:

  1 <bean id="MyPage" parent="Uif-Page">
  2     ...
  3     <property name="items">
  4         <list>
  5             <bean id="Section1" parent="Uif-GridSection" p:order="100">
  6             <bean id="Section2" parent="Uif-GridSection" p:order="200">
  7             <bean id="Section3" parent="Uif-GridSection" p:order="300">
  8         </list>
  9     </property>
 10     <property name="itemOrderingSequence" value="101"/>   

Notice a couple of things here. First, the order was specified for each item such that there is a range of integers that fall between each (<100, 100-200, 200-300, >300). The second is the property value of 101 for itemOrderingSequence.

Now, let's assume we want to create a page that extends from 'MyPage'. For our page, we need to add two sections. However, when these sections are rendered, the first section should be between 'Section1' and 'Section2', and our second section should be after 'Section3'. This can be done as follows:

  1 <bean id="AnotherPage" parent="MyPage">
  2     ...
  3     <property name="items">
  4         <list merge="true">
  5             <bean id="Section4" parent="Uif-GridSection">
  6             <bean id="Section5" parent="Uif-GridSection" p:order="320">
  7         </list>
  8     </property>   

That's it! So what happened? First, we need to understand the rules of merging when the order property is given:

Applying these rules to our example we see that 'Section4' will get an assigned order value or '101', thus it will be placed between 'Section1' and 'Section2' which have order values of 100 and 200 respectively. Finally 'Section5' will be placed after 'Section3' since it has an order of 320 which is greater than 300. The final ordering is 'Section1, Section4, Section2, Section3, Section5'.

In addition to the properties described previously, the label component offers the following properties:

renderColon – This indicates whether a colon should be rendered after the label text. For example, the label text of 'Foo' will result in 'Foo:' being rendered.

requiredMessage – This is a message component that will be rendered with the label to indicate that the element associated with the label (generally a control) is required. By default, the message text is configured to be '*' but can be changed on a global or case by case basis:

  1 <bean parent="Uif-DataField" p:label="My Data Field" p:label.requiredMessage="required"/>

Like all components, the required message will be displayed if its render property is true. Therefore we can set the required message to not display as follows:

  1 <bean parent="Uif-DataField" p:label="My Data Field" p:label.requiredMessage.render="false"/>

However, we typically want to display the required message when the component the label is associated with is required. This is again where our Field component provides value. The field will look at the required property (on all components) of the wrapped component, and, if set to true, will then set the render property to true for the label's required message. Likewise, if the component's required property is false, the render property on the required message will be set to false. Therefore these two properties are synced.

requiredMessagePlacement – Along with the required message, the label component also provides a required message placement option. This indicates where the required message should be rendered in relation to the label text. The type for this property is org.kuali.rice.krad.uif.UifConstants.Position, which is an enum for the four possible positions (LEFT, TOP, RIGHT, BOTTOM). However, in the case of the required message, only the LEFT and RIGHT positions are supported.

The field also provides some additional properties that related to the label. These are:

labelPlacement – Similar to the requiredMessagePlacement of the label component, this property is of type Position. It indicates where the label should be placed in relation to the other field content (the wrapped component(s)). The LEFT, TOP, or RIGHT position may be specified:

  1 <bean parent="Uif-DataField" p:label="My Data Field" p:labelPlacement="LEFT"/>

  1 <bean parent="Uif-DataField" p:label="My Data Field" p:labelPlacement="TOP"/>

  1 <bean parent="Uif-DataField" p:label="My Data Field" p:labelPlacement="RIGHT"/>

These three configurations are shown in Figure 6.1, “labelPlacement Options”.

Figure 6.1. labelPlacement Options

shortLabel – On the field component, we can also configure an alternate 'short' label. When necessary, the short label can be pulled instead of the standard 'long' label. For example, the table layout manager in KRAD will use the short label for the table headers.

  1 <bean parent="Uif-DataField" p:label="My Data Field" p:shortLabel="My Fld"/>

With the various configuration options such as what to render and where, it can overwhelming. We certainly do not want to think through each setting for every field we create. To help with this, base beans are provided sensible defaults based on the label placement. These beans exist for the data field and input field (two most commonly used fields).

Uif-DataField – Default which sets label placement to left, render colon as true, and required message placement to right

Uif-DataField-LabelTop – Sets label placement as top, render colon as false, and required message placement to right

Uif-DataField-LabelRight – Sets label placement to right, render colon as false, and required message placement to left

Similar beans exist for the Uif-InputField. To use one of the label configurations, we simply change our parent bean:

  1 <bean parent="Uif-DataField-LabelTop" p:labelText="My Data Field" />

A Data Field is used to display a property value from the model as read-only. When we say read-only, this means the value is displayed as static text on the page and the user cannot change its value. To create a data field we specify a new bean with parent="Uif-DataField":

  1 <bean parent="Uif-DataField" ... >

When configuring a data field for our view, we must associate it with a property on the model object. This is accomplished using the propertyName property. For example, suppose we had the following model object:

  1 
  2 public class BookForm {
  3   private String bookId;
  4   private String bookTitle;
  5   // getters/setters
  6 }
  7             

To create a data field for the bookId property, our configuration would be as follows:

<bean parent="Uif-DataField" p:propertyName="bookId" p:label="Book"/>

Recall from the previous section that our data field includes a label element and, by default, is configured to be placed to the left of the field content. Therefore, the result of this will appear as in Figure 6.2, “Data Field Label”.

Figure 6.2. Data Field Label

The given property name can be a nested path. For an example of this, suppose now our model is the following:

  1 
  2 public class BookForm {
  3   private Book book;
  4   
  5   // getters/setters
  6 }
  7 
  8 public class Book {
  9   private String bookId;
 10   private String bookTitle;
 11 }
 12             

To display the bookId now, our property name should be "book.bookId". This is the same as doing getBook().getBookId(). More complex situations will be covered in the section 'Data Binding '.

An Input Field extends from the Data Field and gives edit capability. This means the user can change the value for the associated property and submit it back using the HTML form. Values are edited using an HTML control which is represented in KRAD with a Control content element. We will learn all about the various types of controls later on in this chapter.

To create a new input field, we specify a new bean with parent="Uif-InputField":

  1 <bean parent="Uif-InputField" ... >

Now since input field is also a data field, we must specify the property it is associated with using the propertyName property:

  1 <bean parent="Uif-InputField" p:propertyName="bookId"/>

Furthermore, since we have an input field and want to allow the user to change the value, we need to configure a control component to use. We set the control component for the input field using the control property:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="bookId" p:label="Book">
  3     <property name="control">
  4     <bean parent="Uif-TextControl"/>
  5     </property>
  6 </bean>

The control component is a new object, not a primitive. Therefore, we use a bean or ref tag to provide the value. In this example, we are using the text control whose bean id is 'Uif-TextControl'. If needed, we could set properties on the text control component using the p namespace or nested property tags.

In Figure 6.3, “Input Field” we see the result of the above input field configuration.

Figure 6.3. Input Field

The rendered HTML for our input field will be the following:

  1 <input id="u66" name="bookId" class="uif-control uif-textControl valid" tabindex="0" type="text" value="" size="30" aria-invalid="false">

Where did all these attributes come from? Since we didn't assign an id, the framework generated one for us and outputted as the element id. Next, the propertyName given for the input field was used as the name attribute on the tag. This is important for binding the data which will be discussed in the section 'Data Binding'. The 'Uif-TextControl' bean that was used for the control property included a default size of '30', and also includes the style classes 'uif-control' and 'uif-textControl'. Finally, the framework set a tabindex for us (this happens to be the first field on the page) and added aria markup for accessibility. Don't worry if this all doesn't make sense now, we'll see all these properties many more times!

Through configuration of the data field, we can also initialize the backing property of the model. The value specified will then be set as the property value when the model is initialized. Chapter 12 will cover how the model gets initialized along with other concerns of the lifecycle. In terms of default values, it is important just to know that the model gets created for a new request to a view (such as a request from the portal or other application menu) and, once created, is reused throughout the conversation (series of posts on the same view). Generally for initial requests we do not need to perform a lot of business logic. That is, usually we just want to display the view for the user to begin completing. Being able to set default values that will display on the initial view is convenient in that we don't have to override the controller method to do the same in code.

There are three properties available on a data field that allows us to configure a default value. The first is the property 'defaultValue', which takes the actual value to use. For example, suppose we want to set a default value of '2012' for the bookYear property. This would be done as follows:

  1 <bean parent="Uif-DataField" p:propertyName="bookYear" p:defaultValue="2012"/>

This is equivalent to code:

bookForm.setBookYear("2012");

The default value given must be convertible to the property type without a custom property editor.

A very powerful feature we will be looking at later on in this training manual is the Spring Expression Language (EL). KRAD allows you to use expressions for most component properties, including the defaultValue. There are many things you can do with EL, but to give you a taste here are a couple:

  1 <bean parent="Uif-DataField" p:propertyName="bookYear" p:defaultValue="@{2010 + 2}"/>

  1 <bean parent="Uif-DataField" p:propertyName="bookYear" p:defaultValue="@{bookId < 1000 ? 2011 : 2012}"/>

  1 <bean parent="Uif-DataField" p:propertyName="bookTitle" p:defaultValue="New Book for @{bookYear}"/>

The second way to configure default values is by setting the 'defaultValues' property (notice the 's' on the end). This property provides the ability to set multiple default values. For example, if you wanted to default items with values of either 2 or 3 you could add the following.

  1 <property name="defaultValues" >
  2         <list>
  3         <value>2</value>
  4         <value>3</value>
  5         </list>
  6         </property>
  7       

The third way to configure a default value is by setting the defaultValueFinderClass property. This is the full class name for the class that implements the org.kuali.rice.krad.valuefinder.ValueFinder interface. This interface is very simple with just the one method:

public String getValue();

Implementations of this can be made to determine the default value in whatever manner necessary. Previous to KRAD, this was helpful for retrieving the default value from a system parameter. However, with KRAD EL, you can do this with the defaultValue property using the getParm function.

Let's create a default value finder class that calls a service to retrieve the value. Our finder class would be setup like:

  1 
  2 package edu.myedu.sample;
  3 public class BookCopyrightYearValueFinder implements ValueFinder {
  4   public String getValue() {
  5      return getBookService().getDefaultCopyrightYear();
  6   }
  7 
  8   Protected BookService getBookService() {
  9      ServiceLocator.getBookService();
 10   }
 11 }
 12             

We would then configure the data field to use our value finder class like this:

  1 <bean parent="Uif-DataField" p:propertyName="bookYear" 
  2      p:defaultValueFinderClass="edu.myedu.sample.BookCopyrightYearValueFinder"/>

One additional note that should be made regarding default values is for collection group fields. Data or Input fields declared in these groups behave differently from the standard group, in that for each collection line that exists in the model, a new set of fields is created. When configuring a default value (by either mechanism) for a collection field, the value is picked up each time a new line is created (as a result of an add line request). Thus it is a default value for the collection line.

In certain situations, it is necessary to change the display of a data or input field when it is read only. For example, we might want to display additional information along with the value of the property, or we might want to display a different property value. This can be accomplished using the alternate and additional display properties that are available on data field (and therefore input field through inheritance).

As is the case throughout much of the UIF, there is more than one way to accomplish this. The first method we can use is to directly configure the alternate or additional value that should be displayed. This is done using the readOnlyDisplayReplacement and readOnlyDisplaySuffix properties respectively. For example, instead of displaying the value for the bookId property, we want to display the string 'Id Val':

  1 <bean parent="Uif-InputField" p:propertyName="bookId" p:readOnlyDisplayReplacement="Id Val"/>

This would result in the text 'Id Val' being displayed (along with the field label).

Now, if we decide we just want to append the 'Id Val' string the actual value of the bookId property, our configuration would then be:

  1 <bean parent="Uif-InputField" p:propertyName="bookId" p:readOnlyDisplaySuffix="Id Val"/>

Assuming the bookId is '3', this would result in the text '3 *-* Id Val' being displayed as shown below.

Figure 6.4. Data Field Label

This has limited benefits by itself, but as mentioned earlier, KRAD allows us to use expressions to set a value. With EL we can display one or more other property values, perform operations and functions, and mix in static text!

  1 <bean parent="Uif-InputField" p:propertyName="bookId" p:readOnlyDisplaySuffix="with title @{bookTitle}"/>

Again assuming the bookId is '3' and bookTitle is 'Dogs and Cats', this would result in the text '3 *-* with title Dogs and Cats' being displayed.

Often, there is a need to display another property value as the alternate or additional display value. For example, when we have an id or code field (that generally doesn't have any meaning to the user), it is preferred to display the name instead of the code (or in addition to it). For these cases, you can simply configure the readOnlyDisplayReplacementPropertyName or readOnlyDisplaySuffixPropertyName properties with the name of the property whose value should be used:

  1 <bean parent="Uif-InputField" p:propertyName="bookId" p:readOnlyDisplayReplacementPropertyName="bookTitle"/>

Assuming bookTitle is 'Dogs and Cats', this would result in the text 'Dogs and Cats'.

  1 <bean parent="Uif-InputField" p:propertyName="bookId" p:readOnlyDisplaySuffixPropertyName ="bookTitle"/>

Assuming bookId is '3' and bookTitle is 'Dogs and Cats', this would result in the text '3 *-* Dogs and Cats'.

When a field is of type List<String> and the readOnly property is set to true, there are a few more options that you can take advantage of to change how this data is displayed. By default this values will be output in a comma and space (", ") separated list, but this can be changed with the readOnlyListDisplayType property of DataField (and child type InputField). The following options are allowed:

The following would put a dash with spaces between each item of the list:

  1 <bean parent="Uif-InputField-LabelTop" p:propertyName="field120" p:label="Alternate Delimiter"
  2               p:instructionalText="CheckboxGroupControl using an optionsFinder" p:width="auto"
  3               p:readOnlyListDisplayType="DELIMITED" p:readOnlyListDelimiter=" - ">
  4 ...

The result would be something like this "Value1 - Value2 - Value3"

p:readOnlyDisplayReplacement="@{#emptyList(field115)?'No Options Selected':''}

For certain widgets (i.e. quickfinder, date picker, spinner, etc) a user can interact through the widget or enter a value directly into the input field. In some cases it may be desirable to allow changes to these widgets through its controls. In order to do so set the widgetInputOnly property of the InputField to true. This will cause the value of the widget to become read only while the widget controls are fully functional.

The following would put a dash with spaces between each item of the list:

  1 <bean parent="Uif-InputField" p:propertyName="author" p:widgetInputOnly="true">
  2 ...

When binding the data between the JSP page and the model, Spring will again invoke registered Property Editors to perform the necessary type conversion. All values within the interface are treated as Strings. When going from or to a property type, other than the primitive types or String type, a property editor must be used.

Spring provides out-of-the-box property editors for common Java types that are registered by default (registration is the process of configuring the Spring container to use a property editor). Also, some optional property editor implementations are provided that can be used. These include: ByteArrayPropertyEditor, ClassEditor, CustomBooleanEditor, CustomCollectionEditor, CustomDateEditor, CustomNumberEditor, FileEditor, InputStreamEditor, LocaleEditor, PatternEditor, PropertiesEditor, StringTrimmerEditor, and URLEditor.

In addition to the provided Spring property editors, KRAD provides a set that can be used with the custom Kuali types (such as KualiDecimal and KualiInteger) and other common formatting practices. These include:

UifBooleanEditor – Formats any of the strings "/true/yes/y/on/1/" to the Boolean true, and any of the strings "/false/no/n/off/0/" to Boolean false. Conversely, the Boolean true is formatted as the string "yes" and the Boolean false is formatted as the string "no".

UifCurrencyEditor – Used for converting between a KualiDecimal and a string. The string is formatted using commas and to two decimal places.

UifDateEditor – Used for converting between a java.util.Date and a string. The Rice DateTimeService is used to perform the string formatting and for parsing the string to create a date object.

UifKualiIntegerEditor – Used for converting between a KualiInteger and a string. The string is formatted using commas and to zero decimal places.

UifPercentageEditor – Used for converting between a KualiPercent and a string. Formatting is similar to UifCurrencyEditor.

UifTimestampEditor – Used for converting between a java.sql.Timestamp and a string. The Rice DateTimeService is used to perform the string formatting and Timestamp creation.

These property editors, along with Spring editors, are registered with Spring by property type. This means whenever Spring encounters the associated type for the property being bound to, it will use the registered property editor. For example, the UifCurrencyEditor is registered with the KualiDecimal type. Thus, when binding to a property with type KualiDecimal, the UifCurrencyEditor will be used.

If needed, KRAD allows you to also specify a property editor to use for a data field. This might be needed to support a custom data type or to perform custom formatting (formatting refers to the process of rendering a String from an object). To create a new property editor, a class must be created that implements the PropertyEditor interface. The easiest way to do this is to extend the Spring provided class java.beans.PropertyEditorSupport, and then override the getAsText() and setAsText(String text) methods.

  1 
  2 package edu.sampleu.demo.kitchensink;
  3 public class UITestPropertyEditor extends PropertyEditorSupport implements Serializable {
  4     private static final long serialVersionUID = -4113846709722954737L;
  5 
  6     /**
  7      * @see java.beans.PropertyEditorSupport#getAsText()
  8      */
  9     @Override
 10     public String getAsText() {
 11         Object obj = this.getValue();
 12 
 13         if (obj == null) {
 14             return null;
 15         }
 16 
 17         String displayValue = obj.toString();
 18         if (displayValue.length() > 3) {
 19             displayValue = StringUtils.substring(displayValue, 0, 3) + "-" + StringUtils.substring(displayValue, 3);
 20         }
 21 
 22         return displayValue;
 23     }
 24 
 25     /**
 26      * @see java.beans.PropertyEditorSupport#setAsText(java.lang.String)
 27      */
 28     @Override
 29     public void setAsText(String text) {
 30         String value = text;
 31         if (StringUtils.contains(value, "-")) {
 32             value = StringUtils.replaceOnce(value, "-", "");
 33         }
 34 
 35         this.setValue(value);
 36     }
 37 }
 38             

The two methods implemented here correspond to the two directions: outgoing to the page (to string), and incoming to the model (to object). The getAsText() method is invoked to build the string that should be displayed. We can use the getValue() method provided by the base class to get current object, then build the string and return. The setAsText(String text) method is used to build the object from the String. After we have constructed the object, we can call the setValue method to set the object that will be used for the model property value.

Once we have the property editor class created, we can configure it to be used with our data field by specifying the full class name in the propertyEditor property:

  1 <bean parent="Uif-DataField" p:propertyName="bookId" p:propertyEditor="edu.sampleu.demo.kitchensink.UITestPropertyEditor"/>

Likewise the property editor can be specified for an input field:

  1 <bean parent="Uif-InputField" p:propertyName="bookId" p:propertyEditor="edu.sampleu.demo.kitchensink.UITestPropertyEditor"/>

So far, we have used examples where the property was either directly on the model (form) object, or one level down. Now let's look at more complex paths for binding that include many levels of nesting and collection properties.

Let's assume we have the following objects:

  1 
  2 public class TestForm {
  3   private String field1;
  4   private Test1Object test1Object;
  5 }
  6 
  7 public class Test1Object {
  8   private String t1Field;
  9   private Test2Object test2Object;
 10   private List<Test2Object> test2List;
 11 }
 12 
 13 public class Test2Object {
 14   private String t2Field;
 15   private Map<String, String> t2Map;
 16 }
 17                 
 18             

Some example paths for these properties would be:

Field1 on TestForm – "field1"

Each time we go into a nested object, we use a dot:

T1Field on Test1Object = "test1Object.t1Field" 

T2Field on Test2Object – "test1Object.test2Object.t2Field"

The path for a collection field must specify the item index using the brackets [] and the index within the brackets:

T2Field on Test1List – "test1Object.test2List[0].t2Field",
        "test1Object.test2List[1].t2Field", "test1Object.test2List[2].t2Field", … 

For binding to a map we again use the brackets with the map key within the brackets and quoted:

T2Map on Test2Object – "test1Object.test2Object.t2Map['key1']",
        "test1Object.test2Object.t2Map['key2']" 

We can continue forming paths for objects that are nested at deeper levels by adding additional dots to the path. In this way, we can form the path and set the propertyName value for any model property:

  1 <bean parent="Uif-DataField"
  2         p:propertyName="test1Object.test2Object.t2Field">

Now suppose Test2Object had a large set of fields we wanted to display. We could configure all of them just as in the previous example:

  1 <bean parent="Uif-DataField" p:propertyName="test1Object.test2Object.t2Field1">

  1 <bean parent="Uif-DataField" p:propertyName="test1Object.test2Object.t2Field2">

  1 <bean parent="Uif-DataField" p:propertyName="test1Object.test2Object.t2Field3">

This is, however, very tedious and repetitive. Luckily, the UIF provides a class named BindingInfo for which a property exists on a data field. This class separates the path into three parts. The first is called the binding object path. This is the path to a data object on the model. The second is called the binding prefix, and the third part is the binding name.

The binding name is usually the same as the given property name, and will be synced if not set. The binding prefix is then a prefix to add before the binding name (property name). Finally, the full path is formed by joining the prefix and name to the object path. This is known as the binding path and is invoked by the templates to set the Spring path attribute. Please note the binding prefix is optional and not always beneficial to use.

Let's breakdown the path "test1Object.test2Object.t2Field1" from the previous example. A good candidate for the object path is "test1Object.test2Object". That just leaves "t2Field1" so there is not really a need for a binding prefix. Therefore, our configuration would be:

<bean parent="Uif-DataField" p:bindingInfo.bindingObjectPath="test1Object.test2Object" p:propertyName="t2Field1">

We could also configure out data field as follows:

<bean parent="Uif-DataField" p:bindingInfo.bindingObjectPath="test1Object" p:bindingInfo.bindByNamePrefix="test2Object" p:propertyName="t2Field1">

You might be wondering what the KRAD designers were thinking at this point. This doesn't seem to remove the repetition, and in fact, it is much more verbose! On an individual field level, that is true. The benefit is that we can put multiple fields which share similar paths together into a group.

We will learn all about the Group component in the next chapter, but two properties that exist are fieldBindByNamePrefix and fieldBindingObjectPath. When one or both of these properties are configured on the group, the value will be taken and set on corresponding binding info property for each group field.

For example:

  1 
  2 <bean parent="Uif-VerticalBoxGroup" p:fieldBindingObjectPath="test1Object.test2Object">
  3     <property name="items">
  4         <list>
  5             <bean parent="Uif-DataField" p:propertyName="t2Field1">
  6             <bean parent="Uif-DataField" p:propertyName="t2Field2">
  7             <bean parent="Uif-DataField" p:propertyName="t2Field3">
  8         </list>
  9     </property>
 10 </bean>

This will result in "test1Object.test2Object" being set as the bindingInfo.bindingObjectPath for each of the three contained fields. Now that's better!

But KRAD goes one step further! We can also specify a default object binding path for the entire view. This is done by setting the defaultBindingObjectPath property on the View component. This will set the binding object path for all fields (and collection groups) if it not already set (we can override if necessary). This is very useful in particular for the various view types provided. One example is the MaintenanceView. This view targets the maintenance of a data object instance. This data object instance is found in the model with path 'document.newMaintainableObject.dataObect'. Since typically all these views do are present all data for a particular record to be edited, we just need to specify the properties of the data object we want to present. The maintenance view makes this easy for us by setting "document.newMaintainableObject.dataObject" as the defaultBindingObjectPath. Therefore, when specifying the view fields, we just need to specify the property name relative to the data object:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="number"/>
  3 <bean parent="Uif-InputField" p:propertyName="name"/>
  4 ...

Which would result in binding paths:

  1 
  2 'document.newMaintainableObject.dataObect.number' 
  3 'document.newMaintainableObject.dataObect.name'
  4             

The data and input field components implement the interface org.kuali.rice.krad.uif.component.DataBinding. This indicates to the framework that the component binds to the model, and provides the binding info and property name properties. The other component that implements this interface is the CollectionGroup. A collection group is a group that iterates over a model collection and presents fields for each line. Therefore, when configuring a collection group, we must point it to the property that holds the collection. This is done exactly the same as for data fields, using the propertyName property and the bindingInfo property. For example:

  1 <bean parent="Uif-TableCollectionGroup" p:propertyName="mycollection" ... >

One thing to note is how the binding path for the fields within the collection group is formed. These fields will automatically receive a binding prefix that is the path for the collection line. This path includes the collection path plus the line index: "mycollection[0]", "mycollection[1]". Therefore the fields specified within the collection are relative to the line (data object for the collection). This would be the same as setting the fieldBindByNamePrefix property on a standard group component.

Finally, there are a couple other properties on the binding info class that are helpful to know about. The first of these is the bindToMap property. This is necessary when our property name (or binding name) is actually a Map key. Recall in these cases that we need to use the special bracket notation. When this property is true, the binding path will be formed using the object path, binding prefix, then the brackets with the binding name in quotes.

  1 
  2 <bean parent="Uif-DataField" p:bindingInfo.bindingObjectPath="test1Object.test2Object" p:bindingInfo.bindByNamePrefix="t2Map" p:bindingInfo.bindToMap="true" p:propertyName="key1">

This would result in the following binding path:

"test1Object.test2Object.t2Map['key1']"

Another useful property on binding info is the bindToForm property. This is essentially an indicator to not add on any binding object path (either from the view or a group). The binding prefix is still added, if specified.

For example:

  1 
  2 <bean parent="Uif-VerticalBoxGroup" p:fieldBindingObjectPath="test1Object.test2Object">
  3     <property name="items">
  4         <list>
  5             <bean parent="Uif-DataField" p:propertyName="t2Field1">
  6             <bean parent="Uif-DataField" p:propertyName="field1" p:bindingInfo.bindToForm="true">
  7         </list>
  8     </property>
  9 </bean>

The binding path for the first data field would be "test1Object.test2Object.t2Field1", but the binding path for the second data field will only be "field1", due to the bindToForm property being set to true.

The Checkbox control renders an HTML input tag with type of "checkbox". This control is used to toggle the state of a property between two values (usually the Booleans true and false). The image shows an example checkbox control.

Figure 6.5. Checkbox Control

To create a new checkbox control, we create a new bean with parent of 'Uif-CheckboxControl'. Controls cannot be set on their own; they must be defined within an input field using the control property:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="acceptIndicator" p:label="Accept?">
  3     <property name="control">
  4         <bean parent="Uif-CheckboxControl"/>
  5     </property>
  6 </bean>
  7             

The checkbox control has one custom property that can be set which is the value property. This can be used to specify a string value that will be sent to the server when the checkbox is checked. If not set, the default Boolean 'true' will be sent.

The File control is used to allow the user to select a file from their file system whose contents will be submitted with the form. The server can then make use of the file contents, or simply store the file on the server (for example a note attachment).

To specify that a file control should be used, a bean with parent of 'Uif-FileControl' should be given:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="fileUpload" p:label="File Upload">
  3     <property name="control">
  4         <bean parent="Uif-FileControl"/>
  5     </property>
  6 </bean>
  7 

This control supports no custom properties (just the inherited component and base control properties). The image below shows an example file control:

Figure 6.6. File Control

In order to use the control, there are a couple of requirements for the backend. First, the backing property must be of type org.springframework.web.multipart.MultipartFile. This is so Spring can set all the necessary file information (name, content type, size, bytes). Many times, a pattern employed is to have a property on the form with this type that is used for holding the upload, and then in a controller method, the contents are pulled to populate a property with type File (or store the File object). The MultipartFile class provides a convenient method for doing this called transferTo(java.io.File file).

The second requirement for uploading files is the HTML form encoding type "multipart/form-data". KRAD takes care of this by setting this as the encoding type for all forms.

The Hidden control is used to render an HTML input of type hidden. A hidden control is not visible to the user, therefore its value can only be changed by a script. These are often used to hold some state that is needed when the page is posted back, or to provide data for scripting purposes.

To specify a hidden control should be used, a bean with parent of 'Uif-HiddenControl' should be given:

  1     
  2 <bean parent="Uif-InputField" p:propertyName="hiddenField">
  3     <property name="control">
  4         <bean parent="Uif-HiddenControl"/>
  5     </property>
  6 </bean>
  7             

Using a hidden control is not the same as making the field state hidden (covered in Chapter 10). When the field state is hidden, all of the field contents will be rendered (including a control that is possibly not hidden) but not visible by default. The field contents can then be shown with a script once a condition is met. With the hidden control, the other field contents (such as label and lookup) can still be visible. One usage of the hidden control is to provide a field quickfinder (lookup icon) that forces the user to select a value from the lookup instead of allowing them to type the value.

The Password control renders the HTML input element with type of "password". This is a single-line box that allows the user to type a masked value.

To specify that a password control should be used, a bean with parent of 'Uif-PasswordControl' should be given:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="password" p:label="Password">
  3     <property name="control">
  4         <bean parent="Uif-PasswordControl"/>
  5     </property>
  6 </bean>
  7             

The password control supports the following properties:

size – This is the display size for the control in number of characters.

maxLength – When a value is given, this is the maximum number of characters in length the value can have. If set, the browser will stop the user from entering more characters than allowed.

minLength – When a value is given, this is the minimum number of characters in length the value can have. Note that this is not supported by the HTML input tag itself, but is used by the KRAD validators to check the value client side or server side.

The Text control renders the HTML input element with type of "text". This is a single-line box that allows the user to type the value.

To specify that a text control should be used, a bean with parent of 'Uif-TextControl' should be given:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="title" p:label="Title">
  3     <property name="control">
  4         <bean parent="Uif-TextControl"/>
  5     </property>
  6 </bean>
  7             

The text control supports the following properties:

size – This is the display size for the control in number of characters.

maxLength – When a value is given, this is the maximum number of characters in length the value can have. If set, the browser will stop the user from entering more characters than allowed.

minLength – When a value is given, this is the minimum number of characters in length the value can have. Note that this is not supported by the HTML input tag itself, but is used by the KRAD validators to check the value client side or server side.

datePicker – This is a nested widget component that renders an icon next to the text input that can be used to selected a calendar day. Like all components, the date picker will be rendered if its render property is set to true. This widget and others are covered in Chapter 8.

watermarkText – Specifies text that will appear in the text control when the value is empty. This is used to show example inputs to the user and is sometimes referred to as a placeholder (HTML 5). Once the user begins to input a value the watermark text is cleared.

textExpand – A Boolean type which indicates whether the text input can be expanded. When enabled, an icon is rendered next to the text input that allows the user to click for getting a text area input that allows more room for entering the value. This is useful if the maximum length for the field is longer than the display size.

The UIF provides a handful of base beans for the text control that have various commonly used configuration. These are as follows:

Uif-TextControl – The default text control bean which sets the size to 30. None of the other text control properties are set by default.

Uif-SmallTextControl – Similar to Uif-TextControl but sets the size to 10 and applies an additional style class of 'uif-smallTextControl'.

Uif-MediumTextControl – The same as Uif-TextControl except adds a style class of 'uif-mediumTextControl'.

Uif-LargeTextControl – Similar to Uif-TextControl but sets the size to 100 and applies an additional style class of 'uif-largeTextControl'.

Uif-CurrencyTextControl – Same as Uif-TextControl except adds a style class of 'uif-currencyControl'. This adds a right align style to the control useful for displaying currency.

Uif-DateControl – Same as Uif-SmallTextControl with the data picker added and an additional style class of 'uif-dateControl'.

Below are various examples of using these beans and setting other properties:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="field" p:label="Field Label">
  3     <property name="control">
  4         <bean parent="Uif-MediumControl" p:watermarkText="It's watermarked"/>
  5     </property>
  6 </bean>
  7             

Figure 6.7. Watermark Control

  1             
  2 <bean parent="Uif-InputField" p:propertyName="field" p:label="Date 1">
  3     <property name="control">
  4         <bean parent="Uif-DateControl"/>
  5     </property>
  6 </bean>
  7             

Figure 6.8. Date Control

  1             
  2 <bean parent="Uif-InputField" p:propertyName="field" p:label="Field Label">
  3     <property name="control">
  4         <bean parent="Uif-TextControl" p:textExpand="true"/>
  5     </property>
  6 </bean>
  7             

Figure 6.9. Text Expand Control

The TextArea control is similar to the text control with the exception of providing multiple lines for input. This control is used for entering longer strings of data such as a description.

To specify a text area control should be used, a bean with parent of 'Uif-TextAreaControl' should be given:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="title" p:label="Title">
  3     <property name="control">
  4         <bean parent="Uif-TextAreaControl"/>
  5     </property>
  6 </bean>
  7             

The text area control supports the following properties:

rows – Specifies the number of rows (or lines) the input should have. This determines the height of the control.

cols – Specifies the width in characters the input should have.

maxLength – Similar to the text control, when a value is given restricts the number to a certain number of characters.

minLength – When a value is given, requires the length be greater than or equal to a certain number of characters.

textExpand - A Boolean type which indicates whether the text area input can be expanded.

watermarkText – Specifies text that will appear in the text area control when the value is empty.

The UIF provides a handful of base beans for the text area control that have various commonly used configuration. These are as follows:

Uif-TextAreaControl – The default text area control bean which sets rows to 3, and cols to 40.

Uif-SmallTextAreaControl – Sets rows to 2 and cols to 35. Adds the style class 'uif-smallTextAreaControl'.

Uif-MediumTextAreaControl – Sets rows to 3 and cols to 40. Adds the style class 'uif-mediumTextAreaControl'.

Uif-LargeTextAreaControl – Sets rows to 6 and cols to 50. Adds the style class 'uif-largeTextAreaControl'.

Below shows an example text area control.

Figure 6.10. TextArea Control

The Spinner control is a special text control that renders up and down arrows to the right of the control for incrementing and decrementing the value. This is an example of a 'decorated' control. That is, HTML does not support a Spinner control inherently, but we use JavaScript to provide the additional functionality. This means the rendered content will be the input element with type of 'text', with a script invocation to add the spinner functionality.

Within the UIF, these script decorations are represented by a widget component. The widget is associated with the component it works with. In this case, we extend the text control component and add the spinner widget. The spinner widget will be covered in more detail in Chapter 8.

To specify a spinner control should be used, a bean with parent of 'Uif-SpinnerControl' should be given:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="count" p:label="Spinner Control">
  3     <property name="control">
  4         <bean parent="Uif-SpinnerControl"/>
  5     </property>
  6 </bean>
  7             

Screen shot 13 shows the spinner control.

Figure 6.11. Spinner Control

Up to this point, the controls we have seen hold a single value. Next, we will look at controls that can hold multiple values to choose from. Some also allow selecting multiple values to be submitted. These components are known as multi-value controls and implement the org.kuali.rice.krad.uif.control.MultiValueControl interface.

  1 
  2 <property name="options">
  3     <list>
  4         <bean parent="Uif-KeyLabelPair" p:key="AL" p:value="Alabama"/>
  5         <bean parent="Uif-KeyLabelPair" p:key="CO" p:value="Colorado"/>
  6         <bean parent="Uif-KeyLabelPair" p:key="IN" p:value="Indiana"/>
  7         <bean parent="Uif-KeyLabelPair" p:key="OH" p:value="Ohio"/>
  8         <bean parent="Uif-KeyLabelPair" p:key="TX" p:value="Texas"/>
  9 </property>
 10                 

public List<KeyValue> getKeyValues();

  1 
  2 public List<KeyValue> getKeyValues() {
  3     List<KeyValue> labels = new ArrayList<KeyValue>();
  4     List<State> codes = 
  5 LocationApiServiceLocator.getStateService().findAllStatesInCountry(countryCode);
  6 
  7 labels.add(new ConcreteKeyValue("", ""));
  8 for (State state : codes) {
  9     if(state.isActive()) {
 10         labels.add(new ConcreteKeyValue(state.getCode(), state.getName()));
 11         }
 12     }
 13     return labels;
 14 }
 15                 

  1 <bean id="StateOptionsFinder" class="org.kuali.rice.location.framework.state.StateValuesFinder"/>

  1 
  2 <bean parent="Uif-InputField" p:propertyName="stateCode">
  3     <property name="optionsFinder">
  4         <bean parent="StateOptionsFinder" p:includeInactive="true"/>
  5     </property>
  6 </bean>
  7                 

  1 <bean parent="Uif-InputField" p:propertyName="stateCode" 
  2       p:optionsFinderClass="org.kuali.rice.location.framework.state.StateValuesFinder"/> 

public List<KeyValue> getKeyValues(ViewModel model);

  1 
  2 public class FoodKeyValuesFinder extends UifKeyValuesFinderBase { 
  3 
  4 @Override
  5 public List<KeyValue> getKeyValues(ViewModel model) {
  6     UifComponentsTestForm testForm = (UifComponentsTestForm) model;  
  7                         
  8     List<KeyValue> options = new
  9                         ArrayList<KeyValue>();  
 10 
 11         if (testForm.getFoodGroup().equals("Fruits")) {
 12             options.add(new ConcreteKeyValue("Apples", "Apples"));
 13             options.add(new ConcreteKeyValue("Bananas", "Bananas"));
 14             options.add(new ConcreteKeyValue("Cherries", "Cherries"));
 15             options.add(new ConcreteKeyValue("Oranges", "Oranges"));
 16             options.add(new ConcreteKeyValue("Pears", "Pears"));
 17         } else if (testForm.getFoodGroup().equals("Vegetables")) {
 18             options.add(new ConcreteKeyValue("Beans", "Beans"));
 19             options.add(new ConcreteKeyValue("Broccoli", "Broccoli"));
 20             options.add(new ConcreteKeyValue("Cabbage", "Cabbage"));
 21             options.add(new ConcreteKeyValue("Carrots", "Carrots"));
 22             options.add(new ConcreteKeyValue("Celery", "Celery"));
 23             options.add(new ConcreteKeyValue("Corn", "Corn"));
 24             options.add(new ConcreteKeyValue("Peas", "Peas"));
 25         }  
 26         
 27         return options;
 28     }
 29 }
 30                 

  1 
  2 <bean parent="Uif-InputField" p:propertyName="food" p:label="Foods" 
  3      p:optionsFinderClass="edu.sampleu.travel.options.FoodKeyValuesFinder" p:refreshWhenChanged="field88">
  4     <property name="control">
  5         <bean parent="Uif-DropdownControl"/>
  6     </property>
  7 </bean>
  8                 

labels.add(new ConcreteKeyValue("", ""));

public boolean isAddBlankOption();

CheckboxGroup

The CheckboxGroup control is a multi-value control that presents each option as a checkbox. When a checkbox is selected the corresponding option key will be selected as a value. The checkbox group allows the selection of multiple options, therefore multiple checkboxes for the group may be selected. The option label for each checkbox is rendered to the right of the control.

The checkbox group control supports one custom property named delimiter. This is a string that will be rendered between each checkbox (including the label). Two common options for this are the '&nbsp;' and '</br>' strings. Note this is the HTML entity and tag and thus the first adds a space between each checkbox, while the second adds a link break between each. These can be used to horizontally or vertically align the checkboxes. KRAD provides base beans for both these options named 'Uif-HorizontalCheckboxesControl' and 'Uif-VerticalCheckboxesControl'.

To specify a checkbox control should be used, a bean with parent of 'Uif-HorizontalCheckboxesControl' or 'Uif-VerticalCheckboxesControl' should be given:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="selectedOpts" p:label="Checkboxes 1">
  3     <property name="control">
  4         <bean parent="Uif-VerticalCheckboxesControl">
  5             <property name="options">
  6                 <list>
  7                     <bean parent="Uif-KeyLabelPair" p:key="O1" p:value="Option 1"/>
  8                     <bean parent="Uif-KeyLabelPair" p:key="O2" p:value="Option 2"/>
  9                     <bean parent="Uif-KeyLabelPair" p:key="O3" p:value="Option 3"/>
 10                 </list>
 11             </property>
 12         </bean>
 13     </property>
 14 </bean>
 15                 

Note we could also have chosen to configure the optionsFinder or optionsFinderClass on the input field bean instead of configuring the options directly on the control.

Below shows the checkbox group control.

Figure 6.12. CheckboxGroup Control

Since the checkbox group control allows selecting multiple values, our back model property must be a List type of primitives (usually string). For example:

private List<String> checkboxGroupProperty;

After the request data is bound to the model, each value that was checked will be an entry in the List.

  1 
  2 <bean parent="Uif-InputField" p:propertyName="selectedOpt" p:label="Radio 1">
  3     <property name="control">
  4         <bean parent="Uif-VerticalRadioControl">
  5             <property name="options">
  6                 <list>
  7                     <bean parent="Uif-KeyLabelPair" p:key="O1" p:value="Option 1"/>
  8                     <bean parent="Uif-KeyLabelPair" p:key="O2" p:value="Option 2"/>
  9                     <bean parent="Uif-KeyLabelPair" p:key="O3" p:value="Option 3"/>
 10                 </list>
 11             </property>
 12         </bean>
 13     </property>
 14 </bean>
 15                 

Select

The Select control is another variation of a multi-value control. The select control appears similar to the text control, but with an arrow to display a dropdown list of options. The select control can be configured to only allow one selection, or multiple.

To specify a select control should be used that allows only one value to be selected, a bean with parent of 'Uif-DropdownControl' should be used:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="selectedOpt" p:label="Select Control">
  3     <property name="control">
  4         <bean parent="Uif-DropdownControl">
  5             <property name="options">
  6                 <list>
  7                     <bean parent="Uif-KeyLabelPair" p:key="O1" p:value="Option 1"/>
  8                     ...
  9                 </list>
 10             </property>
 11         </bean>
 12     </property>
 13 </bean>
 14                 

The back model property in this case should be a simple primitive (string, integer, …).

Below shows the select control allowing only one selection.

Figure 6.13. Select Control

To specify a select control should be used that allows one or more values to be selected, a bean with parent of 'Uif-MultiSelectControl' should be used:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="selectedOpts" p:label="Multi Select Control">
  3     <property name="control">
  4         <bean parent="Uif-MultiSelectControl">
  5             <property name="options">
  6                 <list>
  7                     <bean parent="Uif-KeyLabelPair" p:key="O1" p:value="Option 1"/>
  8                     ...
  9                 </list>
 10             </property>
 11         </bean>
 12     </property>
 13 </bean>
 14                 

Below shows the select control allowing multiple values to be selected.

Figure 6.14. Multi Select Control

The select control supports two custom properties. The first is the multiple property which is a boolean indicating whether selection of more than one value is allowed (set to true by the 'Uif-MultiSelectControl' bean). The second property is named size and configures how many options should be visible to the user without using the arrow. This dictates the vertical size of the control. As an example the select control above was set to 4.

Location Select (Navigation Select)

Select controls have the ability to be backed by a location, which allows for navigation when an option is selected. This should only be used for single Select controls. This control may be particularily useful in configuring a siblingBreadcrumbComponent for a BreadcrumbItem (see "Breadcrumbs" section in "The View").

This is set up the same way a normal Select control would be set up, except instead of using a UifKeyValue object, a UifKeyValueLocation object is used instead. The location property of this object is backed by a UrlInfo object for ease of the configuration (minimal set-up of navigation information for Views and controller mappings).

The following configuration demonstrates this usage:

  1         <bean parent="Uif-InputField" p:label='Dropdown Navigation' p:instructionalText="Navigate on dropdown selection"
  2               p:width="auto">
  3           <property name="control">
  4             <bean parent="Uif-DropdownControl">
  5               <property name="options">
  6                 <list>
  7                   <bean parent="Uif-KeyValueLocation" p:key="1" p:value="" p:location.href=""/>
  8                   <bean parent="Uif-KeyValueLocation" p:key="2" p:value="Kuali.org"
  9                         p:location.href="http://www.kuali.org"/>
 10                   <bean parent="Uif-KeyValueLocation" p:key="3" p:value="Jira"
 11                         p:location.href="https://jira.kuali.org"/>
 12                   <bean parent="Uif-KeyValueLocation" p:key="4" p:value="InputField Demo"
 13                         p:location.viewId="Demo-InputField-View"
 14                         p:location.controllerMapping="/kradsampleapp"/>
 15                 </list>
 16               </property>
 17             </bean>
 18           </property>
 19         </bean>

OptionList

The OptionList control is a MultiValueControl which is used for the display a read only list of key-value pairs. It can be used to display those key-value pairs which were "selected" (when backed by with a propertyName and setting the appropriate option) or to display all available key-value pairs configured by the options (default). The values which are considered "selected" (whether all options are being render or not) have an addiontal css style class when rendered defined by selectedItemCssClass property.

The main use case of this control is to display the available set of options available in an option list or to display the ones that may have been selected previously (for display in a read-only View for example).

The following code displays an OptionsList that only shows the values which match in the property defined by propertyName:

  1       <bean parent="Uif-InputField" p:label='Option List'
  2               p:propertyName="optionListSelection">
  3           <property name="control">
  4             <bean parent="Uif-OptionListControl">
  5               <property name="showOnlySelected" value="true"/>
  6               <property name="options">
  7                 <list>
  8                   <bean parent="Uif-KeyLabelPair" p:key="1" p:value="Option 1"/>
  9                   <bean parent="Uif-KeyLabelPair" p:key="2" p:value="Option 2"/>
 10                   <bean parent="Uif-KeyLabelPair" p:key="3" p:value="Option 3"/>
 11                   <bean parent="Uif-KeyLabelPair" p:key="4" p:value="Option 4"/>
 12                 </list>
 13               </property>
 14             </bean>
 15           </property>
 16         </bean>

Lets assume that the optionListSelection property defined by propertyName only contains the values 2 and 4. Since showOnlySelected is set to true, the result is a read-only control that will look like the following:

Figure 6.15. OptionList Control

Though it is not apparent, the selected values also have a different css style class added. By default it is not different from normal text and must be customized for your project needs, when applicable.

Navigation OptionList

Like a location-backed Select control, an OptionList can also be backed by a list of UifKeyValueLocation beans for its options. This will output the OptionList as a list of links which the user can click. If showOnlySelected flag is being used, only those links which match the value of the property defined by propertyName of the field will be shown. Like a location-backed Select control, this control is useful for use in the siblingBreadcrumbComponent property of a BreadcrumbItem.

The following configuration will output a list of links (note that no propertyName is being used here nor the showOnlySelected property):

  1 <bean parent="Uif-InputField" p:label='Nav Option List'>
  2           <property name="control">
  3             <bean parent="Uif-OptionListControl">
  4               <property name="options">
  5                 <list>
  6                   <bean parent="Uif-KeyValueLocation" p:key="1" p:value="Kuali.org"
  7                         p:location.href="http://www.kuali.org"/>
  8                   <bean parent="Uif-KeyValueLocation" p:key="2" p:value="Jira"
  9                         p:location.href="https://jira.kuali.org"/>
 10                   <bean parent="Uif-KeyValueLocation" p:key="3" p:value="InputField Demo"
 11                         p:location.viewId="Demo-InputField-View"
 12                         p:location.controllerMapping="/kradsampleapp"/>
 13                 </list>
 14               </property>
 15             </bean>
 16           </property>
 17         </bean>

That will look like the following:

Figure 6.16. Navigation OptionList Control

The KIM Group control is not an actual different type of HTML control. Instead, it is a wrapper for the text control that provides additional functionality related to selecting a KIM group. The KIM group and KIM user entities are used often in Rice enabled applications; therefore, these controls are provided to simplify the configuration.

The group control adds a quickfinder (lookup icon) to the text control that is configured to invoke the KIM group lookup. The lookup is configured to return the group id, namespace, and name. The namespace and name fields can then be displayed as data or input fields, and the group id will be added as a hidden.

To use the KIM group control a bean with parent of 'Uif-KimGroupControl' should be given. The property that backs the input field for which the control is configured is assumed to hold the group name. As usual this is configured using the propertyName property on input field. In order for the control to work properly, we must then specify the properties that hold the group id and namespace:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="groupNamespaceCode" p:label="Namespace Code"/>
  3 <bean parent="Uif-InputField" p:propertyName="groupName" p:label="Name">
  4     <property name="control">
  5         <bean parent="Uif-KimGroupControl" p:groupIdPropertyName="groupId" p:namespaceCodePropertyName="groupNamespaceCode"/>
  6     </property>
  7 </bean>
  8                 

Notice we are displaying the group namespace in an input field before the group name.

The KIM User control is similar to the KIM Group control but instead of a KIM group, it allows us to find a KIM User. This control does several things for us. First, like the group control, it will configure a quickfinder for our field that is configured to invoke the KIM User lookup. The lookup will then return the principal id, principal name (username), and person name (full name). Also, like the group control, it will automatically add the principal id as a hidden field for us. In addition, it sets up a field query (covered later on in this chapter) that displays the person name under the control on return from the lookup, or when tabbing out of the control.

To use the KIM User control, a bean with parent of 'Uif-KimPersonControl' should be given. The property that backs the input field for which the control is configured is assumed to hold the principal name. As usual this is configured using the propertyName property on input field. In order for the control to work properly, we must then specify the properties that hold the principal id and the person name:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="principalName" p:label="Person Name" p:required="true">
  3     <property name="control">
  4         <bean parent="Uif-KimPersonControl" p:principalIdPropertyName="principalId" p:personNamePropertyName="personName"/>
  5     </property>
  6 </bean>
  7                 

It a common setup to carry the principal id as a primitive field, with a nested Person object. In these cases, it is not necessary to have a separate property for the principal name and person name, but instead the properties on the nested person object can be used. For these cases, the user control provides a simpler way to configure it by setting the personObjectPropertyName. This is the name of the property that holds the nested person object.

  1 
  2 <bean parent="Uif-InputField" p:propertyName="principalName" p:label="Person Name" p:required="true">
  3     <property name="control">
  4         <bean parent="Uif-KimPersonControl" p:personObjectPropertyName="person"/>
  5     </property>
  6 </bean>
  7                 

Below shows the user control with the person name displayed:

Figure 6.17. KIM Group Control

For many instances where a lookup or inquiry is desired, there is an underlying relationship in the model. In Chapter 3, we learned how to represent one-to-one relationships in code (with nested data objects) and then provide configuration to OJB using a reference descriptor. In Chapter 4, we learned about the data dictionary and the ability to declare relationship definitions for our data object entry. These sources of metadata are then consumed by the UIF to automatically configure lookups and inquiries for our fields!

For each data or input field, the framework will attempt to find a model relationship if two conditions are met: one, we have not manually configured the lookup and inquiry; and two, the render flag for both is not set to false. Setting the render flag to false on the fieldLookup or fieldInquiry indicates to the framework that we do not want them rendered regardless of the existence of a relationship.

The basic strategy for determining the existence of a relationship is as follows:

This is a complicated process and not all details are important as a user of KRAD. However, the first step is critical to understand and deserves more explanation. The determination of the parent data object class drives the metadata picked up by the framework and therefore where the relationships will be found. Recall the three parts to the fields binding path: the object path, binding prefix, and binding name (property name). The framework will use the object path and prefix as the path to the parent object (everything except the property name). Then it will get the type for the property from the model which is used as the data object class.

A couple of things should be noted about the automatic lookups and inquiries. First, if no relationship is found, the render flag on the widget will be set to false. Second, recall for the lookup and inquiry, we need to configure field mappings (fieldConversions and inquiryParameters). The framework builds these mappings from the fields that participate in the relationship.

Each time the field is rendered, the information display property values will be displayed. This is useful, however, by itself it is not 'dynamic'. That is, if the user then changes the value, the information properties will not change to reflect the update. To make this happen, we need to associate a piece of functionality called attribute query with our field.

An attribute query is represented by the class org.kuali.rice.krad.uif.field.AttributeQuery. This is not a component, just a class that configures behavior that can be added to the input field component. Basically, this class provides properties for configuring a query to retrieve these information properties. It has similar concepts to the lookup (quickfinder widget) with a more targeted purpose. There are two mechanisms for configuring a query. The first involves configuring the necessary properties to allow the framework to automatically perform a query. This involves the following attribute query properties:

dataObjectClassName – Name of the data object class the query will go against. The class given must be mapped to the database (with ORM metadata) to support the automatic lookup. This functions the same as the dataObjectClassName for the lookup view (or quickfinder widget).

queryFieldMapping – A map type that holds the mappings of properties from the calling view to properties on the data object class. Each entry represents one property mapping. The map key is the property name in the calling view, and the map value is the property name on the data object class. This will usually include the property name of the field for which the query is configured (since we want to query based on the value the user has inputted). We might need to pass in additional properties from the view to complete the query. This property functions similarly to the inquiryParameters on the inquiry widget.

Note this mapping is used to build criteria for the query. The values for the calling view properties are retrieved and used to restrict the retrieved data object records based on the mapped data object fields. For example, suppose we have the following query field mapping: "document.rentedBookId:bookId" and the value of the document.rentedBookId on our view is '3'. When the query is performed the following clause will be created "where bookId = '3'" (note the actual SQL is not constructed by KRAD, but created by the OJB criteria object).

returnFieldMapping – A map type that holds the mappings of properties from the data object class to the calling view. Each entry represents one property mapping. The map key is the property name on the data object class, and the map value is the property name on the calling view. We can use this property to map properties on the data object class back to configured information display properties of the field. However, it is not limited to that. We can also map properties of the data object class back to properties that are separate fields (thus filling in the control value for those corresponding fields).

additionalCriteria – A map that holds additional criteria for the query. The criteria specified will be added to the constructed criteria based on query field mapping. The map key is the name of the property on the data object class the criteria should apply to, and the map value is the value for the criteria. All map entries are joined using the AND clause. Note, the map value does support query characters as provided by the lookup framework ('!' – not, '>' – greater than, '<' – less than, '*' – wildcard, and so on). In addition for the map values, we can use expressions ('@{}').

To hook up an attribute query with an input field we use the fieldAttributeQuery property. We can then create an instance of the attribute query class by creating a bean with parent of 'Uif-AttributeQueryConfig':

  1 
  2 <bean parent="Uif-InputField" p:propertyName="rentedBookId" p:label="Book Id" 
  3       p:informationalDisplayPropertyNames="rentedBookTitle,rentedBookCopyright">
  4     <property name="fieldAttribueQuery">
  5         <bean parent="Uif-AttributeQueryConfig" p:dataObjectClassName="edu.sampleu.bookstore.bo.Book" 
  6          p:queryFieldMapping="rentedBookId:bookId" 
  7          p:returnFieldMapping="bookTitle:rentedBookTitle, bookCopyright:rentedBookCopyright"/>
  8     </property>
  9 </bean>
 10             

In this example we have an input field for the rentedBookId property. We then setup a query that will go against the Book data object, passing the value for rentedBookId as criteria for the bookId property. From the resulting record, the bookTitle and bookCopyright property values will be copied to the rentedBookTitle and rendedBookCopyright properties. These are configured as informational display properties, therefore the updated values will display under the control for rentedBookId.

Note the framework takes care of triggering the query (with the 'onblur' event), performing the query, and updating the mapping return fields all client side (without a page post). It is expected the field attribute query will return only one result. If more than one record is retrieved, the first record of the hit list will be used. In the case of no matching records, a message will be rendered stating '{field label} not found', where {field label} is the configured label. This message can be disabled by setting fieldAttributeQuery.renderNotFoundMessage to false. In addition, attribute query contains a property named returnMessageText that can be used to configure a message that will display with the results, or a custom message in the case where no results are found.

The attribute query class also allows us to hook up a custom query that will be invoked to retrieve the additional information. In this case, the developer writes the actual code to perform the query (call another service or whatever) and return the results. The framework will then take care of triggering the query and handling the results (updating the values).

There is a great deal of flexibility for invoking a custom query method. Let's start with the way that requires the least amount of configuration. First, we need to know a little bit about the framework code, in particular one service. The UIF invokes a service of type org.kuali.rice.krad.uif.service.ViewHelperService to perform building of the view and many other UI related functions. An implementation of this service (ViewHelperServiceImpl) carries out this processing. The framework allows us to extend this service and declare that one or more views should use the custom view helper. This is our gateway for code-based customizations. So let's do it! The following sets up a custom view helper service:

  1 
  2 package edu.myedu.sample;
  3 public class CustomViewHelperServiceImpl extends ViewHelperServiceImpl {
  4 }

Next we configure our view to use the custom view helper service. This is done by setting the viewHelperServiceClass property on the view component (the View component is covered in complete detail in Chapter 9):

  1 
  2 <bean id="MyView" parent="Uif-FormView">
  3     ...
  4     <property name="viewHelperServiceClass" value="edu.myedu.sample.CustomViewHelperServiceImpl"/>
  5 </bean>
  6             

Now we have a place to put our custom query method. The signature of this method depends on the query being performed, but there are a few guidelines:

To understand this better, let's take an example. We will create a method that will perform the same search as our automatic book query example. The query will go against the Book data object and take in the book id as a parameter:

  1 
  2 public Book retrieveBookById(String bookId) {
  3     Book foundBook;
  4     // do query to find the book
  5     
  6     return foundBook;
  7 }
  8             

Now we need to configure the attribute query for the book id input field. To specify the name of our method that should be called, we use the queryMethodToCall property provided by the AttributeQuery class. Then we specify the arguments for our method using the queryMethodArgumentFieldList property. Note this property functions similarly to the queryFieldMapping, except we are not mapping properties from the calling view to properties on a data object, but instead to method arguments. The value for each property configured in the queryMethodArgumentFieldList list is retrieved and passed as a method argument in the order listed.

The final step is to configure the returnFieldMapping property. This is the same as when doing the automatic query. It maps properties on the returned object (returned from the method) to properties on the view.

  1 
  2 <bean parent="Uif-InputField" p:propertyName="rentedBookId" p:label="Book Id" 
  3      p:informationalDisplayPropertyNames="rentedBookTitle,rentedBookCopyright">
  4     <property name="fieldAttribueQuery">
  5         <bean parent="Uif-AttributeQueryConfig" p:queryMethodToCall="retrieveBookById" 
  6           p:queryMethodArgumentFieldList ="rentedBookId" 
  7           p:returnFieldMapping="bookTitle:rentedBookTitle, bookCopyright:rentedBookCopyright"/>
  8     </property>
  9 </bean>
 10             

Here we configure the attribute query to invoke the 'retrieveBookById' method. Since this is the only configuration we gave, the framework assumes this is on the view helper service. Next, we set the query method argument list as 'rentedBookId'. This means the value for the rentedBookId (the backing property for the field) will be pulled and sent as the first argument to our method. If we added another property; its value would be passed as the second argument, and so on. Finally, we configure the return field mapping to pull the bookTitle and bookCopyright properties from the data object returned from our method, and copy those values to the rentedBookTitle and rentedBookCopyright properties on the view model.

In addition to calling methods on a custom view helper service, we can choose to call a method within another class. This could be a static class method somewhere, or a method on another service configured in the Spring container. To configure an alternate class, we use the queryMethodInvokerConfig property on AttributeQuery.

The type for this property is org.kuali.rice.krad.uif.component.MethodInvokerConfig. This type is used in various places within KRAD to configure a method invocation (for example setting component properties through code which is covered in Chapter 10). The class that contains the query method can be specified using one of the following three properties:

targetClass – Fully qualified class that contains the method. A new instance of this class will be created before the method is invoked.

targetObject – Object instance the method should be invoked on. This is useful for referencing other Spring beans such as services.

staticMethod – This configures a static method invocation and includes the class and method name (e.g. 'edu.myedu.sample.QueryUtils.retrieveById').

When using targetClass or targetObject, the method name can be configured by using the queryMethodToCall property on AttributeQuery, or by setting the targetMethod property on MethodInvokerConfig. If needed, the argument types can be specified using the argumentTypes property (in the case of overloaded methods), or even more information (such as generics and so on) can be configured using the methodObject property.

Wow! That's a lot of options. Let's look at a couple of examples.

First let's assume we have the following static method:

  1 
  2 package edu.myedu.sample;
  3 public class QueryUtils {
  4     public static Book retrieveBookById(String bookId) {
  5         Book foundBook;
  6         // do query to find the book
  7         return foundBook;
  8     }
  9 } 
 10             

Our query configuration would then be as follows:

  1 
  2 <property name="fieldAttribueQuery">
  3     <bean parent="Uif-AttributeQueryConfig" 
  4         p:queryMethodInvokerConfig.staticMethod=
  5         "edu.myedu.sample.QueryUtils.retrieveBookById"
  6         p:returnFieldMapping="bookTitle:rentedBookTitle,
  7         bookCopyright:rentedBookCopyright"/>
  8 </property>
  9             

Next assume we have a service that has our retrieveBookById method, and we have the following Spring bean:

  1 
  2 <bean id="BookService" class="edu.myedu.sample.BookServiceImpl"/>

Our query configuration would then be as follows:

  1 
  2 <property name="fieldAttribueQuery">
  3     <bean parent="Uif-AttributeQueryConfig"
  4         p:queryMethodToCall="retrieveBookById"
  5         p:returnFieldMapping="bookTitle:rentedBookTitle,
  6         bookCopyright:rentedBookCopyright">
  7     <property name="queryMethodInvokerConfig.targetObject">
  8         <ref bean="BookService"/>
  9     </property>
 10     </bean>
 11 </property>
 12             

Finally the case of a non-static class method:

  1 
  2 package edu.myedu.sample;
  3 public class QueryUtils {
  4     public Book retrieveBookById(String bookId) {
  5         Book foundBook;
  6         // do query to find the book
  7         return foundBook;
  8     }
  9 } 
 10             

Our query configuration would be as follows:

  1   
  2 <property name="fieldAttribueQuery">
  3     <bean parent="Uif-AttributeQueryConfig"
  4         p:queryMethodToCall="retrieveBookById"
  5         p:queryMethodInvokerConfig.targetClass=
  6         "edu.myedu.sample.QueryUtils" 
  7         p:returnFieldMapping="bookTitle:rentedBookTitle,
  8         bookCopyright:rentedBookCopyright"/>
  9 </property>
 10             

The attribute query class is also used for configuring the Suggest widget. The Suggest widget decorates the standard text control to show the user options as they are inputting text (also known as auto-complete). The Suggest widget itself provides configuration on the client side behavior (such as delay, minimum number of characters for query, and so on). This widget along with others is covered in Chapter 8.

The attribute query for the field Suggest widget is configured much like the field query. The only difference is instead of returning multiple fields from one record, we want to return values for one field only, but potentially multiple records. These make up the options the user sees when inputting a value (similar to the options provided by multi-value controls). In addition, the framework assumes that property from the data object class maps back to the field we configured the suggest with, therefore, we do not have to specify the returnFieldMapping.

We configure the Suggest widget using the input field's suggest property. This is the nested Suggest widget, which contains a nested AttributeQuery in the suggestQuery property. The base bean for the Suggest widget is 'Uif-Suggest'. We again have the two mechanisms for configuring the query (automatic with dataObjectClassName, or build our own query and specify queryMethodToCall). After we have configured the data object or the query method, we can then specify the property name for the data object class that provides values using the suggest.valuePropertyName:

  1 
  2 <bean parent="Uif-InputField" p:propertyName="rentedBookTitle">
  3     <property name="suggest">
  4         <bean parent="Uif-Suggest" p:valuePropertyName ="bookTitle"
  5             p:suggestQuery.dataObjectClassName="edu.myedu.sample.Book"/>
  6     </property>
  7     </bean>
  8             

Since our query can now return multiple records, we should sort them so the field values appear in ascending order to the user. This can be accomplished by specifying the property names to sort by with the attribute query sortPropertyNames property:

  1 
  2 <property name="suggest">
  3     <bean parent="Uif-Suggest" p:valuePropertyName ="bookTitle"
  4         p:suggestQuery.dataObjectClassName="edu.myedu.sample.Book"
  5         p:suggestQuery.sortPropertyNames="bookTitle"/>
  6 </property>
  7             

In this example we are sorting the resulting Book data objects by their bookTitle property. The sortPropertyNames property is a List type, therefore multiple columns to sort on can be given (using a comma for the shorthand notation, or the Spring list tag).

  1 
  2 <bean parent="Uif-InputField" p:propertyName="bookId"
  3     p:readOnlyDisplaySuffixPropertyName="bookTitle"
  4     p:informationalDisplayPropertyNames="bookTitle,bookCopyright">
  5     <property name="fieldLookup">
  6         <bean parent="Uif-Quickfinder"
  7             p:dataObjectClassName="edu.myedu.sample.Book"
  8             p:fieldConversions="id:bookId"/>
  9     </property>
 10 </bean>
 11                 

Sometimes it can be useful to identify an action based on an event (functional, not technical such as onclick) that we can use to make decisions when the action is invoked. For example, one common action screens must have is the save operation. This is invoked to save the current data on the client to the server. Generally these are labeled as 'Save', but they don't have to be. For example the designer might choose to label the action 'Save Document', or 'Save Course'. Using the actionEvent property available on the Action component, we can configure all these buttons as invoking a 'save' event:

  1 
  2 <bean parent="Uif-PrimaryActionButton" p:actionLabel="Save Document" p:methodToCall="saveDocument" p:actionEvent="save"/>  
  3 
  4 <bean parent="Uif-PrimaryActionButton" p:actionLabel="Save Course" p:methodToCall="saveCourse" p:actionEvent="save"/>
  5             

When an action is invoked, the corresponding action event value will be passed as a request parameter along with the method to call. We can then inspect the request value (using the request object, or if our model extends UifFormBase it provides the property for us) and perform the logic associated with the event.

So exactly what could we do with this? One good use is within the business rules framework (discussed in Chapter 13). Business rules are written to respond to an event (a rule event), thus the action event name can be mapped to a rule event. Action events can also be useful within the view rendering logic. For example, one use the UIF currently has is to determine when the add action has been taken for a collection. Since the button could be labeled differently between collections and views, the framework determines if the action requested was a collection 'add' by looking at the action event. It then sets up a script to perform highlighting on the added row once the component refreshes.

Along with the method to call and action event parameters that are sent for an action, there are cases where we might need more information to complete a request. An example of this are actions that operate on a collection line. These actions are likely available for each line (for instance the delete button), so if we only invoke the deleteLine button or send in the 'delete' action event, how will we know which line(s) to delete? Furthermore, if there are multiple collections on the page, how will we know which collection?

The framework allows us to specify additional request data that will be sent when an action is taken using the actionParameters property. This is a map type where the key specifies the name for the request parameter, and the map value the request parameter value. Let's assume we are configuring a button with a collection group (covered in next chapter):

  1 
  2 <bean parent="Uif-PrimaryActionButton" p:actionLabel="delete" p:methodToCall="deleteAccount" 
  3       p:actionParameters="chart:@{#line.chartCode},account:@{#line.accountNumber}"/>
  4             

Here we are using the shorthand map notation to setup two action parameters. The first will have name 'chart' and will be equal to the value for the chart code property on the current collection line (collections make the '#line' variables available that refers to the current line instance for which the component is being built). Likewise the second parameter will have name 'account' and will be equal to the value for the account number property on the current line.

When the user takes the action and our controller method is invoked, we will have request parameters with names 'chart' and 'account' that we can use to determine which account data object instance we should delete. In Chapter 12 we will learn about a base form class our model can extend which does many things for us. Among these is providing a map property populated with the action parameter sent in the request, and a convenience method for getting the value of a parameter by name:

  1 
  2 public Map<String, String> getActionParameters();
  3 public String getActionParamaterValue(String actionParameterName);
  4             

Thus in our controller method we can do the following:

  1 
  2 public ModelAndView deleteAccount(@ModelAttribute("KualiForm") UifFormBase
  3 uifForm, BindingResult result, HttpServletRequest request, HttpServletResponse response) {
  4     AccountForm accountForm = (AccountForm) uifForm;
  5     String selectedChartCode = accountForm.getActionParamaterValue("chart");
  6     String selectedAccountNumber = accountForm.getActionParamaterValue("account");
  7     // delete account
  8     ...
  9 }
 10             

Along with the action parameters we configure in XML, the framework will add parameters for us automatically in certain situations. For example, any action component within a collection group will receive a parameters 'selectedCollectionPath' and 'selectedLineIndex', which indicate the collection name and line index the action took place on.

An action component can occur anywhere in a view, including in the middle of page. In most cases after an action is taken the user wants to continue completing the form at the location the action took place (location of the button or link). In a page with lots of vertical scrolling, what we don't want to happen is after the user clicks a button in the middle of the page, they are pushed back to the top on refresh and have to scroll back down to their previous position. Therefore, we want to set anchor points that will be used when the page refreshes after the action.

To set this up, the action component provides the jumpToIdAfterSubmit and jumpToNameAfterSubmit properties. We can specify one of these properties to set the anchor position. For the jump to id, we specify the id for a component on the view. This could be the button itself, a group (with a div element) or any other field. For example, on the following button we are specifying the page should scroll back to the button location on refresh:

  1 
  2 <bean id="delete_button" parent="Uif-PrimaryActionButton" p:actionLabel="delete"
  3 p:methodToCall="deleteAccount"
  4 p:jumpToIdAfterSubmit="delete_button"/>
  5             

If we want to scroll back to the location of a data or input field, we can specify the property name for the field using the jumpToNameAfterSubmit property:

  1 
  2 <bean parent="Uif-PrimaryActionButton" p:actionLabel="delete"
  3 p:methodToCall="deleteAccount"
  4 p:jumpToIdAfterSubmit="newAccount.accountNumber"/>
  5             

To scroll back to the top or bottom of the page, the keywords "TOP" or "BOTTOM" can be given for the jump to id:

  1 
  2 <bean parent="Uif-PrimaryActionButton" p:actionLabel="Save" p:methodToCall="save" p:jumpToIdAfterSubmit="TOP"/>
  3             

In addition to anchoring, we might want to set focus to a particular field after an action is taken. The UIF includes an example of this in the collection group. After the add action is taken, the focus is set back to the first field on the collection add line.

We can configure the focused component using the focusOnIdAfterSubmit property. This is the id of the field that should receive focus when the page (or component) refreshes. The keyword "FIRST" exists to set focus to the first visible input field control on the view:

  1 
  2 <bean parent="Uif-PrimaryActionButton" p:actionLabel="Save" 
  3 p:methodToCall="save" p:focusOnIdAfterSubmit="FIRST"/>
  4             

One other property on the action component that deserves mentioning is the disabled property. This performs the same function as the disabled property on Control elements. When set to true, the button will not allow the user to take the associated action.

Below shows two buttons. The first is enabled and the second is disabled.

Figure 6.28. Enabled and Disabled Buttons