Package org.apache.velocity.tools.view

Class UiDependencyTool

  • @DefaultKey("depends")
@ValidScope("request")
public class UiDependencyTool
extends org.apache.velocity.tools.generic.SafeConfig
    NOTE: This tool is considered "beta" quality due to lack of public testing and is not automatically provided via the default tools.xml file. Tool to make it easier to manage usage of client-side dependencies. This is essentially a simple dependency system for javascript and css. This could be cleaned up to use fewer maps, use more classes, and cache formatted values, but this is good enough for now. To use it, create a ui.xml file at the root of the classpath. Follow the example below. By default, it prepends the request context path and then "css/" to every stylesheet file and the request context path and "js/" to every javascript file path. You can alter those defaults by changing the type definition. In the example below, the file path for the style type is changed to "/styles/", leaving out the {context}. This is safe in request scope, but the group info (from ui.xml) should only be read once. It is not re-parsed on every request.

    Example of use: 

      Template
  ---
  <html>
    <head>
      $depends.on('profile').print('
      ')
    </head>
  ...

  Output
  ------
  <html>
    <head>
      <style rel="stylesheet" type="text/css" href="css/globals.css"/>
      <script type="text/javascript" src="js/jquery.js"></script>
      <script type="text/javascript" src="js/profile.js"></script>
    </head>
  ...

    Example tools.xml:

     <tools>
   <toolbox scope="request">
     <tool class="org.apache.velocity.tools.view.beta.UiDependencyTool"/>
   </toolbox>
 </tools>

    Example ui.xml:

     <ui>
   <type name="style"><![CDATA[<link rel="stylesheet" type="text/css" href="/styles/{file}">]]></type>
   <group name="globals">
     <file type="style">css/globals.css<file/>
   </group>
   <group name="jquery">
     <file type="script">js/jquery.js<file/>
   </group>
   <group name="profile">
     <needs>globals</needs>
     <needs>jquery</needs>
     <file type="script">js/profile.js<file/>
   </group>
 </ui>
    Version:
    $Revision: 16660 $
    Author:
    Nathan Bubna

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected static class  UiDependencyTool.FileRule
      NOTE: This class may change or disappear w/o warning; don't depend on it unless you're willing to update your code whenever this changes.
      protected class  UiDependencyTool.Group
      NOTE: This class may change or disappear w/o warning; don't depend on it unless you're willing to update your code whenever this changes.
      protected static class  UiDependencyTool.GroupRule
      NOTE: This class may change or disappear w/o warning; don't depend on it unless you're willing to update your code whenever this changes.
      protected static class  UiDependencyTool.NeedsRule
      NOTE: This class may change or disappear w/o warning; don't depend on it unless you're willing to update your code whenever this changes.
      protected static class  UiDependencyTool.TypeRule
      NOTE: This class may change or disappear w/o warning; don't depend on it unless you're willing to update your code whenever this changes.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String DEFAULT_SOURCE_FILE  
      static java.lang.String GROUPS_KEY_SPACE  
      static java.lang.String SOURCE_FILE_KEY  
      static java.lang.String TYPES_KEY_SPACE  

      • Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

        LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void addDependencies​(java.util.Map<java.lang.String,​java.util.List<java.lang.String>> fbt)
      Adds the specified files organized by type to this instance's current dependencies.
      protected void addFile​(java.lang.String type, java.lang.String file)
      Adds a file to this instance's dependencies under the specified type.
      protected void configure​(org.apache.velocity.tools.generic.ValueParser params)  
      UiDependencyTool context​(java.lang.String path)
      Sets a custom {context} variable for the formats to use.
      protected org.apache.commons.digester3.Digester createDigester()
      Creates the Digester used by read(java.lang.String, boolean) to create the group info for this instance out of the specified XML file.
      protected java.lang.String format​(java.lang.String format, java.lang.String value)
      Applies the format string to the given value.
      java.util.Map<java.lang.String,​java.util.List<java.lang.String>> getDependencies()
      Returns the current dependencies of this instance, organized as an ordered map of file types to lists of the required files of that type.
      java.util.List<java.lang.String> getDependencies​(java.lang.String type)
      Returns the List of files for the specified file type, if any.
      java.lang.String getFormat​(java.lang.String type)
      Retrieves the configured format string for the specified file type.
      protected UiDependencyTool.Group getGroup​(java.lang.String name)
      NOTE: This method may change or disappear w/o warning; don't depend on it unless you're willing to update your code whenever this changes.
      java.util.Map<java.lang.String,​java.util.List<java.lang.String>> getGroupDependencies​(java.lang.String name)
      Returns the dependencies of the specified group, organized as an ordered map of file types to lists of the required files of that type.
      protected UiDependencyTool.Group makeGroup​(java.lang.String name)
      NOTE: This method may change or disappear w/o warning; don't depend on it unless you're willing to update your code whenever this changes.
      UiDependencyTool on​(java.lang.String name)
      Adds all the files required for the specified group, then returns this instance.
      UiDependencyTool on​(java.lang.String type, java.lang.String file)
      Adds the specified file to this instance's list of dependencies of the specified type, then returns this instance.
      java.lang.String print()
      Formats and prints all the current dependencies of this tool, using a new line in between the printed/formatted files.
      java.lang.String print​(java.lang.String typeOrDelim)
      If the parameter value is a known type, then this will format and print all of this instance's current dependencies of the specified type, using a new line in between the printed/formatted files.
      java.lang.String print​(java.lang.String type, java.lang.String delim)
      Formats and prints all of this instance's current dependencies of the specified type, using the specified delimiter in between the printed/formatted files.
      java.lang.String printAll​(java.lang.String delim)
      Formats and prints all the current dependencies of this tool, using the specified delimiter in between the printed/formatted files.
      protected void read​(java.lang.String file, boolean required)
      Reads group info out of the specified file and into this instance.
      void setFormat​(java.lang.String type, java.lang.String format)
      Sets the format string for the specified file type.
      java.lang.String toString()
      Returns an empty String to avoid polluting the template output after a successful call to on(String) or on(String,String).

      • Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

        configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • GROUPS_KEY_SPACE

        public static final java.lang.String GROUPS_KEY_SPACE

      • TYPES_KEY_SPACE

        public static final java.lang.String TYPES_KEY_SPACE

      • DEFAULT_SOURCE_FILE

        public static final java.lang.String DEFAULT_SOURCE_FILE
        See Also:
        Constant Field Values

    • Constructor Detail

      • UiDependencyTool

        public UiDependencyTool()

    • Method Detail

      • configure

        protected void configure​(org.apache.velocity.tools.generic.ValueParser params)
        Overrides:
        configure in class org.apache.velocity.tools.generic.SafeConfig

      • on

        public UiDependencyTool on​(java.lang.String name)
        Adds all the files required for the specified group, then returns this instance. If the group name is null or no such group exists, this will return null to indicate the error.
        Parameters:
        name - group name
        Returns:
        this or null

      • on

        public UiDependencyTool on​(java.lang.String type,
                           java.lang.String file)
        Adds the specified file to this instance's list of dependencies of the specified type, then returns this instance. If either the type or file are null, this will return null to indicate the error.
        Parameters:
        type - file type
        file - dependency file
        Returns:
        this or null

      • print

        public java.lang.String print()
        Formats and prints all the current dependencies of this tool, using a new line in between the printed/formatted files.
        Returns:
        all dependencies

      • print

        public java.lang.String print​(java.lang.String typeOrDelim)
        If the parameter value is a known type, then this will format and print all of this instance's current dependencies of the specified type, using a new line in between the printed/formatted files. If the parameter value is NOT a known type, then this will treat it as a delimiter and print all of this instance's dependencies of all types, using the specified value as the delimiter in between the printed/formatted files.
        Parameters:
        typeOrDelim - type asked for, or delimiter
        Returns:
        all dependencies
        See Also:
        print(String,String), printAll(String)

      • print

        public java.lang.String print​(java.lang.String type,
                              java.lang.String delim)
        Formats and prints all of this instance's current dependencies of the specified type, using the specified delimiter in between the printed/formatted files.
        Parameters:
        type - file type
        delim - lines delimiter
        Returns:
        list of dependencies for thie type, formatted using delimiter

      • printAll

        public java.lang.String printAll​(java.lang.String delim)
        Formats and prints all the current dependencies of this tool, using the specified delimiter in between the printed/formatted files.
        Parameters:
        delim - delimiter
        Returns:
        list of dependencies

      • context

        public UiDependencyTool context​(java.lang.String path)
        Sets a custom {context} variable for the formats to use.
        Parameters:
        path - context path
        Returns:
        this

      • getFormat

        public java.lang.String getFormat​(java.lang.String type)
        Retrieves the configured format string for the specified file type.
        Parameters:
        type - file type
        Returns:
        configured format

      • setFormat

        public void setFormat​(java.lang.String type,
                      java.lang.String format)
        Sets the format string for the specified file type.
        Parameters:
        type - file type
        format - format string

      • getDependencies

        public java.util.Map<java.lang.String,​java.util.List<java.lang.String>> getDependencies()
        Returns the current dependencies of this instance, organized as an ordered map of file types to lists of the required files of that type.
        Returns:
        map of all dependencies

      • getDependencies

        public java.util.List<java.lang.String> getDependencies​(java.lang.String type)
        Returns the List of files for the specified file type, if any.
        Parameters:
        type - file type
        Returns:
        all dependencies for this type

      • getGroupDependencies

        public java.util.Map<java.lang.String,​java.util.List<java.lang.String>> getGroupDependencies​(java.lang.String name)
        Returns the dependencies of the specified group, organized as an ordered map of file types to lists of the required files of that type.
        Parameters:
        name - group name
        Returns:
        map of all dependencies for this group

      • toString

        public java.lang.String toString()
        Returns an empty String to avoid polluting the template output after a successful call to on(String) or on(String,String).
        Overrides:
        toString in class java.lang.Object
        Returns:
        empty string

      • read

        protected void read​(java.lang.String file,
                    boolean required)
        Reads group info out of the specified file and into this instance. If the file cannot be found and required is true, then this will throw an IllegalArgumentException. Otherwise, it will simply do nothing. Any checked exceptions during the actual reading of the file are caught and wrapped as RuntimeExceptions.
        Parameters:
        file - file
        required - whether this file is required

      • createDigester

        protected org.apache.commons.digester3.Digester createDigester()
        Creates the Digester used by read(java.lang.String, boolean) to create the group info for this instance out of the specified XML file.
        Returns:
        new digester

      • format

        protected java.lang.String format​(java.lang.String format,
                                  java.lang.String value)
        Applies the format string to the given value. Currently, this simply replaces '{file}' with the value. If you want to handle more complicated formats, override this method.
        Parameters:
        format - format string
        value - dependency file
        Returns:
        formatted string

      • getGroup

        protected UiDependencyTool.Group getGroup​(java.lang.String name)
        NOTE: This method may change or disappear w/o warning; don't depend on it unless you're willing to update your code whenever this changes.
        Parameters:
        name - file name
        Returns:
        group this file belongs to, or null

      • makeGroup

        protected UiDependencyTool.Group makeGroup​(java.lang.String name)
        NOTE: This method may change or disappear w/o warning; don't depend on it unless you're willing to update your code whenever this changes.
        Parameters:
        name - group name
        Returns:
        new group

      • addDependencies

        protected void addDependencies​(java.util.Map<java.lang.String,​java.util.List<java.lang.String>> fbt)
        Adds the specified files organized by type to this instance's current dependencies.
        Parameters:
        fbt - dependencies map

      • addFile

        protected void addFile​(java.lang.String type,
                       java.lang.String file)
        Adds a file to this instance's dependencies under the specified type.
        Parameters:
        type - file type
        file - file name