org.kuali.rice.krad.theme

Class ThemeBuilder

java.lang.Object

org.kuali.rice.krad.theme.ThemeBuilder

All Implemented Interfaces:

org.kuali.common.util.execute.Executable

public class ThemeBuilder
extends Object
implements org.kuali.common.util.execute.Executable

Class that gets executed from the Spring context to build out view themes.

A view theme is a collection of assets that provides the base css and js for one or more views (see ViewTheme. The theme builder provides utilities for creating and configuring themes that follow a standard directory convention.

By default, the theme builder processes any directories under '/themes' as theme directories. Other theme directories can be added through the property getAdditionalThemeDirectories() The basic functions provided by the theme builder are:

• Overlay assets from a parent theme directory (if a parent is configured). Only assets that exist in the parent directory but not in the child will be overlaid
• Applies one or more configured ThemePreProcessor instances to the theme files. For example, Less files are compiled to CSS files here by the LessThemePreProcessor
• Collects JS and CSS resources for the theme. This includes bringing in plugin resources and base KRAD script. Resources can be filtered and ordered as needed
• Perform merging and minification for each file type. During this the file types can perform additional processing (for example, URL rewriting is done for CSS files)

To just perform the first step (overlay parent assets), the property isSkipThemeProcessing() can be set to true. This is useful in development where an update to a parent file just needs pushed to the output directory.

Author:

Kuali Rice Team (rice.collab@kuali.org)

See Also:

ThemeBuilderOverlays, ThemePreProcessor, ThemeFilesProcessor

Constructor Summary

Constructors

Constructor and Description
ThemeBuilder()

Method Summary

Modifier and Type	Method and Description
protected void	buildMappings(List<File> themeDirectories, List<File> pluginDirectories) Builds convenience maps (theme name to path map, theme name to properties mapping, and plugin name to path mapping) for the given theme and plugin directories.
protected Map<String,File>	collectThemePluginDirs(Properties themeProperties) Helper method that filters the list of all plugins and returns those that should be used with the theme
protected void	copyParentThemeConfig(String themeName) If the given theme has a parent, retrieve the theme properties (if exists) for the parent, then for each config property copy the parent value to the child theme properties if missing
void	execute() Invoked from the spring context to execute the theme builder.
List<String>	getAdditionalPluginDirectories() List of absolute paths to include as additional plugin directories
List<String>	getAdditionalThemeDirectories() List of absolute paths to include as additional theme directories
protected List<String>	getAllThemeParents(String themeName, List<String> themeParents) Gets all parents (ancestors) for the given theme name.
protected List<File>	getPluginDirectories() Retrieves the directories that should be processed as plugins.
String	getProjectVersion() Version for the project that will be used to stamp the minified file
String	getThemeBuilderOutputDir() Absolute path to the directory the theme builder should output content to
protected List<File>	getThemeDirectories() Retrieves the directories that should be processed as themes.
List<String>	getThemeExcludes() List of theme names that should be excluded from theme processing
protected Map<String,String>	getThemeNamePathMapping() Map that associates theme names with their path, provided here for subclasses
protected Map<String,Properties>	getThemeNamePropertiesMapping() Map that associates theme names with their properties, provided here for subclasses
List<ThemePreProcessor>	getThemePreProcessors() List of ThemePreProcessor instances that should be applied to the themes
String	getWebappSourceDir() Absolute path to the directory that contains the web application source
boolean	isSkipThemeProcessing() Indicates whether processing of the themes should be skipped
protected List<String>	orderThemesForBuilding() Builds a list containing theme names in the order for which they should be processed.
protected void	processThemeAssets(String themeName) Performs the various steps to process the given theme
void	setAdditionalPluginDirectories(List<String> additionalPluginDirectories) Setter for the list of additional plugin directory paths
void	setAdditionalPluginDirectoriesStr(String additionalPluginDirectories) Convenience setter that takes a string and parses to populate the additional plugin directories list
void	setAdditionalThemeDirectories(List<String> additionalThemeDirectories) Setter for the list of additional theme directory paths
void	setAdditionalThemeDirectoriesStr(String additionalThemeDirectories) Convenience setter that takes a string and parses to populate the additional theme directories list
void	setProjectVersion(String projectVersion) Setter for the project version
void	setSkipThemeProcessing(boolean skipThemeProcessing) Setter to skip theme processing
void	setThemeBuilderOutputDir(String themeBuilderOutputDir) Setter for the path to the output directory
void	setThemeExcludes(List<String> themeExcludes) Setter for the list of theme names to exclude from processing
void	setThemeExcludesStr(String themeExcludes) Convenience setter that takes a string and parses to populate the theme excludes list
void	setThemePreProcessors(List<ThemePreProcessor> themePreProcessors) Setter for the list of theme pre processors
void	setWebappSourceDir(String webappSourceDir) Setter for the path to the webapp source

Methods inherited from class java.lang.Object

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

Constructor Detail

ThemeBuilder

public ThemeBuilder()

Method Detail

execute

public void execute()

Invoked from the spring context to execute the theme builder.

Invokes processing of the main theme builder functions, this includes:

• Copying assets from web source directory to the output directory
• Retrieving all theme and plugin directories, then setting up convenience maps for acquiring paths
• Iterating through each theme that should be built (those not excluded with getThemeExcludes())
• For each theme, invoking parent and additional directory overlays, then finally calling a helper method to process the theme assets

To just perform copying of the web assets, and parent/additional directory overlays, set the property isSkipThemeProcessing() to true

Specified by:

execute in interface org.kuali.common.util.execute.Executable

getThemeDirectories

protected List<File> getThemeDirectories()

Retrieves the directories that should be processed as themes.

By default all directories in '/themes' are included as theme directories. Additional directories can be included by setting getAdditionalThemeDirectories()

Returns:

list of file objects pointing to the theme directories

getPluginDirectories

protected List<File> getPluginDirectories()

Retrieves the directories that should be processed as plugins.

By default all directories in '/plugins' are included as plugins. Additional directories can be included by setting getAdditionalPluginDirectories()

Returns:

list of file objects pointing to the plugin directories

buildMappings

protected void buildMappings(List<File> themeDirectories,
                             List<File> pluginDirectories)
                      throws IOException

Builds convenience maps (theme name to path map, theme name to properties mapping, and plugin name to path mapping) for the given theme and plugin directories.

Parameters:

themeDirectories - list of theme directories to build mappings for

pluginDirectories - list of file directories to build mappings for

Throws:

IOException

orderThemesForBuilding

protected List<String> orderThemesForBuilding()

Builds a list containing theme names in the order for which they should be processed.

For the parent overlays to work correctly, the parent must be processed before the child. There can be multiple parents in the hierarchy, so here we go through and figure out the correct order

Returns:

list of ordered theme names

getAllThemeParents

protected List<String> getAllThemeParents(String themeName,
                                          List<String> themeParents)

Gets all parents (ancestors) for the given theme name.

The parent for a theme is determined by retrieving the theme's properties file, then pulling the property with key 'parent'. Then the properties file for the parent theme is pulled and check to see if it has a parent. So on until a theme is reached that does not have a parent

Parameters:

themeName - name of theme to retrieve parents for

themeParents - list of parents that have been previously found (used to find circular references)

Returns:

list of theme names that are parents to the given theme

copyParentThemeConfig

protected void copyParentThemeConfig(String themeName)

If the given theme has a parent, retrieve the theme properties (if exists) for the parent, then for each config property copy the parent value to the child theme properties if missing

Parameters:

themeName - name of the theme to pull parent config for and copy

processThemeAssets

protected void processThemeAssets(String themeName)

Performs the various steps to process the given theme

The theme is processed first by applying any configured ThemePreProcessor instances (such as less processing). Once the pre processors are applied, the CSS and JS post processors are then invoked to do the final processing After processing is complete the 'theme-derived.properties' file gets written to the theme directory, which contains all the properties for the theme (set, inherited, derived)

Parameters:

themeName - name of the theme to process

collectThemePluginDirs

protected Map<String,File> collectThemePluginDirs(Properties themeProperties)

Helper method that filters the list of all plugins and returns those that should be used with the theme

Which plugins to include for a theme can be configured using the pluginIncludes and pluginExlcudes property keys

Parameters:

themeProperties - properties file for the theme, used to retrieve the plugin configuration

Returns:

map containing the plugins for the theme, map key is the plugin name and map value gives the plugin directory

getThemeNamePathMapping

protected Map<String,String> getThemeNamePathMapping()

Map that associates theme names with their path, provided here for subclasses

Returns:

map of theme name/paths, map key is the theme name, map value is the theme path

getThemeNamePropertiesMapping

protected Map<String,Properties> getThemeNamePropertiesMapping()

Map that associates theme names with their properties, provided here for subclasses

Returns:

map of theme name/properties, map key is the theme name, map value is the properties object

getWebappSourceDir

public String getWebappSourceDir()

Absolute path to the directory that contains the web application source

Generally this is the base directory for the application/module, then /src/main/webapp

If you are using the maven plugin this can be set by the maven property webapp.source.dir

Returns:

path to webapp source directory

setWebappSourceDir

public void setWebappSourceDir(String webappSourceDir)

Setter for the path to the webapp source

Parameters:

webappSourceDir -

getThemeBuilderOutputDir

public String getThemeBuilderOutputDir()

Absolute path to the directory the theme builder should output content to

Generally this will be the output directory for the exploded war being created. However you can also choose to output to a temporary directory, then copy the assets over at a later phase

If you are using the maven plugin this can be set by the maven property theme.builder.output.dir

Returns:

path to the output directory

setThemeBuilderOutputDir

public void setThemeBuilderOutputDir(String themeBuilderOutputDir)

Setter for the path to the output directory

Parameters:

themeBuilderOutputDir -

getThemeExcludes

public List<String> getThemeExcludes()

List of theme names that should be excluded from theme processing

Directories for themes that are excluded will be copied to the output directory but no further processing will occur on that theme.

If your web application receives web overlays which include themes, they will already be processed. Processing them again will result in duplicate content. Therefore you should exclude these themes using this property

If you are using the maven plugin this can be set by the maven property theme.builder.excludes

Returns:

list of excluded theme names

setThemeExcludes

public void setThemeExcludes(List<String> themeExcludes)

Setter for the list of theme names to exclude from processing

Parameters:

themeExcludes -

setThemeExcludesStr

public void setThemeExcludesStr(String themeExcludes)

Convenience setter that takes a string and parses to populate the theme excludes list

Parameters:

themeExcludes - string containing theme names to exclude which are delimited using a comma

getAdditionalThemeDirectories

public List<String> getAdditionalThemeDirectories()

List of absolute paths to include as additional theme directories

By default all directories under the web root folder themes are included. Other web directories can be processed as themes by including their path in this list

If you are using the maven plugin this can be set by the maven property theme.builder.theme.adddirs

Returns:

list of paths for additional themes

setAdditionalThemeDirectories

public void setAdditionalThemeDirectories(List<String> additionalThemeDirectories)

Setter for the list of additional theme directory paths

Parameters:

additionalThemeDirectories -

setAdditionalThemeDirectoriesStr

public void setAdditionalThemeDirectoriesStr(String additionalThemeDirectories)

Convenience setter that takes a string and parses to populate the additional theme directories list

Parameters:

additionalThemeDirectories - string containing additional theme directories which are delimited using a comma

getAdditionalPluginDirectories

public List<String> getAdditionalPluginDirectories()

List of absolute paths to include as additional plugin directories

By default all directories under the web root folder plugins are included. Other web directories can be processed as plugins by including their path in this list

If you are using the maven plugin this can be set by the maven property theme.builder.plugin.adddirs

Returns:

list of paths for additional plugins

setAdditionalPluginDirectories

public void setAdditionalPluginDirectories(List<String> additionalPluginDirectories)

Setter for the list of additional plugin directory paths

Parameters:

additionalPluginDirectories -

setAdditionalPluginDirectoriesStr

public void setAdditionalPluginDirectoriesStr(String additionalPluginDirectories)

Convenience setter that takes a string and parses to populate the additional plugin directories list

Parameters:

additionalPluginDirectories - string containing additional plugin directories which are delimited using a comma

getProjectVersion

public String getProjectVersion()

Version for the project that will be used to stamp the minified file

In order to facilitate automatic downloads between project releases, the minified files are stamped with the version number.

If you are using the maven plugin this can be set by the maven property project.version

Returns:

version string for project

setProjectVersion

public void setProjectVersion(String projectVersion)

Setter for the project version

Parameters:

projectVersion -

getThemePreProcessors

public List<ThemePreProcessor> getThemePreProcessors()

List of ThemePreProcessor instances that should be applied to the themes

Returns:

list of pre processors to apply

setThemePreProcessors

public void setThemePreProcessors(List<ThemePreProcessor> themePreProcessors)

Setter for the list of theme pre processors

Parameters:

themePreProcessors -

isSkipThemeProcessing

public boolean isSkipThemeProcessing()

Indicates whether processing of the themes should be skipped

In development it can be useful to just update the output directory with the theme assets, and skip processing such as Less and minification (which can be time consuming). Setting this flag to true will skip processing of pre and post processors, just doing the overlay. By default this is false

Returns:

true if theme processing should be skipped, false if not

setSkipThemeProcessing

public void setSkipThemeProcessing(boolean skipThemeProcessing)

Setter to skip theme processing

Parameters:

skipThemeProcessing -