You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by do...@apache.org on 2005/08/22 21:31:19 UTC
svn commit: r239227 -
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsJavascript.xml
Author: dolander
Date: Mon Aug 22 12:31:15 2005
New Revision: 239227
URL: http://svn.apache.org/viewcvs?rev=239227&view=rev
Log:
Update the JavaScript support document
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsJavascript.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsJavascript.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsJavascript.xml?rev=239227&r1=239226&r2=239227&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsJavascript.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/tagsJavascript.xml Mon Aug 22 12:31:15 2005
@@ -8,19 +8,19 @@
<body>
<section id="intro">
<title>Introduction</title>
- <p>The following topic explains how the NetUI JSP tags provide support for JavaScript development.
- The primary JavaScript support provides the ability to looking up the HTML DOM elements
- produced by the tags. This support allows looking up DOM elements by either the
- <strong>id</strong> or
- <strong>name</strong>. In addition, the NetUI tags provide the ability to uniquely generate
- the
- <strong>id</strong> attribute.
+ <p>The following topic explains how the NetUI JSP tags provide support for client side
+ JavaScript development.
+ The primary JavaScript support provides the ability to looking up HTML DOM elements
+ produced by the tags. Lookup may be done by either the <strong>id</strong> or
+ <strong>name</strong> attributes. In addition, the NetUI tags provide the ability to
+ generate unique values for
+ the HTML <strong>id</strong> attribute.
</p>
<p> NetUI owns the value of the
<strong>name</strong> attribute generated for the HTML form controls.
- It's very common to write JavaScript that would like to access the HTML control DOM elements
- using the name. The JavaScript supports mapping a local name to the generated name allowing
- this type of code to be written.
+ It's very common to write JavaScript that would like to access these control DOM elements
+ using the name. The NetUI JavaScript support provides a mapping between the local name to the
+ generated name.
</p>
<p> In addition, NetUI provides scoping facilities that ensure the HTML
<strong>id</strong> attribute is unique
@@ -28,14 +28,26 @@
of the
<strong>id</strong> attributes are specified in a single source file. There are situations,
such as content within portal, where a Page Flow page is generated as a portion of a larger page.
- In this case,
- unique
+ In these cases, unique
<strong>id</strong> values must be generated when the page is generated. The JavaScript support
in NetUI allows for looking up DOM elements in JavaScript using a "local" name and scope. This allows
JavaScript to be written as if the page was a simple page and for it to become part of a composite
page without modification.
</p>
</section>
+ <section id="back_compatability">
+ <title>Backward Compatibility</title>
+ <p>There are two JavaScript functions intended to support client side JavaScript,
+ <strong>lookupIdByTagId()</strong> and <strong>lookupNameByTagId()</strong>. These are the public
+ interfaces provided to lookup HTML DOM elements and Beehive will maintain backward compatibility
+ on these methods. All of the other JavaScript methods and the values of the HTML <strong>name</strong>
+ and <strong>id</strong> attributes output into the generated HTML may change over time. Developers
+ should not build dependencies on these values. In some cases, this document describes the details
+ of these low level features for explination purposes.
+ </p>
+ <p>
+ </p>
+ </section>
<section>
<title>JSP Tags and Attribute</title>
<p>This section describes the primary NetUI JSP tags and attributes used to support JavaScript.</p>
@@ -48,41 +60,49 @@
The value of this attribute is used to generate the
<strong>id</strong> attribute of the resulting
HTML elements. In addition, for form controls, a mapping is maintained from the
- <strong>tagId</strong> value to the generated name.
+ <strong>tagId</strong> value to the generated <strong>name</strong>.
</p>
</section>
<section id="ScriptContainer">
<title>ScriptContainer</title>
<p> Scoping of the generated HTML
- <strong>id</strong> attributes is done through the
- <strong>ScriptContainer</strong> tags. A ScriptContainer can provide either
- an explicit or a unique implicit name all of the tagId values found in it's
- decedents.
+ <strong>id</strong> attributes is done by the
+ <strong>ScriptContainer</strong> tags. A ScriptContainer provides either
+ an explicit name or a uniquely generated name. All of the tagId values found in its
+ decedents will have this name prefixed to their tagId value when their qualified <strong>id</strong>
+ value is created.
</p>
<p> There are two NetUI JSP tags that are ScriptContainers, <netui:scriptContainer> and
<netui:html>. The ScriptContainer tag represents the basic features. The Html
tag is a subclass of ScriptContainer and provides additional HTML specific features.
ScriptContainers may be nested. The
- <strong>id</strong> value is generated by prepending
+ <strong>id</strong> value is generated by prefixing
all of the ancestor ScriptContainer names to the value of the
<strong>tagId</strong>.
</p>
- <p> The ScriptContainer tags support two attributes for creating a name, <strong>idScope</strong>
- and <strong>generateIdScope</strong>. The <strong>idScope</strong> sets a explicit value
- for the generated scope. The <strong>generateIdScope</strong>, when <strong>true</strong>,
+ <p> The ScriptContainer tags support two attributes for creating a name,
+ <strong>idScope</strong>
+ and
+ <strong>generateIdScope</strong>. The
+ <strong>idScope</strong> sets an explicit value
+ for the generated scope. The
+ <strong>generateIdScope</strong>, when
+ <strong>true</strong>,
will cause a unique id scope name to be generated. This value is unique for the request.
</p>
- <p>The NetUI tags dynamically generate JavaScript in certain situations. One of the tasks of
- the ScriptContainer is to gather up the generated JavaScript then render it into the HTML
+ <p>The NetUI tags dynamically generate JavaScript in certain situations.
+ The top most ScriptContainer gathers up generated JavaScript then render it into the HTML
document. There isn't a requirement to have a ScriptContainer for most of the JavaScript
enabled features; this includes the lookup methods. If the ScriptContainer is not present,
the generated
JavaScript will be output inline with the tags. The result is duplicate JavaScript will be
- rendered throughout the page for features like setting <strong>tagId</strong> or image
+ rendered throughout the page for features like setting
+ <strong>tagId</strong> or image
rollovers. The advantages of using a ScriptContainer is this JavaScript is not duplicated
and will be written out in a single script block in the generated HTML file.
</p>
- <p><strong>Note:</strong> the generated id scope may not be the same from request to request on
+ <p>
+ <strong>Note:</strong> the generated id scope may not be the same from request to request on
the same page. It may change if content preceding the JSP page changes from request to
request, or some conditional logic on the page, such as JSTL, changes the number or order
of ScriptContainers.
@@ -90,30 +110,30 @@
</section>
<section id="ScriptBlock">
<title>ScriptBlock</title>
- <p>
- The <netui:scriptBlock> tag is used to position user provided JavaScript in relationship
+ <p> The <netui:scriptBlock> tag is used to position user provided JavaScript in relationship
to the framework generated JavaScript. The tag supports inserting JavaScript before or after
the framework generated JavaScript. When you want to create valid XHTML or HTML this tag is
- required. [See the HTML Structure and Valid HTML for further explanation.
+ required. [See the HTML Structure and Valid HTML for further explanation.]
</p>
- </section>
+ </section>
</section>
<section id="simple_example">
<title>Simple Example</title>
- <p>This section defines a very simple example which demonstrates the use of the
+ <p> This section presents a very simple example which demonstrates the use of the
<strong>tagId</strong>
- attribute, scoping ids, and the use of the lookup methods for finding DOM elements. In this example
+ attribute, scoping ids, and the lookup methods. In this example
there is a simple form containing a checkbox. The document is automatically scoped to generate
unique ids within the document.
</p>
<section id="simple_jsp">
<title>JSP Code</title>
- <p> This simple JSP file demonstrates the use of <strong>tagId</strong> and scoping.
- It also contains JavaScript that looks up DOM elements and creates some output
- verifying those elements are found.
- </p>
- <p><strong>tagIdSupport.jsp</strong>
+ <p> This JSP file demonstrates the use of
+ <strong>tagId</strong> and scoping.
+ It also contains JavaScript that looks up DOM elements and dynamically creates some output
+ verifying these elements are found. The screen shot at the end of this page
+ displays the expected dynamically generated content.
</p>
+ <p><strong>tagIdSupport.jsp</strong></p>
<source><![CDATA[
<%@ page language="java" contentType="text/html;charset=UTF-8"%>
<%@ taglib prefix="netui" uri="http://beehive.apache.org/netui/tags-html-1.0"%>
@@ -162,40 +182,64 @@
</netui:html>
]]></source>
<p> In the JSP code, the <netui:form> and <netui:checkbox> elements are both named
- using the <strong>tagId</strong> attribute. The value of the tagId ("form" and "check")
+ using the
+ <strong>tagId</strong> attribute. The values of the tagId ("form" and "check")
are the local name of these elements.
</p>
<source>
<netui:form <strong>tagId="form"</strong> action="begin">
<netui:checkBox <strong>tagId="check"</strong> dataSource="pageFlow.check" />
</source>
- <p> In this example, the <netui:html> tag generates a scope for the name of all
- <strong>tagId</strong> values. In this example, the scoping isn't required, but this
- demonstrates the use of scoping within a page. In this case, the <strong>generateIdScope</strong>
- attribute will generate a unique "name" for the scope. This name will be prepended to all
- <strong>tagId</strong> values to generate the name of the HTML elements.
+ <p> In this example, the <netui:html> tag generates a scope name for all
+ <strong>tagId</strong> values. This scoping isn't required in this example, but
+ demonstrates the use of scoping within a page. The
+ <strong>generateIdScope</strong>
+ attribute on the <netui:html> tag will automatically generate a unique "name" for the scope
+ defined by the tag. The fully qualified
+ name for each DOM element is creating by prefixing the local name with each scope name
+ defined by all ancestor ScriptContainer JSP tags. Prefixing is done moving up the hierarchy
+ until the root is found. In this example, the <netui:html> tag will generate a name of
+ <strong>n0</strong>.
+ The generated name for the <netui:form> tag will then become
+ <strong>n0.form</strong>.
+ The '.' character is used to separate the names.
</p>
<source>
<netui:html <strong>generateIdScope="true"</strong>>
</source>
<p>The source JavaScript in the page is found inside of a ScriptBlock. The reason for using
a ScriptBlock is to control the placement of the script in relationship to the framework
- generated lookup functions. In this casee the <strong>placement</strong> attribute is set
- to the value <strong>after</strong> indicating that the contents of this block should appear
- after the framework generated JavaScript.
+ generated lookup functions. In this example the
+ <strong>placement</strong> attribute is set
+ to the value
+ <strong>after</strong> indicating that the contents of this block should appear
+ after the framework generated JavaScript. This is required because the JavaScript contains calls
+ to functions which are generated by the framework.
</p>
<source>
<netui:scriptBlock <strong>placement="after"</strong>>
</source>
+ <p> When one of the NetUI JSP tags contains a
+ <strong>tagId</strong> attribute, the framework will
+ generate some JavaScript which supports looking up DOM elements based upon the local name and
+ a scope. There are two primary JavaScript functions generated,
+ <strong>lookupIdByTagId</strong>
+ and
+ <strong>lookupNameByTagId</strong>. The former will return the real id of a DOM element based upon
+ the tagId value and the later will return the real name based upon the tagId value. In the
+ example, we lookup the form based upon by id. Then we lookup the DOM input element
+ representing the checkbox based upon its name.
+ </p>
<source>
var form = document.getElementById(lookupIdByTagId("form",scope));
-</source>
-<source>
check = form[lookupNameByTagId("check",scope)];
</source>
</section>
<section id="simple_controller">
<title>Controller</title>
+ <p> The Page Flow controller simply supports the sample. It defines the
+ required begin action and a property bound to by the <netui:checkbox>.
+ </p>
<p>
<strong>Controller.jsp</strong>
</p>
@@ -227,9 +271,14 @@
</section>
<section id="simple_generated_html">
<title>Generated HTML</title>
+ <p> This section contains the generated HTML page sent to the browser. The output of the
+ NetUI JSP tags and the literal content are contained in the page. The tagId has been used to name
+ HTML elements and the framework generated JavaScript is present.
+ </p>
<p>
<strong>Generate HTML on Client Browser</strong>
</p>
+
<source><![CDATA[
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
>
@@ -326,9 +375,115 @@
</body>
</html>
]]></source>
+ <p> In the generated HTML, the names and ids of the form and checkbox input
+ elements have been generated by the NetUI JSP tags. The <strong>n0</strong> portion of the
+ name is prefixed
+ to the tagId because the <netui:html> tag generated that value. For the checkbox, the name
+ is generated by the JSP tag and contains an expression allowing the Page Flow
+ <strong>check</strong> property to be updated by the Page Flow framework.
+ </p>
+ <source>
+<form <strong>name="n0.form"</strong> <strong>id="n0.form"</strong> action="/dev/tagIdSupport/begin.do" method="post">
+<input type="checkbox" <strong>name="wlw-checkbox_key:{pageFlow.check}"</strong> <strong>id="n0.check"</strong>>
+ </source>
+ <p>In addition, the framework generated JavaScript and the JavaScript defined in the JSP page have
+ the proper relationship with each other. The framework JavaScript precedes the JSP defined
+ JavaScript.
+ </p>
+ <p> Finally, there the <html> element has an additional attribute name spaced into NetUI. In many
+ cases the NetUI tags generate additional attributes on some HTML elements to provide information
+ to JavaScript. These attributes will always be name spaced into the <strong>netui</strong> name
+ space. In this
+ case, the <strong>netui:idScope</strong> attribute is used by the lookup code create the fully
+ qualified name.
+ </p>
+ <source>
+<html lang="en" <strong>netui:idScope="n0"</strong>>
+ </source>
+ </section>
+ <section id="simple_famework_generate_javascript">
+ <title>Framework Generated JavaScript</title>
+ <p> This section describes the details of the framework generated JavaScript. This JavaScript
+ was generated because NetUI tags used the <strong>tagId</strong> attribute. This JavaScript
+ will not be generated in pages that do not use tagId.
+ </p>
+ <p><strong>Framework Generated JavaScript</strong></p>
+ <source><![CDATA[
+
+// **** Start the NetUI Framework Generated JavaScript ****
+
+// Build the netui_names table to map the tagId attributes
+// to the real id written into the HTML
+if (netui_tagIdNameMap == null)
+ var netui_tagIdNameMap = new Object();
+netui_tagIdNameMap.n0___form="n0.form"
+netui_tagIdNameMap.n0___check="wlw-checkbox_key:{pageFlow.check}"
+
+
+// lookup by tagId to "real id"
+function lookupIdByTagId(id, tag)
+{
+ var idScope = lookupIdScope(tag,".");
+ return (idScope == "") ? id : idScope + id;
+}
+
+// lookup by tagId to "real name"
+function lookupNameByTagId(id, tag)
+{
+ var idScope = lookupIdScope(tag,"_");
+ if (idScope == "")
+ return netui_tagIdNameMap[id];
+ else
+ return netui_tagIdNameMap[idScope + "__" + id];
+}
+
+//Non-Legacy lookup method creating a fully qualified scope id
+function lookupIdScope(tag,sep)
+{
+ var val = "";
+ if (sep == null) sep = "";
+ while (tag != null && tag.getAttribute != null) {
+ try {
+ var attrVal = tag.getAttribute("netui:idScope");
+ } catch (e) { /* ignore, in IE6 calling on a table results in an exception */ }
+ if (attrVal != null)
+ val = attrVal + sep + val;
+ tag = tag.parentNode;
+ }
+ return val;
+}
+ ]]></source>
+ <p>There are two JavaScript functions intended to support user JavaScript,
+ <strong>lookupIdByTagId</strong> and <strong>lookupNameByTagId</strong>. Both methods
+ take a name and scope. The name should be local name of the DOM element you want to
+ lookup. The scope is some type of DOM element that is found in the same scope as
+ the element that is to be looked up. This is typically a button or link that is
+ found in the same scope.
+ </p>
+ <source>
+<a onclick="someFunction(this);return false;" href="#">
+ </source>
+ <p> The user defined JavaScript function <strong>someFunction</strong> receives a reference
+ to the anchor DOM element that can then be used to lookup other DOM elements in the same
+ scope.
+ </p>
+ <p>These two methods act as the public interface to the framework lookup code. NetUI will
+ maintain backward compatibility for these two methods. The other code generated by the
+ framework and the value of the <strong>name</strong> and <strong>id</strong>
+ attributes may change over time. Developers should not build dependence on these features
+ of the framework generated JavaScript support.
+ </p>
+ <p> <strong>Note:</strong> In the example, we are using an element found in the document using
+ the <strong>id</strong> attribute value. This is actually not a typical usage because
+ the id value is not scoped by the framework. This JSP page could not be included twice
+ in a composite page.
+ </p>
</section>
<section id="sample_browser_results">
<title>Browser Results</title>
+ <p>This section contains a screen shoot of the page from the browser. The dynamically generated
+ content can be seen.
+ </p>
<p>
<strong>Page as seen in a browser</strong>
</p>