define a fragment

Step 1. First take a look at the dlm.xml file

Open the dlm.xml file which located at ../uportal-impl/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.

The 'ownerID' Attribute

Each fragment must declare an ownerID attribute. This is the log-in to use when logging in to edit the layout for this fragment. It is important that this account not exist prior to adding the fragment. When dlm.xml is modfied, the portal must be restarted for the configuration to be loaded. Upon loading, if that account already exists and has a layout it will immediately be pushed to users. If the account does not exist, then upon restarting the portal, DLM will create that account and populate its layout with a copy of the layout of the account specified with dlm.xml's defaultLayoutOwner property. That layout has no visible content. In this way this fragment does not push any content to users until the owner has time to set up the layout that should be pushed. Note: the md5passwd command line utility must still be used after restarting to set the password for the new account to allow a fragment maintainer to log in to that account and set up the layout:

ant md5passwd -Dusername=guest-lo

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 that precedence elements can override a lower precedence, movement-restricted element forcing it to a less valueable real-estate location. For example, the default dlm.xml file defines three fragments:

Guests	precedence = 10
Entertainment	precedence = 100
News	precedence = 80

When a regular user, in this case the student account, logs in to the portal and selects the Preferences link the following ordering of tabs will appear. Note that the entertainment tab can move to the right of the news tab but that the student tab is not allowed to move to the left of the news tab.

This behavior is due to the owner of the news tab's fragment marking the news tab as not moveable. However, restricting movement is relative. All elements from a fragment inherit the precedence of that fragment. A tab from a fragment with higher precedence like the entertainment tab, can override a movement restriction of a lower precedence tab.

Now the student tab is owned by the student user. User layout elements have a precedence of zero and hence any fragment element can always force user owned elements to lower-valued real-estate locations. However, if a fragment element has not been movement restricted then lower precedence tabs can move them as is shown below with the student tab moved to the left of the entertainment tab. But note that due to the locked news tab and the relative precedences that the student tab is never allowed to move beyond the news tab.

As can be seen, movement restrictions restrict movement of lower precedence elements to higher valued screen real-estate locations. DLM allows users to alter fragment elements pushed into their layouts if such changes are allowed by the fragment. This means that users can add columns to fragment tabs and channels to fragment columns. Accordingly, real-estate value differs based on element type. For tabs, the most valued real-estate is furthest to the left since tabs to the right can ultimately be forced off of the right side of the page and outside the view being shown by the browser. Columns have a similar value direction of left to right from highest to lowest value for a similar reason. Channels have a direction from the top of a column to the bottom for highest to lowest value respectively since channels further down in a column can be forced off of the bottom of the browser's visible viewing area.

When multiple fragments have equal preference the order of appearance is determined by the order in DLM.xml.

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 only Faculty OR Student 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='Students'/>
        <attribute mode='memberOf' name='Faculty'/>                  
        <paren mode="NOT">
          <attribute mode='memberOf' name='Staff'/>
        </paren>
      </paren>
    </dlm:audience>
  </dlm:fragment>

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-ear
```

Step 4: Restart uPortal

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

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

From your uPortal source directory create the new account by issuing the following command:
```
ant md5passwd -Dusername=library-lo
```

You will be prompted to enter a password for the new account

Buildfile: build.xml

prodPrompt:

md5passwd:

install-parent-pom:
[artifact:install] [INFO] Installing /portal/uPortal-3.2.2/pom.xml to /root/.m2/repository/org/jasig/portal/uportal-parent/3.2.2/uportal-parent-3.2.2.pom
    [touch] Creating /tmp/jasig/uportal-parent.pom-1617936594-marker
     [echo] Artifact '/portal/uPortal-3.2.2/uportal-impl/target/uportal-impl-3.2.2.jar' is up-to-date
[artifact:install] [INFO] Installing /portal/uPortal-3.2.2/uportal-impl/target/uportal-impl-3.2.2.jar to /root/.m2/repository/org/jasig/...
     [java] Working directory ignored when same JVM is used.
     [java] log4j:WARN No appenders could be found for logger (org.jasig.portal.spring.locator.PortalDbLocator).
     [java] log4j:WARN Please initialize the log4j system properly.
     [java] Enter Password for library-lo:

Once you enter a password you should receive the success message

...
[java] Password Updated...

BUILD SUCCESSFUL
Total time: 34 seconds

Now login to uPortal as an administrator and you will automatically receive the library-lo account in the Password Management portlet (see image below)

If you highlight the library-lo account and click on "Fetch" you can enter further details for the account such as first and last name, etc...

Step 6: Setup the layout for our fragment

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

Additional References

Having problems with these instructions?

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