Announcements Portlet Configuration

Setting up the Database
Defining Audience Members
Separating Announcements based on Topic (Whitelist/Blacklist)
Configuring the WYSIWYG Editor
Changing Announcement List Sort Order

Setting up the Database

Edit the pom.xml to define the jdbc driver to be used.

<!-- The Default JDBC Driver used by the portlet -->
<jdbc.groupId>org.hsqldb</jdbc.groupId>
<jdbc.artifactId>hsqldb</jdbc.artifactId>
<jdbc.version>2.2.9</jdbc.version>

Define your database details in src/main/resources/database.properties

## Default configuration uses an in-memory database that will reset 
## whenever you restart the portlet
driver.class=org.hsqldb.jdbc.JDBCDriver
driver.url=jdbc:hsqldb:mem:announce
driver.username=sa
driver.password=
driver.validationQuery=select 1 from INFORMATION_SCHEMA.SYSTEM_USERS
hibernate.dialect=org.hibernate.dialect.HSQLDialect

Defining Audience Members

If you have additional user groups (i.e, PAGS) that you need to send announcements to that are not listed in the default options, adding additional audience members is quite simple.

Open src/main/webapp/WEB-INF/portlet.xml

Around line #210 you will see role definitions. Here you can add your additional audience roles you want as options.

<!-- Do not change the role-name of this role, doing so may lock you out of your topics -->
<security-role-ref>
     <role-name>Portal_Administrators</role-name>
     <role-link>Portal Administrators</role-link>
</security-role-ref>

<security-role-ref>
     <role-name>Everyone</role-name>
     <role-link>Everyone</role-link>
</security-role-ref>

<security-role-ref>
    <role-name>All_Logged_In_Users</role-name>
    <role-link>Authenticated Users</role-link>
</security-role-ref>

<security-role-ref>
    <role-name>Faculty</role-name>
    <role-link>Faculty</role-link>
</security-role-ref>

<security-role-ref>
    <role-name>Staff</role-name>
    <role-link>Staff</role-link>
</security-role-ref>

<security-role-ref>
    <role-name>Students</role-name>
    <role-link>Students</role-link>
</security-role-ref>...

The changes above require a rebuild of the portlet and redeployment to the uPortal project

Rebuild Announcements portlet
```
mvn clean package
```

Redeploy the portlet under the portal space and restart tomcat.
```
ant deployPortletApp -DportletApp=/path/to/Announcements.war
```

Separating Announcements based on Topic

There may be occasions where you may wish to create multiple instances of the announcements portlet that only contain specific topics. This is very simple to do using the Whitelist and Blacklist feature in the portlet configuration.

WhiteList Feature

This feature is where you would specify the topic(s) you want to display in a given announcements portlet.

EMERGENCY announcements will always be displayed in addition to the specified topics.

Case Scenario: If I want an announcements portlet to display announcements with only the topic, "IT System Outages", that I had created, I would do the following:

Register a new Announcements portlet and fill out the forms.
When you get to the end you will be presented with a "Save" or "Save and Configuration" button. Click on the "Save and Configuration" button.
Select "Whitelist" from the drop-down menu and type the topic(s) in the textarea field you want to appear. (topics should be on a separate line.)
The resulting portlet looks like this:

BlackList Feature

This feature is where you would exclude a topic(s) but display the remaining topic options.

Case Scenario: If I want an announcements portlet to display all announcements except for my "All Campus" topic I created, I would do the following:

Register a new Announcements portlet and fill out the forms.
When you get to the end you will be presented with a "Save" or "Save and Configuration" button. Click on the "Save and Configuration" button.
Select "Blacklist" from the drop-down menu and type the topic(s) in the textarea field you want to EXCLUDE. (topics should be on a separate line).

The default before and after result (Note: "All Campus" is gone):

Configuring the WYSIWYG editor

Adding WYSIWYG Buttons

The announcement portlet's WYSIWYG editor is driven by TinyMCE and by default contains a very small number of buttons. This default list may be expanded to support a large number of HTML elements, including images, fonts, and special characters. To change the buttons displayed in the editor, open src/main/webapp/WEB-INF/jsp/addAnnouncement.jsp and scroll to the bottom of the file.

The tinyMCE.init call in the JavaScript at the bottom of the page contains properties starting with theme_advanced_button that control the displayed editor buttons. Each property corresponds to a button row, and each row is numbered appropriately. Buttons may be added to each row and ordered as desired. The available buttons are listed in the TinyMCE documentation, and the name "separator" may be used to separate buttons.

The following example configures an editor with two rows of buttons:

<script type="text/javascript">
<!--
tinyMCE.init({
        mode : "textareas",
        editor_selector : "mceEditor",
        theme : "advanced",
        theme_advanced_buttons1 : "bold,italic,underline,blockquote,separator,indent,fontselect,fontsizeselect,charmap",
        theme_advanced_buttons2 : "image,anchor,separator,bullist,numlist,undo,redo,link,unlink,indent,code",
        theme_advanced_buttons3 : "",
        theme_advanced_toolbar_location : "top",
        theme_advanced_toolbar_align : "left",
        extended_valid_elements : "a[name|href|target|title|onclick],span[class|align|style]"
});
//-->
</script>

The code above would produce an editor that looks like:

Enabling HTML Source Editing

Direct HTML source editing of announcements may be enabled by adding the "code" button to the TinyMCE editor, as described above. Once this button is available, clicking the "HTML" control in the button bar will launch a popup window that allows direct source code manipulation.

While this mode allows an administrator to enter any HTML content, TinyMCE is configured with rules that enforce valid HTML and limit the set of allowed HTML elements and attributes. In particular, administrators may find that the "class" attribute is not generally permitted by the editor. To configure the list of allowed elements and attributes, edit the extended_valid_elements property, adding elements and attributes as desired. For example, to allow administrators to add a class attribute to links, edit the line

        extended_valid_elements : "a[name|href|target|title|onclick],span[class|align|style]"

to

        extended_valid_elements : "a[name|href|target|title|onclick|class],span[class|align|style]"

More information about this configuration option, as well as documentation on the default configuration, is available in TinyMCE's FAQ.

Changing Announcement list sort order

The order that announcements are displayed in both the normal user view as well as the admin view can be adjusted via Portlet Preference settings. For the normal user Announcement view list you will want to adjust the AnnouncementsViewController.AnnouncementSortStrategy preference and for the admin view you will want to adjust the AdminTopicController.AnnouncementSortStrategy preference. The possible values for either of these preferences is:

CREATE_DATE_ASCENDING - Sort by the announcement creation date in ascending order
CREATE_DATE_DESCENDING - Sort by the announcement creation date in descending order
START_DISPLAY_DATE_ASCENDING - Sort by the announcement "Start Display" date in ascending order
START_DISPLAY_DATE_DESCENDING - Sort by the announcement "Start Display" date in descending order
END_DISPLAY_DATE_ASCENDING - Sort by the announcement "End Display" date in ascending order
END_DISPLAY_DATE_DESCENDING - Sort by the announcement "End Display" date in descending order