Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum.util
Class SkinUtils

java.lang.Object
  extended by com.jivesoftware.forum.util.SkinUtils

public class SkinUtils
extends java.lang.Object

A collection of utility methods for use in Jive Skins. Because these methods make skin development much easier, skin authors should study them carefully.

Five major areas of functionality are provided:

  1. Password reset methods.

  2. Other methods.


Method Summary
static java.lang.String dateToText(javax.servlet.http.HttpServletRequest request, User user, java.util.Date date)
          Returns an English sentence which describes the Date parameter relative to the current time.
static boolean emailResetPasswordInstructions(java.lang.String username, javax.servlet.http.HttpServletRequest request)
          This method will send the user specified an email with instructions on how to reset their password.
static java.util.Iterator filterPendingMessages(java.util.Iterator messages)
          Assumes index of iterator is at front of iterator (ie, iterator hasn't been used).
static java.lang.String formatDate(javax.servlet.http.HttpServletRequest request, User user, java.util.Date date)
          Formats a date for a user, according to their locale and time zone preferences.
static java.lang.String getCommunityName()
          Returns the name of the community or "Support Forums" (English only) as the default.
static java.lang.String getCommunityName(java.lang.String i18nDefaultKey)
          Returns the name of the community or the value of the given i18n key as the default.
static java.lang.String getDisplayName(User user)
          A simple method to check whether to display a user's full name or their username.
static long getLastVisited(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Returns the Date the user last visited.
static java.util.List getParentCategories(Forum forum)
          Returns a list of parent categories for the given forum in top-down order.
static java.lang.String getSkinProperty(Forum forum, java.lang.String name)
          Searches for the property name in the given forum.
static java.lang.String getTheme()
          Returns the current skin theme or the string "default" to denote the default theme.
static boolean isNew(ForumCategory category, java.util.Date time)
          Returns true if the category has been modified since the specified time.
static boolean isNew(Forum forum, java.util.Date time)
          Returns true if the forum has been modified since the specified time.
static boolean isNew(ForumMessage message, java.util.Date time)
          Returns true if the forum message has been modified since the specified time.
static boolean isNew(ForumThread thread, java.util.Date time)
          Returns true if the forum thread has been modified since the specified time.
static boolean isSlimLayout()
          Used to tell if we should user a slimmer layout
static boolean isValidPasswordToken(long userId, java.lang.String token)
          Returns true is the supplied token is valid for the userId given.
static java.lang.String quoteOriginal(java.lang.String body, java.lang.String delimiter, int lineLength)
          Formats the unfiltered body of a message to make it appear in the "quote original" format.
static boolean resetUserPassword(long userId, java.lang.String token, java.lang.String newPassword)
          This method is used in conjunction with the emailResetPasswordInstructions method to reset a user's password.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

formatDate

public static java.lang.String formatDate(javax.servlet.http.HttpServletRequest request,
                                          User user,
                                          java.util.Date date)
Formats a date for a user, according to their locale and time zone preferences.

Parameters:
request - the servlet request object.
user - the User that the date is being formatted for.
date - the Date object we're comparing the current time with.
Returns:
the date formatted for the correct locale and time zone.

quoteOriginal

public static java.lang.String quoteOriginal(java.lang.String body,
                                             java.lang.String delimiter,
                                             int lineLength)
Formats the unfiltered body of a message to make it appear in the "quote original" format. This is simply the body of the message with the delimiter appended to the beginning of each line. The delimiter is most often "> " by convention. A desired length for each line in the returned String can be specified to aid in formatting.

This method uses message.getUnfilteredBody() in order to get the body of the message. This usually yields better results for the formatting required by this method. However, it also has the potential of being a security risk if malicious HTML code is embedded in the body. Therefore, you should always filter HTML from the result of this method before showing it in an environment where HTML is interpreted. If you are showing the results of this method in an HTML <textarea>, there is no need to worry about malicious HTML.

Parameters:
body - the message body to quote.
delimiter - a String that will start each line of the quoted message. For example, "> ";
lineLength - the desired length of each line in the quoted message.
Returns:
the unfiltered body of the message in the "quote original" format.

isNew

public static boolean isNew(ForumCategory category,
                            java.util.Date time)
Returns true if the category has been modified since the specified time.

Parameters:
category - the category to check.
time - the time to reference the category against.
Returns:
true if the category has been modified since the specified time.

isNew

public static boolean isNew(Forum forum,
                            java.util.Date time)
Returns true if the forum has been modified since the specified time.

Parameters:
forum - the forum to check.
time - the time to reference the forum against.
Returns:
true if the forum has been modified since the specified time.

isNew

public static boolean isNew(ForumThread thread,
                            java.util.Date time)
Returns true if the forum thread has been modified since the specified time.

Parameters:
thread - the thread to check.
time - the time to reference the thread against.
Returns:
true if the thread has been modified since the specified time.

isNew

public static boolean isNew(ForumMessage message,
                            java.util.Date time)
Returns true if the forum message has been modified since the specified time.

Parameters:
message - the message to check.
time - the time to reference the message against.
Returns:
true if the message has been modified since the specified time.

getParentCategories

public static java.util.List getParentCategories(Forum forum)
Returns a list of parent categories for the given forum in top-down order. This will not include the "root" category. Also, if a forum is in the root category an empty list will be returned.

Parameters:
forum - the forum to return parent categories.
Returns:
a list of parent categories in top-down order or an empty iterator if no parent categories exist.

getSkinProperty

public static java.lang.String getSkinProperty(Forum forum,
                                               java.lang.String name)
Searches for the property name in the given forum. If the property is not found there, the property is checked for in the forum's category. Finally, if the property is not found there, the global property list is searched.

This is a useful method for skin writers if they want to apply per-forum or per-category level UI changes. For example, the property for the forum page background color is stored as the global property "skin.default.bgColor". To apply a forum-level background color, simply create an extended property of the forum named "skin.default.bgColor" and call this method when retrieving the property from the skin.

Parameters:
forum - the Forum where we begin searching for the property. If the property is not found in the forum, this forum's category is checked and failing that, then global property list is checked. If this is null then this method simply calls JiveGlobals.getJiveProperty(String).
name - the name of the property we're looking for.
Returns:
the value of the given property or null if was not found.

getLastVisited

public static long getLastVisited(javax.servlet.http.HttpServletRequest request,
                                  javax.servlet.http.HttpServletResponse response)
Returns the Date the user last visited. If no date was found (stored in a cookie) the current time is used.

Parameters:
request - the HttpServletRequest object, known as "request" on a JSP page.
response - the HttpServletRequest object, known as "response" on a JSP page.
Returns:
the time of the last visit in milliseconds since Jan 1st, 1970.

filterPendingMessages

public static java.util.Iterator filterPendingMessages(java.util.Iterator messages)
Assumes index of iterator is at front of iterator (ie, iterator hasn't been used).

Parameters:
messages -
Returns:
an Iterator of non-pending messages from the given iterator.

emailResetPasswordInstructions

public static boolean emailResetPasswordInstructions(java.lang.String username,
                                                     javax.servlet.http.HttpServletRequest request)
                                              throws java.lang.IllegalArgumentException
This method will send the user specified an email with instructions on how to reset their password. Included in the instructions is a 'token' string which is good for 72 hours. By following the instructions given in the email the user will be able to reset their password.

If the user has already been sent a password reset email in the last 72 hours, the token will not be regenerated but will instead be reused in the instructional email. Conversely, if the user has been sent an email prior to the last 72 hours, the token will be regenerated and saved. In either case, no more than 1 email every 24 hours will be sent. Attempts to send more than 1 email per 24 hours will result in this method returning false.

You can insert the following tokens into the subject or body of the email message and they'll be dynamically replaced with the appropriate values when the email is sent: {userID}, {username}, {name}, {email}, {token}, {requestIP}, {host}, {port} and {webAppDir}.

The details of the email can be changed using the Jive admin skin, the default email is below:

{host} - Jive Forums reset password request.

We have received a request from {requestIP} to reset your password. If you have requested to reset your password, please follow the instructions below. If you do not wish to reset your password, please simply disregard this message.

To reset your Jive password at {host} you can either:

- Click the following url:

http://{host}:{port}{webAppDir}/resetPassword.jsp?userid={userID}&token={token}

- Goto http://{host}:{port}{webAppDir}/resetPassword.jsp and enter the following information into the fields provided:

UserID: {userID}

Token: {token}

Parameters:
username - the usename of the user for whom we wish to send an email with instructions on how to reset their password
request - the servlet request object
Returns:
True if the email was send successfully, false otherwise
Throws:
java.lang.IllegalArgumentException - if either username or request is null

isValidPasswordToken

public static boolean isValidPasswordToken(long userId,
                                           java.lang.String token)
Returns true is the supplied token is valid for the userId given. This method checks the consistency of the token (case sensitive) as well as whether the token is valid timewise (The token is only good for 72 hours). If the token is not valid timewise, the user property storing the token will be deleted.

Parameters:
userId - the id of the user for whom we are validating the password reset token.
token - the password reset token associated with the above user.
Returns:
true is the token is valid, false otherwise.

resetUserPassword

public static boolean resetUserPassword(long userId,
                                        java.lang.String token,
                                        java.lang.String newPassword)
This method is used in conjunction with the emailResetPasswordInstructions method to reset a user's password. The system generated token will be provided in the instructional email. Returns true if the password was reset, false otherwise. Possible reasons for failure:

Parameters:
userId - the id of the user for whom the password should be changed.
token - the password reset token associated with the above user.
newPassword - the password to use for the specified user.
Returns:
true is the password was changed, false otherwise.

dateToText

public static java.lang.String dateToText(javax.servlet.http.HttpServletRequest request,
                                          User user,
                                          java.util.Date date)
Returns an English sentence which describes the Date parameter relative to the current time. For instance, if the passed in date was 39 seconds ago, this method returns:

"Less than 1 min ago"

Similiarly, a date 1 ago would be:

"Yesterday at 3:53 PM"

The method obeys user preferences for time zone if they exist.

Parameters:
request - the servlet request object.
user - the User that the date is being formatted for, or null if an anonymmous user.
date - the Date object we're comparing the current time with.

getDisplayName

public static java.lang.String getDisplayName(User user)
A simple method to check whether to display a user's full name or their username. This is controlled by the jive property ("skin.default.displayFullNames"

Parameters:
user - the user to return the display name for
Returns:
the display name for the user.

getCommunityName

public static java.lang.String getCommunityName()
Returns the name of the community or "Support Forums" (English only) as the default. Users wishing to override this can set the value as a Jive property with the key of 'skin.default.communityName'.

The name of the community will prefix titles by default so it should be something short like "XYZ Support Forums" or "My Company Support".

Returns:
the name of the community or "Support Forums" as the default.

getCommunityName

public static java.lang.String getCommunityName(java.lang.String i18nDefaultKey)
Returns the name of the community or the value of the given i18n key as the default. Users wishing to override this can set the name of the community as a Jive property with the key of 'skin.default.communityName'.

Parameters:
i18nDefaultKey - the i18n key to use as the default value for the community name.
Returns:
the name of the community as the value of the given i18n key or the value and admin specifies as the "skin.default.communityName" Jive property.

getTheme

public static java.lang.String getTheme()
Returns the current skin theme or the string "default" to denote the default theme. Set the theme name by the admin console or by setting a Jive property of 'skin.theme'.

Returns:
the current skin theme or "default" to denote the default theme.

isSlimLayout

public static boolean isSlimLayout()
Used to tell if we should user a slimmer layout

Returns:
true if we should use a slimmer version of the layout

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.