svn commit: r1022677 - /wicket/branches/wicket-1.4.x/wicket/src/main/java/org/apache/wicket/markup/html/border/Border.java

[iv...@apache.org]

Author: ivaynberg
Date: Thu Oct 14 19:37:53 2010
New Revision: 1022677

URL: http://svn.apache.org/viewvc?rev=1022677&view=rev
Log:
javadoc

Modified:
    wicket/branches/wicket-1.4.x/wicket/src/main/java/org/apache/wicket/markup/html/border/Border.java

Modified: wicket/branches/wicket-1.4.x/wicket/src/main/java/org/apache/wicket/markup/html/border/Border.java
URL: http://svn.apache.org/viewvc/wicket/branches/wicket-1.4.x/wicket/src/main/java/org/apache/wicket/markup/html/border/Border.java?rev=1022677&r1=1022676&r2=1022677&view=diff
==============================================================================
--- wicket/branches/wicket-1.4.x/wicket/src/main/java/org/apache/wicket/markup/html/border/Border.java (original)
+++ wicket/branches/wicket-1.4.x/wicket/src/main/java/org/apache/wicket/markup/html/border/Border.java Thu Oct 14 19:37:53 2010
@@ -98,6 +98,29 @@ import org.apache.wicket.model.IModel;
  *   </html>
  * </pre>
  * 
+ * 
+ * <p>
+ * IMPORTANT NOTE<br/>
+ * It is important that components added to the border by downstream users are added to the border's
+ * body container instead of directly to the border. This will properly maintain the component
+ * hierarchy synchronicity with markup hierarchy because in markup children are added under the
+ * {@code border:body} tag which is presented by the border's body container and not the border
+ * itself. Here is an example of an improper usage of the border:
+ * 
+ * <pre>
+ * BoxBorder border=new BoxBorder("border");
+ * border.add(new Label("label")); <== INVALID
+ * </pre>
+ * 
+ * Instead, the label should be added to border's body container:
+ * 
+ * <pre>
+ * BoxBorder border=new BoxBorder("border");
+ * border.getBodyContainer().add(new Label("label")); <== INVALID
+ * </pre>
+ * 
+ * </p>
+ * 
  * @see BorderBodyResolver
  * @see BorderBodyContainer
  *