Reference » Chains


Last modified by Andreas Hahn on 2011/06/09 10:21


The term 'chain' means a concatenation of 2 segments. The default visual representation for chains is the link icon linkgo.png  (see Tutorial). Typically you chain an originating source segment and the subsequent target segment. All chain definitions should be placed by convention in WEB-INF/chains.xml. A simple yet typical chain definition looks like this

<bean parent="sheptChainTemplate" >
 <property name="from" ref="persons" />
 <property name="to" ref="addresses" />
 <property name="relation" value="addresses" />
 <property name="info">
   <bean parent="sheptInfoItemTemplate" p:code="info.addresses" p:selector="name" />

This snippet from the SheptDemo project shows the definition for navigating from persons to a persons addresses. In this case there is a 1:N relation #addresses() defined on the Person entity object which backs the persons segment name. In this example we might even omit the relation specification because it would have been picked up by default. Look for details in the filter section.

In the view you just need to specify the chain tag with the targets segments name and an optional message code and an optional icon image.

<table:chainRow chainName="addresses" code="addresses" />

The appropriate configuration will be retrieved by looking up the chainName in all configured chains of the originating source segment in the following order:

  • check for chain configuration bean name match
  • check for a bean with a relation name match
  • check for a target segment bean name match
  • recursively checking the chain parent confurations for the conditions above

source from and destination to specification

Source and destination are specified as a property reference to the segments. Springs dependency injection will already do some basic validation during startup of the container. The from property may be omitted. In this case there is no predecessor and this is a typical specification for the first segment of a webpage. This is a snippet from WEB-INF/sheptDemo-servlet.xml from the SheptDemo

<bean name="/person.shept" parent="sheptController">
 <property name="configuration">
   <bean parent="sheptTargetTemplate">
     <property name="to" ref="persons" />
     <property name="info.code" value="persons" />

defining the relation between segments

In technical terms the relation between segments is defined by any implementation of the FilterDefinition Interface. There are 4 out of the box implementations included with the shept distribution and they will all be covered in greater detail in the filter section. By default the filter is taken from the targets segment specification. Of course you can override this default

 <property name="filterClass" value="yourFilterClass" />

There is a special shortcut to simplify the case that the filter shall be build from a relationship between entity objects that is already defined in your object-relational layer. in this case you can use the relation property instead of the filterClass property.

 <property name="relation" value="addresses" />

When you specify a relation property for your chain your source entity class will be checked in the example above for the existence of a #getAddresses() method during startup of the container and properly initialize an appropriate filter.

showing additional info

The info property can be used to show additional information. The info properties value contains an InfoItem object containing a message source object subject to localization and a message selector which is sent to the source entity to determine the details ('Mustermann').


individual commandFactory

The commandFactory is responsible for creating a new instance of the subCommand backing the target subForm. By default you don't need to care about specification of a commandFactory because it will be created automatically during the startup of the application. The proper CommandFactory will be determined and initialized from the source and target segment and their entityClass, filterClass and relation properties. For relationships an instance of AssociationCommandFactory and in all other cases a RefreshableListCommandFactory is created.  read more ...

However you can override this by specifying your own command fatory for your individual requirements.

Created by Andreas Hahn on 2011/01/03 15:39

© 2011 - Andreas Hahn