Kuali Rice 2.5.0-M4-SNAPSHOT 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 quickstart archetype is a new Maven-based Rice client project. This includes the directory structures for building out your application, along with the necessary configuration files. This includes the Maven pom.xml file and the src directory, which has the standard Maven directory breakdown:

As a part of the installation process, some files are modified or created to match the options specified above.

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 src/main/resources/org/foo/bar/BootStrapConfig.xml

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 an IDE so that we will be ready to further develop the application code. We will use Eclipse as an example here.

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 data dictionary files, package prefixes, and resource bundles) 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 <bean id="sampleAppModuleConfiguration" class="org.kuali.rice.kns.bo.ModuleConfiguration">
  2     <property name="namespaceCode" value="KR-SAP"/>
  3     <property name="initializeDataDictionary" value="true"/>
  4     <property name="dataDictionaryPackages">
  5         <list>
  6             <value>edu/sampleu/travel/datadictionary</value>
  7         </list>
  8     </property>
  9     <property name="packagePrefixes">
 10         <list>
 11           <value>edu.sampleu.travel</value>
 12         </list>
 13     </property>
 14     <property name="providers">
 15         <list>
 16             <ref bean="jpaPersistenceProvider"/>
 17             <ref bean="metadataProvider"/>
 18         </list>
 19     </property>
 20 </bean>

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 data dictionary, 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 <bean id="sampleAppModuleService" class="org.kuali.rice.krad.service.impl.ModuleServiceBase">
  2     <property name="moduleConfiguration" ref="sampleAppModuleConfiguration"/>
  3 </bean>

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).

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).

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 object in KRAD is known as a Data Object. There are two primary types of data object: those that persist to the database and those that do not. 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.DataObjectBase. 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. Data objects that do not persist to the database do not have to extend any particular class.

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 data objects. One of these special types is data 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 data 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 data 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 data 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. Data 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.

