svn commit: r544636 - in /velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic: DisplayTool.java tools.xml

[nb...@apache.org]

Author: nbubna
Date: Tue Jun  5 14:19:58 2007
New Revision: 544636

URL: http://svn.apache.org/viewvc?view=rev&rev=544636
Log:
initial revision of DisplayTool (rewrite of VelocityFormatter functions not represented in VelocityTools)

Added:
    velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/DisplayTool.java   (with props)
Modified:
    velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/tools.xml

Added: velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/DisplayTool.java
URL: http://svn.apache.org/viewvc/velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/DisplayTool.java?view=auto&rev=544636
==============================================================================
--- velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/DisplayTool.java (added)
+++ velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/DisplayTool.java Tue Jun  5 14:19:58 2007
@@ -0,0 +1,324 @@
+package org.apache.velocity.tools.generic;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.    
+ */
+
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.Map;
+import org.apache.velocity.tools.config.DefaultKey;
+
+/**
+ * Provides general utility methods for controlling the display of references.
+ * Currently, this class contains methods for "pretty printing" an array or
+ * {@link Collection}, methods for truncating the string value of a reference
+ * at a configured or specified length, and methods for displaying an alternate
+ * value when a specified value is null.  
+ *
+ * <p><b>Example Use:</b>
+ * <pre>
+ * tools.xml...
+ * &lt;tools&gt;
+ *   &lt;toolbox scope="application"&gt;
+ *     &lt;tool class="org.apache.velocity.tools.generic.DisplayTool&lt;/tool&gt;
+ *   &lt;/toolbox&gt;
+ * &lt;/tool&gt;
+ *
+ * template...
+ *   #set( $list = [1..5] )
+ *   $display.list($list)
+ *   $display.truncate(10, "This is a long string.")
+ *   Not Null: $display.alt("not null", "--")
+ *   Null: $display.alt($null, "--")
+ *
+ * output...
+ *   1, 2, 3, 4 and 5
+ *   This is...
+ *   Not Null: not null
+ *   Null: --
+ *   
+ * </pre></p>
+ *
+ * @since VelocityTools 2.0
+ * @author <a href="sean@somacity.com">Sean Legassick</a>
+ * @author <a href="dlr@collab.net">Daniel Rall</a>
+ * @author Nathan Bubna
+ * @version $Id: DisplayTool.java 463298 2006-10-12 16:10:32Z henning $
+ */
+@DefaultKey("display")
+public class DisplayTool
+{
+    public static final String LOCK_CONFIG_KEY = "lock-config";
+    public static final String LIST_DELIM_KEY = "listDelim";
+    public static final String LIST_FINAL_DELIM_KEY = "listFinalDelim";
+    public static final String TRUNCATE_MAX_LENGTH_KEY = "truncateMaxLength";
+    public static final String TRUNCATE_SUFFIX_KEY = "truncateSuffix";
+    public static final String DEFAULT_ALTERNATE_KEY = "defaultAlternate";
+
+    private String defaultDelim = ", ";
+    private String defaultFinalDelim = " and ";
+    private int defaultMaxLength = 30;
+    private String defaultSuffix = "...";
+    private String defaultAlternate = "null";
+    private boolean configLocked = false;
+
+    /**
+     * Looks for configuration values in the given params.
+     */
+    public void configure(Map params)
+    {
+        if (!configLocked)
+        {
+            ValueParser values = new ValueParser(params);
+            configure(values);
+
+            // by default, lock down this method after use
+            // to prevent templates from re-configuring this instance
+            configLocked = values.getBoolean(LOCK_CONFIG_KEY, true);
+        }
+    }
+
+    /**
+     * Does the actual configuration. This is protected, so
+     * subclasses may share the same ValueParser and call configure
+     * at any time, while preventing templates from doing so when 
+     * configure(Map) is locked.
+     */
+    protected void configure(ValueParser values)
+    {
+        String listDelim = values.getString(LIST_DELIM_KEY);
+        if (listDelim != null)
+        {
+            setListDelimiter(listDelim);
+        }
+
+        String listFinalDelim = values.getString(LIST_FINAL_DELIM_KEY);
+        if (listFinalDelim != null)
+        {
+            setListFinalDelimiter(listFinalDelim);
+        }
+
+        Integer truncateMaxLength = values.getInteger(TRUNCATE_MAX_LENGTH_KEY);
+        if (truncateMaxLength != null)
+        {
+            setTruncateMaxLength(truncateMaxLength);
+        }
+
+        String truncateSuffix = values.getString(TRUNCATE_SUFFIX_KEY);
+        if (truncateSuffix != null)
+        {
+            setTruncateSuffix(truncateSuffix);
+        }
+
+        String defaultAlternate = values.getString(DEFAULT_ALTERNATE_KEY);
+        if (defaultAlternate != null)
+        {
+            setDefaultAlternate(defaultAlternate);
+        }
+    }
+
+    protected void setListDelimiter(String delim)
+    {
+        this.defaultDelim = delim;
+    }
+
+    protected void setListFinalDelimiter(String finalDelim)
+    {
+        this.defaultFinalDelim = finalDelim;
+    }
+
+    protected void setTruncateMaxLength(int maxlen)
+    {
+        this.defaultMaxLength = maxlen;
+    }
+
+    protected void setTruncateSuffix(String suffix)
+    {
+        this.defaultSuffix = suffix;
+    }
+
+    protected void setDefaultAlternate(String dflt)
+    {
+        this.defaultAlternate = dflt;
+    }
+
+
+    /**
+     * Formats a collection or array into the form "A, B and C".
+     *
+     * @param list A collection or array.
+     * @return A String.
+     */
+    public String list(Object list)
+    {
+        return list(list, this.defaultDelim, this.defaultFinalDelim);
+    }
+
+    /**
+     * Formats a collection or array into the form
+     * "A&lt;delim&gt;B&lt;delim&gt;C".
+     *
+     * @param list A collection or array.
+     * @param delim A String.
+     * @return A String.
+     */
+    public String list(Object list, String delim)
+    {
+        return list(list, delim, delim);
+    }
+
+    /**
+     * Formats a collection or array into the form
+     * "A&lt;delim&gt;B&lt;finaldelim&gt;C".
+     *
+     * @param list A collection or array.
+     * @param delim A String.
+     * @param finaldelim A String.
+     * @return A String.
+     */
+    public String list(Object list, String delim, String finaldelim)
+    {
+        if (list instanceof Collection)
+        {
+            return format((Collection)list, delim, finaldelim);
+        }
+        else
+        {
+            return format(Arrays.asList(list), delim, finaldelim);
+        }
+    }
+
+    /**
+     * Does the actual formatting of the collection.
+     */
+    protected String format(Collection list, String delim, String finaldelim)
+    {
+        StringBuilder sb = new StringBuilder();
+        int size = list.size();
+        Iterator iterator = list.iterator();
+        for (int i = 0; i < size; i++)
+        {
+            sb.append(iterator.next());
+            if (i < size - 2)
+            {
+                sb.append(delim);
+            }
+            else if (i < size - 1)
+            {
+                sb.append(finaldelim);
+            }
+        }
+        return sb.toString();
+    }
+
+    /**
+     * Limits the string value of 'truncateMe' to the configured max length
+     * in characters (default is 30 characters).
+     * If the string gets curtailed, the configured suffix
+     * (default is "...") is used as the ending of the truncated string.
+     *
+     * @param obj The value to be truncated.
+     * @return A String.
+     */
+    public String truncate(Object truncateMe)
+    {
+        return truncate(truncateMe, this.defaultMaxLength);
+    }
+
+    /**
+     * Limits the string value of 'truncateMe' to 'maxLength' characters.
+     * If the string gets curtailed, the configured suffix
+     * (default is "...") is used as the ending of the truncated string.
+     *
+     * @param maxLength An int with the maximum length.
+     * @param obj The value to be truncated.
+     * @return A String.
+     */
+    public String truncate(Object truncateMe, int maxLength)
+    {
+        return truncate(truncateMe, maxLength, this.defaultSuffix);
+    }
+
+    /**
+     * Limits the string value of 'truncateMe' to the configured max length
+     * in characters (default is 30 characters).
+     * If the string gets curtailed, the specified suffix
+     * is used as the ending of the truncated string.
+     *
+     * @param obj The value to be truncated.
+     * @param suffix A String.
+     * @return A String.
+     */
+    public String truncate(Object truncateMe, String suffix)
+    {
+        return truncate(truncateMe, this.defaultMaxLength, suffix);
+    }
+
+    /**
+     * Limits the string value of 'truncateMe' to the specified max length
+     * in characters. If the string gets curtailed, the specified suffix
+     * is used as the ending of the truncated string.
+     *
+     * @param maxLength An int with the maximum length.
+     * @param obj The value to be truncated.
+     * @param suffix A String.
+     * @return A String.
+     */
+    public String truncate(Object truncateMe, int maxLength, String suffix)
+    {
+        if (truncateMe == null)
+        {
+            return null;
+        }
+
+        String string = String.valueOf(truncateMe);
+        if (string.length() <= maxLength)
+        {
+            return string;
+        }
+        return string.substring(0, maxLength - suffix.length()) + suffix;
+    }
+
+    /**
+     * Returns a configured default value if specified value is null.
+     * @param checkMe
+     * @return a configured default value if the specified value is null.
+     */
+    public Object alt(Object checkMe)
+    {
+        return alt(checkMe, this.defaultAlternate);
+    }
+
+    /**
+     * Returns the second argument if first argument specified is null.
+     * @param checkMe
+     * @param alternate
+     * @return the second argument if the first is null.
+     */
+    public Object alt(Object checkMe, Object alternate)
+    {
+        if (checkMe == null)
+        {
+            return alternate;
+        }
+        return checkMe;
+    }
+
+}

Propchange: velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/DisplayTool.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/DisplayTool.java
------------------------------------------------------------------------------
    svn:keywords = Revision

Modified: velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/tools.xml
URL: http://svn.apache.org/viewvc/velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/tools.xml?view=diff&rev=544636&r1=544635&r2=544636
==============================================================================
--- velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/tools.xml (original)
+++ velocity/tools/branches/2.x/src/main/java/org/apache/velocity/tools/generic/tools.xml Tue Jun  5 14:19:58 2007
@@ -25,6 +25,7 @@
     <toolbox scope="application">
         <tool class="org.apache.velocity.tools.generic.AlternatorTool"/>
         <tool class="org.apache.velocity.tools.generic.ComparisonDateTool"/>
+        <tool class="org.apache.velocity.tools.generic.DisplayTool"/>
         <tool class="org.apache.velocity.tools.generic.EscapeTool"/>
         <tool class="org.apache.velocity.tools.generic.IteratorTool"/>
         <tool class="org.apache.velocity.tools.generic.ListTool"/>