001    package hirondelle.web4jtools.help;
002    
003    import javax.servlet.jsp.JspException;
004    import java.util.logging.*;
005    import javax.servlet.jsp.PageContext;
006    import hirondelle.web4j.util.Util;
007    import hirondelle.web4j.util.Consts;
008    import hirondelle.web4j.ui.tag.TagHelper;
009    
010    /**
011    * Conditionally display help text in a page.
012    * 
013    * <P>Example use case :<br>
014    * <PRE>
015    * &lt;w:help&gt;
016    *  Report on wildebeest population density.
017    *  Sorted by country, shows only data from 1952-1995.
018    * &lt;/w:help&gt;
019    * </PRE>
020    * 
021    * <P>This tag searches session scope for an object identified by a certain {@link #KEY}.
022    * If that object is present, and corresponds to {@link Boolean#TRUE}, then the 
023    * body of this text will be emitted. Otherwise, the body of this tag will not be 
024    * emitted.
025    * 
026    * <P>The toggling of this value is performed by {@link ShowHelpAction}.
027    */
028    public final class ShowHelpTag extends TagHelper {
029    
030      /** 
031      * Key which identifies a {@link Boolean} attribute placed in session scope.
032      * The value of this attribute toggles the display of help text on and off. 
033      */
034      public static final String KEY = "web4j_help";
035      
036      /** See class comment. */
037      protected String getEmittedText(String aOriginalBody) throws JspException {
038        String result = Consts.EMPTY_STRING;
039        Boolean showHelp = Boolean.FALSE;
040        Object object = getPageContext().getAttribute(KEY, PageContext.SESSION_SCOPE);
041        if ( object != null){
042          try {
043            showHelp = (Boolean)object;
044          }
045          catch (ClassCastException ex){
046            fLogger.severe("Was expecting Attribute named " + KEY + " to refer to a Boolean value. Actually refers to " + object);
047            throw new JspException(ex);
048          }
049        }
050        if (showHelp.booleanValue()){
051          result = aOriginalBody;
052        }
053        return result;
054      }
055      
056      // PRIVATE //
057      private static final Logger fLogger = Util.getLogger(ShowHelpTag.class);
058    }