At times, there is a need to add additional attributes to existing objects in Rice or in a Rice-based client application. Since not all objects can be subclassed safely (as some code may instantiate the base classes directly, we recommend creating an "extension" object with the additional attributes. This object will need to have the same primary key field(s) as the class being extended.

Rice helps to faciltate this through two additional features.

@Entity
@Table(name="TRV_ACCT_EXT")
@ExtensionFor(Account.class)
public class AccountExtension { ...} 
	            	

@Entity
@Table(name="TRV_ACCT_EXT")
@ExtensionFor(value=Account.class,extensionPropertyName="extensionObject")
public class AccountExtension { ...} 
	            	

KradEntityManagerFactoryBean

The KradEntitymanagerFactory is a KRAD-managed entity manager factory bean which can be used to configure a JPA persistence unit using the Spring Framework. This implementation does not support the use of a custom PersistenceUnitManager, but rather stores and manages one internally. This is intended to be an alternative to direct usage of Spring's LocalContainerEntityManagerFactoryBean in order to make JPA configuration with KRAD simpler.

Configuration

The minimal configuration for the KRADEntityManagerFactory is a persistence unit name, JTA or non-JTA datasource, and JPA vendor adapter.

Behavior

When leveraging this class, persistence.xml files are not used. Rather, persistence unit configuration is loaded via the various settings provided on this factory bean which contain everything needed to create the desired persistence unit configuration in the majority of cases. If a KRAD application needs more control over the configuration of the persistence unit or wants to use persistence.xml and JPA's default bootstrapping and classpath scanning behavior, an EntityManagerFactory can be configured using the other classes provided by the Spring framework or by other means as needed. See the LocalContainerEntityManagerFactoryBean class for an alternative approach.

Only one of JTA or non-JTA datasource can be set. Depending on which one is set, the underlying persistence unit will have it's javax.persistence.spi.PersistenceUnitTransactionType set to either RESOURCE_LOCAL or JTA. If both of these are set, then this class will throw an IllegalStateException when the afterPropertiesSet method is invoked by the Spring Framework.

Elsewhere, this class delegates to implementations of LocalContainerEntityManagerFactoryBean and DefaultPersistenceUnitManager, so information on the specific behavior of some of the settings and methods on this class can be found on the javadoc for those classes as well.

JPA Property Defaults

When the afterPropertiesSet method is invoked, this class will scan the current config context for JPA properties and make them available to the persistence unit. It will combine these with any properties that were set directly on this factory bean via the setJpaProperties(java.util.Properties) or the setJpaPropertyMap(java.util.Map) methods.

This scanning occurs in the following order, items later in the list will override any properties from earlier if they happen to set the same effective property value:

KradEclipseLinkEntityManagerFactoryBean

The KradEclipseLinkEntityManagerFactory is a KRAD-managed enitity manager factory which can be used to configure an EclipseLink persistence unit using JPA. This class inherits from the KradEntityManagerFactoryBean class, but adds the following behavior:

Typical KradEclipseLinkEntityManagerFactoryBean Configuration

<bean id="sampleApplicationDataSource" class="org.kuali.rice.core.framework.persistence.jdbc.datasource.PrimaryDataSourceFactoryBean" lazy-init="true">
	<property name="preferredDataSourceParams">
		<list>
			<value>sampleApplication.datasource</value>
		</list>
	</property>
	<property name="preferredDataSourceJndiParams">
		<list>
			<value>sampleApplication.datasource.jndi.location</value>
		</list>
	</property>
	<property
		name="serverDataSource"
		value="false" />
</bean>

<bean id="jpaPersistenceUnitName" class="java.lang.String">
		<constructor-arg value="sample-application" />
</bean>

<util:list id="sampleJpaPackagesToScan">
	<value>org.kuali.rice.krad.sampleapp.jpa</value>
	<value>org.kuali.rice.krad.sampleapp.bo</value>
</util:list>

// empty since we are doing package scans
<util:list id="managedClassNames" />

<bean id="entityManagerFactory" class="org.kuali.rice.krad.data.jpa.eclipselink.KradEclipseLinkEntityManagerFactoryBean"
    p:jtaDataSource-ref="sampleApplicationDataSource" p:persistenceUnitName-ref="jpaPersistenceUnitName"
    p:packagesToScan-ref="sampleJpaPackagesToScan" p:managedClassNames-ref="managedClassNames" />

            

EclipseLink Bytecode Weaving Concerns

In order to leverage a number of features provided by EclipseLink, bytecode weaving of the JPA entities in the persistence unit must be performed. EclipseLink uses this technique to enable lazy loading, change tracking, fetch groups, and internal optimizations for JPA entites. Weaving is the technique that is used to perform this manipulation of the bytecode of compiled Java classes.

You can read more about it in the EclipseLink documentation on Weaving.

There are essentially four approaches that you can take:

Except in the case of very simple applications, performing bytecode weaving is recommended.

If you are building library code which contains JPA entities, then static weaving is a good choice as it will allow you to distribute your JARs with "pre-weaved" class files. EclipseLink provides an Ant task for performing this. If you are using Maven instead there is a plugin you can use. A typical configuration of the plugin would look like this:

<plugin>
  <groupId>au.com.alderaan</groupId>
  <artifactId>eclipselink-staticweave-maven-plugin</artifactId>
  <version>1.0.4</version>
    <executions>
      <execution>
        <goals>
          <goal>weave</goal>
        </goals>
        <phase>process-classes</phase>
        <configuration>
          <logLevel>FINER</logLevel>
          <persistenceXMLLocation>META-INF/persistence-weaving.xml</persistenceXMLLocation>
        </configuration>
      </execution>
    </executions>
  </version>
</plugin>

Note the reference to a "persistence-weaving.xml" file. Static weaving requires a JPA-standard persistence.xml file in order to identify the entities, mapped super classes, and embedded classes which need to be bytecode weaved. If you are using the KradEclipseLinkEntityManagerFactoryBean, then it is assembling the persistence unit for you programatically and there is no persistence.xml file. We can work around this by defining a separate persistence-weaving.xml file that simply contains a list of the JPA entities, mapped superclasses, and embeddables in our persistence unit. A typical file might look like this:

<persistence ...>
  <persistence-unit name="...">
    <class>my.package.JpaEntityOne</class>
    <class>my.package.JpaEntityTwo</class>
    ...
  </persistence-unit>
</persistence>

If your JPA entity code will only be consumed internally by your application, then load-time weaving is easy to configure and likely the best choice. It is recommend to do this using the capabilities that the Spring framework provides for load-time weaving. See the Spring documentation on registering a LoadTimeWeaver.

For the "hybrid" approach, you simply configure both static and load-time weaving. They can work in conjunction with each other. This is primarily useful if you are developing in an IDE environment. Whenever you change an entity class in the IDE it will recompile that class and the newly compiled version will be missing any bytecode weaving until either static weaving is performed (by executing the Ant task or Maven goal) or a load time weaver is used when the class is loaded. In the hybrid approach, the load-time weaver simply acts as a backup for those situations where the statically weaved bytecode gets blown away by an incremental IDE compile.

This hybrid approach is actually the technique that Kuali Rice uses internally since it distributes libraries containing statically-weaved JPA entities. If you are distributing libraries for usage by others and would like to use the hybrid approach, you might also consider looking at the org.kuali.rice.core.framework.util.spring.OptionalContextLoadTimeWeaver class to avoid requiring any clients of your libraries to also have to configure load-time weaving just to use your library.

Persistence providers are implementations of the Java Persistence API (JPA) specification.

When creating a new instance of the JpaPersistenceProvider, a reference to a "shared" entity manager like that created by Spring's org.springframework.orm.jpa.support.SharedEntityManagerBean must be injected. Additionally, a reference to a DataObjectService must be injected as well.

Spring JpaPersistenceProvider Setup

<util:list id="location.managedClassNames">
   <value>org.kuali.rice.foo.FooBo</value>
   <value>org.kuali.rice.foo.BarBo</value>
</util:list>

<bean id="location.entityManagerFactory" class="org.kuali.rice.krad.data.jpa.eclipselink.KradEclipseLinkEntityManagerFactoryBean"
    p:jtaDataSource-ref="locationDataSource" p:persistenceUnitName="rice.location"
    p:managedClassNames-ref="location.managedClassNames"/>

<bean id="dataObjectService" class="org.kuali.rice.krad.data.KradDataFactoryBean"/>
            
<bean id="sharedEntityManager" class="org.springframework.orm.jpa.support.SharedEntityManagerBean"
    p:entityManagerFactory-ref="entityManagerFactory" />

<bean id="jpaPersistenceProvider" class="org.kuali.rice.krad.data.jpa.JpaPersistenceProvider"
    p:dataObjectService-ref="dataObjectService" p:sharedEntityManager-ref="sharedEntityManager"/>

        

The JpaPersistenceProvider must then be registered with the Provider Registry in one of two ways:

Inject into ProviderRegistar bean

<bean id="location.providerRegistrar" class="org.kuali.rice.krad.data.provider.ProviderRegistrar">
    <property name="providerRegistry" ref="providerRegistry" />
    <property name="providers">
      <util:list>
        <ref bean="location.jpaPersistenceProvider" />
        <ref bean="location.metadataProvider" />
      </util:list>
    </property>
  </bean>
 
        

Inject into the ModuleConfiguration

<bean id="locationModuleConfiguration" class="org.kuali.rice.krad.bo.ModuleConfiguration">
    <property name="namespaceCode" value="location"/>
    <property name="dataSourceName" value="locationDataSource"/>
    ...
    <property name="providers">
      <list>
        <ref bean="jpaPersistenceProvider"/>
        <ref bean="metadataProvider"/>
      </list>
    </property>
    ...
</bean>      

        

Transactions are handled by default via this configuration. The JpaPersistenceProvider uses Spring's @Transactional annotation along with the corresponding setup to ensure that all calls through the DataObjectService are wrapped in transactions. Any alternate persistence provider that supports transactions will also be handled in this manner. In other words, the DataObjectService acts as a transactional boundary and uses the default Propagation.REQUIRED to ensure that either a transaction exists or a new one is created.

For some objects, such as DocumentType which depends on parent types of the same class, KRAD uses optimistic locks on the parent type to force any transaction that has updated the parent type to finish before creating a new transaction to update the current type.

To assist with the processing and displaying of information, Kuali Rice comes with a JPA-based metadata provider that extracts information from the JPA annotations and infers information about object keys, attributes, collections, relationships, and default display values. This is an essential part of any JPA-based setup, so any application implementing JPA in Rice must at the very least hook up to the metadata provider.

In the configuration for each module, the following must be included to hook into the provider.

<property name="providers">
    <list>
        <ref bean="jpaPersistenceProvider"/>
        <ref bean="metadataProvider"/>
    </list>
</property>

The key here is the metadataProvider which is a list that includes the JPA metadata provider, among others. By default, this points back into Rice to

<bean id="metadataProviderJpa"
    class="org.kuali.rice.krad.data.jpa.eclipselink.EclipseLinkJpaMetadataProviderImpl"
    p:entityManager-ref="sharedEntityManager" />

which uses the EclipseLink reference implementation classes to populate metadata objects. Only applications that wish to use a different JPA implementation would ever have to override this bean.

Implementers can create their own providers for persistence and metadata by implementing certain interfaces. Any persistence provider should use the org.kuali.rice.krad.data.provider.PersistenceProvider interface which requires implementing methods for finding, saving, and deleting data objects. Singleton metadata providers should use the org.kuali.rice.krad.data.provider.MetadataProvider interface which requires implementing methods for retrieving metadata for a certain type. In addition, the org.kuali.rice.krad.data.provider.CompositeMetadataProvider interface defines a container of several singleton metadata providers. This interface is mainly used in situations where there is custom logic to merge the metadata from multiple providers. For convenience in creating any metadata provider, KRAD includes the base class org.kuali.rice.krad.data.provider.impl.MetadataProviderBase.

Providers can be included in the system by declaring them in Spring and then hooking them up via the providers list in the module, in the same way as normally done with the default persistence or metadata providers.

<property name="providers">
    <list>
        <ref bean="jpaPersistenceProvider"/>
        <ref bean="customPersistenceProvider"/>
        <ref bean="metadataProvider"/>
        <ref bean="customMetadataProvider"/>
    </list>
</property>

Each kind of provider defines methods to determine whether it can provide data for any given type, so the registry will search each provider in the list in the module and return the first provider that handles the given type.

The metadata about data objects is available now directly via the DataObjectService.wrap(..) method, which loads the metadata from the metadata repository and places it in a DataObjectWrapper. This wrapper gives access to such information as the primary keys, the business keys, the foreign keys, the attributes, the collections inside the data object, and the relationships to the data object. It also provides methods to perform manual linking between foreign key and relationship values in case that is not possible or unwanted to do automatically through JPA.

For example, if you wanted to get all of the primary key values from a data object, you could write the following:

T dataObject = getDataObject();
DataObjectWrapper<T> wrapper = getDataObjectService().wrap(dataObject);
Map<String, Object> primaryKeyValues = wrapper.getPrimaryKeyValues();

In JPA there are several ways to execute queries. The following are the best practices that should be used when using JPA in Kuali applications. In general the order of consideration for a query should go as the following:

Simple DataObjectService fetch by Primary Key

CountryBo countryBo = getDataObjectService().find(CountryBo.class,code);

// Fetch by Compound Primary Key
final Map<String, Object> map = new HashMap<String, Object>();
map.put("countryCode", countryCode);
map.put("code", code);
StateBo stateBo = getDataObjectService().find(StateBo.class,new CompoundKey(map)));

