define an audience

Each <dlm:fragment> element can contain from zero to many <dlm:audience> elements. Each audience element defines a group of users who will receive that fragment. If a fragment has more than one audience element then the set of users that get that fragment is the union of all nested audience elements.

The 'evaluatorFactory' Attribute

The <dlm:audience> element has a single required attribute, evaluatorFactory. This attribute should have the fully qualified path name of a class which implements the org.jasig.portal.layout.dlm.EvaluatorFactory interface for aquiring an evaluator. The factory implementation should have a zero argument constructor and implement the only method in the interface:

public Evaluator getEvaluator( org.w3c.dom.Node audience )
throws Exception;

The DLM infrastructure will instantiate the factory using the zero argument constructor and call getEvalutator passing a node representing the <dlm:audience> element. This can then be used by the factory to return an evaluator appropriate for any configuration information included within the audience block. This means that the contents of the audience element are dictated completely by the declared EvaluatorFactory.

The object returned from getEvalutator must implement the org.jasig.portal.layout.dlm.Evaluator interface as shown below.

public boolean isApplicable( IPerson p )

DLM obtains from each audience's factory an evaluator and when a user logs in it passes through every fragment asking its audience evaluators, isApplicable, passing an IPerson implementation. If the user meets the requirements defined for that audience then the method returns a value of true and that fragment is included in the layout for that user. If the factory is unable to create and return an evaluator it should throw an Exception with a clear message indicating the problem. For example, suppose the element were as follows:

<dlm:audience evaluatorFactory="IPersonEvaluatorFactory"/>

This would result in the IPersonEvaluatorFactory, to be explained shortly, throwing an exception with the following message since it requires nested configuration content:

Invalid content. Expected one to many <paren>, <NOT>, or <attribute> in '<dlm:audience evaluatorFactory="IPersonEvaluatorFactory"/>'

If an exception is thrown when obtaining an evaluator from an evaluator factory then the message is logged as a warning and the audience element in question is discarded and not included in the evaluators for that layout fragment. Other evaluators for that layout would still be in effect.

The following evaluator factories are provided. All are found in the org.jasig.portal.layout.dlm.providers package.

The GuestUserEvaluatorFactory

This factory produces an evaluator that returns the value of IPerson.isGuest(). As such it does not use any configuration information within the audience element that declares it so the element can be empty. This factory is used in the version of dlm.xml included in the portal to push the Guest fragment to the guest user so that it shows on the log-in page.

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

The AllUsersEvaluatorFactory

This factory produces and evaluator that always returns true. This can be used to push a fragment to all portal users including the guest user. Like GuestUserEvaluatorFactory it requires no content within the audience element and hence the element can be empty.

The PersonEvaluatorFactory

This factory produces an evaluator configured as defined by required content nested within its declaring audience element. It supports a configuration syntax from which arbitrarily complex grants of the fragment can be made based on attributes found in the passed-in IPerson object. Specifically, it obtains attributes from the IPerson object using the getAttribute call. The following syntax elements are supported.<paren> ELEMENT

This element has one optional attribute "mode" which can contain one of three cast-sensitive values: OR, which is the default, AND, or NOT. OR causes the paren element to evaluate all contained tests and if any of them returns true then it too will return true. AND returns true only if all contained tests are true. NOT inverts any contained test. If more than one contained test is included then a logical OR operation is performed first and that result inverted. It should be noted that when PersonEvaluatorFactory factory is used it provides an implicit element into which all child elements of <dlm:audience> are placed. So if your configuration requires such a top level paren element you can just specify its children within the <dlm:audience> element.<attribute> ELEMENT

This element is used to specify which one of five available tests should be performed on an attribute in the passed-in IPerson object. The particular attribute to be tested is indicated in the required name attribute. The required mode attribute indicates the type of test and can be one of the following: exists, equals, contains, startsWith, and endsWith. The value to be compared is indicated by the value attribute. The value attribute is not required and indeed not used for the "exists" mode. Values for both mode and name are case sensitive.

The Entertainment fragment included in the default dlm.xml file in the portal uses this factory to push the entertainment fragment to all users that do not have a "username" attribute with a value of "guest".

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

The GroupMembershipEvaluatorFactory

This factory returns an evaluator that can evaluate group memberships. Specifically, the returned class inherits from the evaluator provided by PersonEvaluatorFactory. This means that its syntax semantics are identical except for the <attribute> element. Its semantics are overwritten to support 2 modes: memberOf and deepMemberOf. memberOf will test for membership of the named group only, whereas deepMemberOf will also test for membership in groups contained by the named group. The name attribute should contain the name of the group with matching case. The value attribute is not used. The News fragment in the default dlm.xml file in the portal uses this factory to push the news fragment to members of the Students group who are not also members of the Faculty group.

<dlm:fragment name='News' ownerID='news-lo' precedence='80'>
  <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>