define a fragment using dlm.xml

Warning

Starting with uPortal 4.0.4: The default method of defining DLM fragment definitions has switched from the dlm.xml file to database persistence. If you currently have fragments in dlm.xml, this update will require you to make a minor configuration change. Please see the following for further information about the update: define fragments

Step 1: The dlm.xml file

Open uportal-war/src/main/resources/properties/dlm.xml and let's take a look at the existing fragments that are defined. Below is a snippet of the fragments that come with uPortal already in place.

<dlm:fragment name='Guests' ownerID='guest-lo' precedence='80'>
    <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GuestUserEvaluatorFactory'/>
  </dlm:fragment>

  <dlm:fragment name='Welcome' ownerID='welcome-lo' precedence='80'>
    <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='60'>
    <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.AllUsersEvaluatorFactory'/>
  </dlm:fragment>

  <dlm:fragment name='Faculty' ownerID='faculty-lo' precedence='50'>
    <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GroupMembershipEvaluatorFactory'>
      <paren mode="OR">
        <attribute mode='memberOf' name='Faculty'/>
      </paren>
    </dlm:audience>
  </dlm:fragment>

  <dlm:fragment name='Staff' ownerID='staff-lo' precedence='50'>
    <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GroupMembershipEvaluatorFactory'>
      <paren mode="OR">
        <attribute mode='memberOf' name='Staff'/>
      </paren>
    </dlm:audience>
  </dlm:fragment>

  <dlm:fragment name='Student' ownerID='student-lo' precedence='50'>
    <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GroupMembershipEvaluatorFactory'>
      <paren mode="OR">
        <attribute mode='memberOf' name='Students'/>
      </paren>
    </dlm:audience>
  </dlm:fragment>

  <dlm:fragment name='Developer' ownerID='developer-lo' precedence='40'>
    <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GroupMembershipEvaluatorFactory'>
      <paren mode="OR">
        <attribute mode='memberOf' name='Portal Developers'/>
      </paren>
    </dlm:audience>
  </dlm:fragment>

  <dlm:fragment name='Admin' ownerID='admin-lo' precedence='40'>
    <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GroupMembershipEvaluatorFactory'>
      <paren mode="OR">
        <attribute mode='memberOf' name='Portal Administrators'/>
        <attribute mode='memberOf' name='Portal Developers'/>
      </paren>
    </dlm:audience>
  </dlm:fragment>

Let's now dissect the "Student" fragment below to get an idea of how this works. The name of the fragment is Student and the fragment is owned by the user account student-lo. What we want to do is push this fragment to our Students group and to do this we define our audience using the GroupMembershipEvaluatorFactory . GroupMembershipEvaluatorFactory evaluates group memberships and with the <paren> and <attribute> directives we specify the group we wish to target. So we will interpret the syntax below as find everyone who is a memberOf the Students group and push this fragment to them.
```
<dlm:fragment name='Student' ownerID='student-lo' precedence='50'>
    <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GroupMembershipEvaluatorFactory'>
      <paren mode="OR">
        <attribute mode='memberOf' name='Students'/>
      </paren>
    </dlm:audience>
  </dlm:fragment>
```

What if we want to push the fragment to more than one group? What if we wanted to push the fragment to Students OR Faculty? We can do this by using the <paren> directive's mode attributes OR, NOT, or AND.

Here are some examples of using <paren> and <attribute> together to target specific groups:

<!-- Push this fragment to anyone who is a member of the Students OR Faculty group -->
<dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GroupMembershipEvaluatorFactory'>
    <paren mode="OR">
      <attribute mode='memberOf' name='Students'/>
      <attribute mode='memberOf' name='Faculty'/>
    </paren>
  </dlm:audience>

<!-- Push this fragment to members of the Students group who are NOT also members of the Faculty group -->
<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>

So as you can see from the above examples there is some flexibility to targeting specific groups of interest.

For complete documentation of how to target your audience take a look at the "define audiences" manual page for details.

Step 2: Define a new fragment

Let's imagine that we want to setup a fragment named "Library". This library fragment will contain all information about library services that we wish to send out to Faculty groups but NOT Staff groups. Here's what we would do:
Define our new fragment as follows in the dlm.xml file

<dlm:fragment name='Library' ownerID='library-lo' precedence='40'>
    <dlm:audience evaluatorFactory='org.jasig.portal.layout.dlm.providers.GroupMembershipEvaluatorFactory'>
      <paren mode="OR">
         <attribute mode='memberOf' name='Faculty'/>                  
        <paren mode="NOT">
          <attribute mode='memberOf' name='Staff'/>
        </paren>
      </paren>
    </dlm:audience>
  </dlm:fragment>

Setting the precedence attribute
- Each fragment must also declare an integer precedence value. This value is used during merging of fragments to position elements contributed from different fragments. It is also used to determine which precedence elements can override a lower precedence.
- A higher precedence means a fragment appears earlier. In terms of a tabular UI layout, that would be tabs with higher precedence appearing to the left. TBD validation of this part: Tabs with equal precedence are shown in unspecified order (the order processed from the DB query).

Step 3: Deploy your new fragment

Go back to the source uPortal directory and issue the following command to deploy your new fragment
```
ant clean deploy-war
```

Step 4: Restart uPortal

Now that we have created our new fragment we need to restart tomcat to activate the new fragment.

$TOMCAT_HOME/bin/shutdown.sh
$TOMCAT_HOME/bin/startup.sh

Step 5: Setup our new fragment user account

After we restarted uPortal we now need to create our new user account who owns the fragment we just defined above (library-lo).

Follow the steps to Add Local User Accounts

Step 6: Setup the layout for the new fragment

Now, that we have setup our new fragment we can now start customizing the layout. For the second half of this tutorial see detailed instructions at this manual page Setup a fragment layout using the Admin UI.

Additional References

Having problems with these instructions?

Please send us feedback at uportal-user@lists.ja-sig.org