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:52:44 UTC
svn commit: r756913 -
/incubator/click/trunk/click/framework/src/org/apache/click/util/PageImports.java
Author: sabob
Date: Sat Mar 21 10:52:44 2009
New Revision: 756913
URL: http://svn.apache.org/viewvc?rev=756913&view=rev
Log:
javadoc
Modified:
incubator/click/trunk/click/framework/src/org/apache/click/util/PageImports.java
Modified: incubator/click/trunk/click/framework/src/org/apache/click/util/PageImports.java
URL: http://svn.apache.org/viewvc/incubator/click/trunk/click/framework/src/org/apache/click/util/PageImports.java?rev=756913&r1=756912&r2=756913&view=diff
==============================================================================
--- incubator/click/trunk/click/framework/src/org/apache/click/util/PageImports.java (original)
+++ incubator/click/trunk/click/framework/src/org/apache/click/util/PageImports.java Sat Mar 21 10:52:44 2009
@@ -40,55 +40,65 @@
import org.apache.commons.lang.StringUtils;
/**
- * Provides a utility object for rendering a Page's HTML header imports and its
- * control HTML header imports.
+ * Provides a utility object for rendering a Page's HEAD elements and
+ * control HEAD elements.
* <p/>
- * A PageImports instance is automatically added to the Velocity Context
- * for Velocity templates, or as a request attribute for JSP pages using the key
- * name "<span class="blue">imports</span>".
- *
- * <h3>PageImports Examples</h3>
+ * PageImports automatically makes the HEAD elements available to Velocity
+ * templates and JSP pages through the following variables:
+ * <ul>
+ * <li><span class="st">$headElements</span> - this variable includes all HEAD
+ * elements except JavaScript elements</li>
+ * <li><span class="st">$jsElements</span> - this variable includes only
+ * JavaScript elements</li>
+ * </ul>
+ * By splitting JavaScript elements from other HEAD elements allows you to place
+ * JavaScript elements at the bottom of the Page which allows the HTML content
+ * to be rendered faster.
+ * <p/>
+ * To use the HEAD elements simply reference them in your page template. For
+ * example:
*
- * To use the PageImports object simply reference it your page header
- * section. For example:
- * <pre class="codeHtml">
+ * <pre class="htmlCode">
* <html>
* <head>
- * <span class="blue">$imports</span>
+ * <span class="blue">$headElements</span>
* </head>
* <body>
* <span class="red">$form</span>
+ *
+ * <span class="blue">$jsElements</span>
* <body>
* </html> </pre>
*
- * "<span class="blue">imports</span>" include all javascript and stylesheet
- * imports.
- * <p/>
- * PageImports also provides a way of including the javascript and stylesheet
- * separately using the key names "<span class="blue">cssImports</span>" and
- * "<span class="blue">jsImports</span>".
- * <p/>
- * You should follow the performance best practice by importing CSS includes
- * in the head section, then include the JS imports after the html body.
- * For example:
- * <pre class="codeHtml">
+ * Its not always possible to move the JavaScript elements to the bottom of
+ * the Page, for example there might be JavaScript scoping issues. In those
+ * situations you can simply place the JavaScript elements variable in the Page
+ * HEAD section:
+ *
+ * <pre class="htmlCode">
* <html>
* <head>
- * <span class="blue">$cssImports</span>
+ * <span class="blue">$headElements</span>
+ * <span class="blue">$jsElements</span>
* </head>
* <body>
* <span class="red">$form</span>
- * <br/>
- * <span class="red">$table</span>
* <body>
- * </html>
- * <span class="blue">$jsImports</span>
- * </pre>
+ * </html> </pre>
+ *
+ * <b>Please note: </b>the above variables are new in Click 2.1.0. For backwards
+ * compatibility the HEAD elements are also available through the following
+ * variables:
*
- * Please also see {@link org.apache.click.Page#getHtmlHeaders()},
- * {@link org.apache.click.Control#getHtmlHeaders()},
- * {@link org.apache.click.Page#getHtmlImports()} and
- * {@link org.apache.click.Control#getHtmlImports()}.
+ * <ul>
+ * <li><span class="st">$imports</span> - this variable includes all HEAD
+ * elements including JavaScript and Css elements</li>
+ * <li><span class="st">$cssImports</span> - this variable includes only Css elements</li>
+ * <li><span class="st">$jsImports</span> - this variable includes only Javascript elements</li>
+ * </ul>
+ *
+ * Please also see {@link org.apache.click.Page#getHeadElements()},
+ * {@link org.apache.click.Control#getHeadElements()}.
*
* @author Malcolm Edgar
*/
@@ -129,9 +139,9 @@
// --------------------------------------------------------- Public Methods
/**
- * Add the given HtmlHeader to the Page HTML imports.
+ * Add the given Element to the Page HEAD elements.
*
- * @param element the HtmlHeader to add
+ * @param element the Element to add
*/
public void add(Element element) {
if (element instanceof JsImport) {
@@ -170,7 +180,7 @@
/**
* Add the given HTML import line to the Page HTML imports.
*
- * @deprecated use the new {@link #add(org.apache.click.util.HtmlHeader)}
+ * @deprecated use the new {@link #add(org.apache.click.element.Element)}
* instead
*
* @param value the HTML import line to add
@@ -422,7 +432,7 @@
}
/**
- * Process the Page's set of control HTML head imports.
+ * Process the Page's set of control HEAD elements.
*/
protected void processPageControls() {
if (isInitialized()) {
@@ -445,20 +455,20 @@
addImport(page.getHtmlImports());
- processHtmlHeaders(page.getHeadElements());
+ processHeadElements(page.getHeadElements());
}
/**
- * Process the given control HTML headers. This method will recursively
+ * Process the given control HEAD elements. This method will recursively
* process Containers and all child controls.
* <p/>
- * This method delegates to {@link #processHtmlHeaders(java.util.List)}
- * to add the HTML headers to the Page imports.
+ * This method delegates to {@link #processHeadElements(java.util.List)}
+ * to add the HEAD elements to the Page imports.
*
* @param control the control to process
*/
protected void processControl(Control control) {
- processHtmlHeaders(control.getHeadElements());
+ processHeadElements(control.getHeadElements());
if (control instanceof Container) {
Container container = (Container) control;
@@ -481,21 +491,26 @@
}
/**
- * Process the given list of HTML headers.
+ * Process the given list of HEAD elements.
* <p/>
* This method invokes {@link #add(org.apache.click.element.Element)} for
- * every <tt>HeadElement</tt> entry in the specified list.
+ * every <tt>Element</tt> entry in the specified list.
*
- * @param headElements the list of HTML HEAD elements to process
+ * @param elements the list of HEAD elements to process
*/
- protected void processHtmlHeaders(List headElements) {
- if (headElements == null || headElements.isEmpty()) {
+ protected void processHeadElements(List elements) {
+ if (elements == null || elements.isEmpty()) {
return;
}
- Iterator it = headElements.iterator();
+ Iterator it = elements.iterator();
while (it.hasNext()) {
- add((Element) it.next());
+ Object element = it.next();
+ if (!(element instanceof Element)) {
+ throw new IllegalStateException("non Element object added to"
+ + " head elements.");
+ }
+ add((Element) element);
}
}
@@ -702,16 +717,13 @@
}
/**
- * 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 org.apache.click.element.Element#setId(java.lang.String) ID}
- * attribute.
+ * Ensure the given element and content will be unique.
*
* @deprecated use {@link org.apache.click.element.Element#setId(java.lang.String) ID}
* instead
*
- * @param cssStyle sets whether the HtmlHeader import should be unique or not
+ * @param element sets whether the HEAD element should be unique or not
+ * @param content sets whether the HEAD element should be unique or not
*/
private void setUnique(Element element, String content) {
String id = element.getId();