Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

MailPortlet v2.0.0-alpha-

...

3 User Manual

Foreword

Matt Young and Ren Provey of the Internet Frameworks Services division of Duke University's Office Of Information Technology (OIT) created the original version of this portlet in 2007 and it was contributed by Duke University to the JA-SIG community in early 2008. Since then Jen Bourey (of Yale University), Eric Dalquist (of University of Wisconsin-Madison), Erik A. Olsson (of University of California, Irvine), and Gary Weaver (of Duke University) have made contributions. Mail Portlet was free under the BSD License upon original contribution and since then has converted to an Apache 2.0 license per Jasig. The MailPortlet is a collaborative open-source project whose source control, wiki, and project tracking is hosted by Jasig.

...

Code Block
svn co https://www.ja-sig.org/svn/sandbox/MailPortlet/tags/rel-2.0.0-alpha-23

To get the latest dev version of the source (which may not build and may be buggy and/or unstable):

...

Code Block
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:tx="http://www.springframework.org/schema/tx"
       xsi:schemaLocation="
            http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
            http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd
            http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd">

    <bean name="mailAccountTemplateManager" class="org.jasig.portlet.mail.MailAccountTemplateManager">
        <property name="templates">
            <list>
                <!-- Order here doesn't matter, as order is dictated by ordinal set in each bean. -->
                <!-- Anything you add below must be added here. -->
                <ref bean="custom"/>
                <ref bean="aol"/>
                <ref bean="gmail"/>
                <ref bean="dotMac"/>
                <ref bean="mobileMe"/>
                <!-- examples:
                <ref bean="myInstitutionalMailServer"/>
                <ref bean="anotherInstitutionalMailServer"/>
                <ref bean="demo"/>
                -->
            </list>
        </property>
    </bean>

    <!-- Change the values of this bean to reflect the situation at your institution -->

    <!-- Note: name is the formal name of the account that will be listed. displayName is the default tabname. -->



  <!-- default custom to imaps, to hopefully influence user to choose an imaps server if available over imap, pops, pop -->
    <bean name="custom" parent="imaps"<bean name="gmail" parent="imaps">
        <property name="host" value="imap.gmail.com"/>
        <property name="namelink" value="Email accounthttp://mail.google.com"/>
        <property name="displayNamename" value="CustomGmail"/>
        <property name="ordinaldisplayName" value="99999Gmail"/>
        <property name="customordinal" value="true100"/>
    </bean>
    <!-- remember to make sure your server bean name is listed in the mailAccountTemplateManager above -->

    <bean name="aoldotMac" parent="imaps">
        <property name="host" value="imapmail.aolmac.com"/>
        <property name="link" value="http://webmailwww.aolmac.com"/>
        <property name="name" value="AOL.Mac"/>
        <property name="displayName" value="AOL.Mac"/>
        <property name="ordinal" value="30200"/>
    </bean>
    <!-- remember to make sure your server bean name is listed in the mailAccountTemplateManager above -->

    <bean name="gmailmobileMe" parent="imaps">
        <property name="host" value="imapmail.gmailme.com"/>
        <property name="link" value="http://mailwww.googleme.com"/>
        <property name="name" value="GmailMobileMe"/>
        <property name="displayName" value="GmailMobileMe"/>
        <property name="ordinal" value="40300"/>
    </bean>
    <!-- remember to make sure your server bean name is listed in the mailAccountTemplateManager above -->

    <bean name="dotMacaol" parent="imaps">
        <property name="host" value="mailimap.macaol.com"/>
        <property name="link" value="http://wwwwebmail.macaol.com"/>
        <property name="name" value=".MacAOL"/>
        <property name="displayName" value=".MacAOL"/>
        <property name="ordinal" value="50400"/>
    </bean>
    <!-- remember to make sure your server bean name is listed in the mailAccountTemplateManager above -->>

    <bean name="custom" class="org.jasig.portlet.mail.model.MailAccountTemplate">
        <property name="fixed" value="false"/>
        <property name="defaultFolder" value="INBOX"/>
        <property name="name" value="Other Email"/>
        <bean<property name="mobileMedisplayName" parentvalue="imapsOther Email"/>
        <property name="hostordinal" value="mail.me.com99999"/>
        <property name="linkcustom" value="http://www.me.comtrue"/>
        <!-- note: credentialsService is the key  <property name="name" value="MobileMe"/of the service in CredentialsServiceManager, not the bean -->
        <property name="displayNamecredentialsService" value="MobileMeencryptedCredentialsService"/>
        <property name="ordinalincludeInDefault" value="60false"/>
    </bean>
    <!-- remember to make sure your server bean name is listed in the mailAccountTemplateManager above -->

    <!-- Other Examplesexamples: -->

    <!-- Example of a mail tab that gets username from REMOTE_USER and password from a userinfo attribute you would
         define in mailsecurity.xml. This mail tab would show up by default but can be removed or added by the user.
         To make it such that the user could not remove it, we'd change fixed to true. -->
    <!--
    <bean name="myInstitutionalMailServer" parent="imap">
        <property name="host" value="imap.exampleuniversity.edu"/>
        <property name="link" value="https://webmail.exampleuniversity.edu"/>
        <property name="name" value="EU Mail"/>
        <property name="displayName" value="EU"/>
        <property name="ordinal" value="10"/>
        <property name="credentialsService" value="userInfoCredentialsService"/>
        <property name="includeInDefault" value="true"/>
        <property name="fixed" value="false"/>
    </bean>
    -->

    <!-- Example of a mail tab for a server that defines some extra javamail properties and requires the student to be
         in a PAGS group with the PAGS group key "sample". Note that in order to have a PAGS group work, it must be also
         declared in the portlet.xml in the portlet.xml's portlet element like:

         <security-role-ref>
            <role-link>pags.Law</role-link>
         </security-role-ref>

         The user must enter their own username and password since it inherits the .
         This mail tab would not show up by default but is user addable.

         This example also shows how custom JavaMail properties can be defined. Note that JavaMail properties that are
         defined here will override the ones set by setting host and port, for example (so if set in both places, the
         JavaMail properties trump the others).
         -->
    <!--
    <bean name="anotherInstitutionalMailServer" parent="imaps">
        <property name="host" value="imap.law.exampleuniversity.edu"/>
        <property name="port" value="888"/>
        <property name="javaMailProperties">
            <props merge="true">
                <prop key="mail.imap.fetchsize">16384</prop>
                <prop key="mail.imap.allowreadonlyselect">true</prop>
            </props>
        </property>
        <property name="link" value="https://webmail.law.exampleuniversity.edu"/>
        <property name="name" value="Law School Mail"/>
        <property name="displayName" value="Law"/>
        <property name="memberOfAny">
            <list>
                <value>pags.Law</value>
            </list>
        </property>
        <property name="ordinal" value="20"/>
        <property name="includeInDefault" value="false"/>
        <property name="fixed" value="false"/>
    </bean>
    -->

    <!-- Example of a configured test account for test/demonstration purposes. This could also be used to allow everyone
         or certain PAGS group(s) access to a shared account, in theory, not that we're suggesting that. The password
         should be encrypted, so a way to do this is to create the account manually using the portlet and then
         copy that password from the database into the credentials below. At one point I tried offering plain text
         credentials as an option for testing, but there is too much danger of exposing credentials as those are
         persisted also. -->
    <!--
    <bean name="demo" parent="imaps">
        <property name="host" value="imap.gmail.com"/>
        <property name="link" value="http://mail.google.com"/>
        <property name="name" value="Demo"/>
        <property name="displayName" value="Demo"/>
        <property name="ordinal" value="40"/>
        <property name="includeInDefault" value="true"/>
        <property name="credentials" ref="demoCredentials"/>
        <property name="custom" value="true"/>
    </bean>

    <bean name="demoCredentials" class="org.jasig.portlet.mail.model.impl.MailCredentialsImpl">
        <property name="username" value="test"/>
        <property name="password" value="test"/>
    </bean>
    -->

