https://javaserverfaces-spec-public.dev.java.net/issues/show_bug.cgi?id=199
PROPOSAL:
Change the renderkit description of the command link renderer.
Index: standard-html-renderkit.xml
===================================================================
RCS file: /cvs/javaserverfaces-sources/jsf-api/doc/standard-html-renderkit.xml,v
retrieving revision 1.113
diff -u -r1.113 standard-html-renderkit.xml
--- standard-html-renderkit.xml 21 Jun 2006 22:56:12 -0000 1.113
+++ standard-html-renderkit.xml 30 Aug 2006 20:11:59 -0000
@@ -17948,119 +17948,36 @@
<description><![CDATA[<p>Render an HTML "a" anchor element that acts like a
form submit button when clicked.</p>
- <p>General Behaviour</p>
-
- <p>Both the encode and decode behavior require the ability to get
- the id/name for a hidden field whose value is set by the
- JavaScript form submit. This name must be constructed as
- follows:</p>
-
- <ul>
-
- <li><p>Get the clientId for the form of which this component is a
- child.</p></li>
-
- <li><p>Append
- <code>NamingContainer.SEPARATOR_CHAR</code>.</p></li>
-
- <li><p>Append a constant string that is the same for all command
- link components in the tree.</p></li>
-
- </ul>
-
- <p>In the following text, this String is called
- hiddenFieldName.</p>
-
<p>Decode Behavior</p>
<ul>
- <p>Obtain the "clientId" property of the component. Obtain the
- <code>Map</code> from the "requestParameterMap" property of the
- <code>ExternalContext</code>. Derive hiddenFieldName as above.
- Get the entry in the <code>Map</code> under the key that is the
- hiddenFieldName. If the there is no entry, or the entry is the
- empty String, or the entry is not equal to the value of the
- "clientId" property, return immediately. If there is an entry,
- and its value is equal to the value of the "clientId" property,
- create a new <code>javax.faces.event.ActionEvent</code> instance
- around the component and call <code>queueActionEvent()</code> on
- the component, passing the event.</p>
+ <p>Obtain the <code>Map</code> from the "requestParameterMap"
+ property of the <code>ExternalContext</code>. If the value in
+ the <code>Map</code> for the value of the "clientId" property of
+ the component is <code>non-null</code>, create a
+ <code>javax.faces.event.ActionEvent</code> around the component,
+ and pass it to the <code>queueEvent()</code> method of the
+ component, which must be an instance of
+ <code>UICommand.</code></p>
</ul>
-
<p>Encode Behavior</p>
<ul>
- <p>If the value of the <code>disabled</code> attribute is
- <code>true</code>, render a span element. Render all the passthru
- attributes and the <code>target</code> attribute as pass-through
- attributes on the span, even though the <code>target</code>
- attribute will have no effect on a span. Render the current value
- of the component as the content of the span. Return.</p>
-
- <p>If the <code>disabled</code> attribute is not present, or its
- value is <code>false</code>, render an HTML <code>a</code>
- element. Render "#" as the value of the "href" attribute. Render
- the current value of the component as the link text if it is
- specified. Render JavaScript that is functionally equivalent to
- the following as the value of the "onclick" attribute:</p>
-
- <p><code>document.forms['CLIENT_ID']['hiddenFieldName'].value='CLIENT_ID';
- document.forms['CLIENT_ID']['PARAM1_NAME'].value='PARAM1_VALUE';
- document.forms['CLIENT_ID']['PARAM2_NAME'].value='PARAM2_VALUE';
- return false;</code></p>
-
- <p>document.forms['CLIENT_ID'].submit()" where hiddenFieldName is
- as described above, CLIENT_ID is the clientId of the UICommand
- component, PARAM*_NAME and PARAM*_VALUE are the names and values,
- respectively, of any nested UIParameter children. The name and
- the value must be URLEncoded. If an "onclick" attribute was
- specified by the user, render this JavaScript in a function,
- and render the user's JavaScript in a function. Render both functions
- in a choice function as follows:</p>
-
- <p><code>var a=function(){#USER_FUNCTION#};
- var b=function(){#JSF_FUNCTION#};
- return (a()==false) ? false : b();</code></p>
-
- <p>where #USER_FUNCTION# is the user's JavaScript and
- #JSF_FUNCTION# is the JavaScript rendered by JSF. The choice
- function should operate such that if the user's JavaScript returns
- true, then the rendered JavaScript will also execute.</p>
-
- <p>If the "styleClass" attribute is specified, render its value as
- the value of the "class" attribute. Render any non-UIParameter
- output children as normal inside of the "a" element. These will
- appear as the link text. Allow the form renderer to output a
- single "input" element (for the entire page, regardless of how
- many command link components are in the page) of "type" "hidden"
- whose "name" is the value of hiddenFieldName, and which must not
- have a "value" attribute. Multiple occurrences of command link
- components in the tree should not cause multiple hiddenFieldName
- hidden fields. Allow the form renderer to output an "input"
- element of "type" "hidden" for each of the nested UIParameter
- children, taking the name property (but not the value) from each
- one in turn. If the "disabled" attribute is specified, do not
- render the HTML "a" anchor element or its "href" attribute.
- Instead, render a "span" element. If the "styleClass" attribute
- is specified, render its value as the value of the "class"
- attribute on the "span". Render any pass-through attributes on
- the "span". The content of the span element comes from the value
- of the component or its children as specified above.</p>
-
- <p>If the user specified a <code>target</code> attribute, its
- value must be set using javascript since the <code>onclick</code>
- handler will prevent the target attribute from being generated.
- This must be accomplished using JavaScript that is equivalent to
- the following.</p>
-
- <p><code>document.forms['CLIENT_ID'].target='TARGET';</p>
+ <p>This is the only component in the HTML_BASIC RenderKit that
+ requires the use of JavaScript. JavaScript is the only way to
+ usurp the behavior of the anchor tag to submit the form via HTTP
+ post rather than having the browser do the usual HTTP GET. The
+ manner in which this is accomplished is an implementation
+ detail, but any JavaScript that fulfills the requirement of
+ causing a name=value pair to be submitted in the form data,
+ where the name is the "clientId" of the component, and the value
+ is non-empty is acceptable. Care must be taken to ensure that
+ the ephemeral name=value pair does not persist in the DOM.</p>
- <p>Where TARGET is the value of the target attribute on the JSP
- tag.</p>
</ul>]]></description>
<component-family>javax.faces.Command</component-family>
--
| ed.burns_at_sun.com | {home: 407 869 9587, office: 408 884 9519 OR x31640}
| homepage: | http://purl.oclc.org/NET/edburns/
| aim: edburns0sunw | iim: ed.burns_at_sun.com