Package org.kuali.rice.krad.theme

Class ThemeBuilder

java.lang.Object
org.kuali.rice.krad.theme.ThemeBuilder
All Implemented Interfaces:
Runnable
public class ThemeBuilder extends Object implements Runnable
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 org.kuali.rice.krad.uif.view.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:

  • Constructor Details

    • ThemeBuilder

      public ThemeBuilder()

  • Method Details

    • run

      public void run()
      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:
      run in interface Runnable

    • 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 -