DataObjectService query for matching results

// Fetch all matching results by countryCode and that have active equivalent to true
final Map<String, Object> map = new HashMap<String, Object>();
map.put("countryCode", countryCode);
map.put("active", Boolean.TRUE);

QueryResults<PostalCodeBo> postalCodeBoQueryResults = getDataObjectService().
    findMatching(PostalCodeBo.class,QueryByCriteria.Builder.andAttributes(map).build());

// Fetch all Countries that have alternateCountryCode equal to value passed in
QueryByCriteria qbc = QueryByCriteria.Builder.forAttribute(
    KRADPropertyConstants.ALTERNATE_POSTAL_COUNTRY_CODE, alternateCode).build();
QueryResults<CountryBo> countryBoQueryResults = getDataObjectService().findMatching(CountryBo.class,qbc);
List<CountryBo> countryList = countryBoQueryResults.getResults();

DataObjectService query returning the count based on Criteria

//Fetch count based on document id and principal id and current indicator being true
QueryByCriteria.Builder criteria = QueryByCriteria.Builder.create().setPredicates(
                                       equal(DOCUMENT_ID, documentId),
                                       equal(PRINCIPAL_ID, principalId),
                                       equal(CURRENT_INDICATOR, Boolean.TRUE));
criteria.setCountFlag(CountFlag.ONLY);
return getDataObjectService().findMatching(ActionTakenValue.class, criteria.build()).getTotalRowCount();

