Defining DLM Fragments

Distributed Layout Manager (DLM) allows portal administrators to define Layout Fragments. Each fragment containes one or more tabs of portal content (portlets and channels) and defines an audience.

Defining Fragments in dlm.xml

DLM functionality and fragments are most commonly defined in a file called, dlm.xml, which is located in the properties directory. The default dlm.xml file for 2.5.0 is shown below. Although no DTD or schema is currently used two top level elements are supported by the DLM code: dlm:property and dlm:fragment. As of uPortal 3.1.0, it is also possible to define DLM fragments in the portal database (see below).

dlm.xml

<managedLayoutFragments xmlns:dlm="http://org.jasig.portal.layout.dlm.config">

  <dlm:property name='defaultLayoutOwner' value='fragmentTemplate'/>
  <!--  <dlm:property name='layoutDecorator' value='someClass'/> -->
  
  <!-- Controls clearing of dlm fragment cache.  This allows changes  made to layout
  owners to be reflected once the cache has been updated.  Specified in minutes. -->
  
  <dlm:property name='org.jasig.portal.layout.dlm.RDBMDistributedLayoutStore.fragment_cache_refresh' value="5"/>

  <dlm:fragment name='Entertainment' ownerID='ent-lo' precedence='100'>
	 <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.PersonEvaluatorFactory'>
	  <paren mode="NOT">
       <attribute name="username" mode='equals' value='guest'/>
 	  </paren>
	 </dlm:audience>
  </dlm:fragment>

  <dlm:fragment name='News' ownerID='news-lo' precedence='80'>
   <!--  <dlm:role>Students</dlm:role> -->
   <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GroupMembershipEvaluatorFactory'>
     <paren mode="AND">     
       <attribute mode='memberOf' name='Students'/>
       <paren mode="NOT">
	       <attribute mode='memberOf' name='Faculty'/>
       </paren>
     </paren>
   </dlm:audience>
 </dlm:fragment>
  
</managedLayoutFragments>

dlm:property

The following properties are currently supported by the DLM infrastructure as found in 2.5.0.

Property	Description
defaultLayoutOwner	The user account whose layout will be used to perform a cookie cutter copy for newly created fragment owner accounts when they first log in. This concept is similar to the usertemplate account for new uPortal users.
layoutDecorator	The fully qualified name of a class that is delegated to by the DLM infrastructure immediately after all layout merging has taken place at log-in time. This class can then add or modify layout information if needed. This functionality will most likely be going away at some point in the future. A better solution is to use a TransientLayoutManager.
org.jasig.portal.layout.dlm .RDBMDistributedLayoutStore .fragment_cache_refresh	This value indicates how often changes are reloaded that are made to the layouts of fragment owner accounts. This is to accomodate a multi-server environment where changes to layouts could be made on a different server and not get pushed into the local cache at storage time. The value specified should be an integer number representing the number of minutes between reload attempts.

dlm:fragment

The <dlm:fragment> element defines a single fragment to be pushed into the layouts of a set of users. This element has four possible attributes as outlined in the following table. It also can contain from one to many nested audience elements. See dlm:audience below.

Attribute	Description
name	A required unique name by which this fragment is known
ownerID	The required login id of the user who owns the distributed layout and hence can edit the layout. There was no UI created three years ago when this ALM approach was constructed. For speed the layout of a regular account was used to specify the fragment. So each fragment must have a corresonding account created solely for defining what that fragment entails. This also means that the smallest fragment that can be created is a tab. With a fragment specific creation UI such a restriction will be removed.
precedence	A required positive, decimal number or zero. Negative numbers are not allowed. This number is used to indicate the ordering of layouts for a user during their layout construction sequence. When a user logs in the system asks each distributed layout if it is applicable to that user. (See Audiences Defined below.) Those that answer yes are placed in a layout construction sequence in order of precedence, the higher the number the higher the precedence and the earlier the layout will be merged into the user's viewed or constructed layout. Layouts merged in prior to other layouts have higher precedence and hence can restrict actions taken by layouts merged in later enforcing such things as position for their elements. A user's personal layout fragment, that portion representing changes made to incorporated layouts, has a precedence of zero. If two or more layouts have the same value then their precedence is determined by their order in this file. Those at the top have higer precedence than those appearing later.
defaultLayoutOwner	This is an optional attribute. If included then it identifies the default user whose layout is copied for this fragments layout when the fragment owner first logs in. If not included it defaults to the value of the only defined property element of the same name declared in this file. If neither is defined then the default is the user indicated by the org.jasig.portal.services.Authentication.defaultTemplateUserName property in portal.properties.