</beans>

...

Warning

Note that version 2.0.0-alpha-2 3 has not been tested with CAS authentication, so it likely needs additional work.

...

Starting with MailPortlet v2.0.0-alpha-23, we're trying our best to use some sort of uPortal standard styling that would be most compatible with existing and custom skins.

...

In addition, if you don't have the following JSR-168 PLT.C classes defined (the "portlet-*" classes), you might want to define them to suit your skin's needs. In older versions of uPortal these classes were defined per portlet in the skin, like cartoon_portlet.css in uPortal 2.5.3.1. In comparison, the default skin has a dedicated CSS file in the skin jsr168_portlet_spec.css in uPortal 3.1.1. Here are the portlet-* CSS classes it uses as of 2.0-alpha-23:

  • portlet-msg-info
  • portlet-msg-error
  • portlet-form-button
  • portlet-section-header
  • portlet-section-subheader
  • portlet-form-field-label

...

Code Block
# MailPortlet messages

# All entries for CredentialsServiceManager in WEB-INF/context/portlet/mailsecurity.xml should have corresponding
# (keyname).description defined.
casProxyCredentialsService.description=Use username/password from CAS
encryptedCredentialsService.description=Password encrypted and username/password stored in database
userInfoCredentialsService.description=Use logged-in user's username/password

# This is the date format used for messages sent today's date and sent prior to today's date
# see: http://java.sun.com/j2se/1.5.0/docs/api/java/util/Formatter.html#dt
dateFormatNotSentToday=%tD %tl:%tM %tp
dateFormatSentToday=%tl:%tM %tp