DataObjectService save

// Fetch by Compound Primary Key
final Map<String, Object> map = new HashMap<String, Object>();
map.put("countryCode", countryCode);
map.put("code", code);
StateBo stateBo = getDataObjectService().find(StateBo.class,new CompoundKey(map)));

// make the StateBo inactive
stateBo.setActiveToDate(new Timestamp(System.currentTimeMillis());

// save the StateBo and get the updated instance
stateBo = getDataObjectService().save(stateBo);

DataObjectService save with PersistenceOption

// Fetch by Compound Primary Key
final Map<String, Object> map = new HashMap<String, Object>();
map.put("countryCode", countryCode);
map.put("code", code);
StateBo stateBo = getDataObjectService().find(StateBo.class,new CompoundKey(map)));

// make the StateBo inactive
stateBo.setActiveToDate(new Timestamp(System.currentTimeMillis());

// save the StateBo, include a PersistenceOption, and get the updated instance
stateBo = getDataObjectService().save(stateBo, PersistenceOption.FLUSH);

PersistenceOptions

One or more persistence options can be passed to indicate whether or not linking should be performed prior to persistence. By default, linking foreign key values on the wrapped data object is performed. Below is a list of PersistionOption values.

DataObjectService delete

// Fetch by Compound Primary Key
final Map<String, Object> map = new HashMap<String, Object>();
map.put("countryCode", countryCode);
map.put("code", code);
StateBo stateBo = getDataObjectService().find(StateBo.class,new CompoundKey(map)));

// delete the StateBo
getDataObjectService().delete(stateBo);

Injecting the Shared Entity Manager

// Add the following to your Spring DAO implementation to assign the appropriate Persistence Unit to your DAO
public class DocumentTypeDAOJpa implements DocumentTypeDAO {

    @PersistenceContext(unitName="kew")
    private EntityManager entityManager;

}

Simple example of Named Query in Rice

// Fetch Application Document ID by Document ID
// Define constants for named query in DAO - In this case DocumentRouteHeaderDAOJpa
// Name your queries such that they start with the Entity name
// like @NamedQuery(name="ParameterBo.findAll", query="SELECT p FROM ParameterBo")
public static final String GET_APP_DOC_STATUS_NAME = "DocumentRouteHeaderValue.GetAppDocStatus";
public static final String GET_APP_DOC_STATUS_QUERY = "SELECT d.appDocStatus from "
            + "DocumentRouteHeaderValue as d where d.documentId = :documentId";

