Ext-Scripting has a complete appendix list over all configuration and setup options as well as example configurations. For a quick overview please visit the following links. If you need detailed setup information, then read further on.
For a short checklist of setup steps please follow this link. For a detailed setup guide, please continue reading.
With version 1.0.x Ext-Scripting provides all necessary artifacts as download artifacts to get quickly started. A kickstart project is provided which can be used as shell for your own projects.
For Download information please visit the download page.
Once you downloaded the necessary artifacts please check the manual setup section of this document.
While Ext-Scripting is already in stable stage, the best way to get started is probably to checkout and build ext-scripting yourself from the latest codebase. All other installation steps will have this step as prerequisite if you want to use the latest codebase instead of one of the beta releases! First you have to check out the latest codebase from http://svn.apache.org/repos/asf/myfaces/extensions/scripting/trunk via a subversion client.
Make sure you have following requirements fulfilled before checking out:
- A valid Subversion client
- A valid servlet 3.0+ container
- Java 6 or higher
- Maven 2.0.9 or higher
After checkout, a full build can be obtained from the root directory of your checkout via mvn clean install.
Once finished, a valid build is installed, which can be used further on. Additionally you can find two blueprint projects which you can use as starting points for your own projects under <checkoutDir>/examples , which can be started viamvn jetty:run-exploded. The now generated files either can be used to be included in a maven install or be included manually (please go to the next section for detailed setup instructions)
Before setting up Ext-Scripting for your project make sure following requirements are met.
- JAVA_HOME points towards a valid Java SDK (JRE is not sufficient)
- You know how to create and deploy a web application within your preferred setup (command line, ide)
While one of the aims of Ext-Scripting was to enable an easy setup, for now it was not entirely possible for now to get a plug and play configuration. Several configuration steps have to be performed.
- A valid MyFaces installation has to be present
- Ext-Scripting and its dependencies has to be added to the MyFaces installation
- The paths to the scripts have to be present (see also below)
The easiest way once Extension scripting is compiled is probably a setup via Apache Maven 2
Depending on your configuration and preferred JDK version you can add following entries to your Maven pom.xml to enable Ext-Scripting
<dependency> <groupId>org.apache.myfaces.extensions.scripting</groupId> <artifactId>extscript-myfaces20-bundle</artifactId> <version>1.0.3</version> </dependency>
You have to add following artifacts to your dependency list for additional language support
<dependency> <groupId>org.codehaus.groovy</groupId> <artifactId>groovy-all</artifactId> <version>1.7.1</version> </dependency>
<dependency> <groupId>org.scala-lang</groupId> <artifactId>scala-library</artifactId> <version>2.9.1</version> </dependency> <dependency> <groupId>org.scala-lang</groupId> <artifactId>scala-compiler</artifactId> <version>2.9.1</version> </dependency>
If you do not like Maven or you prefer a manual setup, Ext-Scripting provides convenient meta bundles. A manual setup comes down to the task of adding the appropriate meta bundle (extscript-myfaces20-bundle) to your WEB-INF/lib directory and adding a groovy-all.jar as additional dependency. For Scala support you have to add scala-library.jar and scala-compiler.jar to your WEB-INFU/lib. Note not adding those additional libs automatically will disable the respective language support.
you can obtain both bundle jars after the build from:
After having done that you are ready to setup the rest of the Ext-Scripting configuration manually as described in the section blow
To enable Ext-Scripting you also have to add several entries to your web.xml file.
First a context param has to be set which attaches the Ext-Scripting plugins to MyFaces
<context-param> <description> Enables our scripting engine support plugins </description> <param-name>org.apache.myfaces.FACES_INIT_PLUGINS</param-name> <param-value> org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader </param-value> </context-param>
Ext-Scripting exposes a number configuration parameters which can be set via context parameters in your web.xml
Since the goal of Ext-Scripting is to provide scriptability to a running web application, it has to know where to find the sources. For this, a default location has been chosen according to the standards set by the Mojarra Groovy Extension.
The location looks like:
as root location for Groovy files
as root location for java files.
Following image displays the default locations:
However in a normal development scenario, it is often undesirable to have the files located in a deployment location, and a pointer mechanism towards the actual source locations would be more desirable. To provide such a mechanism, Ext-Scripting allows two optional web.xml context parameters, which allow the rerouting of source locations of the supported languages!
<context-param> <description>Additional comma separated loader paths to allow direct editing on the sources directory instead of the deployment dir </description> <param-name>org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS</param-name> <param-value> <some project path>/src/main/webapp/WEB-INF/groovy </param-value> </context-param> <context-param> <description>Additional comma separated loader paths to allow direct editing on the sources directory instead of the deployment dir </description> <param-name>org.apache.myfaces.extensions.scripting.java.LOADER_PATHS</param-name> <param-value> <some project path>/src/main/webapp/WEB-INF/java </param-value> </context-param>
- org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS can be a comma separated list of paths which point to the actual Groovy sources.
- org.apache.myfaces.extensions.scripting.java.LOADER_PATHS does the same for Java sources..
- org.apache.myfaces.extensions.scripting.scala.LOADER_PATHS does the same for Java Scala (Ext-Scripting 1.0.3 or newer)...
additionally Ext-Scripting allows the reloading of dynamic web resources like facelets templates images css files etc... An additional config param is available to enable this functionality.
- org.apache.myfaces.extensions.scripting.resources.LOADER_PATHS This parameter points to the root of your dynamic resources, usually the same dir as the root of your web application.
- facelets.RESOURCE_RESOLVER also needs to be set to org.apache.myfaces.extensions.scripting.facelet.ReroutingResourceResolver if you want dynamic facelet reloading enabled
<!-- ====================================================================================== Optional Loader Paths for resource files ====================================================================================== --> <context-param> <description>resource paths for our custom JSF2 resource resolver</description> <param-name>org.apache.myfaces.extensions.scripting.resources.LOADER_PATHS</param-name> <param-value> ~/extensions-scripting3/examples/myfaces20-example/src/main/webapp </param-value> </context-param> <!-- ====================================================================================== Optional: Tell Facelets to load the resources from your source dir ====================================================================================== --> <context-param> <description>a redirecting Facelet resource resolver which allows to pick up templates and resources from our source dir </description> <param-name>facelets.RESOURCE_RESOLVER</param-name> <param-value>org.apache.myfaces.extensions.scripting.facelet.ReroutingResourceResolver</param-value> </context-param>
The last possible config entry is the ability to whitelist packages. If you have set this option then only whitelisted packages will be picked up for dynamic recompilation
With this option you can point your source dir to the normal compile source and mark special packages as dynamic (to isolate the dynamic part from the rest)To enalbe this option, add following entry to your web.xml:
<!-- ====================================================================================== Optional: Whitelist of root packages where your sources should come from ====================================================================================== --> <context-param> <description>a comma separated whitelist of root packages which are compiled those and nothing else will be compiled during all compile stages, all other files stay permanently as they are </description> <param-name>org.apache.myfaces.extensions.scripting.PGK_WHITELIST</param-name> <param-value>org.apache.myfaces.groovyloader.blog,org.apache.myfaces.javaloader.blog</param-value> </context-param>