Author: mrdon
Date: Sun Nov 27 19:35:01 2005
New Revision: 349353
URL: http://svn.apache.org/viewcvs?rev=349353&view=rev
Log:
Adding a user guide, more overview information, more documentation links
Added:
struts/scripting/trunk/xdocs/user-guide.xml
Modified:
struts/scripting/trunk/xdocs/index.xml
struts/scripting/trunk/xdocs/navigation.xml
Modified: struts/scripting/trunk/xdocs/index.xml
URL:
http://svn.apache.org/viewcvs/struts/scripting/trunk/xdocs/index.xml?rev=349353&r1=349352&r2=349353&view=diff
==============================================================================
--- struts/scripting/trunk/xdocs/index.xml (original)
+++ struts/scripting/trunk/xdocs/index.xml Sun Nov 27 19:35:01 2005
@@ -30,9 +30,20 @@
to allow scripts to be written in any language BSF supports like Perl,
Python, Ruby, JavaScript, BeanShell, and even VBScript.
</p>
- </section>
+ <p>
+ Struts Scripting allows an application to be developed rapidly with
+ the quick development cycle (edit file -> refresh browser) that one
+ would expect in a scripting environment. Furthermore, it enables other
+ non-Java trained members of a development team, such as web designers
who
+ may have a scripting background, to be more involved, leaving the Java
+ developers to create the reusable services the Struts actions will
interact
+ with. Finally, when used with Java-like languages such as <a
+ href="http://www.beanshell.org";>BeanShell</a>, applications can
quickly be
+ stood up, then later the Struts action scripts can be migrated to Java
for
+ better performance.
+ </p>
- <section name="Features">
+ <subsection name="Features">
<a name="features"/>
<ul>
<li>Implement Actions with JavaScript, BeanShell, etc.</li>
@@ -40,106 +51,20 @@
<li>Scripts cached in memory on first use</li>
<li>Ability to pass parameters to script through Struts
config</li>
</ul>
- </section>
- <section name="What's New">
- <a name="new"/>
- <subsection name="0.4 - April 26, 2004">
- <ul>
- <li>Updated Beanshell to 1.3</li>
- <li>Updated Jakarta BSF to 2.3.0</li>
- <li>Changed default engine mappings so if no properties file
is specified, uses default BSF mappings</li>
- <li>Fixed example bugs</li>
- <li>Fixed StrutsInfo to correctly return action forward object
if specified</li>
- <li>Fixed bug in RequestToVariableFilter to correct check for
pre-existing scripting variable using the same name as a request parameter.</li>
- </ul>
- </subsection>
- <subsection name="0.3 - June 6, 2003">
- <ul>
- <li>Reorganized how Struts objects are presented</li>
- <li>Added a configurable filter system to easily manipulate
the context</li>
- <li>Added a filter that adds request parameters as
variables</li>
- <li>Added ability to pass parameters to scripts in the action
definition</li>
- <li>Added and updated Javadocs, code cleanups,
documentation</li>
- </ul>
- </subsection>
- <subsection name="0.2 - Unreleased">
- <ul>
- <li>Added the ability to configure other BSF engines</li>
- </ul>
- </subsection>
- <subsection name="0.1 - Unreleased">
- <ul>
- <li>Working Action implementation with hardcoded BeanShell
support</li>
- <li>Rewrote struts-example to demonstrate usage</li>
- </ul>
- </subsection>
- </section>
- <section name="Usage Notes">
- <a name="usage"/>
- <p>To determine what script will be executed, the "parameter"
attribute of
- the action mapping should contain the name of the script relative to
- the web application root directory (i.e. http://server/app). In the
place of
- the traditional Action implementation, use the value
<code>org.apache.struts.scripting.ScriptAction</code>.
- For example:
- </p>
-<pre>
- <action path="/logoff"
- type="org.apache.struts.scripting.ScriptAction"
- parameter="/WEB-INF/scripts/Logoff.bsh">
- <forward name="success" path="/index.jsp"/>
- </action>
-</pre>
- <p>In addition to specifying the script file, the "parameter"
attribute can
- also contain parameters that will be passed to the script in the form
of
- pre-defined variables. The format follows the URL format:</p>
-<pre>
-
parameter="/path/file.bsh?PARAMETER_NAME=PARAMETER_VALUE[&amp;PARAMETER_NAME=PARAMETER_VALUE..]"
-</pre>
- <p>One example of how passed parameters can be used is have one script
file
- handle multiple actions.</p>
- <p>
- Before the script completes, the next ActionForward needs to be
- specified. This can be done one of two ways:
- </p>
- <ol>
- <li>Set <code>struts.forwardName</code> to the name of the
forward</li>
- <li>Set <code>struts.forward</code> to the actual ActionForward
object
- </li>
- </ol>
- <p>A number of pre-defined variables are available to the script:</p>
- <ul>
- <li><code>request</code> - The HTTP request</li>
- <li><code>response</code> - The HTTP response</li>
- <li><code>session</code> - The session</li>
- <li><code>application</code> - The servlet context</li>
- <li><code>struts</code> - A grouping of all Struts-related
objects</li>
- <li><code>log</code> - A logging instance</li>
- </ul>
- <p>
- You can add your own variables by creating a BSFManagerFilter and
- configuring it in struts-scripting.properties:
- </p>
- <ul>
-
<li><code>struts-scripting.filters.FILTER_NAME.class=FILTER_CLASS</code> - The
- class implementing BSFManagerFilter where FILTER_NAME is the
name you
- are calling the filter.</li>
-
<li><code>struts-scripting.filters.FILTER_NAME.PROPERTY_NAME=PROPERTY_VALUE</code>
- - A property to be used by the filter.</li>
- </ul>
- <p>
- To use other scripting engines other than BeanShell, create a file
called
- <code>struts-scripting.properties</code> and add two properties for
each engine:
- </p>
- <ul>
- <li><code>struts-scripting.engine.ENGINE_NAME.class</code> - The
class of the BSF
- engine where ENGINE_NAME is the name you are calling the
engine.</li>
- <li><code>struts-scripting.engine.ENGINE_NAME.extensions</code> - A
comma-delimited
- list of file extensions that will be used to identify the
engine to use
- to execute the script.</li>
- </ul>
- </section>
-
-
- </body>
+ </subsection>
+ <subsection name="Documentation">
+ <a name="documentation"/>
+ <ul>
+ <li><a href="user-guide.html">User Guide</a> - Covers installation
and usage</li>
+ <li><a href="apidocs/index.html">Javadocs</a> - Includes
+ <a
href="apidocs/org/apache/struts/scripting/StrutsInfo.html"><code>struts</code></a>
variable and
+ <a
href="apidocs/org/apache/struts/scripting/BSFManagerFilter.html">Filter</a>
API's.</li>
+ <li><a
href="http://svn.apache.org/viewcvs.cgi/struts/scripting/trunk/src/struts-example/";>Struts
+ Mailreader</a> - A rewrite of the Struts 1.2.8 Mailreader
example application using Struts Scripting
+ and <a href="http://www.beanshell.org";>BeanShell</a></li>
+ </ul>
+ </subsection>
+ </section>
+ </body>
</document>
Modified: struts/scripting/trunk/xdocs/navigation.xml
URL:
http://svn.apache.org/viewcvs/struts/scripting/trunk/xdocs/navigation.xml?rev=349353&r1=349352&r2=349353&view=diff
==============================================================================
--- struts/scripting/trunk/xdocs/navigation.xml (original)
+++ struts/scripting/trunk/xdocs/navigation.xml Sun Nov 27 19:35:01 2005
@@ -4,8 +4,9 @@
<body>
<menu name="Struts BSF Scripting">
<item name="Welcome" href="index.html"/>
- <item name="What's New" href="index.html#What_s_New"/>
- <item name="Usage" href="index.html#Usage_Notes"/>
+ <item name="Features" href="index.html#features"/>
+ <item name="Documentation" href="index.html#documentation"/>
+ <item name="User Guide" href="user-guide.html"/>
<item name="Download (Sourceforge)"
href="http://sourceforge.net/project/showfiles.php?group_id=49385&package_id=84734"/>
</menu>
Added: struts/scripting/trunk/xdocs/user-guide.xml
URL:
http://svn.apache.org/viewcvs/struts/scripting/trunk/xdocs/user-guide.xml?rev=349353&view=auto
==============================================================================
--- struts/scripting/trunk/xdocs/user-guide.xml (added)
+++ struts/scripting/trunk/xdocs/user-guide.xml Sun Nov 27 19:35:01 2005
@@ -0,0 +1,165 @@
+<?xml version="1.0"?>
+<!--
+Copyright 1999-2005 The Apache Software Foundation
+Licensed 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.
+-->
+<!--
+// ======================================================================== 78
+-->
+<document>
+ <properties>
+ <title>Struts Scripting User Guide</title>
+ </properties>
+
+ <body>
+ <section name="Struts Scripting User Guide">
+ <a name="overview"/>
+ <p>The entire Struts Scripting project is only a few classes, since most
of
+ the heavy lifting is done by the
+ <a href="http://jakarta.apache.org/bsf";>Beans Scripting Framework</a>
+ and the scripting engines themselves. Therefore, there are only a few
steps
+ you'll need to take in order to sucessfully install and use Struts
Scripting.
+ </p>
+ <ul>
+ <li><a href="#installation">Installation</a></li>
+ <li><a href="#usage">Usage</a></li>
+ </ul>
+ <subsection name="Installation">
+ <a name="installation"/>
+ <p>After downloading the Struts Scripting distribution, copy the
Struts
+ Scripting jar, <code>struts-scripting-1.0.jar</code>, to your
application's
+ libraries directory. When deployed, this directory will be
<code>WEB-INF/lib</code>.
+ </p>
+ <p>Next, choose which scripting engine you want to use. BSF ships
with knowledge about
+ the following languages and script extensions:</p>
+ <table>
+ <caption>
+ <strong>BSF-supported languages and extentions</strong>
+ </caption>
+ <thead>
+ <tr>
+ <td>javascript (js)</td>
+ <td>jacl (jacl)</td>
+ <td>netrexx (nrx)</td>
+ </tr>
+ <tr>
+ <td>java (java)</td>
+ <td>javaclass (class)</td>
+ <td>bml (bml)</td>
+ </tr>
+ <tr>
+ <td>vbscript (vbs)</td>
+ <td>jscript (jss)</td>
+ <td>perlscript (pls)</td>
+ </tr>
+ <tr>
+ <td>perl (pl)</td>
+ <td>jpython (py)</td>
+ <td>jython (py)</td>
+ </tr>
+ <tr>
+ <td>lotusscript (lss)</td>
+ <td>xslt (xslt)</td>
+ <td>pnuts (pnut)</td>
+ </tr>
+ <tr>
+ <td>beanbasic (bb)</td>
+ <td>beanshell (bsh)</td>
+ <td>ruby (rb)</td>
+ </tr>
+ <tr>
+ <td>judoscript (judo, jud)</td>
+ </tr>
+ </thead>
+ </table>
+ <p>Once you have picked a language, you need to download its libraries
and install it
+ into your application, which usually means copying its jar files into
the same location
+ you copied the Struts Scripting jar. If you are not sure, we
recommend BeanShell
+ which ships with Struts Scripting, as it features a very similar
Java-like syntax.
+ </p>
+ <p><i>Optional</i>: If you don't see your desired language that claims
to support BSF,
+ or their BSF engine has changed from what BSF expects, you can
manually define BSF
+ engines and have them loaded by Struts Scripting.
+ Create a file called
+ <code>struts-scripting.properties</code> and add two properties for
each engine:
+ </p>
+ <ul>
+ <li><code>struts-scripting.engine.ENGINE_NAME.class</code> - The
class of the BSF
+ engine where ENGINE_NAME is the name you are calling the
engine.</li>
+ <li><code>struts-scripting.engine.ENGINE_NAME.extensions</code> - A
comma-delimited
+ list of file extensions that will be used to identify the
engine to use
+ to execute the script.</li>
+ </ul>
+ <p>The <code>struts-scripting.properties</code> should then stored in
a directory
+ accessible to the classloader, usually <code>WEB-INF/classes</code>.
+ </p>
+ </subsection>
+ <subsection name="Usage">
+ <a name="usage"/>
+ <p>To determine what script will be executed, the "parameter"
attribute of
+ the action mapping should contain the name of the script relative to
+ the web application root directory (i.e. http://server/app). In the
place of
+ the traditional Action implementation, use the value
<code>org.apache.struts.scripting.ScriptAction</code>.
+ For example:
+ </p>
+<pre>
+ <action path="/logoff"
+ type="org.apache.struts.scripting.ScriptAction"
+ parameter="/WEB-INF/scripts/Logoff.bsh">
+ <forward name="success" path="/index.jsp"/>
+ </action>
+</pre>
+ <p>In addition to specifying the script file, the "parameter"
attribute can
+ also contain parameters that will be passed to the script in the form
of
+ pre-defined variables. The format follows the URL format:</p>
+<pre>
+
parameter="/path/file.bsh?PARAMETER_NAME=PARAMETER_VALUE[&amp;PARAMETER_NAME=PARAMETER_VALUE..]"
+</pre>
+ <p>One example of how passed parameters can be used is have one script
file
+ handle multiple actions.</p>
+ <p>
+ Before the script completes, the next ActionForward needs to be
+ specified. This can be done one of two ways:
+ </p>
+ <ol>
+ <li>Set <code>struts.forwardName</code> to the name of the
forward</li>
+ <li>Set <code>struts.forward</code> to the actual ActionForward
object
+ </li>
+ </ol>
+ <p>A number of pre-defined variables are available to the script:</p>
+ <ul>
+ <li><code>request</code> - The HTTP request</li>
+ <li><code>response</code> - The HTTP response</li>
+ <li><code>session</code> - The session</li>
+ <li><code>application</code> - The servlet context</li>
+ <li><code><a
href="apidocs/org/apache/struts/scripting/StrutsInfo.html">struts</a></code>
+ - A grouping of all Struts-related objects</li>
+ <li><code>log</code> - A logging instance</li>
+ </ul>
+ <p>
+ You can add your own variables by creating a BSFManagerFilter and
+ configuring it in struts-scripting.properties:
+ </p>
+ <ul>
+
<li><code>struts-scripting.filters.FILTER_NAME.class=FILTER_CLASS</code> - The
+ class implementing BSFManagerFilter where FILTER_NAME is the
name you
+ are calling the filter.</li>
+
<li><code>struts-scripting.filters.FILTER_NAME.PROPERTY_NAME=PROPERTY_VALUE</code>
+ - A property to be used by the filter.</li>
+ </ul>
+ </subsection>
+ </section>
+
+ </body>
+
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