// Definition of NamedQuery on Queried Entity(DocumentRouteHeaderValue)
@NamedQuery(name=DocumentRouteHeaderDAOJpa.GET_APP_DOC_STATUS_NAME, query =
    DocumentRouteHeaderDAOJpa.GET_APP_DOC_STATUS_QUERY)

// Code to call NamedQuery
TypedQuery<String> query = getEntityManager().createNamedQuery("DocumentRouteHeaderValue.GetAppDocId",String.class);
query.setParameter("documentId",documentId);

String applicationDocId = null;
if (query.getResultList() != null && !query.getResultList().isEmpty()){
    applicationDocId = query.getResultList().get(0);
}

return applicationDocId;

More Complex example of NamedQuery

// Fetch all distinct document IDs by document type and application document ID
public static final String GET_DOCUMENT_ID_BY_DOC_TYPE_APP_ID_NAME =
            "DocumentRouteHeaderValue.GetDocumentIdByDocTypeAndAppId";
public static final String GET_DOCUMENT_ID_BY_DOC_TYPE_APP_ID_QUERY = "SELECT "
            + "DISTINCT(DH.documentId) FROM DocumentRouteHeaderValue DH, DocumentType DT "
            + "WHERE DH.appDocId = :appDocId AND DH.documentTypeId = DT.documentTypeId  AND DT.name = :name";

@NamedQuery(name=DocumentRouteHeaderDAOJpa.GET_DOCUMENT_ID_BY_DOC_TYPE_APP_ID_NAME, query =
    DocumentRouteHeaderDAOJpa.GET_DOCUMENT_ID_BY_DOC_TYPE_APP_ID_QUERY)

TypedQuery<String> query = getEntityManager().createNamedQuery(GET_DOCUMENT_ID_BY_DOC_TYPE_APP_ID_NAME, String.class);
query.setParameter("appDocId",appId);
query.setParameter("name",documentTypeName);

return query.getResultList();

Caused by: java.lang.ClassCastException:
                        org.eclipse.persistence.jpa.jpql.parser.NullExpression
                        cannot be cast to org.eclipse.persistence.jpa.jpql.parser.IdentificationVariable
                     

Using Rice Criteria API

// Example of Dynamic query, this query needs to add date checks dates if effectiveDate parameter is not null
// This should be in a DAO class - RuleDAOJpa in this case

public List<RuleBaseValues> fetchAllCurrentRulesForTemplateDocCombination(String ruleTemplateId, List documentTypes,
        Timestamp effectiveDate) {
    QueryByCriteria.Builder builder = QueryByCriteria.Builder.create();
    List<Predicate> predicates = new ArrayList<Predicate>();
    predicates.add(equal("ruleTemplateId",ruleTemplateId));
    predicates.add(in("docTypeName", documentTypes));
    predicates.add(equal("active", Boolean.TRUE));
    predicates.add(equal("delegateRule",Boolean.FALSE));
    predicates.add(equal("templateRuleInd",Boolean.FALSE));

    if (effectiveDate != null) {
        predicates.add(lessThanOrEqual("activationDate",effectiveDate));
        predicates.add(greaterThanOrEqual("deactivationDate", effectiveDate));
    }

    List<Predicate> datePredicateList = generateFromToDatePredicate(new Date());
    Predicate[] datePreds = generateFromToDatePredicate(new Date()).toArray(new Predicate[datePredicateList.size()]);
    predicates.add(and(datePreds));
    Predicate[] preds = predicates.toArray(new Predicate[predicates.size()]);
    builder.setPredicates(preds);
    QueryResults<RuleBaseValues> results = getDataObjectService().findMatching(RuleBaseValues.class, builder.build());

    return results.getResults();
}

public List<Predicate> generateFromToDatePredicate(Date date){
    List<Predicate> datePredicates = new ArrayList<Predicate>();

    Predicate orFromDateValue = or(lessThanOrEqual("fromDateValue",new Timestamp(date.getTime())), isNull("fromDateValue"));
    Predicate orToDateValue = or(greaterThanOrEqual("toDateValue",new Timestamp(date.getTime())), isNull("toDateValue"));

    datePredicates.add(orFromDateValue);
    datePredicates.add(orToDateValue);

    return datePredicates;
}

Using JPA Criteria API

// Using JPA Criteria Builder

