Custom Events Portlet

Gives you the ability to share events between sites via an RSS feed. This portlet is styled to look like our regular events portlet, but can pull events from another site or a subset of events on your site. Only events in the published state, that will occur in the future, will display in a Custom Events Portlet.

This is an advanced feature of our web system.  As such, you need to be comfortable working with HTML to implement this.  

Collections and Their RSS Feeds

The Custom Events Portlet can pull events from any site within our School of Medicine web system.  More specifically, it pulls them from a collection.  You can use the default Events collection that was created with every site, or, you can create a custom collection to fine tune which events you wish to display.   For example, you can display all the events of a department or just their grand rounds.

Every collection automatically has its own RSS feed.  It is the url of the RSS feed that you will use to build a Custom Events Portlet.  Simply add "/RSS" (in all caps) to the end of the url of a collection to get the address of its RSS feed.  For example, the events collection for The UNC Health Care Newsroom site has the following address: http://news.unchealthcare.org/events/aggregator.  The RSS feed address for this collection would then be http://news.unchealthcare.org/events/aggregator/RSS.  Even though you can list the RSS address of a collection containing different types of content (pages, news items, images), only published events will display in the Custom Events Portlet.

 

Add a Custom Events Portlet

The Custom Events Portlet can be placed in any portlet location on a page.  

  1. Before you can add a Custom Event Portlet, you must first change your editing preferences.  Doing so will disable the editor and will require you to work with the HTML.  Don't worry, there isn't much you need to do other than copy and paste some custom code.  Since you can't change the editing preferences for a portlet, you must globally change your editing preferences as described on the Editing Preferences page.  If you do not change your editing preferences before adding a Custom Event Portlet, the editor will modify the custom code and the portlet will never work.
     
  2. Navigate to the page you wish to add the Custom Events Portlet to.  Decide where (what portlet area) you wish to place the portlet (reference labels 1 through 8 in the image below).

     
    PortletLocations.jpg

  3. Click on one of the green portlet links to either "Manage portlets" or "Add, edit, or remove a portlet".
     
  4. From the Add portlet... drop-down menu, select Static text portlet
    Add Portlet
  5. Copy the code listed below and paste it into the static text portlet.  
  6. You will need to replace the two URLs listed in the code and that are highlighted in bold red.  The first URL is a link that is a safety feature in the event that a site visitor has their JavaScript turned off.  If their JavaScript is turned off, the portlet will not display properly.  In this event we've designed the system to simply display "Link to Upcoming Events."  The first URL in the code is the link that is attached to this text.  The second link is the url of the RSS feed for whose events you wish to display.

  7. Check the option to "Omit portlet border." 
    OmitPortletBorder.png 
  8. Click the Save button.

The Code

Copy the code listed below and paste it into a static text portlet.  When creating the static text portlet, ensure you put a check next to "Omit portlet border."

<div id="somAjaxEvents">
     <p class="no-js"><a href="http://news.unchealthcare.org/events" target="_blank">Link to Upcoming Events</a></p>
</div>

<script src="++theme++SOMTheme/js/somajaxevents.js" type="text/javascript"></script>

<script type="text/javascript">
    somAjaxEvents({
        url: 'http://news.unchealthcare.org/events/aggregator/RSS'
    });
</script>

You will need to replace the two URLs listed in the code and that are highlighted in bold red.  

  • The first URL is a link that is a safety feature in the event that a site visitor has their JavaScript turned off.  If their JavaScript is turned off, the portlet will not display properly.  In this event we've designed the system to simply display "Link to Upcoming Events."  The first URL in the code is the link that is attached to this text.  
  • The second link is the url of the RSS feed for whose events you wish to display.

 

Options

Here is a list of all the options that can be configured to customize the Custom Events Portlet.

NameTypeDefaultDescription
url string "http://news.unchealthcare.org/events/aggregator/RSS" Required–the event collection RSS url.
source string "" Optional–A manually specified url for more info (i.e. 'Upcoming events'), useful for instance if a different location than the events collection is desired (such as a page). If left blank, the upcoming events link will be distilled from 'url' provided above, pointing to the collection.
title string "Upcoming Events" Optional - allows a customized portlet title.
limit number 4 Optional - number of event items to display.
fallbackPrefix string "" Optional - custom fallback text to preceed a direct link to the url's "calendar". If left blank, the fallback link simply says "View the calendar"

The code for these options needs to be passed into the somAjaxEvents function within the script. Each option needs to be followed by a comma unless it is the last option listed. Here is an example:

<div id="somAjaxEvents">
<p class="no-js"><a href="http://news.unchealthcare.org/events" target="_blank">Link to Upcoming Events</a></p>
</div> <script src="++theme++SOMTheme/js/somajaxevents.js" type="text/javascript"></script> <script type="text/javascript">
somAjaxEvents({
url: 'http://news.unchealthcare.org/events/aggregator/RSS',
title: 'Health Care News',
limit: 6,
source: 'http://news.unchealthcare.org/events/',
fallbackPrefix: 'View our entire '
});
</script>


URL

This is the url of the RSS feed for whose events you wish to display.

Source

At the bottom of a Custom Events Portlet there is a "more..." link that site visitors can click to be taken to the entire collection of events.  The system will automatically take the URL of the RSS that you specify and chop off the "/RSS."  It will then use the new url as the link for the "more..." button.  You can however specify a different link for the more button using the Source configuration.

Title

The default  title of the Custom Events Portlet is "Upcoming Events."   The Title configuration allows you to specify your own custom title.  

Limit

Allows you to specify the maximum number of events to display in the portlet. 

FallbackPrefix

The Custom Events Portlet does not display in IE 8 & 9.  We are not concerned since these are outdated browser and people can update to a newer version for free.  However, we do not want site visitors to miss out on important content.  As such site visitors withe IE 8 & 9 will see the portlet title and a link to the collection of events.  The link will say "View the calendar."  You can customize this text using the fallbackPrefix configuration.  All that you can change is the "View the" text since the system will automatically add the word "calendar" with a link to the end.

CustomEventsPortlet_01.png

 

Examples

The Office of Information Systems

Here at the Office of Information Systems, we list our upcoming web system training class on our Help site.  We also list these same events on our web guide.  Rather than manage the same events on two sites, we manage them on one and use a custom events portlet to display them on the other.  

 CustomEventsPortlet_02.png