WritingPortlets

How to write a Homepage Component (Portlet)

Portlets are the panels that appear in your "RT-at-a-glance" home page, such as "n Highest Priority Tickets I own", "Quick Ticket Creation" and "Quick Search". When you click on the "Edit" link on your home page (or go there via your preferences), you can select which of the available portlets are displayed in the "body" (left) or "summary" (right) columns of the home page.

They can also appear on the Self-Service interface, but have to be hard-coded, because Self-Service users don't get the same preferences available to them. You need to manually edit <rt-base-dir>/local/html/SelfService/index.html. You just have to create your element in <rt-base-dir>/local/html/SelfService/Elements and call it from within the index.html file with something like:

 <& /SelfService/Elements/[[MyPortlet]] &>

This example works with RT 3.8.8 and may work with older versions too - your mileage may vary.

There are at least two things you have to do to create a portlet:

• Create a MASON template file in <rt-base-dir>/local/html/Elements that defines your portlet's behaviour.
• Install your portlet by adding it's name to the HomepageComponents configuration variable in RT_SiteConfig.pm.

Once you have created and installed your portlet, you of course, have to restart Apache.

Create a MASON template file

Here's an example MASON template which creates an inline frame containing a web-page from another site:

 <&|/Widgets/TitleBox, title => loc('External Page')&>
 <table>
 	<tr>
 		<td> <iframe name="external page" src="http://wiki.bestpractical.com/" height="480" width="640" frameborder="0" >
 		     </iframe>
 		</td>
 	</tr>
 </table>
 </&>

For this example, the file is saved as "ExternalPage" in the <rt-base-dir>/local/html/Elements directory.

Installing a portlet into RT-at-a-glance

Edit your RT_SiteConfig.pm file, and edit the $HomepageComponents variable (if it hasn't got one, copy it from the RT_Config.pm file). Add the name of your MASON template file, in this example, "ExternalPage":

 Set($HomepageComponents, [qw(QuickCreate Quicksearch MyCalendar
          MyAdminQueues MySupportQueues MyReminders RefreshHomepage
          ExternalPage
 )]);

Go to the "RT at a glance" page, click on the "Edit" link in the top right corner.

In the "Customize RT at a glance" page, add the ExternalPage portlet to the section you prefer, by choosing it in one of the left-hand columns and then clicking on the button that resembles a right arrow.