dlm:audience

The <dlm:audience> element is responsible for identifying to whom each fragment will be pushed. This is done using a required attribute: evaluatorFactory. The contents of the <dlm:audience> element are completely defined by the class declared in the evaluatorFactory attribute. There are currently three evaluator factories included for use in targeting the fragment to specific audiences. The fully qualified class name is required in the attribute. Each of the supported factories resides in the org.jasig.portal.layout.dlm.providers package.

Class	Description and Use
PersonEvaluatorFactory	This factory produces an evaluator that can target the fragment to an audience using properties found in the attributes of the IPerson object that represents the current user in the portal. See PersonEvaluatorFactory Defined Audiences.
AllUsersEvaluatorFactory	This factory produces an evaluator that targets all users of the portal to receive the fragment including guest users. This factory uses no configuration so the dlm:audience element's content is ignored and can be empty.
GroupMembershipEvaluatorFactory	This factory produces an evaluator that can target the fragment to an audience depending on their group membership. See GroupMembershipEvaluatorFactory Defined Audiences.
GuestUserEvaluatorFactory	This factory produces an evaluator that targets guest users of the portal. If specified then the fragment will be merged in with any layout owned by the guest user. If the guest user's layout is empty then this fragment will be the only content had by the guest user. This factory uses no configuration so the dlm:audience element's content is ignored and can be empty.

dlm:role

The roles element is not supported in 2.5.0. It was meant to determine to what group a fragment owner will belong. Multiple role elements for a fragment would mean that the fragment owner is a member of each of these groups. The fragment owner is defined by the ownerID attribute of the containing fragment element and represents the user account whose layout is used as the layout for the fragment. When modifying the layout, channels can be added. Channels are themselves granted only to certain groups of users. As such there is the potential for a fragment owner to have one set of group memberships and the users of that fragment to have other disjoint group memberships. In such cases channels added to the surface of that layout and them merged into the user's layouts will show up as broken and indicate that the user does not have access to that channel.

The role element was a step toward resolving such problems. Upon loading dlm.xml the infrastructure was to look to see what groups the fragment owner is a member and removes them from all groups except the ones indicated by the nested role elements. Additionally, if they were not a member of these groups then they would be made a member of each.

New features slated to be added would have rendered this declaration unnecessary. The goal is for the fragment editing UI to indicate which channels added to the fragment may not be available to all users of the fragment as defined by the set of users to whom the fragment is published for pushed fragments or the users who can subscribe to the fragment for pulled fragments.

Defining Fragments as Database Entities

As an alternative to defining DLM fragments in dlm.xml, portal administrators may elect to enable the RDBMConfigurationLoader, which loads fragment definitions from the database via Hibernate and JPA. The major advantage of this approach is that it allows fragments to be added, removed, or change their audiences without a portal restart.

RDBMConfigurationLoader can be turned on by modifying persistenceContext.xml and layoutContext.xml

Warning

Once you make this change, DLM will no longer read fragments from dlm.xml; you must define all your fragments in the database.

persistenceContext.xml

Uncomment fragmentDefinitionDao bean:

<bean id="fragmentDefinitionDao" class="org.jasig.portal.layout.dlm.FragmentDefinitionDao">
</bean>

layoutContext.xml

Modify dlmConfigurationLoader bean:

<bean id="dlmConfigurationLoader" class="org.jasig.portal.layout.dlm.RDBMConfigurationLoader">
    <property name="configurationFile" value="classpath:/properties/dlm.xml" />
    <property name="fragmentDao" ref="fragmentDefinitionDao" />
</bean>

Importing Fragment Definitions

Now that you've enabled the RDBMConfigurationLoader, you'll need a way to get fragment definitions into the database. Import/Export provides support for these entities.

Use the following command to import a directory that contains .fragment-definition files:

>ant crn-import -Ddir<path.to.frag-def.dir>

The .fragment-definition files support the same XML syntax as dlm.xml

Example fragment-definition File

<fragment-definition xmlns:dlm="http://org.jasig.portal.layout.dlm.config" script="classpath://org/jasig/portal/io/import-fragment-definition_v3-1.crn">
  <dlm:fragment name='Guests' ownerID='guest-lo' precedence='20'>
   <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GuestUserEvaluatorFactory'/>
  </dlm:fragment>
</fragment-definition>