Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.apache.velocity.tools.view
Class UiDependencyTool

java.lang.Object
  extended by org.apache.velocity.tools.view.UiDependencyTool

@DefaultKey(value="depends")
@ValidScope(value="request")
public class UiDependencyTool
extends java.lang.Object

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
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 static 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.
private static class UiDependencyTool.Type
           
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
private  java.lang.String context
           
static java.lang.String DEFAULT_SOURCE_FILE
           
private static java.util.List<UiDependencyTool.Type> DEFAULT_TYPES
           
private  java.util.Map<java.lang.String,java.util.List<java.lang.String>> dependencies
           
private  java.util.Map<java.lang.String,UiDependencyTool.Group> groups
           
static java.lang.String GROUPS_KEY_SPACE
           
private  org.apache.velocity.runtime.log.Log LOG
           
static java.lang.String SOURCE_FILE_KEY
           
private  java.util.List<UiDependencyTool.Type> types
           
static java.lang.String TYPES_KEY_SPACE
           
 
Constructor Summary
UiDependencyTool()
           
 
Method Summary
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.
 void configure(java.util.Map params)
           
 UiDependencyTool context(java.lang.String path)
          Sets a custom {context} variable for the formats to use.
protected  org.apache.commons.digester.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.
private  void debug(java.lang.String msg, java.lang.Object... args)
           
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.
private  UiDependencyTool.Type getType(java.lang.String type)
          For internal use only.
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).
private  java.net.URL toURL(java.lang.String file)
           
protected static void trace(org.apache.velocity.runtime.log.Log log, java.lang.String msg, java.lang.Object... args)
           
 
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

SOURCE_FILE_KEY

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

DEFAULT_SOURCE_FILE

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

DEFAULT_TYPES

private static final java.util.List<UiDependencyTool.Type> DEFAULT_TYPES

groups

private java.util.Map<java.lang.String,UiDependencyTool.Group> groups

types

private java.util.List<UiDependencyTool.Type> types

dependencies

private java.util.Map<java.lang.String,java.util.List<java.lang.String>> dependencies

LOG

private org.apache.velocity.runtime.log.Log LOG

context

private java.lang.String context
Constructor Detail

UiDependencyTool

public UiDependencyTool()
Method Detail

debug

private void debug(java.lang.String msg,
                   java.lang.Object... args)

trace

protected static final void trace(org.apache.velocity.runtime.log.Log log,
                                  java.lang.String msg,
                                  java.lang.Object... args)

configure

public void configure(java.util.Map params)

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.

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.

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.

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.

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.

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.

context

public UiDependencyTool context(java.lang.String path)
Sets a custom {context} variable for the formats to use.

getFormat

public java.lang.String getFormat(java.lang.String type)
Retrieves the configured format string for the specified file type.

setFormat

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

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.

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.

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.

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

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.

createDigester

protected org.apache.commons.digester.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.

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.

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.

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.

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.

addFile

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

getType

private UiDependencyTool.Type getType(java.lang.String type)
For internal use only. Use/override get/setFormat instead.

toURL

private java.net.URL toURL(java.lang.String file)
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright (c) 2003-2007 Apache Software Foundation