<!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
-->
 
 
#Navigation Top
 [&lt;&lt;Back to the Start Page](./index.html)
 or
 [On to the Openwebbeans Spring Guide &gt;&gt;](./owbSpring.html)
 
#General information
 This page covers the general installation and integration process, it does not
 go into the details of the configuration.
 The section covers the setup via download or custom build. If you need configuration detail info
 or information on how to setup your ide correctly please follow the links in the navigation to
 the correct section.
 
#Setup overview
## General Setup Information
 
 Ext-Scripting has a complete appendix list over all [configuration and
 setup](./configentries.html) options as well as [example configurations](./exampleconfig.html).
 For a quick overview please visit the following links. If you need detailed
 setup information, then read further on.
 
 
## Links
 
<ul><a href="./setupSteps.html">Appendix: Configuration Setup Step Overview</a> </ul>
<ul><a href="./exampleconfig.html">Appendix: Example Configurations</a> </ul>
<ul><a href="./configentries.html">Appendix: List of Configuration Options</a> </ul>
 
 
 
#Checklist
 
 For a short checklist of setup steps please follow [ this link](./setupSteps.html). For a detailed
 setup guide, please continue reading.
 
 
#Download
 
 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](./download.html).
 
 
                Once you downloaded the necessary artifacts please check the [manual setup section](#Manual_Setup) of this document.
 
 
#Checkout and Build
 
 While Ext-Scripting is already in stable state, 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
 ](http://svn.apache.org/repos/asf/myfaces/extensions/scripting/trunk)
 via a subversion client.
 
 
 Make sure you have following requirements fulfilled before checking out:
 
<ul>
   <li>A valid Subversion client</li>
   <li>A valid Servlet 3.0+ container</li>
   <li>Java 6 or higher</li>
   <li>Maven 2.0.9 or higher</li>
</ul>
 
 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
 &lt;checkoutDir&gt;/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)
 
 
#Setup of Ext-Scripting
## Requirements
 
 Before setting up Ext-Scripting for your project make sure following requirements are met.
 
<ul>
   <li>JAVA_HOME points towards a valid Java SDK (JRE is not sufficient)</li>
   <li>You know how to create and deploy a web application within your preferred setup (command line,
       ide)
   </li>
</ul>
 
## Setup
 
 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.
 
<ul>
   <li>A valid
       <b>MyFaces</b>
       installation has to be present
   </li>
   <li>Ext-Scripting and its dependencies has to be added to the MyFaces installation</li>
   <li>The paths to the scripts have to be present (see also below)</li>
</ul>
 
## Preparations via Apache Maven 2
 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
 
 
 MyFaces 2.1+
         <dependency>
            <groupId>org.apache.myfaces.extensions.scripting</groupId>
            <artifactId>extscript-myfaces20-bundle</artifactId>
            <version>1.0.5</version>
         </dependency>
 Additional language libraries
 
 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>
                  
 For Groovy support (version number may vary)
    <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>
                    
 For Scala support.
 
 For OpenWebbeans support please add following entry:
                         <dependency>
                            <groupId>org.apache.myfaces.extensions.scripting</groupId>
                            <artifactId>extscript-cdi</artifactId>
                            <version>1.0.5</version>
                        </dependency>
                     
 
 
## Manual Setup
 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:
<ul>
   <li>&lt;yourbuilderoot&gt;/extscript-bundles/extscript-myfaces20-bundle/target/extscript-myfaces20-bundle-1.0.3-SNAPSHOT.jar</li>
</ul>
 The additional language jars for the respective language
 can be obtained from the language distributions.
 
 
 However following dependencies must be met so that Ext-Scripting can work:
<ul>
   <li>commons-beanutils.jar version 1.8.3 or above</li>
   <li>commons-codec.jar version 1.3 or above</li>
   <li>commons-collections.jar version 3.2 or above</li>
   <li>commons-io.jar version 1.4 or above</li>
   <li>commons-logging.jar version 1.1.1 or above</li>
   <li>commons-digester version 1.8 or above</li>
   <li>groovy-all.jar version 1.7.2 or above</li>
   <li>scala-compiler.jar version 2.10.0-M2 or above</li>
   <li>scala-library.jar version 2.10.0-M2 or above</li>
</ul>
 For your convenience an empty webapp is provided within the [download page](./download.html)
 which delivers all needed dependencies to get you kickstarted.
 
 After having done that you are ready to setup the rest of the Ext-Scripting configuration manually as
 described in the section blow
 
 
## Preparing the Necessary web.xml Entries
 Most important step
 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>
 Additional Optional Steps
 Ext-Scripting exposes a number configuration parameters which can be set via context parameters in
 your web.xml
 
 Adjust the web.xml Root source paths.
 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:
 
         <webapp>/WEB-INF/groovy                    
                    
 
 as root location for Groovy files
 
         <webapp>/WEB-INF/java
                    
 
 as root location for java files.
 
 
 Following image displays the default locations:
 ![](images/ext-default-file.jpg)
 
 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>
    <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.scala.LOADER_PATHS</param-name>
        <param-value>
            <some project path>/src/main/webapp/WEB-INF/scala
        </param-value>
    </context-param>
                    
<ul>
   <li>
       <b>org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS</b>
       can be a comma separated list of paths which point to the actual Groovy sources.
   </li>
   <li>
       <b>org.apache.myfaces.extensions.scripting.java.LOADER_PATHS</b>
       does the same for Java sources..
   </li>
   <li>
       <b>org.apache.myfaces.extensions.scripting.scala.LOADER_PATHS</b>
       does the same for Java Scala (Ext-Scripting 1.0.3 or newer)...
   </li>
</ul>
 Dynamic resource reloading
 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.
 
 
<ul>
   <li>
       <b>org.apache.myfaces.extensions.scripting.resources.LOADER_PATHS</b>
       This parameter points to the root of your dynamic resources, usually the same dir
                       as the root of your web application.
   </li>
   <li><b>facelets.RESOURCE_RESOLVER</b> also needs to be set to <b>org.apache.myfaces.extensions.scripting.jsf.facelet.ReroutingResourceResolver</b> if
   you want dynamic Facelet reloading enabled</li>
</ul>
    <!-- ======================================================================================
             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.jsf.facelet.ReroutingResourceResolver</param-value>
     </context-param>
            
 
 This sums up the quick install and setup guide, if you want more detailed setup examples and
 additional configuration entries
 go to our [Example Configurations](./exampleconfig.html) page, which shows
 a set of different configurations.
 Package Whitelisting
 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 enable 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>
                 
 
## Preparations for Openwebbeans
 From a Ext-Scripting perspective, dropping the extscript-cdi war into your libraries dir
 is enough to enable Openwebbeans support, however you have to have Openwebbeans installed properly
 which means you have to add a beans.xml file to your META-INF directory and you have to add following
 entry to your web.xml file:
    <!-- ========================================================================================
                    Optional: enable only if you have openwebbeans working
    ========================================================================================== -->
    <listener>
        <listener-class>org.apache.webbeans.servlet.WebBeansConfigurationListener</listener-class>
    </listener>
                    
 
 
 
#Navigation Bottom
 [&lt;&lt;Back to the Start Page](./index.html)
 or
 [On to the Openwebbeans Spring Guide &gt;&gt;](./owbSpring.html)