public List<RuleBaseValues> search(String docTypeName, String ruleId, String ruleTemplateId, String ruleDescription, String groupId,
        String principalId, Boolean delegateRule, Boolean activeInd, Map extensionValues, String workflowIdDirective) {
    CriteriaBuilder cb = getEntityManager().getCriteriaBuilder();
    CriteriaQuery<RuleBaseValues> cq = cb.createQuery(RuleBaseValues.class);
    Root<RuleBaseValues> root = cq.from(RuleBaseValues.class);
    List<javax.persistence.criteria.Predicate> predicates = getSearchCriteria(root, cq, docTypeName, ruleTemplateId,
        ruleDescription, delegateRule, activeInd, extensionValues);

    if (ruleId != null) {
        predicates.add(cb.equal(root.get("id"),ruleId));
    }

    if (groupId != null) {
        predicates.add(cb.in(root.get("id")).value(getRuleResponsibilitySubQuery(groupId, cq)));
    }

    Collection<String> kimGroupIds = new HashSet<String>();
    Boolean searchUser = Boolean.FALSE;
    Boolean searchUserInWorkgroups = Boolean.FALSE;
        
    if ("group".equals(workflowIdDirective)) {
        searchUserInWorkgroups = Boolean.TRUE;
    } else if (StringUtils.isBlank(workflowIdDirective)) {
        searchUser = Boolean.TRUE;
        searchUserInWorkgroups = Boolean.TRUE;
    } else {
        searchUser = Boolean.TRUE;
    }
        
    if (!org.apache.commons.lang.StringUtils.isEmpty(principalId) && searchUserInWorkgroups) {
        Principal principal = KimApiServiceLocator.getIdentityService().getPrincipal(principalId);

        if (principal == null) {
            throw new RiceRuntimeException("Failed to locate user for the given principal id: " + principalId);
        }

        kimGroupIds = KimApiServiceLocator.getGroupService().getGroupIdsByPrincipalId(principalId);
    }

    Subquery<RuleResponsibilityBo> subquery
        = addResponsibilityCriteria(cq,kimGroupIds, principalId, searchUser, searchUserInWorkgroups);

    if (subquery != null){
        predicates.add(cb.in(root.get("id")).value(subquery));
    }

    cq.distinct(true);
    javax.persistence.criteria.Predicate[] preds = predicates.toArray(new javax.persistence.criteria.Predicate[predicates.size()]);
    cq.where(preds);
    TypedQuery<RuleBaseValues> q = getEntityManager().createQuery(cq);

    return q.getResultList();
}

private Subquery<RuleResponsibilityBo> getRuleResponsibilitySubQuery(String ruleRespName, CriteriaQuery<RuleBaseValues> query) {
    CriteriaBuilder cb = getEntityManager().getCriteriaBuilder();
    Subquery<RuleResponsibilityBo> subquery = query.subquery(RuleResponsibilityBo.class);
    Root fromResp = subquery.from(RuleResponsibilityBo.class);
    subquery.where(cb.equal(fromResp.get("ruleResponsibilityName"),ruleRespName));
    subquery.select(fromResp.get("ruleBaseValuesId"));

    return subquery;
}

Miscellaneous JPA information

//Relationship foreign key updating can go wrong if missing
//"nullable" on JoinColumn.  It can insert null into the column instead of
//the actual value of the foreign entity key

public class RouteNodeInstance implements Serializable {
    @ManyToOne
    @JoinColumn(name="RTE_NODE_ID", nullable = false)
    private RouteNode routeNode;
}
                      

For automatically generating values for identifier fields, JPA provides @GeneratedValue to place on any field or method. While this works for many databases like Oracle that have their own concepts of sequence objects, some databases like MySQL do not have sequence objects and need additional support. Kuali Rice uses the standard of "sequence tables" in MySQL that use the MyISAM auto increment feature to simulate sequences. This has prompted the creation of @PortableSequenceGenerator to work alongside @GeneratedValue to provide automatic application support for both Oracle and MySQL.

To use this feature, place it with any @GeneratedValue annotation.

@PortableSequenceGenerator(name = "TABLE_S")
@GeneratedValue(generator = "TABLE_S")
@Id
@Column(name = "TABLE_ID")
private String id;

In this example, TABLE_S is the name of the portable sequence generator, and by default, it is taken as the sequence name in the database. In order to specify a separate generator name from the database sequence name, use the name attribute for the generator name instead and add the sequenceName attribute for the database sequence name. Also, the generator can be configured to start at a specified value by using initialValue. By default, it starts at 1000.

@PortableSequenceGenerator(name = "TABLE_S_GEN", sequenceName = "TABLE_S", initialValue = 1)
@GeneratedValue(generator = "TABLE_S")
@Id
@Column(name = "TABLE_ID")
private String id;

Some situations call for being able to access the sequences in Spring beans. The MaxValueIncrementerFactoryBean allows for this. These sequences can then be used in situations where automatically placing them on data objects is not possible or desirable.

<bean id="tableIncrementer" class="org.kuali.rice.krad.data.platform.MaxValueIncrementerFactoryBean">
  <property name="dataSource" ref="dataSource" />
  <property name="incrementerName" value="TABLE_S" />
</bean>

This returns a DataFieldMaxValueIncrementer which can be used to access the next values of the sequence, either through nextIntValue, nextLongValue, or nextStringValue.

Entity Attribute Converters - Converts the current state of the entity attribute value into a data store representation and back again.

Auto Apply

The autoApply attribute of a converter may be set to 'true' or 'false'. When set to true the JPA provider will use the converter to convert all entity attributes of the given type. If autoApply is set to false then a javax.persistence.Convert annotation will need to be added to all attributes that shall be converted, along with the Converter class.

