You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@click.apache.org by sa...@apache.org on 2009/03/21 11:51:08 UTC
svn commit: r756912 - in
/incubator/click/trunk/click/framework/src/org/apache/click: ./ element/
Author: sabob
Date: Sat Mar 21 10:51:07 2009
New Revision: 756912
URL: http://svn.apache.org/viewvc?rev=756912&view=rev
Log:
javadoc
Added:
incubator/click/trunk/click/framework/src/org/apache/click/element/package.html
Modified:
incubator/click/trunk/click/framework/src/org/apache/click/Control.java
incubator/click/trunk/click/framework/src/org/apache/click/Page.java
incubator/click/trunk/click/framework/src/org/apache/click/element/CssImport.java
incubator/click/trunk/click/framework/src/org/apache/click/element/CssStyle.java
incubator/click/trunk/click/framework/src/org/apache/click/element/Element.java
incubator/click/trunk/click/framework/src/org/apache/click/element/JsImport.java
incubator/click/trunk/click/framework/src/org/apache/click/element/JsScript.java
incubator/click/trunk/click/framework/src/org/apache/click/element/ResourceElement.java
Modified: incubator/click/trunk/click/framework/src/org/apache/click/Control.java
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/Control.java?rev=756912&r1=756911&r2=756912&view=diff
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/Control.java (original)
+++ incubator/click/trunk/click/framework/src/org/apache/click/Control.java Sat Mar 21 10:51:07 2009
@@ -215,7 +215,7 @@
* }
* } </pre>
*
- * Alternative one can add the HEAD elements in the Control's constructor:
+ * Alternatively one can add the HEAD elements in the Control's constructor:
*
* <pre class="prettyprint">
* public MyControl extends AbstractControl {
Modified: incubator/click/trunk/click/framework/src/org/apache/click/Page.java
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/Page.java?rev=756912&r1=756911&r2=756912&view=diff
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/Page.java (original)
+++ incubator/click/trunk/click/framework/src/org/apache/click/Page.java Sat Mar 21 10:51:07 2009
@@ -694,7 +694,7 @@
* }
* } </pre>
*
- * An alternative is to add the HEAD elements in the Page constructor:
+ * Alternatively one can add the HEAD elements in the Page constructor:
*
* <pre class="prettyprint">
* public MyPage extends Page {
Modified: incubator/click/trunk/click/framework/src/org/apache/click/element/CssImport.java
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/element/CssImport.java?rev=756912&r1=756911&r2=756912&view=diff
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/element/CssImport.java (original)
+++ incubator/click/trunk/click/framework/src/org/apache/click/element/CssImport.java Sat Mar 21 10:51:07 2009
@@ -19,10 +19,36 @@
package org.apache.click.element;
import org.apache.click.Context;
+import org.apache.click.util.ClickUtils;
import org.apache.click.util.HtmlStringBuffer;
import org.apache.commons.lang.builder.HashCodeBuilder;
/**
+ * Provides a Css HEAD element for importing <tt>external</tt> Cascading
+ * Stylesheet files using the <link> tag.
+ * <p/>
+ * Example usage:
+ * <pre class="prettyprint">
+ * public class MyPage extends Page {
+ *
+ * public List getHeadElements() {
+ * // We use lazy loading to ensure the CSS import is only added the
+ * // first time this method is called.
+ * if (headElements == null) {
+ * // Get the head elements from the super implementation
+ * headElements = super.getHeadElements();
+ *
+ * CssImport cssImport = new CssImport("/css/style.css");
+ * headElements.add(cssImport);
+ * }
+ * return headElements;
+ * }
+ * } </pre>
+ *
+ * The <tt>cssImport</tt> instance will be rendered as follows (assuming the
+ * context path is <tt>myApp</tt>):
+ * <pre class="prettyprint">
+ * <link type="text/css" rel="stylesheet" href="/myApp/css/style.css"/> </pre>
*
* @author Bob Schellink
*/
@@ -31,20 +57,21 @@
// ----------------------------------------------------------- Constructors
/**
- * Constructs a new CssImport link.
+ * Constructs a new Css import element.
*/
public CssImport() {
this(null);
}
/**
- * Construct a new CssImport link with the specified <tt>href</tt> attribute.
+ * Construct a new Css import element with the specified <tt>href</tt>
+ * attribute.
* <p/>
- * <b>Please note</b> if the given <tt>href</tt> begins with a <tt class="wr">"/"</tt>
- * character the href will be prefixed with the web application
- * <tt>context path</tt>.
+ * <b>Please note</b> if the given <tt>href</tt> begins with a
+ * <tt class="wr">"/"</tt> character the href will be prefixed with the web
+ * application <tt>context path</tt>.
*
- * @param href the CSS link href attribute
+ * @param href the Css import href attribute
*/
public CssImport(String href) {
setHref(href);
@@ -64,13 +91,13 @@
}
/**
- * This method always return true because CSS import must be unique based on
+ * This method always return true because Css import must be unique based on
* its <tt>href</tt> attribute. In other words the Page HEAD should only
* contain a single CSS import for the specific <tt>href</tt>.
*
- * @see HtmlHeader#isUnique()
+ * @see ResourceElement#isUnique()
*
- * @return true because CSS import must unique based on its <tt>href</tt>
+ * @return true because Css import must unique based on its <tt>href</tt>
* attribute
*/
public boolean isUnique() {
@@ -120,7 +147,8 @@
// --------------------------------------------------------- Public Methods
/**
- * Render the HTML representation of the CSS import to the specified buffer.
+ * Render the HTML representation of the CssImport element to the specified
+ * buffer.
*
* @param buffer the buffer to render output to
*/
@@ -173,19 +201,4 @@
public int hashCode() {
return new HashCodeBuilder(17, 37).append(getHref()).toHashCode();
}
-
- // ------------------------------------------------ Package Private Methods
-
- /**
- * This operation is not supported because CSS imports is always unique
- * based on their <tt>href</tt> attribute.
- *
- * @see HtmlHeader#setUnique(boolean)
- *
- * @param unique sets whether the Css import should be unique or not
- */
- void setUnique(boolean unique) {
- throw new UnsupportedOperationException("CssImport is always"
- + " unique based on the 'href' attribute");
- }
}
Modified: incubator/click/trunk/click/framework/src/org/apache/click/element/CssStyle.java
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/element/CssStyle.java?rev=756912&r1=756911&r2=756912&view=diff
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/element/CssStyle.java (original)
+++ incubator/click/trunk/click/framework/src/org/apache/click/element/CssStyle.java Sat Mar 21 10:51:07 2009
@@ -19,10 +19,129 @@
package org.apache.click.element;
import org.apache.click.util.HtmlStringBuffer;
-import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.builder.HashCodeBuilder;
/**
+ * Provides a Css HEAD element for including <tt>inline</tt> Cascading
+ * Stylesheets using the <style> tag.
+ * <p/>
+ * Example usage:
+ *
+ * <pre class="prettyprint">
+ * public class MyPage extends Page {
+ *
+ * public List getHeadElements() {
+ * // We use lazy loading to ensure the CSS import is only added the
+ * // first time this method is called.
+ * if (headElements == null) {
+ * // Get the header entries from the super implementation
+ * headElements = super.getHeadElements();
+ *
+ * CssStyle cssStyle = new CssStyle("body { font: 12px arial; }");
+ * headElements.add(cssStyle);
+ * }
+ * return headElements;
+ * }
+ * } </pre>
+ *
+ * The <tt>cssStyle</tt> instance will render as follows:
+ *
+ * <pre class="prettyprint">
+ * <style type="text/css" rel="stylesheet">
+ * body { font: 12px arial; }
+ * </style>
+ * </pre>
+ *
+ * Below is an example showing how to render inline CSS from a Velocity
+ * template.
+ * <p/>
+ * First we create a Velocity template <tt>(/css/style-template.css)</tt> which
+ * contains the variable <tt>$context</tt> that must be replaced at runtime with
+ * the application <tt>context path</tt>:
+ *
+ * <pre class="prettyprint">
+ * .blue {
+ * background: #00ff00 url('$context/css/blue.png') no-repeat fixed center;
+ * } </pre>
+ *
+ * Next is the Page implementation:
+ *
+ * <pre class="prettyprint">
+ * public class MyPage extends Page {
+ *
+ * public List getHeadElements() {
+ * // We use lazy loading to ensure the CSS is only added the first time
+ * // this method is called.
+ * if (headElements == null) {
+ * // Get the head elements from the super implementation
+ * headElements = super.getHeadElements();
+ *
+ * Context context = getContext();
+ *
+ * // Create a default template model to pass to the template
+ * Map model = ClickUtils.createTemplateModel(this, context);
+ *
+ * // Specify the path to CSS Velocity template
+ * String cssTemplate = "/css/style-template.css";
+ *
+ * // Render the template using the model above
+ * String content = context.renderTemplate(cssTemplate, model);
+ *
+ * // Create the inline Css for the given template
+ * CssStyle cssStyle = new CssStyle(content);
+ * headElements.add(cssStyle);
+ * }
+ * return headElements;
+ * }
+ * } </pre>
+ *
+ * The <tt>Css</tt> above will render as follows (assuming the context path is
+ * <tt>myApp</tt>):
+ *
+ * <pre class="prettyprint">
+ * <style type="text/css" rel="stylesheet">
+ * .blue {
+ * background: #00ff00 url('/myApp/css/blue.png') no-repeat fixed center;
+ * }
+ * </style>
+ * </pre>
+ *
+ * <h3>Character data (CDATA) support</h3>
+ *
+ * Sometimes it is necessary to wrap <tt>inline</tt> {link Css} in CDATA tags.
+ * Two use cases are common for doing this:
+ * <ul>
+ * <li>For XML parsing: When using Ajax one often send back partial
+ * XML snippets to the browser, which is parsed as valid XML. However the XML
+ * parser will throw an error if the script contains reserved XML characters
+ * such as '&', '<' and '>'. For these situations it is recommended
+ * to wrap the script content inside CDATA tags.
+ * </li>
+ * <li>XHTML validation: if you want to validate your site using an XHTML
+ * validator e.g: <a target="_blank" href="http://validator.w3.org/">http://validator.w3.org/</a>.</li>
+ * </ul>
+ *
+ * To wrap the CSS Style content in CDATA tags, set
+ * {@link #setCharacterData(boolean)} to true. Below is how a CSS content would
+ * be rendered:
+ *
+ * <pre class="prettyprint">
+ * <style type="text/css">
+ * /∗<![CDATA[∗/
+ *
+ * div > p {
+ * border: 1px solid black;
+ * }
+ *
+ * /∗]]>∗/
+ * </style> </pre>
+ *
+ * Notice the CDATA tags are commented out which ensures older browsers that
+ * don't understand the CDATA tag, will ignore it and only process the actual
+ * content.
+ * <p/>
+ * For an overview of XHTML validation and CDATA tags please see
+ * <a target="_blank" href="http://javascript.about.com/library/blxhtml.htm">http://javascript.about.com/library/blxhtml.htm</a>.
*
* @author Bob Schellink
*/
@@ -30,29 +149,27 @@
// -------------------------------------------------------------- Variables
- /** A buffer holding the inline CSS content. */
+ /** A buffer holding the inline Css content. */
private HtmlStringBuffer content = new HtmlStringBuffer();
/**
- * Indicates if the HtmlHeader's content should be wrapped in a CDATA tag.
- * <b>Note:</b> this property only applies to HtmlHeader imports which contain
- * <tt>inline</tt> content.
+ * Indicates if the HeadElement's content should be wrapped in a CDATA tag.
*/
private boolean characterData = false;
// ------------------------------------------------------------ Constructor
/**
- * Construct a new CSS Style element.
+ * Construct a new Css style element.
*/
public CssStyle() {
this(null);
}
/**
- * Construct a new CSS Style element with the given content.
+ * Construct a new Css style element with the given content.
*
- * @param content the CSS content
+ * @param content the Css content
*/
public CssStyle(String content) {
if (content != null) {
@@ -74,16 +191,16 @@
}
/**
- * Return the CSS content buffer.
+ * Return the Css content buffer.
*
- * @return the CSS content buffer
+ * @return the Css content buffer
*/
public HtmlStringBuffer getContent() {
return content;
}
/**
- * Set the CSS content buffer.
+ * Set the Css content buffer.
*
* @param content the new content buffer
*/
@@ -92,10 +209,10 @@
}
/**
- * Return true if the HtmlHeader's content should be wrapped in CDATA tags,
+ * Return true if the CssStyle's content should be wrapped in CDATA tags,
* false otherwise.
*
- * @return true if the HtmlHeader's content should be wrapped in CDATA tags,
+ * @return true if the CssStyle's content should be wrapped in CDATA tags,
* false otherwise
*/
public boolean isCharacterData() {
@@ -103,9 +220,10 @@
}
/**
- * Sets whether the HtmlHeader's content should be wrapped in CDATA tags or not.
+ * Sets whether the CssStyle's content should be wrapped in CDATA tags or
+ * not.
*
- * @param characterData true indicates that the HtmlHeader's content should be
+ * @param characterData true indicates that the CssStyle's content should be
* wrapped in CDATA tags, false otherwise
*/
public void setCharacterData(boolean characterData) {
@@ -115,16 +233,18 @@
// --------------------------------------------------------- Public Methods
/**
- * Append the given CSS string to the content buffer.
+ * Append the given Css string to the content buffer.
*
* @param content the CSS string to append to the content buffer
+ * @return the Css content buffer
*/
- public void append(String content) {
- this.content.append(content);
+ public HtmlStringBuffer append(String content) {
+ return this.content.append(content);
}
/**
- * Render the HTML representation of the CSS to the specified buffer.
+ * Render the HTML representation of the CssStyle element to the specified
+ * buffer.
*
* @param buffer the buffer to render output to
*/
@@ -143,7 +263,7 @@
// Render CDATA tag if necessary
renderCharacterDataPrefix(buffer);
- buffer.append(getContent());
+ renderContent(buffer);
renderCharacterDataSuffix(buffer);
@@ -193,6 +313,17 @@
return new HashCodeBuilder(17, 37).append(getId()).toHashCode();
}
+ // ------------------------------------------------------ Protected Methods
+
+ /**
+ * Render this CssStyle content to the specified buffer.
+ *
+ * @param buffer the buffer to append the output to
+ */
+ protected void renderContent(HtmlStringBuffer buffer) {
+ buffer.append(getContent());
+ }
+
// ------------------------------------------------ Package Private Methods
/**
@@ -221,21 +352,4 @@
buffer.append(" /*]]>*/");
}
}
-
- /**
- * @see HtmlHeader#setUnique(boolean)
- *
- * @deprecated use {@link #setId(java.lang.String)} instead
- *
- * @param unique sets whether the HtmlHeader import should be unique or not
- */
- void setUnique(boolean unique) {
- super.setUnique(unique);
-
- // If CSS is unique and ID is not defined, derive the ID from the content
- if (unique && StringUtils.isBlank(getId()) && getContent().length() > 0) {
- int hash = getContent().toString().hashCode();
- setId(Integer.toString(hash));
- }
- }
}
Modified: incubator/click/trunk/click/framework/src/org/apache/click/element/Element.java
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/element/Element.java?rev=756912&r1=756911&r2=756912&view=diff
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/element/Element.java (original)
+++ incubator/click/trunk/click/framework/src/org/apache/click/element/Element.java Sat Mar 21 10:51:07 2009
@@ -24,6 +24,11 @@
import org.apache.click.util.HtmlStringBuffer;
/**
+ * Provides a base class for rendering HTML elements, for example
+ * JavaScript (<script>) and Cascading Stylesheets
+ * (<link>/<style>).
+ * <p/>
+ * Subclasses should override {@link #getTag()} to return a specific HTML tag.
*
* @author Bob Schellink
*/
@@ -31,7 +36,7 @@
// -------------------------------------------------------------- Variables
- /** The HtmlHeader attributes Map. */
+ /** The Element attributes Map. */
private Map attributes;
// ------------------------------------------------------ Public properties
Modified: incubator/click/trunk/click/framework/src/org/apache/click/element/JsImport.java
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/element/JsImport.java?rev=756912&r1=756911&r2=756912&view=diff
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/element/JsImport.java (original)
+++ incubator/click/trunk/click/framework/src/org/apache/click/element/JsImport.java Sat Mar 21 10:51:07 2009
@@ -19,10 +19,37 @@
package org.apache.click.element;
import org.apache.click.Context;
+import org.apache.click.util.ClickUtils;
import org.apache.click.util.HtmlStringBuffer;
import org.apache.commons.lang.builder.HashCodeBuilder;
/**
+ * Provides a JavaScript HEAD element for importing <tt>external</tt> JavaScript
+ * files using the <script> tag.
+ * <p/>
+ * Example usage:
+ * <pre class="prettyprint">
+ * public class MyPage extends Page {
+ *
+ * public List getHeadElements() {
+ * // We use lazy loading to ensure the JS import is only added the
+ * // first time this method is called.
+ * if (headElements == null) {
+ * // Get the head elements from the super implementation
+ * headElements = super.getHeadElements();
+ *
+ * JsImport jsImport = new JsImport("/js/js-library.js");
+ * headElements.add(jsImport);
+ * }
+ * return headElements;
+ * }
+ * } </pre>
+ *
+ * The <tt>jsImport</tt> instance will be rendered as follows (assuming the context
+ * path is <tt>myApp</tt>):
+ * <pre class="prettyprint">
+ * <script type="text/javascript" href="/myApp/js/js-library.js"></script> </pre>
+ *
* @author Bob Schellink
*/
public class JsImport extends ResourceElement {
@@ -30,20 +57,21 @@
// ----------------------------------------------------------- Constructors
/**
- * Constructs a new JavascriptImport.
+ * Constructs a new JavaScript import element.
*/
public JsImport() {
this(null);
}
/**
- * Construct a new JavascriptImport with the specified <tt>src</tt> attribute.
+ * Construct a new JavaScript import element with the specified
+ * <tt>src</tt> attribute.
* <p/>
- * <b>Please note</b> if the given <tt>src</tt> begins with a <tt class="wr">"/"</tt>
- * character the src will be prefixed with the web application
- * <tt>context path</tt>.
+ * <b>Please note</b> if the given <tt>src</tt> begins with a
+ * <tt class="wr">"/"</tt> character the src will be prefixed with the web
+ * application <tt>context path</tt>.
*
- * @param src the Javascript src attribute
+ * @param src the JavaScript import src attribute
*/
public JsImport(String src) {
setSrc(src);
@@ -53,20 +81,20 @@
// ------------------------------------------------------ Public properties
/**
- * Returns the Css import HTML tag: <script>.
+ * Returns the JavaScript import HTML tag: <script>.
*
- * @return the Css import HTML tag: <script>
+ * @return the JavaScript import HTML tag: <script>
*/
public String getTag() {
return "script";
}
/**
- * This method always return true because JavaScript import must be unique
+ * This method always return true because a JavaScript import must be unique
* based on its <tt>src</tt> attribute. In other words the Page HEAD should
* only contain a single JavaScript import for the specific <tt>src</tt>.
*
- * @see HtmlHeader#isUnique()
+ * @see ResourceElement#isUnique()
*
* @return true because JavaScript import must unique based on its
* <tt>src</tt> attribute
@@ -118,7 +146,7 @@
// ------------------------------------------------ Package Private Methods
/**
- * Render the HTML representation of the JavaScript import to the specified
+ * Render the HTML representation of the JsImport element to the specified
* buffer.
*
* @param buffer the buffer to render output to
@@ -170,19 +198,4 @@
public int hashCode() {
return new HashCodeBuilder(17, 37).append(getSrc()).toHashCode();
}
-
- // ------------------------------------------------ Package Private Methods
-
- /**
- * This operation is not supported because JavaScript imports is always
- * unique based on their <tt>src</tt> attribute.
- *
- * @see HtmlHeader#setUnique(boolean)
- *
- * @param unique sets whether the JavaScript import should be unique or not
- */
- void setUnique(boolean unique) {
- throw new UnsupportedOperationException("JavascriptImport is always"
- + " unique based on the 'src' attribute");
- }
}
Modified: incubator/click/trunk/click/framework/src/org/apache/click/element/JsScript.java
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/element/JsScript.java?rev=756912&r1=756911&r2=756912&view=diff
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/element/JsScript.java (original)
+++ incubator/click/trunk/click/framework/src/org/apache/click/element/JsScript.java Sat Mar 21 10:51:07 2009
@@ -19,10 +19,131 @@
package org.apache.click.element;
import org.apache.click.util.HtmlStringBuffer;
-import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.builder.HashCodeBuilder;
/**
+ * Provides a HEAD element for including <tt>inline</tt> JavaScript using the
+ * <script> tag.
+ * <p/>
+ * Example usage:
+ *
+ * <pre class="prettyprint">
+ * public class MyPage extends Page {
+ *
+ * public List getHeadElements() {
+ * // We use lazy loading to ensure the JS is only added the
+ * // first time this method is called.
+ * if (headElements == null) {
+ * // Get the head elements from the super implementation
+ * headElements = super.getHeadElements();
+ *
+ * JsScript jsScript = new JsScript("alert('Hello World!);");
+ * headElements.add(jsScript);
+ * }
+ * return headElements;
+ * }
+ * } </pre>
+ *
+ * The <tt>jsScript</tt> instance will be rendered as follows:
+ *
+ * <pre class="prettyprint">
+ * <script type="text/javascript">
+ * alert('Hello World');
+ * </script>
+ * </pre>
+ *
+ * Below is an example showing how to render inline Javascript from a
+ * Velocity template.
+ * <p/>
+ * First we create a Velocity template <tt>(/js/mycorp-template.js)</tt> which
+ * contains the variable <tt>$divId</tt> that must be replaced at runtime with
+ * the real Div ID attribute:
+ *
+ * <pre class="prettyprint">
+ * hide = function() {
+ * var div = document.getElementById('$divId');
+ * div.style.display = "none";
+ * }
+ * </pre>
+ *
+ * Next is the Page implementation:
+ *
+ * <pre class="prettyprint">
+ * public class MyPage extends Page {
+ *
+ * public List getHeadElements() {
+ * // We use lazy loading to ensure the JS is only added the
+ * // first time this method is called.
+ * if (headElements == null) {
+ * // Get the head elements from the super implementation
+ * headElements = super.getHeadElements();
+ *
+ * // Create a default template model to pass to the template
+ * Map model = ClickUtils.createTemplateModel(this, getContext());
+ *
+ * // Add the id of the div to hide
+ * model.put("divId", "myDiv");
+ *
+ * // Specify the path to the JavaScript Velocity template
+ * String jsTemplate = "/js/mycorp-template.js";
+ *
+ * // Render the template providing it with the model
+ * String template = getContext().renderTemplate(jsTemplate, model);
+ *
+ * // Create the inline JavaScript for the given template
+ * JsScript jsScript = new JsScript(template);
+ * headElements.add(jsScript);
+ * }
+ * return headElements;
+ * }
+ * } </pre>
+ *
+ * The <tt>jsScript</tt> instance will render as follows (assuming the context
+ * path is <tt>myApp</tt>):
+ *
+ * <pre class="prettyprint">
+ * <script type="text/javascript">
+ * hide = function() {
+ * var div = document.getElementById('myDiv');
+ * div.style.display = "none";
+ * }
+ * </style>
+ * </pre>
+ *
+ * <h3>Character data (CDATA) support</h3>
+ *
+ * Sometimes it is necessary to wrap <tt>inline</tt> {@link JsScript} in CDATA
+ * tags. Two use cases are common for doing this:
+ * <ul>
+ * <li>For XML parsing: When using Ajax one often send back partial
+ * XML snippets to the browser, which is parsed as valid XML. However the XML
+ * parser will throw an error if the script contains reserved XML characters
+ * such as '&', '<' and '>'. For these situations it is recommended
+ * to wrap the script content inside CDATA tags.
+ * </li>
+ * <li>XHTML validation: if you want to validate your site using an XHTML
+ * validator e.g: <a target="_blank" href="http://validator.w3.org/">http://validator.w3.org/</a>.</li>
+ * </ul>
+ *
+ * To wrap the JavaScript content in CDATA tags, set
+ * {@link #setCharacterData(boolean)} to true. Below is how the JavaScript
+ * content would be rendered:
+ *
+ * <pre class="prettyprint">
+ * <script type="text/javascript">
+ * /∗<![CDATA[∗/
+ *
+ * if(x < y) alert('Hello');
+ *
+ * /∗]]>∗/
+ * </script> </pre>
+ *
+ * Notice the CDATA tags are commented out which ensures older browsers that
+ * don't understand the CDATA tag, will ignore it and only process the actual
+ * content.
+ * <p/>
+ * For an overview of XHTML validation and CDATA tags please see
+ * <a target="_blank" href="http://javascript.about.com/library/blxhtml.htm">http://javascript.about.com/library/blxhtml.htm</a>.
*
* @author Bob Schellink
*/
@@ -30,29 +151,27 @@
// -------------------------------------------------------------- Variables
- /** A buffer holding the inline CSS content. */
+ /** A buffer holding the inline JavaScript content. */
private HtmlStringBuffer content = new HtmlStringBuffer();
/**
- * Indicates if the HtmlHeader's content should be wrapped in a CDATA tag.
- * <b>Note:</b> this property only applies to HtmlHeader imports which contain
- * <tt>inline</tt> content.
+ * Indicates if the JsScript's content should be wrapped in a CDATA tag.
*/
private boolean characterData = false;
// ----------------------------------------------------------- Constructors
/**
- * Construct a new inline Javascript element.
+ * Construct a new inline JavaScript element.
*/
public JsScript() {
this(null);
}
/**
- * Construct a new inline Javascript element with the given content.
+ * Construct a new inline JavaScript element with the given content.
*
- * @param content the Javascript content
+ * @param content the JavaScript content
*/
public JsScript(String content) {
if (content != null) {
@@ -64,25 +183,25 @@
// ------------------------------------------------------ Public Properties
/**
- * Returns the Javascript HTML tag: <script>.
+ * Returns the JavaScript HTML tag: <script>.
*
- * @return the Javascript HTML tag: <script>
+ * @return the JavaScript HTML tag: <script>
*/
public String getTag() {
return "script";
}
/**
- * Return the Javascript content buffer.
+ * Return the JavaScript content buffer.
*
- * @return the Javascript content buffer
+ * @return the JavaScript content buffer
*/
public HtmlStringBuffer getContent() {
return content;
}
/**
- * Set the Javascript content buffer.
+ * Set the JavaScript content buffer.
*
* @param content the new content buffer
*/
@@ -91,10 +210,10 @@
}
/**
- * Return true if the HtmlHeader's content should be wrapped in CDATA tags,
+ * Return true if the JsScript's content should be wrapped in CDATA tags,
* false otherwise.
*
- * @return true if the HtmlHeader's content should be wrapped in CDATA tags,
+ * @return true if the JsScript's content should be wrapped in CDATA tags,
* false otherwise
*/
public boolean isCharacterData() {
@@ -102,9 +221,9 @@
}
/**
- * Sets whether the HtmlHeader's content should be wrapped in CDATA tags or not.
+ * Sets whether the JsScript's content should be wrapped in CDATA tags or not.
*
- * @param characterData true indicates that the HtmlHeader's content should be
+ * @param characterData true indicates that the JsScript's content should be
* wrapped in CDATA tags, false otherwise
*/
public void setCharacterData(boolean characterData) {
@@ -114,17 +233,18 @@
// --------------------------------------------------------- Public Methods
/**
- * Append the given Javascript string to the content buffer.
+ * Append the given JavaScript string to the content buffer.
*
- * @param content the Javascript string to append to the content
+ * @param content the JavaScript string to append to the content
* buffer
+ * @return the JavaScript content buffer
*/
- public void append(String content) {
- this.content.append(content);
+ public HtmlStringBuffer append(String content) {
+ return this.content.append(content);
}
/**
- * Render the HTML representation of the JavaScript to the specified
+ * Render the HTML representation of the JsScript element to the specified
* buffer.
*
* @param buffer the buffer to render output to
@@ -144,7 +264,7 @@
// Render CDATA tag if necessary
renderCharacterDataPrefix(buffer);
- buffer.append(getContent());
+ renderContent(buffer);
renderCharacterDataSuffix(buffer);
@@ -194,6 +314,17 @@
return new HashCodeBuilder(17, 37).append(getId()).toHashCode();
}
+ // ------------------------------------------------------ Protected Methods
+
+ /**
+ * Render this JsScript content to the specified buffer.
+ *
+ * @param buffer the buffer to append the output to
+ */
+ protected void renderContent(HtmlStringBuffer buffer) {
+ buffer.append(getContent());
+ }
+
// ------------------------------------------------ Package Private Methods
/**
@@ -222,21 +353,4 @@
buffer.append(" /*]]>*/");
}
}
-
- /**
- * @see HtmlHeader#setUnique(boolean)
- *
- * @deprecated use {@link #setId(java.lang.String)} instead
- *
- * @param unique sets whether the HtmlHeader import should be unique or not
- */
- void setUnique(boolean unique) {
- super.setUnique(unique);
-
- // If CSS is unique and ID is not defined, derive the ID from the content
- if (unique && StringUtils.isBlank(getId()) && getContent().length() > 0) {
- int hash = Math.abs(getContent().toString().hashCode());
- setId(Integer.toString(hash));
- }
- }
}
Modified: incubator/click/trunk/click/framework/src/org/apache/click/element/ResourceElement.java
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/element/ResourceElement.java?rev=756912&r1=756911&r2=756912&view=diff
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/element/ResourceElement.java (original)
+++ incubator/click/trunk/click/framework/src/org/apache/click/element/ResourceElement.java Sat Mar 21 10:51:07 2009
@@ -22,6 +22,122 @@
import org.apache.commons.lang.StringUtils;
/**
+ * Provides a base class for rendering HEAD resources of an HTML page, for
+ * example JavaScript (<script>) and Cascading Stylesheets
+ * (<link>/<style>).
+ * <p/>
+ * Subclasses should override {@link #getTag()} to return a specific HTML tag.
+ * <p/>
+ * Below are some example Resource elements:
+ * <ul>
+ * <li>{@link JsImport}, for importing <tt>external</tt> JavaScript using the
+ * <script> element.</li>
+ * <li>{@link JsScript}, for including <tt>inline</tt> JavaScript using the
+ * <script> element.</li>
+ * <li>{@link CssImport}, for importing <tt>external</tt> Cascading Stylesheets
+ * using the <link> element.</li>
+ * <li>{@link CssStyle}, for including <tt>inline</tt> Cascading Stylesheets
+ * using the <style> element.</li>
+ * </ul>
+ *
+ * <h3>Remove duplicates</h3>
+ * Click will ensure that duplicate Resource elements are removed by checking
+ * the {@link #isUnique()} property. No matter how many Controls or Pages
+ * import the same Resource, only one will be rendered if {@link #isUnique()}
+ * returns <tt>true</tt>.
+ * <p/>
+ * The rules for defining a unique Resource is as follows:
+ * <ul>
+ * <li>{@link JsImport} and {@link CssImport} is unique based on the
+ * attributes {@link JsImport#getSrc()} and {@link CssImport#getHref()}
+ * respectively.</li>
+ * <li>{@link JsScript} and {@link CssStyle} is unique if their HTML
+ * {@link #setId(java.lang.String) ID} attribute is set. The HTML
+ * spec defines that an element's HTML ID must be unique per page.</li>
+ * </ul>
+ * For example:
+ * <pre class="prettyprint">
+ * public class MyPage extends Page {
+ *
+ * public List getHeadElements() {
+ * // We use lazy loading to ensure the JavaScript and Css is only added
+ * // the first time this method is called.
+ * if (headElements == null) {
+ * // Get the head elements from the super implementation
+ * headElements = super.getHeadElements();
+ *
+ * JsImport jsImport = new JsImport("/js/mylib.js");
+ * // Click will ensure the library "/js/mylib.js" is only included
+ * // once in the Page
+ * headElements.add(jsImport);
+ *
+ * JsScript jsScript = new JsScript("alert('Hello!');");
+ * // Click won't ensure the script is unique because its ID
+ * // attribute is not defined
+ * headElements.add(jsScript);
+ *
+ * jsScript = new JsScript("alert('Hello!');");
+ * jsScript.setId("my-unique-script-id");
+ * // Click will ensure the script is unique because its ID attribute
+ * // is defined. Click will remove other scripts with the same ID
+ * headElements.add(jsScript);
+ *
+ * CssImport cssImport = new CssImport("/css/style.css");
+ * // Click will ensure the library "/css/style.css" is only
+ * // included once in the Page
+ * headElements.add(cssImport);
+ *
+ * CssScript cssScript = new CssScript("body { font-weight: bold; }");
+ * cssScript.setId("my-unique-style-id");
+ * // Click will ensure the css is unique because its ID attribute
+ * // is defined. Click will remove other css styles with the same ID
+ * headElements.add(cssScript);
+ * }
+ * return headElements;
+ * }
+ * } </pre>
+ *
+ * <h3>Conditional comment support for Internet Explorer</h3>
+ *
+ * Sometimes it is necessary to provide additional JavaScript and Css for
+ * Internet Explorer because it deviates quite often from the standards.
+ * <p/>
+ * Conditional comments allows you to wrap the resource in a special comment
+ * which only IE understands, meaning other browsers won't process the resource.
+ * <p/>
+ * You can read more about conditional comments
+ * <a target="_blank" href="http://msdn.microsoft.com/en-us/library/ms537512(VS.85).aspx#syntax">here</a>
+ * and <a target="_blank" href="http://www.quirksmode.org/css/condcom.html">here</a>
+ * <p/>
+ * It has to be said that IE7 and up has much better support for Css, thus
+ * conditional comments are mostly used for IE6 and below.
+ * <pre class="prettyprint">
+ * public class MyPage extends Page {
+ *
+ * public List getHeadElements() {
+ * // We use lazy loading to ensure the JavaScript and Css is only added
+ * // the first time this method is called.
+ * if (headElements == null) {
+ * // Get the head elements from the super implementation
+ * headElements = super.getHeadElements();
+ *
+ * CssImport cssImport = new CssImport("/css/ie-style.css");
+ * // Use one of the predefined conditional comments to target IE6
+ * // and below
+ * cssImport.setConditionalComment(IE_LESS_THAN_IE7);
+ * headElements.add(cssImport);
+ *
+ * cssImport = new CssImport("/css/ie-style2.css");
+ * // Use a custom predefined conditional comments to target only IE6
+ * cssImport.setConditionalComment("[if IE 6]");
+ * headElements.add(cssImport);
+ * }
+ * return headElements;
+ * }
+ * } </pre>
+ *
+ * ResourceElement contains some predefined Conditional Comments namely
+ * {@link #IF_IE}, {@link #IF_LESS_THAN_IE7} and {@link #IF_IE7}.
*
* @author Bob Schellink
*/
@@ -49,24 +165,25 @@
// -------------------------------------------------------------- Variables
- /** The Internet Explorer conditional comment to wrap the HtmlHeader import with. */
+ /**
+ * The Internet Explorer conditional comment to wrap the Resource with.
+ */
private String conditionalComment;
/**
* Indicates if Click should ensure the import is unique, default value is
- * <tt>false</tt>. <b>Note:</b> subclasses of HtmlHeader have different rules to
- * determine if unique should be true or false.
+ * <tt>false</tt>.
*/
private boolean unique = false;
// ------------------------------------------------------ Public properties
/**
- * Return true if the HtmlHeader should be unique, false otherwise. The default
+ * Return true if the Resource should be unique, false otherwise. The default
* value is <tt>true</tt> if the {@link #getId() ID} attribute is defined,
* false otherwise.
*
- * @return true if the HtmlHeader should be unique, false otherwise.
+ * @return true if the Resource should be unique, false otherwise.
*/
public boolean isUnique() {
String id = getId();
@@ -80,21 +197,20 @@
}
/**
- * Return Internal Explorer's <tt>conditional comment</tt> to wrap the HtmlHeader
- * import with.
+ * Return Internal Explorer's <tt>conditional comment</tt> to wrap the
+ * Resource with.
*
- * @return Internal Explorer's conditional comment to wrap the HtmlHeader import
- * with.
+ * @return Internal Explorer's conditional comment to wrap the Resource with.
*/
public String getConditionalComment() {
return conditionalComment;
}
/**
- * Set Internet Explorer's conditional comment to wrap the HtmlHeader import with.
+ * Set Internet Explorer's conditional comment to wrap the Resource with.
*
* @param conditionalComment Internet Explorer's conditional comment to wrap
- * the HtmlHeader import with
+ * the Resource with
*/
public void setConditionalComment(String conditionalComment) {
this.conditionalComment = conditionalComment;
@@ -102,6 +218,16 @@
// --------------------------------------------------------- Public methods
+ /**
+ * Render the HTML representation of the Resource element to the specified
+ * buffer.
+ * <p/>
+ * If {@link #getTag()} returns null, this method will return an empty
+ * string.
+ *
+ * @param buffer the specified buffer to render the Resource element output
+ * to
+ */
public void render(HtmlStringBuffer buffer) {
renderConditionalCommentPrefix(buffer);
@@ -147,29 +273,4 @@
buffer.append("\n<![endif]-->");
}
}
-
- /**
- * This method provides backwards compatibility with the String based
- * HTML imports, to indicate whether Javascript and CSS must be unique
- * or not. The replacement functionality is provided by the html
- * {@link #setId(java.lang.String) ID} attribute.
- * <p/>
- * This property is *not* for public use and will be removed in a future
- * release. This property is only set from PageImports.
- *
- * @deprecated use {@link #setId(java.lang.String)} instead
- *
- * @param unique sets whether the HtmlHeader import should be unique or not
- */
- void setUnique(boolean unique) {
- String id = getId();
-
- // If id is defined, unique property cannot be set to false
- if (StringUtils.isNotBlank(id) && !unique) {
- throw new IllegalArgumentException("Cannot set unique property"
- + " to 'false' because an 'ID' attribute has been defined"
- + " which indicates the import should be unique.");
- }
- this.unique = unique;
- }
}
Added: incubator/click/trunk/click/framework/src/org/apache/click/element/package.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/element/package.html?rev=756912&view=auto
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/element/package.html (added)
+++ incubator/click/trunk/click/framework/src/org/apache/click/element/package.html Sat Mar 21 10:51:07 2009
@@ -0,0 +1,28 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<body>
+Provides basic HTML elements including:
+<ul>
+ <li>{@link org.apache.click.element.JsImport JsImport} - for importing external JavaScript files</li>
+ <li>{@link org.apache.click.element.JsScript JsScript} - for embedding JavaScript content in the page</li>
+ <li>{@link org.apache.click.element.CssImport CssImport} - for importing external Css files</li>
+ <li>{@link org.apache.click.element.CssStyle CssStyle} - for embedding Css content in the page</li>
+</ul>
+</body>
\ No newline at end of file