001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.core.domutil;
015:
016: import org.w3c.dom.DocumentFragment;
017: import org.w3c.dom.Element;
018:
019: /**
020: * Manages a pattern based DOM Element list. The pattern is used to create new elements (by using a deep clone),
021: * so all elements have the same tag name (same as the pattern).
022: *
023: * <p>The starting point is a DOM element list with almost a child element, this first child element
024: * is saved as the pattern (really a deep clone), and new elements are created using this element as the pattern.
025: * The initial element list (including the pattern) may be initially cleared
026: * or kept as is when this object is created and attached to the underlying DOM list.</p>
027: *
028: * <p>This type of list helps to render a list of values into the DOM element list,
029: * for instance, this interface support "out the box" the typical DOM element list where
030: * every child element contains some value usually as the data of a text node.
031: * Methods to add new elements include optionally a <code>value</code> parameter.
032: * The structure and renderer objects are used to customize how and where this value is saved in the list
033: * beyond the default cases.</p>
034: *
035: * <p>A pattern based DOM Element list ever works in "master" mode, see {@link ElementListFree#isMaster()}.</p>
036: *
037: * @see org.itsnat.core.ItsNatDocument#createElementList(org.w3c.dom.Element,boolean)
038: * @author Jose Maria Arranz Santamaria
039: */
040: public interface ElementList extends ElementListBase {
041: /**
042: * Returns the current structure used by this list.
043: *
044: * @return the current structure.
045: * @see #setElementListStructure(ElementListStructure)
046: */
047: public ElementListStructure getElementListStructure();
048:
049: /**
050: * Sets the structure used by this list.
051: *
052: * @param structure the new structure.
053: * @see #getElementListStructure()
054: */
055: public void setElementListStructure(ElementListStructure structure);
056:
057: /**
058: * Returns the current renderer used by this list.
059: *
060: * @return the current renderer.
061: * @see #setElementListRenderer(ElementListRenderer)
062: */
063: public ElementListRenderer getElementListRenderer();
064:
065: /**
066: * Sets the renderer used by this list.
067: *
068: * @param renderer the new renderer.
069: * @see #getElementListRenderer()
070: */
071: public void setElementListRenderer(ElementListRenderer renderer);
072:
073: /**
074: * Returns the element used as a pattern. This element is a clone of the
075: * original first child element used as a pattern.
076: *
077: * @return the pattern element.
078: */
079: public Element getChildPatternElement();
080:
081: /**
082: * Increases or shrinks the list to fit the new size.
083: *
084: * <p>If the new size is bigger new elements are added at the end, if the size
085: * is lower tail elements are removed.</p>
086: *
087: * <p>Note: <code>getLength()</code> returns the current length, this method
088: * is defined in <code>org.w3c.dom.NodeList.getLength()</code>.</p>
089: *
090: * @param len the new length.
091: * @see #addElement()
092: * @see #removeElementAt(int)
093: */
094: public void setLength(int len);
095:
096: /**
097: * Adds a new child element at the end of the list using the pattern (the new element is a clone).
098: *
099: * @return the new element.
100: * @see #addElement(Object)
101: */
102: public Element addElement();
103:
104: /**
105: * Adds a new child element at the end of the list and renders the specified value using
106: * the current structure and renderer.
107: *
108: * @param value the value to render.
109: * @return the new element.
110: * @see #addElement()
111: * @see #getElementListStructure()
112: * @see #getElementListRenderer()
113: * @see ElementListStructure#getContentElement(ElementList,int,Element)
114: * @see ElementListRenderer#renderList(ElementList,int,Object,Element,boolean)
115: */
116: public Element addElement(Object value);
117:
118: /**
119: * Inserts a new child element at the specified position using the pattern (the new element is a clone).
120: *
121: * @param index index of the new element.
122: * @return the new element.
123: * @see #insertElementAt(int,Object)
124: */
125: public Element insertElementAt(int index);
126:
127: /**
128: * Inserts a new child element at the specified position and renders the specified value using
129: * the current structure and renderer.
130: *
131: * @param index index of the element.
132: * @param value the value to render.
133: * @return the new element.
134: * @see #insertElementAt(int)
135: * @see #getElementListStructure()
136: * @see #getElementListRenderer()
137: * @see ElementListStructure#getContentElement(ElementList,int,Element)
138: * @see ElementListRenderer#renderList(ElementList,int,Object,Element,boolean)
139: */
140: public Element insertElementAt(int index, Object value);
141:
142: /**
143: * Renders the specified value into the element with the given position
144: * using the current structure and renderer.
145: *
146: * @param index index of the element.
147: * @param value the value to render.
148: * @see #insertElementAt(int,Object)
149: * @see #getElementListStructure()
150: * @see #getElementListRenderer()
151: * @see ElementListStructure#getContentElement(ElementList,int,Element)
152: * @see ElementListRenderer#renderList(ElementList,int,Object,Element,boolean)
153: */
154: public void setElementValueAt(int index, Object value);
155:
156: /**
157: * Returns the "content" element, this element is used to render below
158: * the associated value of the child element. This element is obtained
159: * using the current structure.
160: *
161: * @param index index of the element.
162: * @return the content element.
163: * @see #getElementListStructure()
164: * @see ElementListStructure#getContentElement(ElementList,int,Element)
165: * @see ElementListRenderer#renderList(ElementList,int,Object,Element,boolean)
166: */
167: public Element getContentElementAt(int index);
168:
169: /**
170: * Informs whether the original (saved as pattern) markup is used to render.
171: *
172: * <p>The default value is defined by {@link org.itsnat.core.ItsNatDocument#isUsePatternMarkupToRender()}</p>
173: *
174: * @return true if the original markup is used.
175: * @see #setUsePatternMarkupToRender(boolean)
176: */
177: public boolean isUsePatternMarkupToRender();
178:
179: /**
180: * Sets whether the original (saved as pattern) markup is used to render.
181: *
182: * @param value true to enable the use of original markup to render.
183: * @see #isUsePatternMarkupToRender()
184: */
185: public void setUsePatternMarkupToRender(boolean value);
186:
187: /**
188: * Returns the pattern used to render values if {@link #isUsePatternMarkupToRender()}
189: * is true.
190: *
191: * @return the pattern used to render values.
192: */
193: public DocumentFragment getChildContentPatternFragment();
194: }
|