Converters are typically specified on a mapping using the @Convert annotation

@Entity
public class Channel {
...
@Convert(converter = BooleanTFConverter.class)
@Column(name = "SUBSCRB_IND", nullable = false)
private boolean subscribable;
...
}
            

The current attribute converters available in Kuali Rice:

The annotation metadata provider will process all Java annotations on a data object class to include them in the system metadata repository. These are applied directly after the JPA metadata is processed and will merge the JPA-based metadata into itself unless directed otherwise.

A good example of using this provider is applying data dictionary attributes to a field in a data object.

@Label("Travel Account Type Code")
@Description("Type code grouping for account")
@KeyValuesFinderClass(AccountTypeKeyValues.class)
private String accountTypeCode;

For accountTypeCode, the annotations define the label that will appear on the interface for any input fields, the description that will go along with the field if requested, and a key values finder class that will search for all possible values that can go into this field.

The annotations can also define relationships between two objects that normally would not have a database link between them.

private String foId;

@Relationship(foreignKeyFields="foId")
private Person fiscalOfficer;

In this case, the relationships directs the metadata to load the Person object using the foreign key field foId.

The spring metadata provider will process all spring beans that hold object metadata and include them in the system metadata repository. These are applied directly after the annotation metadata is processed and will merge both the JPA-based metadata and the annotation metadata into itself unless directed otherwise. This is especially useful when overriding metadata on Rice objects directly on the data level so it will be carried to all instances of this object on the interface.

The spring beans can be used to create a metadata structure for an object rooted at DataObjectMetadata. For example, to override the above accountTypeCode with a new label, add the following:

<bean parent="DataObjectMetadata" p:typeClassName="org.kuali.rice.krad.demo.travel.dataobject.TravelAccount">
    <property name="attributes">
        <list>
            <bean parent="DataObjectAttribute"
                  p:name="accountTypeCode"
                  p:label="University Travel Account Type Code" />
        </list>
    </property>
</bean>

Instead of having the "Travel Account Type Code" this data object would now have the "University Travel Account Type Code."

Relationship fetching allows for a related object to be fetched based on available foreign key values on the object. This provides a facility to load the full state of a related object when only foreign key values have been populated on the parent object. This is a common enough operation that it has been implemented as a general-purpose utility with the fetchRelationship methods on the DataObjectWrapper. When fetching a relationship, the name of the relationship to fetch is supplied (relative to the parent object) along with whether or not a redundant foreign key field should be used as the source of the foreign key value. It is also possible to specify whether or not any dangling relationships should be nullified if no data object is found for the given foreign key values.

Relationship fetching can use either the redundant foreign key field (if one exists) or the current value of the foreign key field on the related object in the case of a simple relationship. When executed, it will use the foreign key value to query the DataObjectService for that related object and then replace the original related object on the parent with the resulting value.

To best deomonstrate the logic, let's look at an example:

EntityOne one = new EntityOne();

// create a partially initialized instance of EntityTwo to hold the foreign key value of "100"
EntityTwo two = new EntityTwo();
two.setId(100);
one.setTwo(two);

DataObjectWrapper<EntityOne> oneWrapped = dataObjectService.wrap(one);

// fetch relationship, useForeignKeyAttribute = false, nullifyDanglingRelationsip = true
oneWrapped.fetchRelationship("two", false, true); 

// now, the "two" field on EntityOne holds our fetched instance of EntityTwo with id of "100"
EntityTwo fetchedTwo = one.getTwo();

Note that in the above example if there was no instance of EntityTwo with an id of "100" in the data store, then one.getTwo() would return null after the call to fetch the relationship. This is because nullifyDanglingRelationship was set to "true" when the method was executed.

More detailed documentation on the fetchRelationship method can be found in the JavaDocs for the DataObjectWrapper.

Reference Linking is a feature which allows for ensuring that relationships and foreign key state are populated and kept in sync as changes are made to a data object. This may include fetching relationships as keys are changed that would necessitate updating the object graph, as well as keeping foreign keys in sync in the scenario where redundant foreign key fields are being used.

Reference linking takes as input a data object and a set of property paths (relative to the given object) which have been modified. The ReferenceLinker will then examine those modified paths and make a decision on how best to synchronize the keys and populate relationships. It requires a set of changes to the object to be specified so as to eliminate ambiguity on what the linking process should do, as well as allow the process to be optimized so that it does not have to analyze and link the entire related object graph when only a portion of the data has been modified.

The set of modified property paths which are supplied to the reference linker can be simple or nested property paths. The reference linking feature itself was designed with the goal of supporting population of missing object state when modifications are occurring to a data object. The most typical case for this in KRAD is during the data binding process that Spring MVC performs. However, the reference linking feature itself does not assume anything about how the changes are made to the data object, it just needs to know what has been modified. This allows the API for reference linking to remain simple.

Reference linking can be executed using the linkChanges method on the DataObjectWrapper. Let's demonstrate with an example:

