Performs round of cleanups
Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/46a2618c Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/46a2618c Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/46a2618c Branch: refs/heads/master Commit: 46a2618ca76c637fcdcfe037572d9ab4a2cdbd5b Parents: 905cf12 Author: Lukasz Lenart <lukaszlen...@apache.org> Authored: Thu Sep 21 12:04:32 2017 +0200 Committer: Lukasz Lenart <lukaszlen...@apache.org> Committed: Thu Sep 21 12:04:32 2017 +0200 ---------------------------------------------------------------------- source/tag-developers/a-tag.md | 44 + .../access-to-valuestack-from-jsps.md | 133 + source/tag-developers/action-tag.md | 56 + .../ajax-and-javascript-recipes.md | 966 +++ source/tag-developers/ajax-tags.md | 75 + source/tag-developers/ajax-theme.md | 431 + source/tag-developers/append-tag.md | 30 + source/tag-developers/bean-tag.md | 30 + .../cewolf-charts-using-velocity-templates.md | 127 + source/tag-developers/css-xhtml-theme.md | 149 + source/tag-developers/date-tag.md | 30 + source/tag-developers/debug-tag.md | 8 + source/tag-developers/else-tag.md | 35 + source/tag-developers/elseif-tag.md | 35 + source/tag-developers/extending-themes.md | 132 + source/tag-developers/form-tags.md | 264 + source/tag-developers/freemarker-tags.md | 147 + source/tag-developers/freemarker.md | 298 + source/tag-developers/generator-tag.md | 30 + source/tag-developers/generic-tag-reference.md | 40 + source/tag-developers/generic-tags.md | 13 + source/tag-developers/i18n-tag.md | 35 + source/tag-developers/if-tag.md | 31 + source/tag-developers/include-tag.md | 51 + source/tag-developers/index.md | 7514 ++---------------- source/tag-developers/iterator-tag.md | 109 + source/tag-developers/jsp-tags.md | 25 + source/tag-developers/jsp.md | 97 + source/tag-developers/merge-tag.md | 40 + source/tag-developers/ognl-basics.md | 124 + .../ognl-expression-compilation.md | 338 + source/tag-developers/ognl.md | 143 + source/tag-developers/param-tag.md | 40 + source/tag-developers/property-tag.md | 40 + source/tag-developers/push-tag.md | 70 + .../selecting-template-directory.md | 51 + source/tag-developers/selecting-themes.md | 48 + source/tag-developers/set-tag.md | 35 + source/tag-developers/simple-theme.md | 37 + source/tag-developers/sort-tag.md | 35 + source/tag-developers/struts-tags.md | 39 + source/tag-developers/subset-tag.md | 55 + source/tag-developers/tag-reference.md | 11 + source/tag-developers/tag-syntax.md | 257 + source/tag-developers/template-loading.md | 111 + source/tag-developers/text-tag.md | 85 + source/tag-developers/themes-and-templates.md | 33 + source/tag-developers/ui-tag-reference.md | 58 + source/tag-developers/ui-tags.md | 35 + source/tag-developers/url-tag.md | 68 + source/tag-developers/velocity-tags.md | 43 + source/tag-developers/velocity.md | 121 + source/tag-developers/xhtml-theme.md | 214 + 53 files changed, 6162 insertions(+), 6904 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/a-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/a-tag.md b/source/tag-developers/a-tag.md new file mode 100644 index 0000000..fceb87c --- /dev/null +++ b/source/tag-developers/a-tag.md @@ -0,0 +1,44 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# a + +Please make sure you have read the [Tag Syntax](tag-syntax.html) document and understand how tag attribute syntax works. + +## Description + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.Anchor} +~~~~~~~ + +> While this tag can be used with the [simple theme](simple-theme.html), [xhtml theme](xhtml-theme.html), and others, +> it is really designed to work best with the [ajax theme](ajax-theme.html). We recommend reading the +> _ajax a template_ documentation for more details. + +## Parameters + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/a.html} +~~~~~~~ + +## Usage + +To get started, use the [head](head-tag.htlm) tag and the [ajax theme](ajax-theme.html). See _ajax head template_ +for more information. Then look at the usage details for the _ajax a template_ . + +If you want to use additional parameters in your s:a the best practice is to use a s:url to create your url and then +leverage this url into your s:a tag. This is done by creating a s:url and specifying an id attribute. like "testUrlId" +in this example. Then in the s:a tag reference this id in the href attribute via `%{testUrlId}` + +```jsp +<s:url var="testUrlId" namespace="/subscriber" action="customField" method="delete"> + <s:param name="customFieldDefinition.id" value="${id}"/> +</s:url> +<s:a errorText="Sorry your request had an error." preInvokeJS="confirm('Are you sure you want to delete this item?')" href="%{testUrlId}"> + <img src="<s:url value="/images/delete.gif"/>" border="none"/> +</s:a> + +<img xsrc="<s:url value="/images/delete.gif"/>" border="none"/><s:a><img xsrc="<s:url value="/images/delete.gif"/>" border="none"/></s:a> +``` http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/access-to-valuestack-from-jsps.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/access-to-valuestack-from-jsps.md b/source/tag-developers/access-to-valuestack-from-jsps.md new file mode 100644 index 0000000..dce5c3a --- /dev/null +++ b/source/tag-developers/access-to-valuestack-from-jsps.md @@ -0,0 +1,133 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Access to ValueStack from JSPs + +To access the ValueStack from third-party JSP taglibs, expose property values to JSP using the `<s:set/>` tag. + +**Set a request scoped parameter 'a' to list of integers** + +```jsp +<s:set name="'a'" value="{ 1, 2, 3, 4 }" scope="request"/> +``` + +After setting parameters, third-party JSP taglibs can access variables or use JSP 2.0 EL (Expression Language). +This is convenient as short hand EL expression syntax `${expression}` can be used in a text or inside of tag attributes: + +``` +a[0] = ${a[0]} + +<sample:tag value="${a[1]}"/> +``` + +In practice, several variables must be exposed to make effective use of third party taglibs like [DisplayTag](http://displaytag.sourceforge.net/11/). +Unfortunately, this approach leads to a lot of `<s:set/>` tags. + +> Unfortunately, it isn't that simple. we tinkered with `JSPFactory.setDefault()` to wrap around `getPageContext()` +> and create `ExpressionEvaluator` that would use OGNL. This strategy works in practice, but code generated by Jasper2 +> doesn't call `JSPFactory.getPageContext().getExpressionEvaluator()` but goes directly to static method that is +> hardwired to Jakarta Commons-EL implementation. + +> Even if this approach did work, it wouldn't be _clean_ as `JSPFactory.setDefault()` should only be called by JSP implementation.| + +There is a simple, if not elegant, solution available in JSP 2.0 EL, for exposing ValueStack to OGNL. It is possible +to create custom functions that can be called from EL expressions. Functions have to be 'public static' and specified +in a TLD file. + +To use a function, import the TLD in a JSP file where you've want to use a function. For example, you could access +Action properties by evaluating OGNL expression by a function 'vs' (for valuestack) in EL. + +```jsp +<%@ taglib uri="/WEB-INF/tld/wwel.tld" prefix="x" %> + +a[0] = ${x:vs('a[0]')} +a[0] * 4 = ${x:vs('a[0] * 4')} + +Current action name: ${x:name()} +Top of ValueStack: ${x:top()} +``` + +To use this code you've got to add `wwel.tld` and `Functions.java` to your webapp project. + +> If someone were interested, it would be helpful for a developer (like you!) to define a set of functions that we could +> include in a future release of the framework. + +**wwel.tld** + +```xml +<?xml version="1.0"?> +<taglib xmlns="http://java.sun.com/xml/ns/j2ee"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd"; + version="2.0"> + +<description> +This taglib enables access to the ValueStack +from JSP 2.0 Expression Language +</description> + +<tlib-version>1.0</tlib-version> + +<short-name>wwel</short-name> + +<function> + <name>vs</name> + <function-class>com.nmote.wwel.Functions</function-class> + <function-signature> + java.lang.Object findOnValueStack(java.lang.String) + </function-signature> +</function> + +<function> + <name>name</name> + <function-class>com.nmote.wwel.Functions</function-class> + <function-signature> + java.lang.Object getActionName() + </function-signature> +</function> + +<function> + <name>top</name> + <function-class>com.nmote.wwel.Functions</function-class> + <function-signature> + java.lang.Object getTopOfValueStack() + </function-signature> +</function> + +</taglib> +``` + +**Functions.java** + +```java +package com.nmote.wwel; + +import com.opensymphony.xwork.ActionContext; + +/** + * Utility functions for accessing value stack and action context + * from JSP 2.0 EL taglibs. + */ +public class Functions { + + public static Object findOnValueStack(String expr) { + ActionContext a = ActionContext.getContext(); + Object value = a.getValueStack().findValue(expr); + return value; + } + + public static Object getTopOfValueStack() { + ActionContext a = ActionContext.getContext(); + Object value = a.getValueStack().peek(); + return value; + } + + public static Object getActionName() { + ActionContext a = ActionContext.getContext(); + Object value = a.getName(); + return value; + } +} +``` http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/action-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/action-tag.md b/source/tag-developers/action-tag.md new file mode 100644 index 0000000..79e086c --- /dev/null +++ b/source/tag-developers/action-tag.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# action + +Please make sure you have read the [Tag Syntax](tag-syntax.html) document and understand how tag attribute syntax works. + +## Description + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.ActionComponent} +~~~~~~~ + +Parameters can be passed to the action using nested [param](param-tag.html) tags. + +## Placement in context + +The action will not be published to the context until the whole tag is evaluated, meaning that inside the body of the tag, +the action cannot be accessed, For example: + +```jsp +<s:action var="myAction" name="MyAction" namespace="/"> + Is "myAction" null inside the tag? <s:property value="#myAction == null" /> +</s:action> + Is "myAction" null outside the tag? <s:property value="#myAction == null" /> +``` + +Will print: + +Is "myAction" null inside the tag? true + +Is "myAction" null outside the tag? false + +## Parameters + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/action.html} +~~~~~~~ + +## Examples + +~~~~~~~ +{snippet:id=javacode|javadoc=true|lang=java|url=org.apache.struts2.components.ActionComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=strutsxml|javadoc=true|lang=xml|url=org.apache.struts2.components.ActionComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=xml|url=org.apache.struts2.components.ActionComponent} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/ajax-and-javascript-recipes.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/ajax-and-javascript-recipes.md b/source/tag-developers/ajax-and-javascript-recipes.md new file mode 100644 index 0000000..23e4195 --- /dev/null +++ b/source/tag-developers/ajax-and-javascript-recipes.md @@ -0,0 +1,966 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Ajax and JavaScript Recipes +{:.no_toc} + +* Will be replaced with the ToC, excluding a header +{:toc} + +**Dojo plugin is deprecated** + +## Common + +All examples on this page assume the following JSP fragment is on the same page as the example. + +```jsp +<%@ taglib prefix="s" uri="/struts-tags" %> +<%@ taglib prefix="sx" uri="/struts-dojo-tags" %> + +<head> + <sx:head /> +</head> + +<s:url id="url" value="/MyAction.action" /> +``` + +## Requests + +### Request is triggered by a topic + +```jsp +<s:submit value="Make Request" onclick="dojo.event.topic.publish('/request')" /> +<sx:bind listenTopics="/request" href="%{#url}" /> +``` + +### Attached to an event + +```jsp +<s:submit value="Make Request" id="submit" /> +<sx:bind sources="submit" events="onclick" href="%{#url}" /> +``` + +### Attached to an event on multiple sources + +```jsp +<s:submit value="Make Request" id="submit0" /> +<s:submit value="Make Request" id="submit1" /> +<sx:bind sources="submit0,submit1" events="onclick" href="%{#url}" /> +``` + +### Attached to multiple events on multiple sources + +```jsp +<s:textarea id="area0" /> +<s:textarea id="area1" /> +<sx:bind sources="area0,area1" events="onfocus,onchange" href="%{#url}" /> +``` + +### Update target element with content returned from url + +```jsp +<s:div id="div" /> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind targets="div" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit targets="div" value="Make Request" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a targets="div" value="Make Request" href="%{#url}" /> +``` + +### Update multiple target elements with content returned from url + +```jsp +<s:div id="div0" /> +<s:div id="div1" /> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind targets="div0,div1" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit targets="div0,div1" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a targets="div0,div1" href="%{#url}" /> +``` + +### Show indicator while request is in progress + +```jsp +<img id="indicator" src="${pageContext.request.contextPath}/images/indicator.gif" style="display:none" /> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind indicator="indicator" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit indicator="indicator" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a indicator="indicator" href="%{#url}" /> +``` + +### Highlight content of target with blue color, for 2 seconds + +```jsp +<s:div id="div" /> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind highlightColor="blue" highlightDuration="2000" targets="div" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit highlightColor="blue" highlightDuration="2000" targets="div" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a highlightColor="blue" highlightDuration="2000" targets="div" href="%{#url}" /> +``` + +### Execute JavaScript in the returned content + +```jsp +<s:div id="div" /> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind executeScripts="true" targets="div" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit executeScripts="true" targets="div" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a executeScripts="true" targets="div" href="%{#url}" /> +``` + +### Publish a topic before the request + +``html +<script type="text/javascript"> +dojo.event.topic.subscribe("/before", function(event, widget){ + alert('inside a topic event. before request'); + //event: event object + //widget: widget that published the topic +}); +</script> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind beforeNotifyTopics="/before" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit beforeNotifyTopics="/before" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a beforeNotifyTopics="/before" href="%{#url}" /> +`` + +### Publish a topic after the request + +```jsp +<script type="text/javascript"> +dojo.event.topic.subscribe("/after", function(data, request, widget){ + alert('inside a topic event. after request'); + //data : text returned from request + //request: XMLHttpRequest object + //widget: widget that published the topic +}); +</script> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind afterNotifyTopics="/after" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit afterNotifyTopics="/after" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a afterNotifyTopics="/after" href="%{#url}" /> +``` + +### Publish a topic on error + +```jsp +<script type="text/javascript"> +dojo.event.topic.subscribe("/error", function(error, request, widget){ + alert('inside a topic event. on error'); + //error : error object (error.message has the error message) + //request: XMLHttpRequest object + //widget: widget that published the topic +}); +</script> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind errorNotifyTopics="/error" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit errorNotifyTopics="/error" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a errorNotifyTopics="/error" href="%{#url}" /> +``` + +### Show a fixed error message on error + +```jsp +<div id="div" /> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind errorText="Error Loading" targets="div" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit errorText="Error Loading" targets="div" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a errorText="Error Loading" targets="div" href="%{#url}" /> +``` + +### Prevent a request + +```jsp +<script type="text/javascript"> +dojo.event.topic.subscribe("/before", function(event, widget){ + alert('I will stop this request'); + event.cancel = true; +}); +</script> + + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind beforeNotifyTopics="/before" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit beforeNotifyTopics="/before" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a beforeNotifyTopics="/before" href="%{#url}" /> +``` + +### Submit a form (plain form) + +```jsp +<form id="form"> + <input type=textbox name="data"> +</form> + +<!-- With a bind tag --> +<s:submit value="Make Request" id="submit" /> +<sx:bind formId="form" sources="submit" events="onclick" href="%{#url}" /> + +<!-- With a submit tag --> +<sx:submit formId="form" href="%{#url}" /> + +<!-- With an anchor tag --> +<sx:a formId="form" href="%{#url}" /> +``` + +### Submit a form (using s:form tag) + +```jsp +<!-- With a submit tag --> +<s:form namespace="/mynamespace" action="MyAction"> + <input type=textbox name="data"> + <sx:submit /> +</s:form> + +<!-- With an anchor tag --> +<s:form namespace="/mynamespace" action="MyAction"> + <input type=textbox name="data"> + <sx:a /> +</s:form> +``` + +## Div + +### Loads its content after page is loaded + +```jsp +<sx:div href="%{#url}"> + Initial Content +</sx:div> +``` + +### Reloads content when topic is published + +```jsp +<sx:div href="%{#url}" listenTopics="/refresh"> + Initial Content +</sx:div> + +<s:submit value="Refresh" onclick="dojo.event.topic.publish('/refresh')" /> +``` + +### Updates its content every 2 seconds, shows indicator while loading content + +```jsp +<img id="indicator" src="${pageContext.request.contextPath}/images/indicator.gif" style="display:none"/> +<sx:div href="%{#url}" updateFreq="2000"> + Initial Content +</sx:div> +``` + +### Loads its content after a delay of 2 seconds + +```jsp +<sx:div href="%{#url}" delay="2000"> + Initial Content +</sx:div> +``` + +### Show some text while content is loaded + +```jsp +<sx:div href="%{#url}" loadingText="reloading" showLoadingText="true"> + Initial Content +</sx:div> +``` + +### Fixed error message + +```jsp +<sx:div href="noaction" errorText="Error loading content"> + Initial Content +</sx:div> +``` + +### Execute JavaScript in the returned content + +```jsp +<sx:div href="%{#url}" executeScripts="true"> + Initial Content +</sx:div> +``` + +### Control refresh timer using topics + +```jsp +<sx:div href="%{#url}" + listenTopics="/refresh" + startTimerListenTopics="/startTimer" + stopTimerListenTopics="/stopTimer" + updateFreq="3000"> + Initial Content +</sx:div> + +<s:submit value="Refresh" onclick="dojo.event.topic.publish('/refresh')" /> +<s:submit value="Start refresh timer" onclick="dojo.event.topic.publish('/startTimer')" /> +<s:submit value="Stop refresh timer" onclick="dojo.event.topic.publish('/stopTimer')" /> +``` + +## Date and Time picker + +### Date picker + +```jsp +<sx:datetimepicker name="picker" /> +``` + +### Time picker + +```jsp +<sx:datetimepicker type="time" name="picker" /> +``` + +### Set value from an String + +```jsp +<sx:datetimepicker value="%{'2007-01-01'}" name="picker" /> +``` + +### Set value from stack (value must evaluate to either a Date, Calendar, or an String that can be parsed using the formats defined in SimpleDateFormat, and RFC 3339) + +```jsp +<sx:datetimepicker value="date" name="picker" /> +``` + +### Set/Get value using JavaScript + +```jsp +<script type="text/javascript"> + function setValue() { + var picker = dojo.widget.byId("picker"); + + //string value + picker.setValue('2007-01-01'); + + //Date value + picker.setValue(new Date()); + } + + function showValue() { + var picker = dojo.widget.byId("picker"); + + //string value + var stringValue = picker.getValue(); + alert(stringValue); + + //date value + var dateValue = picker.getDate(); + alert(dateValue); + } +</script> + +<sx:datetimepicker id="picker" /> +``` + +### Style the textbox + +```jsp +<sx:datetimepicker id="picker" cssStye="background:red" cssClass="someclass"/> +``` + +### Publish topic when value changes + +```jsp +<script type="text/javascript"> + dojo.event.topic.subscribe("/value", function(text, date, widget){ + alert('value changed'); + //textEntered: String entered in the textbox + //date: JavaScript Date object with the value selected + //widget: widget that published the topic + }); +</script> + +<sx:datetimepicker label="Order Date" valueNotifyTopics="/value"/> +``` + +### Use other locales + +Locales must be specified in the sx:head tag. + +```jsp +<sx:head extraLocales="en-us,nl-nl,de-de" /> + +<sx:datetimepicker label="In German" name="dddp7" value="%{'2006-06-28'}" language="de-de" /> +<sx:datetimepicker label="In Dutch" name="dddp8" value="%{'2006-06-28'}" language="nl-nl" /> +``` + +## Tabbed Panel + +### Local Tabs + +```jsp +<sx:tabbedpanel id="tabContainer"> + <sx:div label="Tab 1" > + Local Tab 1 + </sx:div> + <sx:div label="Tab 2" > + Local Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +### Local and remote tabs + +```jsp +<sx:tabbedpanel id="tabContainer"> + <sx:div label="Local Tab 1" > + Tab 1 + </sx:div> + <sx:div label="Remote Tab 2" href="%{#url}"> + Remote Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +### Fixed size (size does not adjust to current tab) + +```jsp +<sx:tabbedpanel cssStyle="width: 500px; height: 300px;" doLayout="true" id="tabContainer"> + <sx:div label="Tab 1" > + Local Tab 1 + </sx:div> + <sx:div label="Tab 2" > + Local Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +### Do not load tab 2 when page loads (it will be loaded when selected) + +```jsp +<sx:tabbedpanel id="tabContainer"> + <sx:div label="Remote Tab 1" href="%{#url}"> + Remote Tab 1 + </sx:div> + <sx:div label="Remote Tab 2" href="%{#url}" preload="false"> + Remote Tab 1 + </sx:div> +</sx:tabbedpanel> +``` + +### Reload tabs content when selected + +```jsp +<sx:tabbedpanel id="tabContainer"> + <sx:div label="Remote Tab 1" href="%{#url}" refreshOnShow="true"> + Remote Tab 1 + </sx:div> + <sx:div label="Remote Tab 2" href="%{#url}" refreshOnShow="true"> + Remote Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +### Disabled tabs + +```jsp +<sx:tabbedpanel id="tabContainer"> + <sx:div label="Tab 1" > + Local Tab 1 + </sx:div> + <sx:div label="Tab 2" disabled="true"> + Local Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +### Enable/Disable tabs using JavaScript + +```jsp +<script type="text/javascript"> + function enableTab(param) { + var tabContainer = dojo.widget.byId('tabContainer'); + tabContainer.enableTab(param); + } + + + function disableTab(param) { + var tabContainer = dojo.widget.byId('tabContainer'); + tabContainer.disableTab(param); + } +</script> + +<sx:tabbedpanel id="tabContainer" id="tabContainer"> + <sx:div id="tab1" label="Tab 1"> + Local Tab 1 + </sx:div> + <sx:div id="tab2" label="Tab 2" disabled="true"> + Local Tab 2 + </sx:div> +</sx:tabbedpanel> + +<!-- By Tab Index --> +<input type="button" onclick="enableTab(1)" value="Enable Tab 2 using Index" /> +<input type="button" onclick="disableTab(1)" value="Disable Tab 2 using Index" /> + +<!-- By Tab Id --> +<input type="button" onclick="enableTab('tab2')" value="Enable Tab 2 using Id" /> +<input type="button" onclick="disableTab('tab2')" value="Disable Tab 2 using Id" /> + +<!-- By Widget --> +<input type="button" onclick="enableTab(dojo.widget.byId('tab2'))" value="Enable Tab 2 using widget" /> +<input type="button" onclick="disableTab(dojo.widget.byId('tab2'))" value="Disable Tab 2 using widget" /> +``` + +### Set Tab labels position to bottom (can be: top, right, bottom, left) + +```jsp +<sx:tabbedpanel labelposition="bottom" id="tabContainer"> + <sx:div label="Tab 1" > + Local Tab 1 + </sx:div> + <sx:div label="Tab 2" > + Local Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +### Allow tab 2 to be removed(closed) + +```jsp +<sx:tabbedpanel id="tabContainer"> + <sx:div label="Tab 1" > + Local Tab 1 + </sx:div> + <sx:div label="Tab 2" closable="true"> + Local Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +### Publish topics when tab is selected + +```jsp +<script type="text/javascript"> + dojo.event.topic.subscribe('/before', function(event, tab, tabContainer) { + alert("Before selecting tab"); + }); + + dojo.event.topic.subscribe('/after', function(tab, tabContainer) { + alert("After tab was selected"); + }); +</script> +<sx:tabbedpanel beforeSelectTabNotifyTopics="/before" afterSelectTabNotifyTopics="/after" id="tabContainer"> + <sx:div label="Tab 1"> + Local Tab 1 + </sx:div> + <sx:div label="Tab 2"> + Local Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +### Select tab using JavaScript + +```jsp +<script type="text/javascript"> + function selectTab(id) { + var tabContainer = dojo.widget.byId("tabContainer"); + tabContainer.selectTab(id); + } +</script> +<sx:tabbedpanel id="tabContainer"> + <sx:div label="Tab 1" id="tab1"> + Local Tab 1 + </sx:div> + <sx:div label="Tab 2" id="tab2"> + Local Tab 2 + </sx:div> +</sx:tabbedpanel> + +<input type="button" onclick="selectTab('tab1')" value="Select tab 1" /> +<input type="button" onclick="selectTab('tab2')" value="Select tab 2" /> +``` + +### Prevent tab 2 from being selected + +```jsp +<script type="text/javascript"> + dojo.event.topic.subscribe('/before', function(event, tab, tabContainer) { + event.cancel = tab.widgetId == "tab2" ; + }); +</script> +<sx:tabbedpanel beforeSelectTabNotifyTopics="/before" id="tabContainer"> + <sx:div id="tab1" label="Tab 1"> + Local Tab 1 + </sx:div> + <sx:div id="tab2" label="Tab 2"> + Local Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +### Customize template css path (Dojo widget template css) + +```jsp +<sx:tabbedpanel templateCssPath="%{#cssUrl}" id="tabContainer"> + <sx:div id="tab1" label="Tab 1"> + Local Tab 1 + </sx:div> + <sx:div id="tab2" label="Tab 2"> + Local Tab 2 + </sx:div> +</sx:tabbedpanel> +``` + +## Autocompleter + +### Fixed list + +```jsp +<sx:autocompleter list="{'apple','banana','grape','pear'}" /> +``` + +### Set initial value + +```jsp +<sx:autocompleter list="{'apple','banana','grape','pear'}" value="apple"/> +``` + +### Force valid option (restore option when focus is lost) + +```jsp +<sx:autocompleter list="{'apple','banana','grape','pear'}" forceValidOption="true"/> +``` + +### Using the JSON plugin to generate the values (one of the possible ways) + +The action + +**AutocompleterExample.java** + +```java +public class AutocompleterExample extends ActionSupport { + + public Map<String, String> getOptions() { + Map<String,String> options = new HashMap<String,String>(); + options.put("Florida", "FL"); + options.put("Alabama", "AL"); + + return options; + } +} +``` + +The mapping: + +**struts.xml** + +```xml +<struts> +... + <package name="autocompleter" namespace="/autocompleter" extends="json-default"> + <action name="getStates" class="AutocompleterExample"> + <result type="json"> + <param name="root">options</param></result> + </action> + </package> +... +</struts> +``` + +The JSP (fragment): + +```jsp +<s:url id="optionsUrl" namespace="/autocompleter" action="getStates" /> + +<sx:autocompleter href="%{#optionsUrl}" /> +``` + +### Example action + +When a form containing an autocompleter is submitted, two values will be submitted for each autocompleter, +one for the selected value, and one for its associated key. + +The action: + +**MyAction.java** + +```java +public MyAction extends ActionSupport { + private String optionsKey; + private String options; + + ... +} +``` + +The JSP: + +```jsp +<s:form id="form"> + <sx:autocompleter name="options" label="Options" /> +</s:form> +``` + +### Set initial key and value + +```jsp +<s:url id="optionsUrl" namespace="/autocompleter" action="getStates" /> + +<sx:autocompleter href="%{#optionsUrl}" value="Florida" keyValue="FL"/> +``` + +### Change default key name + +The action: + +**MyAction.java** + +```java +public MyAction extends ActionSupport { + private String superKey; + private String options; + + ... +} +``` + +The JSP: + +```jsp +<s:form id="form"> + <sx:autocompleter keyName="superKey" name="options" label="Options" /> +</s:form> +``` + +### JSON accepted + +for this autocompleter: + +```jsp +<sx:autocompleter name="state" /> +``` + +The following JSON will be accepted: + +**Map(recommended as it is the easiest one to generate)** + +```json +{ + "Alabama" : "AL", + "Alaska" : "AK" +} +``` + +**Array of arrays** + +```json +[ + ["Alabama", "AL"], + ["Alaska", "AK"] +] +``` + +**Array inside object, same name as field** + +```json +{ + "state" : [ + ["Alabama","AL"], + ["Alaska","AK"] + ] +} +``` + +**Map inside object, same name as field** + +```json +{ + "state" : { + "Alabama" : "Alabama", + "Alaska" : "AK" + } +} +``` + +**Array inside object, field in response starts with the name of the autocompleter("state" in this example)** + +```json +{ + "states" : [ + ["Alabama","AL"], + ["Alaska","AK"] + ] +} +``` + +**No name match, use first array found, and hope for the best** + +```json +{ + "Australopithecus" : [ + ["Alabama","AL"], + ["Alaska","AK"] + ] +} +``` + +### Load characters while user types (when text size >= 3) + +```jsp +<sx:autocompleter href="%{#url}" loadOnTextChange="true" loadMinimumCount="3" /> +``` + +### Hide dropdown arrow + +```jsp +<sx:autocompleter href="%{#url}" showDownArrow="false" /> +``` + +### Limit options shown to 3 + +```jsp +<sx:autocompleter href="%{#url}" resultsLimit="3" /> +``` + +### All matching options are shown + +```jsp +<sx:autocompleter href="%{#url}" resultsLimit="-1" /> +``` + +### Set dropdown height and width, in pixels + +```jsp +<sx:autocompleter href="%{#url}" dropdownHeight="180" dropdownWidth="200" /> +``` + +### Disable it when page is loaded + +```jsp +<sx:autocompleter href="%{#url}" disabled="true" /> +``` + +### Disable it/enable it using JavaScript + +```jsp +<script type="text/javascript"> + function enableit() { + var autoCompleter = dojo.widget.byId("auto"); + autoCompleter.enable(); + } + + function disableit() { + var autoCompleter = dojo.widget.byId("auto"); + autoCompleter.disable(); + } +</script> + +<sx:autocompleter id="auto" href="%{#url}" /> +``` + +### Reload options when topic is published + +```jsp +<sx:autocompleter listenTopics="/reload" href="%{#url}" /> +``` + +### Submit form when options are loaded + +```jsp +<s:form id="form"> + <input type="textbox" name="data"> +</s:form> + +<sx:autocompleter formId="form" href="%{#url}" /> +``` + +### Filter fields top be submitted when options are loaded (return true to include) + +```jsp +<script type="text/javascript"> + function filter(input) { + return input.name == "data1"; + } +</script> + +<s:form id="form"> + <input type="textbox" name="data0"> + <input type="textbox" name="data1"> +</s:form> + +<sx:autocompleter formId="form" formFilter="filter" href="%{#url}" /> +``` + +### Link two autocompleters, using topics + +```jsp +<form id="selectForm"> + <sx:autocompleter name="select" list="{'fruits','colors'}" valueNotifyTopics="/changed" /> +</form> + +<sx:autocompleter href="%{#url}" formId="selectForm" listenTopics="/changed" /> +``` + +### Show options, but don't make suggestion (autocomple) in the textbox + +```jsp +<sx:autocompleter autoComplete="false" href="%{#url}" /> +``` + +### Prevent options from loading when page loads + +```jsp +<sx:autocompleter preload="false" href="%{#url}" /> +``` http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/ajax-tags.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/ajax-tags.md b/source/tag-developers/ajax-tags.md new file mode 100644 index 0000000..ee3e60b --- /dev/null +++ b/source/tag-developers/ajax-tags.md @@ -0,0 +1,75 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Ajax Tags + +**Dojo plugin is deprecated and was removed since Struts 2.5** + + +> **Please** check that documentation and the Dojo tag examples in the showcase app of the appropriate Struts 2 version +> before asking questions on the struts-user mailing list! + +## Description + +To use the AJAX tags from 2.1 on you must: + +- Include the Dojo Plugin distributed with Struts 2 in your /WEB-INF/lib folder. +- Add `<%@ taglib prefix="sx" uri="/struts-dojo-tags" %>` to your page. +- Include the [head](head-tag.html) tag on the page, which can be configured for performance or debugging purposes. + +## Handling AJAX Responses + +The following attributes affect the handling of all ajax responses. + +|Attribute|Default Value|Description| +|---------|-------------|-----------| +|parseContent|true|When true, Dojo will parse the response into an XHTML Document Object and traverse the nodes searching for Dojo Widget markup. The parse and traversal is performed prior to inserting the nodes into the DOM. This attribute must be enabled to nest Dojo widgets (dojo tags) within responses. There's significant processing involved to create and parse the document so switch this feature off when not required. Note also that the response must be valid XHTML for cross-browser support and widgets must have unique IDs.| +|separateScripts|true|When true, Dojo will extract the <script> tags from the response, concatenate the extracted code into one block, create a new Function whose body is the extracted code and immediately invoke the function. The invocation is performed after the DOM has been updated with the XHTML. The function is executed within the scope of the widget (that is, the **this** variable points to the widget instance).\ +\ +When false, Dojo will extract the <script> tags from the response, concatenate the extracted code into one block and:\ +\ +\*in IE: invoke window.execScript() on the code\ +\ +\*in other browsers: create a <script> node containing the code and insert that node into the DOM\ +\ +This invocation occurs after the DOM has been updated with the XHTML. Note that scripts may not be executed if it is not valid to create a <script> node in the DOM at the destination.| +|executeScripts|false|When true, Dojo will extract code from the <script> tags from the response and execute it based on the separateScripts value.\ +\ +When false, the XHTML response is inserted into the DOM and <script> nodes are ignored. | + +> It's possible that the updated DOM will not include <script> nodes even though the inline code has been executed. + +Ensure the response is XHTML-compliant (including, for example, thead and tbody tags in tables). + +If you intend to run inline javascript: + +- Ensure the javascript can be concatenated and executed in one block, +- set executeScripts=true, +- set separateScripts=true (the reliable option) + +## Topics + +Most of the AJAX tags use Dojo topics for event notification and communication between them, to learn about topics visit +[Dojo's documentation](http://dojotoolkit.org/book/dojo-book-0-4/part-5-connecting-pieces/event-system/topics) + +## Examples + +Examples can be found on the documentation for each tag in the [UI Tag Reference](ui-tag-reference.html) page, +for additional examples see [Ajax and JavaScript Recipes](ajax-and-javascript-recipes.html) and the Showcase application +distributed with Struts 2. + +## Tags + +- [a](dojo-href-tag.html) +- [autocompleter](dojo-autocompleter-tag.html) +- [bind](dojo-bind-tag.html) +- [datetimepicker](dojo-datetimepicker-tag.html) +- [div](dojo-div-tag.html) +- [head](dojo-head-tag.html) +- [submit](dojo-submit-tag.html) +- [tabbedpanel](dojo-tabbedpanel-tag.html) +- [textarea](dojo-textarea-tag.html) +- [tree](dojo-tree-tag.html) +- [treenode](dojo-treenode-tag.html) http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/ajax-theme.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/ajax-theme.md b/source/tag-developers/ajax-theme.md new file mode 100644 index 0000000..5c2061a --- /dev/null +++ b/source/tag-developers/ajax-theme.md @@ -0,0 +1,431 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# ajax theme + + +The ajax theme is deprecated! + +| + +The ajax theme extends the [xhtml theme](#PAGE_13834) with AJAX features. The theme uses the popular DOJO AJAX/JavaScript toolkit. AJAX features include: + ++ _AJAX Client Side Validation_ + ++ Remote [form](#PAGE_14201) submission support (works with the [submit](#PAGE_14054) tag as well) + ++ An advanced [div](#PAGE_13908) template that provides dynamic reloading of partial HTML + ++ An advanced [a](#PAGE_14027) template that provides the ability to load and evaluate JavaScript remotely + ++ An AJAX-only [tabbedPanel](#PAGE_14222) implementation + ++ A rich pub-sub event model + ++ Interactive autocomplete tag + + (ok) See also: _Ajax tags_ + +__Browser Compatibility__ + +AJAX (as a technology) uses a browser-side scripting component that varies between browers (and sometimes versions). To hide those differences from the developer, we utilize the dojo toolkit ([http://www.dojotoolkit.org](http://www.dojotoolkit.org)). Several browsers are supported by dojo, and any UI's created with the ajax theme should act the same way for supported browsers. The supported browsers are: + ++ IE 5.5\+ + ++ FF 1.0\+ + ++ Latest Safari (on up-to-date OS versions) + ++ Latest Opera + ++ Latest Konqueror + +__Extending the AJAX Theme__ + +The wrapping technique utilized by the ajax theme is much like [xhtml theme](#PAGE_13834), but the + +~~~~~~~ +controlheader.ftl +~~~~~~~ + is a wee bit different. + + +~~~~~~~ + +<#if parameters.label?if_exists != ""> + <#include "/${parameters.templateDir}/xhtml/controlheader.ftl" /> +</#if> +<#if parameters.form?exists && parameters.form.validate?default(false) == true> + <#-- can't mutate the data model in freemarker --> + <#if parameters.onblur?exists> + ${tag.addParameter('onblur', "validate(this);${parameters.onblur}")} + <#else> + ${tag.addParameter('onblur', "validate(this);")} + </#if> +</#if> + +~~~~~~~ + +The header provides for _AJAX Client Side Validation_ by checking if the + +~~~~~~~ +validate +~~~~~~~ + attribute is set to true. If it is, a validation request is made on each + +~~~~~~~ +onblur +~~~~~~~ + event for a HTML [Struts Tags](#PAGE_14248). Some people don't like the + +~~~~~~~ +onblur +~~~~~~~ + behavior; they would rather a more advanced timer (say, 200ms) be kicked off after every keystroke. You can override this template and provide that type of behavior if you would like. + +__Special Interest__ + +Three ajax_xhtml templates of special interest are + +~~~~~~~ +head +~~~~~~~ +, + +~~~~~~~ +div +~~~~~~~ +, and + +~~~~~~~ +a +~~~~~~~ +. + + + +| Especially with the ajax theme, it is important to use the [head](#PAGE_13997) tag. (See the _ajax head template_ for more information.) Without it, AJAX support may not be set up properly. + +| + ++ _ajax head template_ + ++ _ajax div template_ + ++ _ajax a template_ + + (ok) In addition to these templates, be familiar with the _ajax event system_ provided by the framework and Dojo. + +__ajax a template__ + + +The ajax theme is experimental. Feedback is appreciated. + +| + +The ajax a template is used to make asynchronous calls to the server when the user clicks on the a href link. It is useful when you need to communicate information back to the application from the UI, without requiring the entire page to be re-rendered. An example would be removing an item from a list. + +The _preInvokeJS_ attribute is used to determine whether the URL specified should be called or not, and must contain Javascript that returns _true_ or _false_ . If you want to call a JavaScript function, use the format preInvokeJS='yourMethodName(data,type)'. An example would be to show a confirm dialog to the user to double check whether they want to remove a user from a list. + +**Remember**: the content returned by the _href_ attribute must be JavaScript. That JavaScript will then be evaluated within the webpage. If you only wish to publish an event to the topic specified, then simply return no result (or NONE) from your action and utilize the _notifyTopics_ attribute to specific the topic names. + +For an example of the interaction between the [div](#PAGE_13908) tag and the [a](#PAGE_14027) tag using the topic pub/sub model, see the examples in the _ajax div template_ . + +__ajax div template__ + + +The Ajax theme is experimental. Feedback is appreciated. + +| + +The ajax [div](#PAGE_13908) template provides a much more interesting div rendering option that the other themes do. Rather than simply rendering a + +~~~~~~~ +<div> +~~~~~~~ + tag, this template relies on advanced AJAX features provided by the [Dojo Toolkit](http://dojotoolkit.org)^[http://dojotoolkit.org]. While the [div](#PAGE_13908) tag could be used outside of the [ajax theme](#PAGE_14205), it is usually not very useful. See the [div](#PAGE_13908) tag for more information on what features are provided. + +__Features__ + +The remote div has a few features, some of which can be combined with the [a](#PAGE_14027) tag and the _ajax a template_ . These uses are: + ++ Retrieve remote data + ++ Initialize the div with content before the remote data is retrieved + ++ Display appropriate error and loading messages + ++ Refresh data on a timed cycle + ++ Listen for events and refresh data + ++ JavaScript control support + +__Retrieve Remote Data__ + +The simplest way to use the div tag is to provide an _href_ attribute. For example: + + +~~~~~~~ + +<saf:div theme="ajax" id="weather" href="http://www.weather.com/weather?zip=97239"/> + +~~~~~~~ + +What this does after the HTML page is completely loaded, the specified URL will be retrieved asynchronously in the browser. The entire contents returned by that URL will be injected in to the div. + +__Initializing the Div__ + +Because the remote data isn't loaded immediately, it is sometimes useful to have some placeholder content that exists before the remote data is retrieved. The content is essentially just the body of the div element. For example: + + +~~~~~~~ + +<saf:div theme="ajax" id="weather" href="http://www.weather.com/weather?zip=97239";> + Placeholder... +</saf:div> + +~~~~~~~ + +If you wish to load more complex initial data, you can use the [action](#PAGE_14034) tag and the _executeResult_ attribute: + + +~~~~~~~ + +<saf:div theme="ajax" id="weather" href="http://www.weather.com/weather?zip=97239";> + <ww:action id="weather" name="weatherBean" executeResult="true"> + <ww:param name="zip" value="97239"/> + </ww:action> +</saf:div> + +~~~~~~~ + +__Loading and Error Messages__ + +If you'd like to display special messages when the data is being retrieved or when the data cannot be retrieved, you can use the _errorText_ and _loadingText_ attributes: + + +~~~~~~~ + +<saf:div theme="ajax" id="weather" href="http://www.weather.com/weather?zip=97239"; + loadingText="Loading weather information..." + errorText="Unable to contact weather server"> + Placeholder... +</saf:div> + +~~~~~~~ + +__Refresh Timers__ + +Another feature this div template provides is the ability to refresh data on a timed basis. Using the _updateFreq_ and the _delay_ attributes, you can specify how often the timer goes off and when the timer starts (times in milliseconds). For example, the following will update every minute after a two second delay: + + +~~~~~~~ + +<saf:div theme="ajax" id="weather" href="http://www.weather.com/weather?zip=97239"; + loadingText="Loading weather information..." + errorText="Unable to contact weather server"> + delay="2000" + updateFreq="60000" + Placeholder... +</saf:div> + +~~~~~~~ + +__Listening for Events__ + +The [a](#PAGE_14027) tag (specifically the _ajax a template_ ) and the div tag support an _ajax event system_ , providing the ability to broadcast events to topics. You can specify the **topics** to listen to using a comma separated list in the _listenTopics_ attribute. What this means is that when a topic is published, usually through the _ajax a template_ , the URL specified in the _href_ attribute will be re-requested. + + +~~~~~~~ + +<saf:div theme="ajax" id="weather" href="http://www.weather.com/weather?zip=97239"; + loadingText="Loading weather information..." + errorText="Unable to contact weather server" + listenTopics="weather_topic,some_topic"> + Placeholder... +</saf:div> +<saf:a id="link1" + theme="ajax" + href="refreshWeather.action" + notifyTopics="weather_topic,other_topic" + errorText="An Error ocurred">Refresh</saf:a> + +~~~~~~~ + +__JavaScript Support__ + +There are also javascript functions to refresh the content and stop/start the refreshing of the component. For the remote div with the component id "remotediv1": + +To start refreshing use the javascript: + + +~~~~~~~ + +remotediv1.startTimer(); + +~~~~~~~ + +To stop refreshing use the javascript: + + +~~~~~~~ + +remotediv1.stopTimer(); + +~~~~~~~ + +To refresh the content use the javascript: + + +~~~~~~~ + +remotediv1.refresh(); + +~~~~~~~ + +__JavaScript Examples:__ + +To further illustrate these concepts here is an example. Say you want to change the url of a div at runtime via javascript. Here is what you need to do: + +What you will need to do is add a JS function that listens to a JS event that publishes the id from the select box that was selected. It will modify the URL for the div (adding the id so the correct data is obtained) and then bind() the AJAX div so it refreshes. + + +~~~~~~~ + +<saf:head theme="ajax" /> + +<script type="text/javascript"> + function updateReports(id) { + var reportDiv= window['reportDivId']; + reportDiv.href = '/../reportListRemote.action?selectedId='+id; + reportDiv.refresh(); + } + dojo.event.topic.getTopic("updateReportsListTopic").subscribe(null, "updateReports"); +</script> + +<form ... > +<saf:select .... onchange="javascript: dojo.event.topic.publish("updateReportsListTopic", this.value); " /> + +<saf:div id="reportDivId" theme="ajax" href="/.../reportListRemote.action" > + Loading reports... +</saf:div> +</form> + +~~~~~~~ + +__ajax event system__ + +As you may have seen with the _ajax div template_ and _ajax a template_ , the framework and Dojo provide a nice way to subscribe and notify of topics from within the browser. A benifit of using Dojo as the basis of many of these components is being able to loosely couple UI components. There are two attributes of importance: + +~~~~~~~ +listenTopics +~~~~~~~ + and + +~~~~~~~ +notifyTopics +~~~~~~~ +. + ++ If a component has a + +~~~~~~~ +notifyTopics +~~~~~~~ + attribute, then after the processing has been completed a message with be published to the topic names supplied as a value (comma delimited). + ++ If a component has a + +~~~~~~~ +listenTopics +~~~~~~~ + attribute, then when a message is published to the topic names supplied as a value (comma delimited), the component will perform custom tag-specific logic ( i.e a DIV tag will re-fresh its content). + +As well as this, you can publish and subscribe to topic names with javascript code. To publish to the + +~~~~~~~ +topic_name +~~~~~~~ + topic: + + +~~~~~~~ + +dojo.event.topic.publish("topic_name", "content"); + +~~~~~~~ + +The topic_name attribute is required, the content attribute is not and most elements are triggered without having this attribute. See the _ajax div template_ for an example of this type of interaction. + +To subscribe to the _topic_name_ topic: + + +~~~~~~~ + +function doSomethingWithEvent(data) { +... +} + +dojo.event.topic.getTopic("topic_name").subscribe(null, "doSomethingWithEvent"); + +~~~~~~~ + +The + +~~~~~~~ +subscribe +~~~~~~~ + method takes 2 parameters, the first is the JavaScript object variable (or null if the function is not from an object) and the second is the name of the function to call when an event is recieved on the topic. + +__ajax head template__ + +The ajax [head](#PAGE_13997) template builds upon the _xhtml head template_ by providing additional JavaScript includes for the [Dojo Toolkit](http://dojotoolkit.org)^[http://dojotoolkit.org], which is used by the _ajax a template_ , _ajax div template_ , and the _ajax tabbedPanel template_ . It is required to use this tag, + +~~~~~~~ +<ww:head theme="ajax"/> +~~~~~~~ +, in your HTML + +~~~~~~~ +<head> +~~~~~~~ + block if you wish to use AJAX feature. The contents of **head.ftl** are: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/plugins/dojo/src/main/resources/template/ajax/head.ftl} +~~~~~~~ + + + +| If you are having trouble getting the AJAX theme to work, you should include the above JavaScript in your page manually, changing "isDebug: false" to "isDebug: true". This will log out debugging information directly to the screen. + +| + +Note that Dojo is configured to use the same character encoding specified in _struts.properties_ , typically UTF-8. For a simple example of how to use the [head](#PAGE_13997) tag with the AJAX theme, simply do the following in your HTML: + + +~~~~~~~ +{snippet:id=common-include|lang=xml|url=struts2/apps/showcase/src/main/webapp/ajax/commonInclude.jsp} +~~~~~~~ + + +> + +> + +> The above sample is from Struts trunk; for 2.0.6 you should use <s:head debug="true"/>. + +> + +__ajax tabbedPanel template__ + +TODO: Describe the Ajax TabbedPanel template + +__ajax submit template__ + +TODO: Describe the Ajax Submit template + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/append-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/append-tag.md b/source/tag-developers/append-tag.md new file mode 100644 index 0000000..fad8490 --- /dev/null +++ b/source/tag-developers/append-tag.md @@ -0,0 +1,30 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# append + +Please make sure you have read the [Tag Syntax](tag-syntax.html) document and understand how tag attribute syntax works. + +## Description + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.AppendIterator} +~~~~~~~ + +## Parameters + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/append.html} +~~~~~~~ + +## Example + +~~~~~~~ +{snippet:id=code|lang=java|javadoc=true|url=org.apache.struts2.components.AppendIterator} +~~~~~~~ + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=xml|url=org.apache.struts2.components.AppendIterator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/bean-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/bean-tag.md b/source/tag-developers/bean-tag.md new file mode 100644 index 0000000..c206d63 --- /dev/null +++ b/source/tag-developers/bean-tag.md @@ -0,0 +1,30 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# bean + +Please make sure you have read the [Tag Syntax](tag-syntax.html) document and understand how tag attribute syntax works. + +## Description + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.Bean} +~~~~~~~ + +## Parameters + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/bean.html} +~~~~~~~ + +## Examples + +~~~~~~~ +{snippet:id=examples|javadoc=true|lang=xml|url=org.apache.struts2.components.Bean} +~~~~~~~ + +~~~~~~~ +{snippet:id=examplesdescription|javadoc=true|url=org.apache.struts2.components.Bean} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/cewolf-charts-using-velocity-templates.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/cewolf-charts-using-velocity-templates.md b/source/tag-developers/cewolf-charts-using-velocity-templates.md new file mode 100644 index 0000000..b2f740c --- /dev/null +++ b/source/tag-developers/cewolf-charts-using-velocity-templates.md @@ -0,0 +1,127 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# CeWolf charts using Velocity templates + +#####Setup CeWolf##### + +**This currently only works with the most recent CVS version of WebWork but should be available in the upcoming 2.0 beta2** + +1. Go to [http://cewolf.sourceforge.net](http://cewolf.sourceforge.net) and grab a stable release of CeWolf (at the time of writing, the unstable builds do not work with WebWork). + +2. Edit your webwork.properties file and add "de.laures.cewolf.taglib.tags" to the property "webwork.velocity.tag.path" + +Lastly add the CeWolf servlet to web.xml: + + +~~~~~~~ + +<servlet> + <servlet-name>CewolfServlet</servlet-name> + <servlet-class>de.laures.cewolf.CewolfRenderer</servlet-class> +</servlet> + +<servlet-mapping> + <servlet-name>CewolfServlet</servlet-name> + <url-pattern>/cewolf/*</url-pattern> +</servlet-mapping> + +~~~~~~~ + +#####Create a DatasetProducer##### + +This is the default DatasetProducer from the CeWolf tutorial. + + +~~~~~~~ + +import java.io.Serializable; +import java.util.Date; +import java.util.Map; + +import org.jfree.data.DefaultCategoryDataset; + +import de.laures.cewolf.DatasetProduceException; +import de.laures.cewolf.DatasetProducer; + +public class PageViewCountData implements DatasetProducer, Serializable { + + // These values would normally not be hard coded but produced by + // some kind of data source like a database or a file + private final String[] categories = {"mon", "tue", "wen", "thu", "fri", "sat", "sun"}; + private final String[] seriesNames = {"cewolfset.jsp", "tutorial.jsp", "testpage.jsp", "performancetest.jsp"}; + private final Integer[] [] values = new Integer[OS:seriesNames.length] [OS:categories.length]; + + public Object produceDataset(Map params) throws DatasetProduceException { + DefaultCategoryDataset dataset = new DefaultCategoryDataset(); + for (int series = 0; series < seriesNames.length; series ++) { + int lastY = (int)(Math.random() * 1000 + 1000); + for (int i = 0; i < categories.length; i++) { + final int y = lastY + (int)(Math.random() * 200 - 100); + lastY = y; + dataset.addValue((double)y, seriesNames[OS:series], categories[i]); + } + } + return dataset; + } + + public boolean hasExpired(Map params, Date since) { + return (System.currentTimeMillis() - since.getTime()) > 5000; + } + + public String getProducerId() { + return "PageViewCountData DatasetProducer"; + } +} + +~~~~~~~ + +#####Create the Velocity template##### + +With the new WebWork refactorings, nested JSP tags with arbitrary parameters can be used, so we convert the CeWolf tutorial JSP script to Velocity. + + +~~~~~~~ + +<jsp:useBean id="pageViews" class="de.laures.cewolf.example.PageViewCountData"/> +<cewolf:chart + id="line" + title="Page View Statistics" + type="line" + xaxislabel="Page" + yaxislabel="Views"> + <cewolf:data> + <cewolf:producer id="pageViews"/> + </cewolf:data> +</cewolf:chart> + +<cewolf:img chartid="line" renderer="cewolf" width="400" height="300"/> + +~~~~~~~ + +In Velocity it looks like this: + + +~~~~~~~ + +#set( $pageViews = $stack.findValue("new com.PageViewCountData()") ) +$req.session.setAttribute("pageViews", $pageViews ) + +#bodytag( SimpleChart "id=line" "title=Page View Statistics" "type=line" "xaxislabel=Page" "yaxslabel=Views" ) + #bodytag( Data ) + #tag( Producer "id=pageViews" ) + #end +#end + +#tag( ChartImg "chartid=line" "renderer=cewolf" "width=400" "height=300" ) + +~~~~~~~ + +As you may notice, CeWolf looks up it's DatasetProducer in the request attributes - it has no knowledge of the Velocity context. That's why we call \$req.session.setAttribute(). The other attributes (such as the chartid) will be set by CeWolf, so we don't need to care about them. + +#####Setup an action to disply the template##### + +Now you should be able to fire up an action in the usual way with this template as the result and a nice chart should appear. + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/css-xhtml-theme.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/css-xhtml-theme.md b/source/tag-developers/css-xhtml-theme.md new file mode 100644 index 0000000..eabf779 --- /dev/null +++ b/source/tag-developers/css-xhtml-theme.md @@ -0,0 +1,149 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# css_xhtml theme + +The css_xhtml theme provides all the basics that the [simple theme](#PAGE_14291) provides and adds several features. + ++ Standard two-column CSS-based layout, using + +~~~~~~~ +<div> +~~~~~~~ + for the HTML [Struts Tags](#PAGE_14248) ([form](#PAGE_14201), [textfield](#PAGE_13912), [select](#PAGE_14127), etc) + ++ Labels for each of the HTML [Struts Tags](#PAGE_14248), placed according to the CSS stylesheet + ++ _Validation_ and error reporting + ++ _Pure JavaScript Client Side Validation_ using 100% JavaScript on the browser + +__Wrapping the Simple Theme__ + +The xhtml theme uses the "wrapping" technique described by [Extending Themes](#PAGE_13962). Let's look at how the HTML tags are wrapped by a standard header and footer. For example, in the [textfield](#PAGE_13912) template, + +~~~~~~~ +text.ftl +~~~~~~~ +, the + +~~~~~~~ +controlheader.ftl +~~~~~~~ + and + +~~~~~~~ +controlfooter.ftl +~~~~~~~ + templates are wrapped around the simple template. + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/simple/text.ftl} +~~~~~~~ + +__CSS XHTML theme header__ + +The header used by the HTML tags in the css_xhtml theme is complicated. Unlike the [xhtml theme](#PAGE_13834), the CSS theme does not use a + +~~~~~~~ +labelposition +~~~~~~~ + attribute. Instead, the label position is defined by CSS rules. + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/css_xhtml/controlheader.ftl} +~~~~~~~ + +Note that the + +~~~~~~~ +fieldErrors +~~~~~~~ +, usually caused by _Validation_ , are displayed in a + +~~~~~~~ +div +~~~~~~~ + block before the element is displayed. + +__CSS XHTML theme footer__ + +And the + +~~~~~~~ +controlfooter.ftl +~~~~~~~ + contents: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/css_xhtml/controlfooter.ftl} +~~~~~~~ + +__Special Interest__ + +Two css_xhtml templates of special interest are + +~~~~~~~ +head +~~~~~~~ + and + +~~~~~~~ +form +~~~~~~~ +. + +__Head template__ + +The css_xhtml [head](#PAGE_13997) template is similar to the xhtml head template. The difference is that CSS is used to provide the layout. + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/css_xhtml/head.ftl} +~~~~~~~ + +The head includes a style sheet. + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/css_xhtml/styles.css} +~~~~~~~ + +__Form template__ + +The css_xhtml [form](#PAGE_14201) template is almost exactly like the _xhtml form template_ , including support for _Pure JavaScript Client Side Validation_ . The difference is that instead of printing out an opening and closing + +~~~~~~~ +<table> +~~~~~~~ + element, there are no elements. Instead, the CSS rules for the individual HTML tags are assumed to handle all display logic. However, as noted, client-side validation is still supported. + +__css_xhtml form template__ + +The css_xhtml [form](#PAGE_14201) template is almost exactly like the _xhtml form template_ , including support for _Pure JavaScript Client Side Validation_ . The only difference is that instead of printing out an opening and closing + +~~~~~~~ +<table> +~~~~~~~ + element, there are no elements. Instead, the CSS rules for the individual HTML tags are assumed to handle all dislay logic. However, as noted, client side validation is still supported. + +__css_xhtml head template__ + +The css_xhtml [head](#PAGE_13997) template is very similar to the _xhtml head template_ . The only difference is that CSS that is included is specifically designed to provide the layout for the [css_xhtml theme](#PAGE_14215). The contents of **head.ftl** are: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/css_xhtml/head.ftl} +~~~~~~~ + +The contents of **styles.css** are: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/css_xhtml/styles.css} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/date-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/date-tag.md b/source/tag-developers/date-tag.md new file mode 100644 index 0000000..90f1e8d --- /dev/null +++ b/source/tag-developers/date-tag.md @@ -0,0 +1,30 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# date + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.Date} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/date.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.components.Date} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/debug-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/debug-tag.md b/source/tag-developers/debug-tag.md new file mode 100644 index 0000000..8ee3c48 --- /dev/null +++ b/source/tag-developers/debug-tag.md @@ -0,0 +1,8 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# debug + +Outputs the content of the Value Stack. http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/else-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/else-tag.md b/source/tag-developers/else-tag.md new file mode 100644 index 0000000..21a725d --- /dev/null +++ b/source/tag-developers/else-tag.md @@ -0,0 +1,35 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# else + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.Else} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/else.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.components.Else} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/elseif-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/elseif-tag.md b/source/tag-developers/elseif-tag.md new file mode 100644 index 0000000..88ec177 --- /dev/null +++ b/source/tag-developers/elseif-tag.md @@ -0,0 +1,35 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# elseif + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.ElseIf} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/elseif.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.components.ElseIf} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/extending-themes.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/extending-themes.md b/source/tag-developers/extending-themes.md new file mode 100644 index 0000000..f67c436 --- /dev/null +++ b/source/tag-developers/extending-themes.md @@ -0,0 +1,132 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Extending Themes + + +Most often, an application may just need to override a template (see [Template Loading](#PAGE_13817)) so that a certain control renders differently. Or, an application may need to add a new template to an existing theme. Other times, you might want to create an entirely new theme, perhaps because you are building a rich set of unique and reusable templates for your organization. + +There are three ways to create new themes: + ++ Create a new theme from scratch (**hard!**) + ++ Wrap an existing theme + ++ Extend an existing theme + +__Creating a New Theme from Scratch__ + + +It's probably never a good idea to create a new theme from scratch. Instead, use the [simple theme](#PAGE_14291) as a starting point. The simple theme provides just enough foundation to make it easy to create new controls by extending or wrapping the basic controls. Before starting a new theme, be sure to review the source templates for all of the provided themes. The existing themes are your best guide to creating new themes. + +| + +__Wrapping an Existing Theme__ + +The [xhtml theme](#PAGE_13834) provides several good examples of the "wrapping" technique. The [simple theme](#PAGE_14291) renders the basic control. The xhtml theme "dresses up" many of the controls by adding a header and footer. + +**Wrapping a control** + + +~~~~~~~ +<#include "/${parameters.templateDir}/${parameters.expandTheme}/controlheader.ftl" /> +<#include "/${parameters.templateDir}/simple/xxx.ftl" /> +<#include "/${parameters.templateDir}/${parameters.expandTheme}/controlfooter.ftl" /> + +~~~~~~~ + +Wrapping is a great way to augment the basic HTML elements provided by the simple theme. + +__Extending an Existing Theme__ + +One benefit of object-orientated programming is that it lets us "design by difference." We can extend an object and code only the behaviour that changes. Themes provide a similar capability. The subdirectory that hosts a theme can contain a + +~~~~~~~ +theme.properties +~~~~~~~ + file. A + +~~~~~~~ +parent +~~~~~~~ + entry can be added to the property file to designate a theme to extend. The [ajax theme](#PAGE_14205) extends the [xhtml theme](#PAGE_13834) using this technique. + +**/template/ajax/theme.properties** + + +~~~~~~~ +parent = xhtml + +~~~~~~~ + +An extended theme does not need to implement every single template that the [Struts Tags](#PAGE_14248) expect. It only needs to implement the templates that change. The other templates are loaded from the parent template. + +__Special parameters__ + +[UIBean](http://struts.apache.org/development/2.x/struts2-core/apidocs/org/apache/struts2/components/UIBean.html)^[http://struts.apache.org/development/2.x/struts2-core/apidocs/org/apache/struts2/components/UIBean.html] provides few special parameters which can be used to build a new template (they are already used in + +~~~~~~~ +xhtml +~~~~~~~ + and + +~~~~~~~ +css_xhtml +~~~~~~~ + theme): + ++ + +~~~~~~~ +templateDir +~~~~~~~ + - current value of templateDir parameter, see [Selecting Template Directory](#PAGE_14227) + ++ + +~~~~~~~ +theme +~~~~~~~ + - used theme, see [Selecting Themes](#PAGE_14016) + ++ + +~~~~~~~ +template +~~~~~~~ + - name of the template file to use (i.e. text) + ++ + +~~~~~~~ +themeExpansionToken +~~~~~~~ + - special token used to indicate to search for a template also in parent theme (when used with + +~~~~~~~ +<#include /> +~~~~~~~ + directive) + ++ + +~~~~~~~ +expandTheme +~~~~~~~ + - tells internal template loader mechanism to try load template from current theme and then from parent theme (and parent theme, and so on) + +Using + +~~~~~~~ +expandTheme +~~~~~~~ + parameter allows to override only some parts of the theme's templates, e.g. css.ftl. You can define a new theme (set theme.properties) and override just single file. + +\${parameters.expandTheme} is a recurrence which tells ThemeManager to load template from current theme and then from parent theme (defined in theme.properties) and so on. + +Please also notice that the ThemeManager builds list of possible templates based on current theme and inherited themes (/template/custom/textarea.ftl, /template/xhtml/textarea.ftl, /template/simple/textarea.ftl). This is also true for templates which are loaded via \${parameters.expandTheme}. + + (ok) See also example _Struts 2 Themes_ or [Creating a Theme in Struts 2](http://www.vitarara.org/cms/struts_2_cookbook/creating_a_theme)^[http://www.vitarara.org/cms/struts_2_cookbook/creating_a_theme] (Mark Menard) + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/form-tags.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/form-tags.md b/source/tag-developers/form-tags.md new file mode 100644 index 0000000..d2575ee --- /dev/null +++ b/source/tag-developers/form-tags.md @@ -0,0 +1,264 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Form Tags + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +Within the form tags, there are two classes of tags: the form tag itself, and all other tags, which make up the individual form elements. The behavior of the form tag is different than the elements enclosed within it. + +__Form Tag Themes__ + +As explained in [Themes and Templates](#PAGE_14247), the HTML Tags (which includes Form Tags) are all driven by templates. Templates are grouped together to create themes. The framework bundles three themes in the distribution. + +|simple|Sometimes _too_ simple| +|------|-----------------------| +|xhtml|Extends simple|(default)| +|ajax|Extends xhtml| + +The predefined themes can be used "as is" or customized. + + + +| The xhtml theme renders out a two-column table. If a different layout is needed, do _not_ write your own HTML. Create a new theme or utilize the simple theme. + +| + +__Simple theme caveats__ + +The downside of using the simple theme is that it doesn't support as many of the attributes that the other themes do. For example, the + +~~~~~~~ +label +~~~~~~~ + attribute does nothing in the simple theme, and the automatic display of error messages is not supported. + +__Common Attributes__ + +All the form tags extend the UIBean class. This base class provides a set of common attributes, that can be grouped in to three categories: + +~~~~~~~ +templated-related +~~~~~~~ +, javascript-related, and general attributes. The individual attributes are documented on each tag's reference page. + +In addition to the common attributes, a special attribute exists for all form element tags: + +~~~~~~~ +form +~~~~~~~ + (\${parameters.form}). The + +~~~~~~~ +form +~~~~~~~ + property represents the attributes used to render the form tag, such as the form's id. In a template, the form's ID can be found by calling \${parameters.form.id}. + +__Template-Related Attributes__ + + + +~~~~~~~ +{snippet:id=templateRelatedAttributes|javadoc=true|url=org.apache.struts2.components.UIBean} +~~~~~~~ + +__Javascript-Related Attributes__ + + + +~~~~~~~ +{snippet:id=javascriptRelatedAttributes|javadoc=true|url=org.apache.struts2.components.UIBean} +~~~~~~~ + +__Tooltip Related Attributes__ + + + +~~~~~~~ +{snippet:id=tooltipattributes|javadoc=true|url=org.apache.struts2.components.UIBean} +~~~~~~~ + +__General Attributes__ + + + +~~~~~~~ +{snippet:id=generalAttributes|javadoc=true|url=org.apache.struts2.components.UIBean} +~~~~~~~ + + + +| Some tag attributes may not be utilized by all, or any, of the templates. For example, the form tag supports the tabindex attribute, but none of the themes render the tabindex. + +| + +__Value/Name Relationship__ + +In many of the tags (except for the form tag) there is a unique relationship between the + +~~~~~~~ +name +~~~~~~~ + and + +~~~~~~~ +value +~~~~~~~ + attributes. The + +~~~~~~~ +name +~~~~~~~ + attribute provides the name for the tag, which in turn is used as the control attribute when the form is submitted. The value submitted is bound to the + +~~~~~~~ +name +~~~~~~~ +. In most cases, the + +~~~~~~~ +name +~~~~~~~ + maps to a simple JavaBean property, such as "postalCode". On a submit, the value would be set to the property by calling the + +~~~~~~~ +setPostalCode +~~~~~~~ + mutator. + +Likewise, a form control could be populated by calling a JavaBean accessor, like + +~~~~~~~ +getPostalCode +~~~~~~~ +. In the expression language, we can refer to the JavaBean property by name. An expression like "%{postalCode}" would in turn call + +~~~~~~~ +getPostalCode +~~~~~~~ +. + + +~~~~~~~ +<@s.form action="updateAddress"> + <@s.textfield label="Postal Code" name="postalCode" value="%{postalCode}"/> + ... +</@s.form> + +~~~~~~~ + +However, since the tags imply a relationship between the + +~~~~~~~ +name +~~~~~~~ + and + +~~~~~~~ +value +~~~~~~~ +, the + +~~~~~~~ +value +~~~~~~~ + attribute is optional. If a + +~~~~~~~ +value +~~~~~~~ + is not specified, by default, the JavaBean accessor is used instead. + + +~~~~~~~ +<@s.form action="updateAddress"> + <@s.textfield label="Postal Code" name="postalCode"/> + ... +</@s.form> + +~~~~~~~ + +While most attributes are exposed to the underlying templates as the same key as the attribute (\${parameters.label}), the + +~~~~~~~ +value +~~~~~~~ + attribute is not. Instead, it can be accessed via the + +~~~~~~~ +nameValue +~~~~~~~ + key (\${parameters.nameValue}). The + +~~~~~~~ +nameValue +~~~~~~~ + key indicates that the value may have been generated from the + +~~~~~~~ +name +~~~~~~~ + attribute rather than explicitly defined in the + +~~~~~~~ +value +~~~~~~~ + attribute. + +__ID Name Assignment__ + +All form tags automatically assign an ID to the control, but the ID can be overridden if needed. + +|Forms|The default ID is the action name. For example, "updateAddress".| +|-----|------------------------------------------------------------------| +|Controls|The default ID is the form's name concatenated with the tag name. For example, "updateAddress_postalCode".| + +__Form labelposition propagation__ + +When + +~~~~~~~ +labelposition +~~~~~~~ + attribute was defined for + +~~~~~~~ +<s:form> +~~~~~~~ + tag it will be propagated to all form elements, but if form element defines its own + +~~~~~~~ +labelposition +~~~~~~~ + it will take precedence over + +~~~~~~~ +<s:form> +~~~~~~~ +'s attribute. Since 2.3.17. + +__Required Attribute__ + +The + +~~~~~~~ +required +~~~~~~~ + attribute on many UI tags defaults to true only if you have client-side validation enabled, and a validator is associated with that particular field. + +__Tooltip__ + + + +~~~~~~~ +{snippet:id=tooltipdescription|javadoc=true|url=org.apache.struts2.components.UIBean} +~~~~~~~ + + +~~~~~~~ +{snippet:id=tooltipexample|lang=xml|javadoc=true|url=org.apache.struts2.components.UIBean} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/freemarker-tags.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/freemarker-tags.md b/source/tag-developers/freemarker-tags.md new file mode 100644 index 0000000..8a503a7 --- /dev/null +++ b/source/tag-developers/freemarker-tags.md @@ -0,0 +1,147 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# FreeMarker Tags +{:.no_toc} + +* Will be replaced with the ToC, excluding a header +{:toc} + +FreeMarker tags are extensions of the generic [Struts Tags](struts-tags.html) provided by the framework. You can jump +right in just by knowing the generic structure in which the tags can be accessed: + +```html +<@s.tag> ...</@s.tag> +``` + +, where `tag` is any of the [tags](tags.html) supported by the framework. + +For example, in JSP you might create a form using Struts tags. + +**JSP Form** + +```jsp +<s:form action="updatePerson"> + <s:textfield label="First name" name="firstName"/> + <s:submit value="Update"/> +</s:form> +``` + +In FreeMarker the same form can also be built using Struts tags. + +**FTL Form** + +```html +<@s.form action="updatePerson"> + <@s.textfield label="First name" name="firstName"/> + <@s.submit value="Update"/> +</@s.form> +``` + +**But, wait there's more!** + +Aside from doing everything that the JSP tags do, the FTL tags boast additional features that you can use to make your +pages even easier to code. You can even invoke third-party JSP taglibs as if there were native FTL tags. + +## Attributes and Parameters + +Unlike older versions of JSP (in which the [JSP Tags](jsp-tags.html) are based), FreeMarker allows for _dynamic attributes_, +much like JSP 2.0. You can supply attributes to the tags that the tag doesn't explicitedly support. Those attributes +that cannot be applied directly to the tag object will be set to the tag's general-purpose `parameters` Map. + +Suppose we wanted to build an URL in a JSP. The URL needs to take an arbitary parameter to the query string, +that (being arbitary) isn't specified on the URL tag. In a JSP, we'd have to use the `url` and `param` tags together. + +**Creating a URL with a query string (JSP)** + +```jsp +<s:url value="somePage"> + <s:param name="personId" value="%{personId}"/> +</s:url> +``` + +In FreeMarker, we can pass the arbitrary parameter directly and create the URL in one simple statement. + +**Creating a URL with a query string (FTL)** + +```html +<@s.url value="somePage" personId="${personId}"/> +``` + +### Using inline attributes with templates + +Suppose you created a "three column" theme to replace the typical two column theme (xhtml). You might want an additional +parameter to display in the third column called "description". Using FreeMarker, you can just pop the description +attribute into the textfield tag, no fuss, no muss. + +**Passing an attribute to the template** + +```html +<@s.form action="updatePerson"> + <@s.textfield label="First name" name="firstName" description="..."/> + <@s.submit value="Update"/> +</@s.form> +``` + +In the new template, the description is referenced via the parameters Map: `${parameters.description}`. + +> For simple cases, inline attributes are much easier to use than the param} tag. But, the `param` tag is more flexible +> than inline attributes for advanced use cases. For example, `param` can take the entire body of the tag and apply +> that as the `value` attribute. + +## Attribute Types + +Remember that all tag attributes must first be set as Strings - they are then later evaluated (using [OGNL](ognl.html)) +to a different type, such as List, int, or boolean. This generally works just fine, but it can be limiting when using +FreeMarker which provides more advanced ways to apply attributes. Suppose the following example: + +```html +<@s.select label="Foo label - ${foo}" name="${name}" list="%{{1, 2, 3}}"/> +``` + +What will happen here is that each attribute will be evaluated to a String as best it can. This may involve calling the +`toString` method on the internal FreeMarker objects. In this case, all objects will end up being exactly what you would +expect. Then, when the tag runs, the `list` attribute will be converted from a String to a List using [OGNL](ogn.html)'s +advanced collection support. + +But suppose you wish to use FreeMarker's list or hash support instead? You can do this: + +```html +<@s.select label="Foo label - ${foo}" name="${name}" list=[1, 2, 3]/> +``` + +Notice that the list attribute no longer has quotes around it. Now it will come in to the tag as an object that can't +easily be converted to a String. Normally, the tag would just call `toString`, which would return `[1, 2, 3]` and be +unable to be converted back to a List by OGNL. Rather than go through all this back and forth, the frameworks's FreeMarker +tag support will recognize collections and not pass them through the normal tag attribute. Instead, the framework will +set them directly in the `parameters` Map, ready to be consumed by the template. + +In the end, everything tends to do what you would expect, but it can help to understand the difference of when OGNL is +being used and when it isn't, and how attribute types get converted. + +## JSP Tag Support + +While the framework provides native FreeMarker Tags, you might wish to use other third-party tags that are only available +for JSP. Fortunately, FreeMarker has the ability to run JSP tags. To do so, you must include the JspSupportServlet in +the application's `web.xml`, as this allows the FreeMarker integration to get access to the required objects needed +to emulate a JSP taglib container. + +**Adding JspSupportSerlvet to web.xml** + +```xml +<servlet> + <servlet-name>JspSupportServlet</servlet-name> + <servlet-class>org.apache.struts2.views.JspSupportServlet</servlet-class> + <load-on-startup>1</load-on-startup> +</servlet> +``` + +Once you've done that, you can simply add something like this in your templates: + +```html +<#assign cewolf=JspTaglibs["/WEB-INF/cewolf.tld"] /> +... +<@cewold.xxx ... /> +```
