This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/master by this push:
new afec3bd Cleans up results pages
afec3bd is described below
commit afec3bdfc662f4621d324fdfcf64492843d79114
Author: Lukasz Lenart <lukaszlen...@apache.org>
AuthorDate: Thu Oct 5 09:38:24 2017 +0200
Cleans up results pages
---
source/core-developers/chain-result.md | 5 +-
source/core-developers/dispatcher-result.md | 23 ++-
source/core-developers/freemarker-result.md | 22 +--
source/core-developers/httpheader-result.md | 19 ++-
source/core-developers/plaintext-result.md | 5 +-
source/core-developers/redirect-action-result.md | 26 ++--
source/core-developers/redirect-result.md | 24 +--
source/core-developers/result-types.md | 5 +-
source/core-developers/stream-result.md | 50 ++++---
source/core-developers/xsl-result.md | 181 ++++++++---------------
10 files changed, 171 insertions(+), 189 deletions(-)
diff --git a/source/core-developers/chain-result.md
b/source/core-developers/chain-result.md
index afe0608..27f28b0 100644
--- a/source/core-developers/chain-result.md
+++ b/source/core-developers/chain-result.md
@@ -1,6 +1,9 @@
---
-layout: core-developers
+layout: default
title: Chain Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Chain Result
diff --git a/source/core-developers/dispatcher-result.md
b/source/core-developers/dispatcher-result.md
index 67f05ad..bae8a6a 100644
--- a/source/core-developers/dispatcher-result.md
+++ b/source/core-developers/dispatcher-result.md
@@ -1,24 +1,33 @@
---
-layout: core-developers
+layout: default
title: Dispatcher Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Dispatcher Result
-Includes or forwards to a view (usually a jsp). Behind the scenes Struts will
use a `RequestDispatcher`, where the target servlet/JSP receives the same
request/response objects as the original servlet/JSP. Therefore, you can pass
data between them using `request.setAttribute()` - the Struts action is
available.
+Includes or forwards to a view (usually a jsp). Behind the scenes Struts will
use a `RequestDispatcher`, where
+the target servlet/JSP receives the same request/response objects as the
original servlet/JSP. Therefore, you can pass
+data between them using `request.setAttribute()` - the Struts action is
available.
There are three possible ways the result can be executed:
-- If we are in the scope of a JSP (a PageContext is available), PageContext's
`{@link PageContext#include(String) include}` method is called.
-- If there is no PageContext and we're not in any sort of include (there is no
"javax.servlet.include.servlet_path" in the request attributes), then a call to
`{@link RequestDispatcher#forward(javax.servlet.ServletRequest,
javax.servlet.ServletResponse) forward}` is made.
-- Otherwise, `{@link RequestDispatcher#include(javax.servlet.ServletRequest,
javax.servlet.ServletResponse) include}` is called.
+- If we are in the scope of a JSP (a PageContext is available), PageContext's
`{@link PageContext#include(String) include}`
+ method is called.
+- If there is no PageContext and we're not in any sort of include (there is no
`javax.servlet.include.servlet_path`
+ in the request attributes), then a call to `{@link
RequestDispatcher#forward(javax.servlet.ServletRequest,
javax.servlet.ServletResponse) forward}`
+ is made.
+- Otherwise, `{@link RequestDispatcher#include(javax.servlet.ServletRequest,
javax.servlet.ServletResponse) include}`
+ is called.
-#### Parameters
+## Parameters
- `location` (default) - the location to go to after execution (ex. jsp).
- `parse` - true by default. If set to false, the location param will not be
parsed for OGNL expressions.
-#### Examples
+## Examples
```xml
<result name="success" type="dispatcher">
diff --git a/source/core-developers/freemarker-result.md
b/source/core-developers/freemarker-result.md
index d456eb4..d87f77c 100644
--- a/source/core-developers/freemarker-result.md
+++ b/source/core-developers/freemarker-result.md
@@ -1,31 +1,31 @@
---
-layout: core-developers
+layout: default
title: FreeMarker Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# FreeMarker Result
-Renders a view using the Freemarker template engine. The `FreemarkarManager`
class configures the template loaders so that the template location can be
either
+Renders a view using the Freemarker template engine. The `FreemarkarManager`
class configures the template loaders
+so that the template location can be either
- relative to the web root folder, e.g.: `/WEB-INF/views/home.ftl`
-
- a classpath resource, e.g.: `/com/company/web/views/home.ftl`
-
Also see [Freemarker Support](freemarker-support.html).
-#### Parameters
+## Parameters
- `location` (default) - the location of the template to process.
-
- `parse`- true by default. If set to false, the location param will not be
parsed for expressions.
-
- `contentType` - defaults to `text/html` unless specified.
+- `writeIfCompleted` - `false` by default, write to stream only if there isn't
any error processing the template.
+ Setting `template_exception_handler=rethrow` in `freemarker.properties` will
have the same effect.
-- `writeIfCompleted` - `false` by default, write to stream only if there isn't
any error processing the template. Setting `template_exception_handler=rethrow`
in `freemarker.properties` will have the same effect.
-
-#### Examples
+## Examples
-```
+```xml
<result name="success" type="freemarker">foo.ftl</result>
```
diff --git a/source/core-developers/httpheader-result.md
b/source/core-developers/httpheader-result.md
index 0fda09d..8621e1e 100644
--- a/source/core-developers/httpheader-result.md
+++ b/source/core-developers/httpheader-result.md
@@ -1,28 +1,27 @@
---
-layout: core-developers
+layout: default
title: HttpHeader Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# HttpHeader Result
-A custom Result type for setting HTTP headers and status by optionally
evaluating against the ValueStack. This result can also be used to send an
error to the client. All the parameters can be evaluated against the
ValueStack.
-
-### Parameters
+A custom Result type for setting HTTP headers and status by optionally
evaluating against the ValueStack. This result
+can also be used to send an error to the client. All the parameters can be
evaluated against the ValueStack.
+## Parameters
- `status` - the http servlet response status code that should be set on a
response.
-
- `parse` - true by default. If set to false, the headers param will not be
parsed for OGNL expressions.
-
- `headers` - header values.
-
- `error` - the http servlet response error code that should be set on a
response.
-
- `errorMessage` - error message to be set on response if 'error' is set.
-### Examples
+## Examples
-```
+```xml
<result name="success" type="httpheader">
<param name="status">204</param>
<param name="headers.a">a custom header value</param>
diff --git a/source/core-developers/plaintext-result.md
b/source/core-developers/plaintext-result.md
index 8bfae9d..a2242ad 100644
--- a/source/core-developers/plaintext-result.md
+++ b/source/core-developers/plaintext-result.md
@@ -1,6 +1,9 @@
---
-layout: core-developers
+layout: default
title: PlainText Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# PlainText Result
diff --git a/source/core-developers/redirect-action-result.md
b/source/core-developers/redirect-action-result.md
index b951575..1200fcc 100644
--- a/source/core-developers/redirect-action-result.md
+++ b/source/core-developers/redirect-action-result.md
@@ -1,28 +1,36 @@
---
-layout: core-developers
+layout: default
title: Redirect Action Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Redirect Action Result
-This result uses the `ActionMapper` provided by the `ActionMapperFactory` to
redirect the browser to a URL that invokes the specified action and (optional)
namespace. This is better than the `ServletRedirectResult` because it does not
require you to encode the URL patterns processed by the `ActionMapper` in to
your struts.xml configuration files. This means you can change your URL
patterns at any point and your application will still work. It is strongly
recommended that if you are redir [...]
+This result uses the `ActionMapper` provided by the `ActionMapperFactory` to
redirect the browser to a URL that invokes
+the specified action and (optional) namespace. This is better than the
`ServletRedirectResult` because it does not require
+you to encode the URL patterns processed by the `ActionMapper` in to your
struts.xml configuration files. This means
+you can change your URL patterns at any point and your application will still
work. It is strongly recommended that if you
+are redirecting to another action, you use this result rather than the
standard redirect result.
See examples below for an example of how request parameters could be passed in.
See [ActionMapper](action-mapper.html) for more details
-
-### Parameters
+## Parameters
- `actionName` (default) - The name of the action that will be redirected to.
-- `namespace` - Used to determine which namespace the action is in that we're
redirecting to. If namespace is null, the default will be the current namespace.
-- `suppressEmptyParameters` - Optional boolean (defaults to false) that can
prevent parameters with no values from being included in the redirect URL.
+- `namespace` - Used to determine which namespace the action is in that we're
redirecting to. If namespace is null,
+ the default will be the current namespace.
+- `suppressEmptyParameters` - Optional boolean (defaults to false) that can
prevent parameters with no values from being
+ included in the redirect URL.
- `parse` - Boolean, true by default. If set to false, the actionName param
will not be parsed for OGNL expressions.
- `anchor` - Optional. Also known as "fragment" or colloquially as "hash". You
can specify an anchor for a result.
-### Examples
+## Examples
-```
+```xml
<package name="public" extends="struts-default">
<action name="login" class="...">
<!-- Redirect to another namespace -->
@@ -66,7 +74,7 @@ See [ActionMapper](action-mapper.html) for more details
</package>
```
-```
+```xml
<!--
Example of "anchor" param usage in conjunction with "redirectAction"
result-type.
diff --git a/source/core-developers/redirect-result.md
b/source/core-developers/redirect-result.md
index 9461e8e..d1e633d 100644
--- a/source/core-developers/redirect-result.md
+++ b/source/core-developers/redirect-result.md
@@ -1,26 +1,30 @@
---
-layout: core-developers
+layout: default
title: Redirect Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Redirect Result
-Calls the `{@link HttpServletResponse#sendRedirect(String) sendRedirect}`
method to the location specified. The response is told to redirect the browser
to the specified location (a new request from the client). The consequence of
doing this means that the action (action instance, action errors, field errors,
etc) that was just executed is lost and no longer available. This is because
actions are built on a single-thread model. The only way to pass data is
through the session or with web [...]
+Calls the `{@link HttpServletResponse#sendRedirect(String) sendRedirect}`
method to the location specified. The response
+is told to redirect the browser to the specified location (a new request from
the client). The consequence of doing this
+means that the action (action instance, action errors, field errors, etc) that
was just executed is lost and no longer
+available. This is because actions are built on a single-thread model. The
only way to pass data is through the session
+or with web parameters (`url?name=value`) which can be OGNL expressions.
-### Parameters
+## Parameters
- `location` (default) - the location to go to after execution.
-
- `parse` - true by default. If set to false, the location param will not be
parsed for OGNL expressions.
-
- `anchor` - Optional. Also known as "fragment" or colloquially as "hash". You
can specify an anchor for a result.
-This result follows the same rules from StrutsResultSupport.
-
+This result follows the same rules from `StrutsResultSupport`.
-### Examples
+## Examples
-```
+```xml
<!--
The redirect URL generated will be:
/foo.jsp#FRAGMENT
@@ -32,7 +36,7 @@ This result follows the same rules from StrutsResultSupport.
</result>
```
-```
+```xml
<package name="passingRequestParameters" extends="struts-default"
namespace="/passingRequestParameters">
<-- Pass parameters (reportType, width and height) -->
<!--
diff --git a/source/core-developers/result-types.md
b/source/core-developers/result-types.md
index 8c0d502..21fd12f 100644
--- a/source/core-developers/result-types.md
+++ b/source/core-developers/result-types.md
@@ -24,9 +24,10 @@ own applications.
|[Velocity Result](velocity-result.html)|Used for _Velocity_ integration|
|[XSL Result](xsl-result.html)|Used for XML/XSLT integration|
|[PlainText Result](plaintext-result.html)|Used to display the raw content of
a particular page (i.e jsp, HTML)|
-|[Tiles Result](tiles-result.html)|Used to provide Tiles integration|
+|[Tiles Result](../plugins/tiles/)|Used to provide Tiles integration|
+|[Tiles 3 Result](../plugins/tiles-3/)|Used to provide Tiles 3 integration|
|[Postback Result](postback-result.html)|Used to postback request parameters
as a form to the specified destination|
-|[JSON Result](json-result.html) |Used to serialize actions into JSON|
+|[JSON Result](../plugins/json/) |Used to serialize actions into JSON|
## Optional
diff --git a/source/core-developers/stream-result.md
b/source/core-developers/stream-result.md
index 2402cd5..cac1460 100644
--- a/source/core-developers/stream-result.md
+++ b/source/core-developers/stream-result.md
@@ -1,35 +1,47 @@
---
-layout: core-developers
+layout: default
title: Stream Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Stream Result
-A custom Result type for sending raw data (via an InputStream) directly to the
HttpServletResponse. Very useful for allowing users to download content.
-If you are running your app server under HTTPS and having issues with PDF's or
other file streams you should take a look at [HTTPS and IE
Issues](https-and-ie-issues.html)
+A custom Result type for sending raw data (via an InputStream) directly to the
HttpServletResponse. Very useful for
+allowing users to download content. If you are running your app server under
HTTPS and having issues with PDF's or other
+file streams you should take a look at [HTTPS and IE
Issues](https-and-ie-issues.html)
-### Parameters
+## Parameters
-- `contentType` - the stream mime-type as sent to the web browser (default =
text/plain).
+- `contentType` - the stream mime-type as sent to the web browser (default =
`text/plain`).
- `contentLength` - the stream length in bytes (the browser displays a
progress bar).
-- `contentDisposition` - the content disposition header value for specifying
the file name (default = inline, values are typically
attachment;filename="document.pdf".
-- `inputName` - the name of the InputStream property from the chained action
(default = inputStream).
-- `bufferSize` - the size of the buffer to copy from input to output (default
= 1024).
-- `allowCaching` - if set to 'false' it will set the headers `Pragma` and
`Cache-Control` to `no-cahce`, and prevent client from caching the content
(default = true).
-- `contentCharSet` - if set to a string, ';charset=value' will be added to the
content-type header, where value is the string set. If set to an expression,
the result of evaluating the expression will be used. If not set, then no
charset will be set on the header
+- `contentDisposition` - the content disposition header value for specifying
the file name (default = `inline`, values
+ are typically `attachment;filename="document.pdf"`.
+- `inputName` - the name of the InputStream property from the chained action
(default = `inputStream`).
+- `bufferSize` - the size of the buffer to copy from input to output (default
= `1024`).
+- `allowCaching` - if set to 'false' it will set the headers `Pragma` and
`Cache-Control` to `no-cahce`, and prevent
+ client from caching the content (default = `true`).
+- `contentCharSet` - if set to a string, ';charset=value' will be added to the
content-type header, where value is the string
+ set. If set to an expression, the result of evaluating the expression will
be used. If not set, then no charset will
+ be set on the header
-These parameters can also be set by exposing a similarly named getter method
on your Action. For example, you can provide `getContentType()` to override
that parameter for the current action. To do it you you must explicitly define
this param as an expression i.e. `<param
name="contentType">${contentType}</param>`
+These parameters can also be set by exposing a similarly named getter method
on your Action. For example, you can provide
+`getContentType()` to override that parameter for the current action. To do it
you you must explicitly define this param
+as an expression i.e. `<param name="contentType">${contentType}</param>`
-Please be aware that this was changed since Struts 2.5.2, previously each
parameter was automagically resolved by looking throughout the `ValueStack`,
now you must explicitly define which parameter must be evaluated, even
`inputName`.
+Please be aware that this was changed since Struts 2.5.2, previously each
parameter was automatically resolved by looking
+throughout the `ValueStack`, now you must explicitly define which parameter
must be evaluated, even `inputName`.
+{:.alert .alert-success}
-### Examples
+## Examples
-#### Annotation based Configuration
+### Annotation based Configuration
-To configure Actions and Results with Annotations you need to activate the
Struts2 _Convention Plugin_ in your Struts2 application.
+To configure Actions and Results with Annotations you need to activate the
Struts2 [Convention Plugin](../plugins/convention/)
+in your Struts2 application.
-
-```
+```java
package com.mycompany.webapp.actions;
import java.io.File;
@@ -80,9 +92,9 @@ public class FileDisplay extends ActionSupport {
}
```
-#### XML based Configuration
+### XML based Configuration
-```
+```xml
<result name="success" type="stream">
<param name="contentType">image/jpeg</param>
<param name="inputName">${imageStream}</param>
diff --git a/source/core-developers/xsl-result.md
b/source/core-developers/xsl-result.md
index e6798f8..27ca532 100644
--- a/source/core-developers/xsl-result.md
+++ b/source/core-developers/xsl-result.md
@@ -1,168 +1,111 @@
---
-layout: core-developers
+layout: default
title: XSL Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# XSL Result
+## Description
-####Description####
+XSLTResult uses XSLT to transform an action object to XML. The recent version
has been specifically modified to deal
+with Xalan flaws. When using Xalan you may notice that even though you have a
very minimal stylesheet like this one
-XSLTResult uses XSLT to transform an action object to XML\. The recent version
has been specifically modified to deal with Xalan flaws\. When using Xalan you
may notice that even though you have a very minimal stylesheet like this one
-
-
-~~~~~~~
+```xml
<xsl:template match="/result">
<result/>
</xsl:template>
-~~~~~~~
-
-Xalan would still iterate through every property of your action and all its
descendants\.
+```
-If you had double\-linked objects, Xalan would work forever analysing an
infinite object tree\. Even if your stylesheet was not constructed to process
them all\. It's because the current Xalan eagerly and extensively converts
-everything to its internal DTM model before further processing\.
+Xalan would still iterate through every property of your action and all its
descendants.
-That's why there's a loop eliminator added that works by indexing every
object\-property combination during processing\. If it notices that some
object's property was already walked through, it doesn't go any deeper\. Say
you have two objects, x and y, with the following properties set (pseudocode):
+If you had double-linked objects, Xalan would work forever analysing an
infinite object tree. Even if your stylesheet
+was not constructed to process them all. It's because the current Xalan
eagerly and extensively converts everything
+to its internal DTM model before further processing.
+That's why there's a loop eliminator added that works by indexing every
object-property combination during processing.
+If it notices that some object's property was already walked through, it
doesn't go any deeper. Say you have two objects,
+x and y, with the following properties set (pseudocode):
-~~~~~~~
+```
x.y = y;
and
y.x = x;
action.x=x;
-~~~~~~~
+```
Due to that modification, the resulting XML document based on x would be:
-
-~~~~~~~
+```xml
<result>
<x>
<y/>
</x>
</result>
-~~~~~~~
-
-Without it there would be endless
-
-~~~~~~~
-x/y/x/y/x/y/...
-~~~~~~~
- elements\.
-
-The
-
-~~~~~~~
-XSLTResult
-~~~~~~~
- code tries also to deal with the fact that DTM model is built in a manner
that children are processed before siblings\. The result is that if there is
object x that is both set in action's x property, and very deeply under
action's a property then it would only appear under a, not under x\. That's not
what we expect, and that's why
-
-~~~~~~~
-XSLTResult
-~~~~~~~
- allows objects to repeat in various places to some extent\.
-
-Sometimes the object mesh is still very dense and you may notice that even
though you have a relatively simple stylesheet, execution takes a tremendous
amount of time\. To help you to deal with that obstacle of Xalan, you may
attach regexp filters to elements paths (xpath)\.
-
-
-
-| In your \.xsl file the root match must be named **result**\. This example
will output the username by using **getUsername** on your action class:
-
-| \<xsl:template match="result"\>
- \<html\>
- \<body\>
- Hello \<xsl:value\-of select="username"/\> how are you?
- \</body\>
- \</html\>
- \</xsl:template\>
-
-In the following example the XSLT result would only walk through action's
properties without their childs\. It would also skip every property that has
-
-~~~~~~~
-hugeCollection
-~~~~~~~
- in their name\. Element's path is first compared to
-
-~~~~~~~
-excludingPattern
-~~~~~~~
- \- if it matches it's no longer processed\. Then it is compared to
-
-~~~~~~~
-matchingPattern
-~~~~~~~
- and processed only if there's a match\.
+```
+
+Without it there would be endless `x/y/x/y/x/y/...` elements. The `XSLTResult`
code tries also to deal with the fact
+that DTM model is built in a manner that children are processed before
siblings. The result is that if there is object
+`x` that is both set in action's `x` property, and very deeply under action's
a property then it would only appear under
+`a`, not under `x`. That's not what we expect, and that's why `XSLTResult`
allows objects to repeat in various places
+to some extent.
+
+Sometimes the object mesh is still very dense and you may notice that even
though you have a relatively simple stylesheet,
+execution takes a tremendous amount of time. To help you to deal with that
obstacle of Xalan, you may attach regexp filters
+to elements paths (xpath).
+
+> In your .xsl file the root match must be named `result`. This example will
output the username by using `getUsername` on your action class:
+```xml
+<xsl:template match="result">
+ <html>
+ <body>
+ Hello <xsl:value-of select="username"/> how are you?
+ </body>
+ </html>
+</xsl:template>
+```
+In the following example the XSLT result would only walk through action's
properties without their childs. It would also
+skip every property that has `hugeCollection` in their name. Element's path is
first compared to `excludingPattern` -
+if it matches it's no longer processed. Then it is compared to
`matchingPattern` and processed only if there's a match.
-~~~~~~~
+```xml
<result name="success" type="xslt">
<param name="stylesheetLocation">foo.xslt</param>
<param name="matchingPattern">^/result/[^/*]$</param>
<param name="excludingPattern">.*(hugeCollection).*</param>
</result>
-~~~~~~~
-
-In the following example the XSLT result would use the action's user property
instead of the action as it's base document and walk through it's properties\.
The
+```
-~~~~~~~
-exposedValue
-~~~~~~~
- uses an OGNL expression to derive it's value\.
+In the following example the XSLT result would use the action's user property
instead of the action as it's base document
+and walk through it's properties. The `exposedValue` uses an OGNL expression
to derive it's value.
-
-~~~~~~~
+```xml
<result name="success" type="xslt">
<param name="stylesheetLocation">foo.xslt</param>
<param name="exposedValue">${user}</param>
</result>
-~~~~~~~
+```
-####Parameters####
+## Parameters
This result type takes the following parameters:
-+ **stylesheetLocation** (default) \- the location to go to after execution\.
-
-+ **location** (deprecated) \- the same as **stylesheetLocation** but it was
dropped since Struts 2\.5\.
-
-+ **encoding **\- character encoding used in XML, default UTF\-8\.
-
-+ **parse** \-
-
-~~~~~~~
-true
-~~~~~~~
- by default\. If set to false, the location param will not be parsed for Ognl
expressions\.
-
-+ **matchingPattern **\-
+- `stylesheetLocation` (default) - the location to go to after execution.
+- `location` (deprecated) - the same as `stylesheetLocation` but it was
dropped since Struts 2.5.
+- `encoding` - character encoding used in XML, default UTF-8.
+- `parse` - `true` by default. If set to false, the location param will not be
parsed for Ognl expressions.
+- `matchingPattern` - a `Pattern` that matches only desired elements, by
default it matches everything.
+- `excludingPattern` - a `Pattern` that eliminates unwanted elements, by
default it matches none.
-~~~~~~~
-Pattern
-~~~~~~~
- that matches only desired elements, by default it matches everything\.
+`struts.xml` related configuration:
-+ **excludingPattern** \-
+- `struts.xslt.nocache` - Defaults to `false`. If set to true, disables
stylesheet caching. Good for development, bad for production.
-~~~~~~~
-Pattern
-~~~~~~~
- that eliminates unwanted elements, by default it matches none\.
+## Examples
-
-
-~~~~~~~
-struts.properties
-~~~~~~~
- related configuration:
-
-+ **struts\.xslt\.nocache** \- Defaults to false\. If set to true, disables
stylesheet caching\. Good for development, bad for production\.
-
-####Examples####
-
-
-
-~~~~~~~
+```xml
<result name="success" type="xslt">foo.xslt</result>
-~~~~~~~
-
-
\ No newline at end of file
+```
--
To stop receiving notification emails like this one, please contact
['"commits@struts.apache.org" <commits@struts.apache.org>'].
