Overview
The main aim of the maven resource dependency plugin is reduce the amount of scripts and styles connections to the server when richfaces components are used in the appliction. By default RichFaces library loads scripts and styles for all components on the client. Resource Dependency plugin provide capabilities to generate a javascript and css style file which contains all necessary script and css only for the components which actually used within the application.
Note: this feature requires at least RichFaces 3.3.0.
How it all works
During richfaces library build we collect all information about scripts and css styles used in our components. We store this information in *.component-dependencies.xml files. These files are saved in the META-INF dirs in the next format:
<components>
<namespace> http://foourl.org/foo</namespace>
<component>
< name>foo</name>
<scripts>
<script >path/to/the/foo.js</script>
. . . other script declaration
</scripts>
<styles>
<style> path/to/the/foo.cs</style>
. . . other style declaration
</styles>
<component>
... other component declaration
<components>
... other components declaration
First we should configure our plugin in the application main POM file and run build. During building plugin find all *.component-dependencies.xml files in the project dependencies and classpath of the application, collect information from it about components resources, then scan application *.xhtml files find actually used components and aggregates needed js, xcss files.
Plugin configuration
Plugin is used during process-resources phase. It has one goal assembly-resources. To use the plugin define in your POM or parent POM:
<project>
. . .
<build>
<plugins>
<plugin>
<artifactId>maven-resource-dependency-plugin</artifactId>
<groupId>org.richfaces.cdk</groupId>
<version>3.3.1-SNAPSHOT</version>
. . .
</plugin>
<plugins>
</build>
. . .
</project>
Plugin definition with all available configuration properties:
<project>
...
<build>
<plugin>
<artifactId>maven-resource-dependency-plugin</artifactId>
<groupId>org.richfaces.cdk</groupId>
<version>3.3.1-SNAPSHOT</version>
<configuration>
<webSourceDirectory>
path/to/the/web/files/dir
</webSourceDirectory>
<outputResourceDirectory>
path/to/the/aggregated/resources/dir
</outputResourceDirectory>
<scriptFilePath>generated_js_file pathname string </scriptFilePath>
<beforeScriptIncludes>
<beforeScriptInclude>
path/to/script/before.js
</beforeScriptInclude>
. . . other includes
</beforeScriptIncludes>
<afterScriptIncludes>
<afterScriptInclude>
path/to/script/after.js
</afterScriptInclude>
. . . other includes
</afterScriptIncludes>
<styleFilePath> generated_xcss_file pathname string </styleFilePath>
<beforeStyleIncludes>
<beforeStyleInclude>
path/to/style/before.xss
</beforeStyleInclude>
. . . other includes
</beforeStyleIncludes>
<afterStyleIncludes>
<afterStyleInclude>
path/to/style/after.xcss
</afterStyleInclude>
. . . other style includes
</afterStyleIncludes>
<scriptIncludes>
<scriptInclude>
included_script_ filename or filenames pattern
</scriptInclude>
. . . other includes
</scriptIncludes>
<scriptExcludes>
<scriptExclude>
excluded_script_ filename or filenames pattern
</scriptExclude>
. . . other excludes
</scriptExcludes>
<styleIncludes>
<styleInclude>
included_style _ filename or filenames pattern
</styleInclude>
. . . other includes
</styleIncludes>
<styleExcludes>
<styleExclude>
excluded_style _ filename or filenames pattern
</styleExclude>
. . . other excludes
</styleExcludes>
<namespaceIncludes>
<namespaceInclude>
included namespace
</namespaceInclude>
. . . other includes
</namespaceIncludes>
<namespaceExcludes>
<namespaceExclude>
excluded namespace
</namespaceExclude>
. . . other excludes
</namespaceExcludes>
<componentIncludes>
<componentInclude>
included component
</componentInclude>
. . . other includes
</componentIncludes>
<componentExcludes>
<componentExclude>
excluded component
</componentExclude>
. . . other excludes
</componentExcludes>
<xhtmlIncludes>
<xhtmlnclude>
included xhtml
</xhtmlInclude>
. . . other includes
</xhtmlIncludes>
<xhtmlExcludes>
<xhtmlExclude>
excluded xhtml
</xhtmltExclude>
. . . other excludes
</xhtmlExcludes>
<xmlConfigPatterns>
<xmlConfigPattern>
xml config pattern
</xmlConfigPattern>
other xml config patterns
</xmlConfigPatterns>
</configuration>
<executions>
<execution>
<phase>process-resources</phase>
<goals>
<goal>assembly-resources</goal>
</goals>
</execution>
</executions>
</plugin>
. . .
</build>
</project>
You could specify next configuration properties:
Path to the xhtml files. Default value is${basedir}/src/main/webapp
<webSourceDirectory> path/to/the/web/files/dir</webSourceDirectory>
Result script pathname string. Default is custom-dependencies.js
<scriptFilePath> generated_js_file_name pathname string </scriptFilePath>
Generated script/style output directory. Default is${basedir}/target/generated-resources
<outputResourceDirectory>
path/to/the/aggregated/resources/dir
</outputResourceDirectory>
User javascript which will be included in the result main js file before components specific scripts and frameworks
<beforeScriptIncludes>
<beforeScriptInclude> path/to/script/before.js</beforeScriptInclude>
</beforeScriptIncludes>
User javascript which will be included in the result main js file after components specific scripts and frameworks
<afterScriptIncludes>
<afterScriptInclude> path/to/script/after.js</afterScriptInclude>
</afterScriptIncludes>
Result style file pathname string. Default is custom-dependencies.xcss
<styleFilePath> generated_xcss_file_name </styleFilePath>
User styles (css or xcss) which will be included in the result main styles xcss file before components specific styles
<beforeStyleIncludes>
<beforeStyleInclude> path/to/style/before.xss </beforeStyleInclude>
</beforeStyleIncludes>
User styles which will be included in the result main styles xcss file after components specific styles
<afterStyleIncludes>
<afterStyleInclude> path/to/style/after.css</afterStyleInclude>
</afterStyleIncludes>
NOTE: Path to the after/before scripts/styles should be relative to src/main/scripts, src/main/resources or web application source dirs.
Component depended js files which will be included/excluded in the main generated script. By default all components depended js files are included. User could specify relative paths to this files or path patterns.
<scriptIncludes>
<scriptInclude>
included_script_ filename or filenames pattern
</scriptInclude>
. . . other includes
</scriptIncludes>
<scriptExcludes>
<scriptExclude>
excluded_script_ filename or filenames pattern
</scriptExclude>
. . . other excludes
</scriptExcludes>
The same for the xcss files.
<styleIncludes>
<styleInclude>
included_style _ filename or filenames pattern
</styleInclude>
. . . other includes
</styleIncludes>
<styleExcludes>
<styleExclude>
excluded_style _ filename or filenames pattern
</styleExclude>
. . . other excludes
</styleExcludes>
Define styles/scripts from components with defined namespace included or excluded from common generated scripts/styles files. User could define namespaces or namespace patterns. By default all components with namespaces found in *.component-dependencies.xml are processed.
<namespaceIncludes>
<namespaceInclude>
included namespace
</namespaceInclude>
. . . other includes
</namespaceIncludes>
<namespaceExcludes>
<namespaceExclude>
excluded namespace
</namespaceExclude>
. . . other excludes
</namespaceExcludes>
Define components name which scripts or styles will be included or excluded to the common generated styles, scripts files. User could define components full names or names patterns. The pattern may contain two special characters:
1. '*' means zero or more characters;
2.'?' means one and only one character;
By default all components found in the *.component-dependencies.xml are processed.
<componentIncludes>
<componentInclude>
included component
</componentInclude>
. . . other includes
</componentIncludes>
<componentExcludes>
<componentExclude>
excluded component
</componentExclude>
. . . other excludes
</componentExcludes>
Define what xhtml files should be processed by resource dependency plugin. By default all xhtml found in the webapp dir are processed. User could define relative paths to the xhtml files or paths patterns.
<xhtmlIncludes>
<xhtmlnclude>
included xhtml
</xhtmlInclude>
. . . other includes
</xhtmlIncludes>
<xhtmlExcludes>
<xhtmlExclude>
excluded xhtml
</xhtmltExclude>
. . . other excludes
</xhtmlExcludes>
Define components dependencies xml file path pattern where plugin should collect information about all components resources (see How it all works section for the file format details). By defaut plugin looked for files satisfied **/*.component-dependencies.xml pattern.
<xmlConfigPatterns>
<xmlConfigPattern>
xml config pattern
</xmlConfigPattern>
other xml config patterns
</xmlConfigPatterns>
After all configurations run full application build or goal mvn resource-dependency:assembly-resources.
Using generated resources:
Let’s assume what we have generated custom-dependencies.js and custom-dependencies.xcss and want to use it right now. First off all put generated files in the application classpath e.g WEB-INF/classes. Create resources-config.xml file
<resource-config>
<resource>
<name>css/custom-dependencies.xcss</name>
//path to the generated xcss file in the classpath
<path>custom-dependencies.xcss</path>
</resource>
<resource>
<name>scripts/custom-dependencies.js</name>
//path to the generated js file in the classpath
<path>custom-dependencies.js</path>
</resource>
</resource-config>
and put it in the /WEB-INF/classes/META-INF. Set loadScriptStrategy and loadStyleStrategy to NONE in the application web.xml file:
<context-param>
<param-name>org.richfaces.LoadStyleStrategy</param-name>
<param-value>NONE</param-value>
</context-param>
<context-param>
<param-name>org.richfaces.LoadScriptStrategy</param-name>
<param-value>NONE </param-value>
</context-param>
Set uri prefix param to allow our filter load generated resources
<context-param>
<param-name>org.ajax4jsf.RESOURCE_URI_PREFIX</param-name>
<param-value>rfRes/</param-value>
</context-param>
Finally add to the html head:
<head>
<script src="#{facesContext.externalContext.requestContextPath}/faces/rfRes/scripts/custom-dependencies.js" type="text/javascript"/>
<link rel="stylesheet" href="#{facesContext.externalContext.requestContextPath}/faces/rfRes/css/custom-dependencies.xcss" type="text/css" />
</head>
Note that names of the resources have been defined in resources-config.xml above.
Start application.
Comments