# Miscellaneous
account=Account
accountNotSavedBadFormData=Account not saved. Please fix the errors below.
add=Add
addAccount=Add Account
addModifyAccounts=Add/Modify Accounts
addOrModifyAccounts=Add/Modify Accounts
cancel=Cancel
cannotAddFixedMailAccount=You cannot add this type of account.
cannotDeleteFixedMailAccount=You cannot delete this type of account.
cannotEditFixedMailAccount=You cannot edit this type of account.
configuration=Configuration
createAccount=Create Account
createAccountFormBottomNote=
createAccountFormButtonsNote=
createAccountFormTopNote=If you need assistance filling out this form, please contact your System Administrator or Internet Service Provider.
delete=Remove
deleteAccount=Remove Account
deleteAccountFormBottomNote=
deleteAccountFormButtonsNote=This will remove this account from your preferences. Are you sure?
deleteAccountFormTopNote=
delim=&nbsp;&gt;&nbsp;
displayName=Name of Account
displayNameHelp=The name by which you would like to refer to this account (for example, "My Account").
edit=Edit
editBottomNote=
editThisAccount=Click here to edit your mail account information.
host=Incoming Server
hostHelp=The name of your incoming server (for example, mail.example.net).
link=Webmail URL
linkHelp=Your mail provider's webmail link, if it has one (for example, https://webmail.example.net/).
mail=Mail
moreActions=More Actions
myAccounts=My Accounts
noAccountsFound=No accounts found.
noDate=(No Date)
noEditOrDelete=(May Not Edit/Remove)
noMailAccount=No Mail Account
noSender=(No Sender)
noSubject=(No Subject)
password=Password
passwordHelp=The password for your incoming mail server.
port=Port
portHelp=Your incoming mail server's port number. Usually is 110 for POP, 143 for IMAP, 993 for Secure IMAP (SSL), or 995 for Secure POP3 (SSL).
protocol=Protocol
protocolHelp=You can often guess this by looking at the incoming server name which may start with 'pop' or 'imap'. Please attempt to use the secure version, and default to the other if the secure version does not work.
refreshAccount=Refresh Account
resetPreferences=Reset Preferences
resetPreferencesFormBottomNote=
resetPreferencesFormButtonsNote=This will reset your mail portlet preferences to the defaults, removing any accounts you have created or changes you have made. Are you sure?
resetPreferencesFormTopNote=
returnToMailView=Return to Mail
save=Save
updateAccount=Update Account
updateAccountFormBottomNote=Notes: For some types of accounts, the username may need to be the full email address. The Name of Account is the text that will show up in the tab (the tab's name).
updateAccountFormButtonsNote=
updateAccountFormTopNote=
username=Username
usernameHelp=The username for your incoming mail server. For some accounts (like Gmail), the username may need to be the full email address.

# Form Validation Errors
mailAccount.displayName.required=Name of account is required.
mailAccount.host.required=Incoming server is required.
mailAccount.link.required=Webmail URL is required.
mailAccount.mailServerProtocol.required=Protocol is required.
mailAccount.name.required=Name is required.
mailAccount.ordinal.required=Ordinal is required.
# Bind errors
typeMismatch.mailAccount.port=Port is required and must be an integer.

# Service Errors
authenticationFailedException=Failed to authenticate to mail server. Please ensure your account information is correct. The error was: {0}
folderClosedException=The mail folder was closed while attempting to get mail. Please try again later.
folderNotFoundException=The specified mail folder was not found. Please ensure your account information is correct.
messageRemovedException=The message we were attempting to read was removed. Please try a refresh or try again later.
messagingException=There was a problem retrieving mail from the server. Please try again later and ensure your account information is correct.
noSuchProviderException=The configured protocol is not supported by this portlet.
problemRetrievingMail=Problem retrieving mail.
storeClosedException=The mail store was closed while attempting to get mail. Please try again later or ensure your account information is correct.
timeoutException=Timed out waiting on server to respond. Please check your username and password, or try again later.
unknownErrorGettingMail=There was an unexpected error while attempting to retrieve mail from the server. Please try again later and ensure your account information is correct.
unknownMailCredentialsService=Unknown Mail Credentials Service

# Protocols. The keys should correspond to JavaMail providers (javamail.providers). See:
# http://java.sun.com/products/javamail/FAQ.html
imap=IMAP
imaps=Secure IMAP (Using SSL)
pop3=POP
pop3s=Secure POP (Using SSL)

...

Create the following file at the root of some new project directory you create. Note that this is only an example and you should tailor the groupId and artifactId up top and the finalName to meet the needs of your environment. Please change the versions to match the version of the Jasig MailPortlet as defined in that version's pom.xml (so, for example, you should change the version on the the MailPortlet dependency war to 2.0-alpha-2 3 for that tag or 2.0-SNAPSHOT for trunk).

Code Block
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>edu.example.university</groupId>
    <artifactId>mail</artifactId>
    <packaging>war</packaging>

    <name>Mail</name>
    <version>yourversionnumbergoeshere</version>

    <dependencies>
      <dependency>
        <groupId>org.jasig.portlet</groupId>
        <artifactId>MailPortlet</artifactId>
        <type>war</type>
        <version>2.0.0-alpha-2<3</version>
      </dependency>
    </dependencies>

    <build>
        <finalName>mailportlet</finalName>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <version>2.0</version>
          </plugin>
        </plugins>
    </build>
</project>

...

Code Block
mkdir -P src/main/resources/
mkdir -P src/main/webapp/WEB-INF/context/portlet
mkdir -P src/test

Put the custom datasource.properties and log4j.properties files that you want to use into:

...

Put the Spring config files (mailsecurity.xml and mailservers.xml usually) that you want to use into:

...