EntityOne one = /* a new or existing instance of Entity One */
DataObjectWrapper<EntityOne> oneWrapped = dataObjectService.wrap(one);

// set the value of the id for the related EntityTwo to "100"
oneWrapped.setPropertyValue("two.id", 100);

// execute the reference linking, this will notice that we've changed our foreign key value
// for our reference to EntityTwo and will fetch that relationship for us
Set<String> changes = Sets.newHashSet("two.id");
oneWrapped.linkChanges(changes);

// now, the "two" field on EntityOne holds our fetched instance of EntityTwo with id of "100"
EntityTwo fetchedTwo = one.getTwo();

Notice the reference in the comments above to fetching a relationship. In fact, the reference linking process itself leverages the relationship fetching functionality that we talked about in the previous section. In reality, it takes the set of changes and determines which relationships to fetch and which foreign key values (if multiple exist for the relationship) should be used to perform that fetching. This insulates KRAD applications from having to perform a lot of this type of logic manually in custom controllers and takes full advantage of the metadata that the data framework has available to it when reconciling data object state.

Foreign key linking only applies to situations where there are redundant foreign key fields on a data object or any other data objects that it is related to. This linking operation can be executed against a data object and it will ensure that any redundant foreign key values are populated based on the foreign key values stored in the related data objects. It then recurses through the object graph and performs the same operation on all related data objects.

This operation is often paired with persistence of the data object itself. This is because primary key values which are used in relationships are often generated at the time that an object is saved. This is typically done using a database sequence or similar technique. In these cases, the value for a foreign key field may not be known until after persistence has occurred and the key values have been generated. As a result, there is a shortcut to execute foreign key linking as part of the save operation on DataObjectService by using a persistence option.

The following example demonstrates this usage:

EntityOneWithFK one = new EntityOneWithFK();
EntityTwo two = new EntityTwo();
two.setValue("...");
one.setTwo(two);

// in this case, both the primary key for "one" and "two" are generated when saved, in order to
// ensure that "twoId" gets populated we need to link the foreign keys as part of the save

one = dataObjectService.save(one, PersistenceOption.LINK_KEYS);

// now all of our ids should be generated and the value for "twoId" should match "two.id"
assert one.getId() != null;
assert one.getTwo().getId() != null;
assert one.getTwoId() != null;
assert one.getTwoId() == one.getTwo().getId();

If we had not used the LINK_KEYS persistence option, then the value for one.getTwoId() after the save would have still been null since JPA will not populate this value for us after a persist/merge because the mapping has updatable and insertable set to "false".

In addition to automatic execution of foreign key linking using the LINK_KEYS persistence option, it is also possible to execute this linking manually using the linkForeignKeys method on the DataObjectWrapper.

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>btn btn-primary</value>
 12         </list>
 13     </property>
 14 
 15 <bean id="Uif-SecondaryActionButton" ...
 16     <property name="styleClasses">
 17         <list merge="true">
 18             <value>btn btn-default</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:

showLabel – This indicates whether the label should be shown. Note that the label is still rendered but off screen for accessibility purposes. Set rendering to false to not render the label.

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

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.

requiredIndicator – This is a string that will be rendered with the label to indicate that the element associated with the label (generally a control) is required. By default, the string 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.requiredIndicator="required"/>

However, we typically want to display the required indicator 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 render the label's required indicator. Likewise, if the component's required property is false, the required indicator will not render.

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

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.1, “Data Field Label”.

Figure 6.1. 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.2, “Input Field” we see the result of the above input field configuration.

Figure 6.2. 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 getParam 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.3. 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".

UifCalendarEditor – Used for converting between a java.util.Calendar and a string. The Rice DateTimeService is used to perform the string formatting and Calendar creation.

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.4. 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.5. 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.6. 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.7. 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.8. 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.9. 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.10. 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.11. 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.12. 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.13. 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>

Grouped Select

A grouped select is one that has 'grouping' elements within the drop down of options. The grouping element cannot be selected. This is setup the same way a normal Select control would be set up, except instead of using UifKeyValue object, a UifOptionGroupLabel object is used for the group headers. Here is a sample configuration:

            <bean parent="Uif-DropdownControl">
              <property name="options">
                <list>
                  <bean parent="Uif-OptionGroupLabel" p:label="American"/>
                  <bean parent="Uif-KeyLabelPair" p:key="a1" p:value="Ford"/>
                  <bean parent="Uif-KeyLabelPair" p:key="a2" p:value="Chevy"/>
                  <bean parent="Uif-KeyLabelPair" p:key="a3" p:value="Buick"/>
                  <bean parent="Uif-OptionGroupLabel" p:label="Japan"/>
                  <bean parent="Uif-KeyLabelPair" p:key="j1" p:value="Toyota"/>
                  <bean parent="Uif-KeyLabelPair" p:key="j2" p:value="Honda"/>
                </list>
              </property>
            </bean>
            

This would be rendered like this:

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.14. 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.15. 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.16. 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 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 ORM 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